stonecut 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stonecut",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI that drives PRD-driven development with agentic coding CLIs",
   "license": "MIT",
   "repository": {
@@ -32,7 +32,9 @@
     "prepare": "husky"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.92",
     "@clack/prompts": "^0.10.0",
+    "@openai/codex-sdk": "^0.118.0",
     "commander": "^13.1.0"
   },
   "lint-staged": {

package/src/execute.ts

@@ -14,7 +14,7 @@ import { LocalSource } from "./local";
 import { slugifyBranchComponent } from "./naming";
 import { renderLocal } from "./prompt";
 import { Logger } from "./logger";
-import { defaultGitOps, runAfkLoop } from "./runner";
+import { defaultGitOps, formatTokens, runAfkLoop } from "./runner";
 import { getRunner } from "./runners/index";
 import type { Issue, IterationResult, Session } from "./types";
 
@@ -22,6 +22,22 @@ import type { Issue, IterationResult, Session } from "./types";
 // Stonecut report
 // ---------------------------------------------------------------------------
 
+/** Build the metrics parenthetical for a report line. */
+function formatMetrics(r: IterationResult): string {
+	const parts: string[] = [];
+	if (r.turns != null) {
+		parts.push(`${r.turns} turns`);
+	}
+	const totalTokens =
+		r.inputTokens != null || r.outputTokens != null
+			? (r.inputTokens ?? 0) + (r.outputTokens ?? 0)
+			: undefined;
+	if (totalTokens != null) {
+		parts.push(`${formatTokens(totalTokens)} tokens`);
+	}
+	return parts.length > 0 ? ` (${parts.join(", ")})` : "";
+}
+
 /**
  * Build the Stonecut Report section for a PR body.
  */
@@ -32,11 +48,12 @@ export function buildReport(
 ): string {
 	const lines = ["## Stonecut Report", `**Runner:** ${runnerName}`, ""];
 	for (const r of results) {
+		const metrics = formatMetrics(r);
 		if (r.success) {
-			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed`);
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: completed${metrics}`);
 		} else {
 			const reason = r.error || "unknown error";
-			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}`);
+			lines.push(`- #${r.issueNumber} ${r.issueFilename}: failed — ${reason}${metrics}`);
 		}
 	}
 
@@ -100,10 +117,10 @@ export async function executeLocal(
 	iterations: number | "all",
 	runnerName: string,
 ): Promise<void> {
-	const runner = getRunner(runnerName);
 	const source = new LocalSource(name);
 	const prdIdentifier = slugifyBranchComponent(name) || "spec";
 	const logger = new Logger(prdIdentifier);
+	const runner = getRunner(runnerName, logger);
 
 	const session: Session = { logger, git: defaultGitOps, runner, runnerName };
 

package/src/logger.ts

@@ -29,6 +29,10 @@ export class Logger implements LogWriter {
 
 	log(message: string): void {
 		console.log(message);
+		this.logFile(message);
+	}
+
+	logFile(message: string): void {
 		const ts = new Date().toISOString();
 		const fileWasMissing = !existsSync(this.filePath);
 		try {

package/src/runner.ts

@@ -39,6 +39,7 @@ export const defaultGitOps: GitOps = {
 /** Console-only logger for backward compatibility. */
 export const consoleLogger: LogWriter = {
 	log: (message: string) => console.log(message),
+	logFile: () => {},
 	close: () => {},
 };
 
@@ -124,7 +125,6 @@ export async function runAfkLoop<T extends { number: number }>(
 	const { logger, git, runner, runnerName } = session;
 
 	logger.log(`Session started — runner: ${runnerName}, iterations: ${iterations}`);
-	runner.logEnvironment(logger);
 	logger.log("");
 	const results: IterationResult[] = [];
 	const sessionStart = performance.now();
@@ -182,6 +182,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: runResult.error,
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 
 			if (lastFailedIssueNumber === issue.number) {
@@ -209,6 +212,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: errorMsg,
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 
 			if (lastFailedIssueNumber === issue.number) {
@@ -238,6 +244,9 @@ export async function runAfkLoop<T extends { number: number }>(
 				success: false,
 				elapsedSeconds: runResult.durationSeconds,
 				error: "commit failed after retries",
+				turns: runResult.turns,
+				inputTokens: runResult.inputTokens,
+				outputTokens: runResult.outputTokens,
 			});
 			// Commit failures always stop the session immediately
 			logger.log("Stopping session: unable to commit.");
@@ -264,6 +273,9 @@ export async function runAfkLoop<T extends { number: number }>(
 			issueFilename: name,
 			success: true,
 			elapsedSeconds: runResult.durationSeconds,
+			turns: runResult.turns,
+			inputTokens: runResult.inputTokens,
+			outputTokens: runResult.outputTokens,
 		});
 
 		lastFailedIssueNumber = null;
@@ -284,6 +296,19 @@ export async function runAfkLoop<T extends { number: number }>(
 	return results;
 }
 
+/** Format a token count as a human-readable string (e.g., 12400 → "12.4k"). */
+export function formatTokens(count: number): string {
+	if (count >= 1_000_000) {
+		const m = count / 1_000_000;
+		return m % 1 === 0 ? `${m}M` : `${parseFloat(m.toFixed(1))}M`;
+	}
+	if (count >= 1_000) {
+		const k = count / 1_000;
+		return k % 1 === 0 ? `${k}k` : `${parseFloat(k.toFixed(1))}k`;
+	}
+	return `${count}`;
+}
+
 /** Format seconds as a human-readable duration. */
 export function fmtTime(seconds: number): string {
 	if (seconds < 60) {
@@ -311,7 +336,18 @@ export function printSummary(
 	for (const r of results) {
 		const status = r.success ? "completed" : "failed";
 		const elapsed = fmtTime(r.elapsedSeconds);
-		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${elapsed})`);
+		const details = [elapsed];
+		if (r.turns != null) {
+			details.push(`${r.turns} turns`);
+		}
+		const totalTokens =
+			r.inputTokens != null || r.outputTokens != null
+				? (r.inputTokens ?? 0) + (r.outputTokens ?? 0)
+				: undefined;
+		if (totalTokens != null) {
+			details.push(`${formatTokens(totalTokens)} tokens`);
+		}
+		logger.log(`  Issue ${r.issueNumber} (${r.issueFilename}): ${status} (${details.join(", ")})`);
 	}
 
 	logger.log("");

package/src/runners/claude.ts

@@ -1,94 +1,178 @@
 /**
- * ClaudeRunner — adapter for Claude Code CLI.
+ * ClaudeRunner — adapter for Claude Code via the Agent SDK.
  *
- * Spawns a headless Claude Code session, parses the JSON output to
- * determine success/failure, and translates error subtypes into
- * human-readable messages.
+ * Calls query() from @anthropic-ai/claude-agent-sdk and consumes the
+ * async message stream internally. Console gets concise progress
+ * (tool calls, turn boundaries, errors); the log file captures the
+ * full event stream for debugging.
  */
 
+import { query as sdkQuery } from "@anthropic-ai/claude-agent-sdk";
+import type {
+	Query,
+	SDKAssistantMessage,
+	SDKMessage,
+	SDKPartialAssistantMessage,
+	SDKResultMessage,
+} from "@anthropic-ai/claude-agent-sdk";
 import type { LogWriter, Runner, RunResult } from "../types.js";
 
+const ALLOWED_TOOLS = ["Bash", "Edit", "Read", "Write", "Glob", "Grep"];
+
+type QueryFn = (params: { prompt: string; options?: Record<string, unknown> }) => Query;
+let queryFn: QueryFn = sdkQuery;
+
+/** @internal Replace the SDK query function. Returns a restore function. */
+export function _setQueryFn(fn: QueryFn): () => void {
+	const prev = queryFn;
+	queryFn = fn;
+	return () => {
+		queryFn = prev;
+	};
+}
+
 const ERROR_MESSAGES: Record<string, string> = {
 	error_max_turns: "max turns exceeded",
 	error_max_budget_usd: "max budget exceeded",
+	error_during_execution: "execution error",
+	error_max_structured_output_retries: "max structured output retries exceeded",
 };
 
 export class ClaudeRunner implements Runner {
-	logEnvironment(logger: LogWriter): void {
+	private logger: LogWriter;
+
+	constructor(logger: LogWriter) {
+		this.logger = logger;
 		const configDir = process.env.CLAUDE_CONFIG_DIR || "~/.claude (default)";
 		logger.log(`Claude config: ${configDir}`);
 	}
 
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
+		let result: SDKResultMessage | undefined;
 
-		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
 		try {
-			proc = Bun.spawn(
-				[
-					"claude",
-					"-p",
-					"--output-format",
-					"json",
-					"--allowedTools",
-					"Bash,Edit,Read,Write,Glob,Grep",
-				],
-				{ stdin: new Response(prompt), stdout: "pipe", stderr: "pipe" },
-			);
-		} catch {
-			return {
-				success: false,
-				exitCode: 1,
-				durationSeconds: (performance.now() - start) / 1000,
-				error: "claude binary not found in PATH",
-			};
+			const stream = queryFn({
+				prompt,
+				options: {
+					allowedTools: ALLOWED_TOOLS,
+					permissionMode: "acceptEdits",
+				},
+			});
+
+			for await (const message of stream) {
+				this.handleMessage(message);
+				if (message.type === "result") {
+					result = message;
+				}
+			}
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+
+			if (msg.includes("ENOENT") || msg.includes("not found") || msg.includes("spawn")) {
+				return { success: false, durationSeconds, error: "claude binary not found in PATH" };
+			}
+			return { success: false, durationSeconds, error: msg };
 		}
 
-		const exitCode = await proc.exited;
 		const durationSeconds = (performance.now() - start) / 1000;
 
-		const stdout = await new Response(proc.stdout as ReadableStream).text();
-		const output = stdout || undefined;
+		if (!result) {
+			return { success: false, durationSeconds, error: "no result message received" };
+		}
+
+		const sessionId = result.session_id;
+		const turns = result.num_turns;
+		const inputTokens = result.usage.input_tokens;
+		const outputTokens = result.usage.output_tokens;
 
-		if (output === undefined) {
+		this.logger.logFile(
+			`[claude] Result: ${result.subtype}, turns=${turns}, input=${inputTokens}, output=${outputTokens}`,
+		);
+
+		if (result.subtype === "success") {
 			return {
-				success: false,
-				exitCode,
+				success: true,
 				durationSeconds,
-				error: `no output (exit code ${exitCode})`,
+				output: result.result,
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId,
 			};
 		}
 
-		let data: unknown;
-		try {
-			data = JSON.parse(output);
-		} catch {
-			return {
-				success: false,
-				exitCode,
-				durationSeconds,
-				output,
-				error: "malformed JSON output",
-			};
+		const error = ERROR_MESSAGES[result.subtype] ?? `failed (${result.subtype})`;
+		const detail = result.errors?.length ? `: ${result.errors.join("; ")}` : "";
+		return {
+			success: false,
+			durationSeconds,
+			error: error + detail,
+			turns,
+			inputTokens,
+			outputTokens,
+			sessionId,
+		};
+	}
+
+	private handleMessage(message: SDKMessage): void {
+		switch (message.type) {
+			case "assistant":
+				this.logAssistant(message);
+				break;
+			case "stream_event":
+				this.logStreamEvent(message);
+				break;
+			case "result":
+				break;
+			default:
+				this.logger.logFile(`[claude] ${message.type}: ${JSON.stringify(message)}`);
+				break;
 		}
+	}
 
-		if (typeof data !== "object" || data === null || Array.isArray(data)) {
-			return {
-				success: false,
-				exitCode,
-				durationSeconds,
-				output,
-				error: "unexpected JSON output (not an object)",
-			};
+	private logAssistant(message: SDKAssistantMessage): void {
+		if (message.error) {
+			this.logger.log(`[claude] Error: ${message.error}`);
 		}
 
-		const subtype = (data as Record<string, unknown>).subtype ?? "";
-		if (subtype === "success") {
-			return { success: true, exitCode, durationSeconds, output };
+		for (const block of message.message.content) {
+			if (typeof block === "string") continue;
+			if (block.type === "tool_use") {
+				const target = this.toolTarget(block.name, block.input as Record<string, unknown>);
+				this.logger.log(`[claude] ${block.name}${target ? `: ${target}` : ""}`);
+			}
 		}
 
-		const error =
-			ERROR_MESSAGES[subtype as string] ?? `failed (${(subtype as string) || "unknown"})`;
-		return { success: false, exitCode, durationSeconds, output, error };
+		this.logger.logFile(`[claude] Assistant message: ${JSON.stringify(message.message.content)}`);
+	}
+
+	private logStreamEvent(message: SDKPartialAssistantMessage): void {
+		const event = message.event;
+		if (event.type === "content_block_delta") {
+			const delta = event.delta;
+			if ("text" in delta && typeof delta.text === "string") {
+				this.logger.logFile(`[claude] text: ${delta.text}`);
+			} else if ("thinking" in delta && typeof delta.thinking === "string") {
+				this.logger.logFile(`[claude] thinking: ${delta.thinking}`);
+			}
+		}
+	}
+
+	private toolTarget(name: string, input: Record<string, unknown>): string | undefined {
+		switch (name) {
+			case "Bash":
+				return typeof input.command === "string" ? input.command.slice(0, 80) : undefined;
+			case "Edit":
+			case "Read":
+			case "Write":
+				return typeof input.file_path === "string" ? input.file_path : undefined;
+			case "Glob":
+			case "Grep":
+				return typeof input.pattern === "string" ? input.pattern : undefined;
+			default:
+				return undefined;
+		}
 	}
 }

package/src/runners/codex.ts

@@ -1,81 +1,161 @@
 /**
- * CodexRunner — adapter for OpenAI Codex CLI.
+ * CodexRunner — adapter for OpenAI Codex via the Agent SDK.
  *
- * Spawns a headless Codex session in full-auto mode, uses exit code as
- * the primary success signal, and extracts error details from JSONL
- * output on failure.
+ * Creates a Codex client and thread per run(), consumes the async event
+ * stream internally. Console gets concise progress (tool calls, file
+ * changes, turn boundaries, errors); the log file captures the full
+ * event stream for debugging.
  */
 
+import { Codex, type ThreadEvent, type ThreadItem } from "@openai/codex-sdk";
 import type { LogWriter, Runner, RunResult } from "../types.js";
 
-function extractError(stdout: string): string {
-	for (const raw of stdout.split("\n")) {
-		const line = raw.trim();
-		if (!line) continue;
+type CodexFactory = (...args: ConstructorParameters<typeof Codex>) => InstanceType<typeof Codex>;
+let createCodex: CodexFactory = (...args) => new Codex(...args);
 
-		let event: unknown;
-		try {
-			event = JSON.parse(line);
-		} catch {
-			continue;
-		}
-
-		if (typeof event !== "object" || event === null || Array.isArray(event)) {
-			continue;
-		}
-
-		const rec = event as Record<string, unknown>;
-		const eventType = rec.type;
-
-		if (eventType === "turn.failed") {
-			const nested = rec.error;
-			if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
-				const msg = (nested as Record<string, unknown>).message;
-				if (typeof msg === "string" && msg) return msg;
-			}
-		} else if (eventType === "error") {
-			const msg = rec.message;
-			if (typeof msg === "string" && msg) return msg;
-		}
-	}
-
-	return "codex exited with non-zero status";
+/** @internal Replace the Codex factory. Returns a restore function. */
+export function _setCodexFactory(fn: CodexFactory): () => void {
+	const prev = createCodex;
+	createCodex = fn;
+	return () => {
+		createCodex = prev;
+	};
 }
 
 export class CodexRunner implements Runner {
-	logEnvironment(_logger: LogWriter): void {
-		// No environment-specific config to log for Codex.
+	private logger: LogWriter;
+
+	constructor(logger: LogWriter) {
+		this.logger = logger;
 	}
 
 	async run(prompt: string): Promise<RunResult> {
 		const start = performance.now();
 
-		let proc: Awaited<ReturnType<typeof Bun.spawn>>;
+		let threadId: string | undefined;
+		let turns = 0;
+		let inputTokens = 0;
+		let outputTokens = 0;
+		let failed = false;
+		let completed = false;
+		let errorMessage: string | undefined;
+
 		try {
-			proc = Bun.spawn(["codex", "exec", "--full-auto", "--json", "--ephemeral", "-"], {
-				stdin: new Response(prompt),
-				stdout: "pipe",
-				stderr: "pipe",
+			const codex = createCodex();
+			const thread = codex.startThread({
+				approvalPolicy: "never",
+				sandboxMode: "danger-full-access",
 			});
-		} catch {
+
+			const { events } = await thread.runStreamed(prompt);
+
+			for await (const event of events) {
+				this.handleEvent(event);
+
+				switch (event.type) {
+					case "thread.started":
+						threadId = event.thread_id;
+						break;
+					case "turn.started":
+						turns++;
+						break;
+					case "turn.completed":
+						completed = true;
+						this.logger.log(`[codex] Turn ${turns} completed`);
+						inputTokens += event.usage.input_tokens;
+						outputTokens += event.usage.output_tokens;
+						break;
+					case "turn.failed":
+						failed = true;
+						errorMessage = event.error.message;
+						this.logger.log(`[codex] Error: ${errorMessage}`);
+						break;
+					case "error":
+						failed = true;
+						errorMessage = event.message;
+						this.logger.log(`[codex] Error: ${errorMessage}`);
+						break;
+					case "item.started":
+					case "item.completed":
+						this.logItem(event.type, event.item);
+						break;
+				}
+			}
+		} catch (error: unknown) {
+			const durationSeconds = (performance.now() - start) / 1000;
+			const msg = error instanceof Error ? error.message : String(error);
+
+			if (msg.includes("ENOENT") || msg.includes("not found") || msg.includes("spawn")) {
+				return { success: false, durationSeconds, error: "codex binary not found in PATH" };
+			}
+			return { success: false, durationSeconds, error: msg };
+		}
+
+		const durationSeconds = (performance.now() - start) / 1000;
+
+		const status = failed ? "failed" : completed ? "success" : "incomplete";
+		this.logger.logFile(
+			`[codex] Result: ${status}, turns=${turns}, input=${inputTokens}, output=${outputTokens}`,
+		);
+
+		if (failed) {
 			return {
 				success: false,
-				exitCode: 1,
-				durationSeconds: (performance.now() - start) / 1000,
-				error: "codex binary not found in PATH",
+				durationSeconds,
+				error: errorMessage ?? "codex run failed",
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId: threadId,
 			};
 		}
 
-		const exitCode = await proc.exited;
-		const durationSeconds = (performance.now() - start) / 1000;
-
-		if (exitCode === 0) {
-			return { success: true, exitCode: 0, durationSeconds };
+		if (!completed) {
+			return {
+				success: false,
+				durationSeconds,
+				error: "no terminal event received from Codex",
+				turns,
+				inputTokens,
+				outputTokens,
+				sessionId: threadId,
+			};
 		}
 
-		const stdout = await new Response(proc.stdout as ReadableStream).text();
-		const error = extractError(stdout);
+		return {
+			success: true,
+			durationSeconds,
+			turns,
+			inputTokens,
+			outputTokens,
+			sessionId: threadId,
+		};
+	}
+
+	private handleEvent(event: ThreadEvent): void {
+		this.logger.logFile(`[codex] ${event.type}: ${JSON.stringify(event)}`);
+	}
 
-		return { success: false, exitCode, durationSeconds, error };
+	private logItem(phase: "item.started" | "item.completed", item: ThreadItem): void {
+		switch (item.type) {
+			case "command_execution":
+				if (phase === "item.started") {
+					this.logger.log(`[codex] Bash: ${item.command.slice(0, 80)}`);
+				}
+				break;
+			case "file_change":
+				if (phase === "item.completed") {
+					for (const change of item.changes) {
+						this.logger.log(`[codex] Edit: ${change.path}`);
+					}
+				}
+				break;
+			case "reasoning":
+				this.logger.logFile(`[codex] reasoning: ${item.text}`);
+				break;
+			case "error":
+				this.logger.log(`[codex] Error: ${item.message}`);
+				break;
+		}
 	}
 }

package/src/runners/index.ts

@@ -2,20 +2,20 @@
  * Runner registry — maps runner names to their implementations.
  */
 
-import type { Runner } from "../types.js";
+import type { LogWriter, Runner } from "../types.js";
 import { ClaudeRunner } from "./claude.js";
 import { CodexRunner } from "./codex.js";
 
-const RUNNERS: Record<string, new () => Runner> = {
+const RUNNERS: Record<string, new (logger: LogWriter) => Runner> = {
 	claude: ClaudeRunner,
 	codex: CodexRunner,
 };
 
-export function getRunner(name: string): Runner {
+export function getRunner(name: string, logger: LogWriter): Runner {
 	const Cls = RUNNERS[name];
 	if (!Cls) {
 		const available = Object.keys(RUNNERS).sort().join(", ");
 		throw new Error(`Unknown runner '${name}'. Available runners: ${available}`);
 	}
-	return new Cls();
+	return new Cls(logger);
 }

package/src/skills/stonecut-prd/SKILL.md

@@ -29,7 +29,7 @@ Check with the user that these modules match their expectations. Ask which modul
 
 Ask the user where to save the PRD:
 
-- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID (e.g., `ASC-1`), a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
+- **Local file** — Save as `.stonecut/specs/<name>/prd.md` in the project. Ask the user: "What should I name this spec?" The name can be anything — a ticket ID, a descriptive slug (e.g., `auth-refactor`), or whatever fits. Create the `.stonecut/specs/<name>/` directory if it doesn't exist.
 - **GitHub issue** — Create a GitHub issue using `gh issue create --label prd`. Before creating, ensure the `prd` label exists:
 
   ```bash
@@ -39,8 +39,6 @@ Ask the user where to save the PRD:
   fi
   ```
 
-If the project already has a `.stonecut/` directory, default to suggesting local. Otherwise, just ask.
-
 ### 6. Documentation impact check
 
 Before writing the PRD, ensure that documentation impact has been explicitly addressed. Based on everything you've learned from the interview and codebase exploration, analyze which user-facing documentation artifacts (README, CLI help text, docs/ content) would be affected by these changes.

package/src/types.ts

@@ -5,10 +5,13 @@
 /** Structured result from a single runner execution. */
 export interface RunResult {
 	success: boolean;
-	exitCode: number;
 	durationSeconds: number;
 	output?: string;
 	error?: string;
+	turns?: number;
+	inputTokens?: number;
+	outputTokens?: number;
+	sessionId?: string;
 }
 
 /** Result of a single afk iteration. */
@@ -18,12 +21,14 @@ export interface IterationResult {
 	success: boolean;
 	elapsedSeconds: number;
 	error?: string;
+	turns?: number;
+	inputTokens?: number;
+	outputTokens?: number;
 }
 
 /** Protocol that all runner adapters must satisfy. */
 export interface Runner {
 	run(prompt: string): Promise<RunResult>;
-	logEnvironment(logger: LogWriter): void;
 }
 
 /** Snapshot of the working tree state before a runner session. */
@@ -58,6 +63,8 @@ export interface Source<T> {
 /** Logger interface for session-scoped logging. */
 export interface LogWriter {
 	log(message: string): void;
+	/** Write a message only to the log file (not console). */
+	logFile(message: string): void;
 	close(): void;
 }