march-cli 0.1.21 → 0.1.23

package/src/agent/tool-summary.mjs

@@ -1,112 +1,112 @@
-export function formatToolStartLine(name, args = {}) {
-  if (name === "edit_file") {
-    const path = compactPath(args?.path ?? "");
-    const editCount = Array.isArray(args?.edits) ? args.edits.length : 0;
-    const mode = args?.mode ?? "patch";
-    const summary = mode === "patch" ? `${editCount} edit${editCount === 1 ? "" : "s"}` : mode;
-    return joinToolParts("◆", name, [path, summary]);
-  }
-  if (name === "command_exec") return joinToolParts("◆", name, [compactText(args?.command ?? "")]);
-  if (name === "terminal_send") return joinToolParts("◆", name, [args?.shell_id, formatTerminalSendAction(args)]);
-  if (name?.startsWith?.("terminal_")) return joinToolParts("◆", name, [args?.shell_id, formatTerminalDetails(args)]);
-  if (name === "external_web_search") return joinToolParts("◆", name, [quoteCompact(args?.query ?? "")]);
-  if (name === "web_fetch") return joinToolParts("◆", name, [compactText(args?.url ?? "")]);
-  if (name === "context_stats") return joinToolParts("◆", name, []);
-  if (name === "read") {
-    const path = compactPath(args?.path ?? args?.filePath ?? "");
-    return joinToolParts("→", name, [path, formatReadRange(args)]);
-  }
-  if (name === "grep") {
-    const path = compactPath(args?.path ?? "");
-    return joinToolParts("✱", name, [quoteCompact(args?.pattern ?? ""), path]);
-  }
-  if (name === "glob") {
-    const path = compactPath(args?.path ?? "");
-    return joinToolParts("✱", name, [quoteCompact(args?.pattern ?? ""), path]);
-  }
-  if (name === "find") {
-    const path = compactPath(args?.path ?? "");
-    return joinToolParts("✱", name, [quoteCompact(args?.pattern ?? ""), path]);
-  }
-  return joinToolParts("◆", name, [formatSmallOptions(args)]);
-}
-
-export function formatToolSuccessSummary(name, result, out = "") {
-  if (name === "grep") {
-    const matches = result?.details?.results?.length ?? countMatchLines(out);
-    return `${matches} match${matches === 1 ? "" : "es"}`;
-  }
-  if (name === "glob") {
-    const matches = Array.isArray(result?.details?.matches) ? result.details.matches.length : countNonEmptyLines(out);
-    return `${matches} file${matches === 1 ? "" : "s"}`;
-  }
-  if (name === "find") {
-    const matches = result?.details?.count ?? countNonEmptyLines(out);
-    return `${matches} file${matches === 1 ? "" : "s"}`;
-  }
-  if (name === "memory_open") {
-    return compactText(result?.details?.entry?.name ?? compactPath(result?.details?.path ?? ""));
-  }
-  return "";
-}
-
-function joinToolParts(icon, name, parts) {
-  const clean = parts.map((part) => String(part ?? "").trim()).filter(Boolean);
-  return `${icon} ${name}${clean.length ? ` · ${clean.join(" · ")}` : ""}`;
-}
-
-function formatReadRange(args = {}) {
-  if (args.offset == null && args.limit == null) return "";
-  if (args.offset != null && args.limit != null) return `lines ${args.offset}-${Number(args.offset) + Number(args.limit) - 1}`;
-  if (args.offset != null) return `from line ${args.offset}`;
-  return `limit ${args.limit}`;
-}
-
-function formatTerminalSendAction(args = {}) {
-  const hasText = typeof args.text === "string" && args.text.length > 0;
-  const key = args.key ? String(args.key) : "";
-  if (hasText && key) return `text+${key}`;
-  if (hasText) return args.text.includes("\n") || args.text.includes("\r") ? "text+enter" : "text";
-  return key || "send";
-}
-
-function formatTerminalDetails(args = {}) {
-  const details = [];
-  if (args.pattern) details.push(quoteCompact(args.pattern));
-  if (args.cols && args.rows) details.push(`${args.cols}x${args.rows}`);
-  if (args.command) details.push(compactText(args.command));
-  return details.join(" · ");
-}
-
-function formatSmallOptions(args = {}) {
-  const parts = [];
-  for (const [key, value] of Object.entries(args ?? {})) {
-    if (value == null || typeof value === "object") continue;
-    parts.push(`${key}=${compactText(value)}`);
-    if (parts.length >= 2) break;
-  }
-  return parts.join(", ");
-}
-
-function compactPath(path) {
-  return String(path ?? "").split(/[/\\]/).filter(Boolean).slice(-4).join("\\");
-}
-
-function quoteCompact(value) {
-  return JSON.stringify(compactText(value));
-}
-
-function compactText(value, limit = 80) {
-  const text = String(value ?? "").replace(/\s+/g, " ").trim();
-  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
-}
-
-function countMatchLines(text) {
-  const match = String(text ?? "").match(/(\d+)\s+matches?\b/i);
-  if (match) return Number(match[1]);
-  return countNonEmptyLines(text);
-}
-
-function countNonEmptyLines(text) {
-  return String(text ?? "").split("\n").filter(Boolean).length;
-}
+export function formatToolStartLine(name, args = {}) {
+  if (name === "edit_file") {
+    const path = compactPath(args?.path ?? "");
+    const editCount = Array.isArray(args?.edits) ? args.edits.length : 0;
+    const mode = args?.mode ?? "patch";
+    const summary = mode === "patch" ? `${editCount} edit${editCount === 1 ? "" : "s"}` : mode;
+    return joinToolParts("◆", name, [path, summary]);
+  }
+  if (name === "command_exec") return joinToolParts("◆", name, [compactText(args?.command ?? "")]);
+  if (name === "terminal_send") return joinToolParts("◆", name, [args?.shell_id, formatTerminalSendAction(args)]);
+  if (name?.startsWith?.("terminal_")) return joinToolParts("◆", name, [args?.shell_id, formatTerminalDetails(args)]);
+  if (name === "external_web_search") return joinToolParts("◆", name, [quoteCompact(args?.query ?? "")]);
+  if (name === "web_fetch") return joinToolParts("◆", name, [compactText(args?.url ?? "")]);
+  if (name === "context_stats") return joinToolParts("◆", name, []);
+  if (name === "read") {
+    const path = compactPath(args?.path ?? args?.filePath ?? "");
+    return joinToolParts("→", name, [path, formatReadRange(args)]);
+  }
+  if (name === "grep") {
+    const path = compactPath(args?.path ?? "");
+    return joinToolParts("✱", name, [quoteCompact(args?.pattern ?? ""), path]);
+  }
+  if (name === "glob") {
+    const path = compactPath(args?.path ?? "");
+    return joinToolParts("✱", name, [quoteCompact(args?.pattern ?? ""), path]);
+  }
+  if (name === "find") {
+    const path = compactPath(args?.path ?? "");
+    return joinToolParts("✱", name, [quoteCompact(args?.pattern ?? ""), path]);
+  }
+  return joinToolParts("◆", name, [formatSmallOptions(args)]);
+}
+
+export function formatToolSuccessSummary(name, result, out = "") {
+  if (name === "grep") {
+    const matches = result?.details?.results?.length ?? countMatchLines(out);
+    return `${matches} match${matches === 1 ? "" : "es"}`;
+  }
+  if (name === "glob") {
+    const matches = Array.isArray(result?.details?.matches) ? result.details.matches.length : countNonEmptyLines(out);
+    return `${matches} file${matches === 1 ? "" : "s"}`;
+  }
+  if (name === "find") {
+    const matches = result?.details?.count ?? countNonEmptyLines(out);
+    return `${matches} file${matches === 1 ? "" : "s"}`;
+  }
+  if (name === "memory_open") {
+    return compactText(result?.details?.entry?.name ?? compactPath(result?.details?.path ?? ""));
+  }
+  return "";
+}
+
+function joinToolParts(icon, name, parts) {
+  const clean = parts.map((part) => String(part ?? "").trim()).filter(Boolean);
+  return `${icon} ${name}${clean.length ? ` · ${clean.join(" · ")}` : ""}`;
+}
+
+function formatReadRange(args = {}) {
+  if (args.offset == null && args.limit == null) return "";
+  if (args.offset != null && args.limit != null) return `lines ${args.offset}-${Number(args.offset) + Number(args.limit) - 1}`;
+  if (args.offset != null) return `from line ${args.offset}`;
+  return `limit ${args.limit}`;
+}
+
+function formatTerminalSendAction(args = {}) {
+  const hasText = typeof args.text === "string" && args.text.length > 0;
+  const key = args.key ? String(args.key) : "";
+  if (hasText && key) return `text+${key}`;
+  if (hasText) return args.text.includes("\n") || args.text.includes("\r") ? "text+enter" : "text";
+  return key || "send";
+}
+
+function formatTerminalDetails(args = {}) {
+  const details = [];
+  if (args.pattern) details.push(quoteCompact(args.pattern));
+  if (args.cols && args.rows) details.push(`${args.cols}x${args.rows}`);
+  if (args.command) details.push(compactText(args.command));
+  return details.join(" · ");
+}
+
+function formatSmallOptions(args = {}) {
+  const parts = [];
+  for (const [key, value] of Object.entries(args ?? {})) {
+    if (value == null || typeof value === "object") continue;
+    parts.push(`${key}=${compactText(value)}`);
+    if (parts.length >= 2) break;
+  }
+  return parts.join(", ");
+}
+
+function compactPath(path) {
+  return String(path ?? "").split(/[/\\]/).filter(Boolean).slice(-4).join("\\");
+}
+
+function quoteCompact(value) {
+  return JSON.stringify(compactText(value));
+}
+
+function compactText(value, limit = 80) {
+  const text = String(value ?? "").replace(/\s+/g, " ").trim();
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+}
+
+function countMatchLines(text) {
+  const match = String(text ?? "").match(/(\d+)\s+matches?\b/i);
+  if (match) return Number(match[1]);
+  return countNonEmptyLines(text);
+}
+
+function countNonEmptyLines(text) {
+  return String(text ?? "").split("\n").filter(Boolean).length;
+}

package/src/agent/tools.mjs

@@ -1,58 +1,58 @@
-import { createCommandExecTool } from "./command-exec-tool.mjs";
-import { createContextStatsTool } from "./context-stats-tool.mjs";
-import { createEditFileTool } from "./file-edit-tool.mjs";
-import { createReadFileTool } from "./file-tools/read-file-tool.mjs";
-import { createReadImageTool } from "./file-tools/read-image-tool.mjs";
-import { createScreenTool } from "./screen-tools/screen-tool.mjs";
-import { createListWindowsTool } from "./screen-tools/list-windows-tool.mjs";
-import { toolText } from "./tool-result.mjs";
-import { createShellTools } from "../shell/tools.mjs";
-import { initImageGen } from "../image-gen/index.mjs";
-import { createSuperGrokTool } from "../supergrok/tool.mjs";
-
-export function createMarchCustomTools({ cwd, engine, ui, memoryTools = [], shellRuntime = null, lspService = null, mcpTools = [], webTools = [], permissionController = null, authStorage = null, projectMarchDir = null, getCurrentModel = null }) {
-  const commandExecTool = createCommandExecTool({ cwd });
-  const contextStatsTool = createContextStatsTool({ engine });
-  const editFileTool = createEditFileTool({ engine, ui, lspService });
-  const readFileTool = createReadFileTool({ engine });
-  const readImageTool = createReadImageTool({ engine, getCurrentModel });
-  const screenTool = createScreenTool({ getCurrentModel });
-  const listWindowsTool = createListWindowsTool();
-
-  const tools = [
-    readFileTool,
-    readImageTool,
-    screenTool,
-    listWindowsTool,
-    contextStatsTool,
-    commandExecTool,
-    editFileTool,
-    ...createShellTools(shellRuntime),
-    ...memoryTools,
-    ...mcpTools,
-    ...webTools,
-    ...(authStorage ? [createSuperGrokTool({ authStorage, projectMarchDir })] : []),
-    ...(authStorage ? initImageGen({ authStorage, projectMarchDir }) : []),
-  ];
-
-  if (!permissionController) return tools;
-
-  return tools.map((tool) => {
-    const execute = tool.execute;
-    if (!execute) return tool;
-    const wrapped = async (toolCallId, params, signal, onUpdate) => {
-      const decision = await permissionController.requestApproval(
-        tool.name,
-        params,
-        ui.requestPermission
-          ? (ctx) => ui.requestPermission(ctx)
-          : null,
-      );
-      if (decision.behavior === "deny") {
-        return toolText(`Permission denied: ${decision.message}`, { error: true, permissionDenied: true });
-      }
-      return execute(toolCallId, params, signal, onUpdate);
-    };
-    return { ...tool, execute: wrapped };
-  });
-}
+import { createCommandExecTool } from "./command-exec-tool.mjs";
+import { createContextStatsTool } from "./context-stats-tool.mjs";
+import { createEditFileTool } from "./file-edit-tool.mjs";
+import { createReadFileTool } from "./file-tools/read-file-tool.mjs";
+import { createReadImageTool } from "./file-tools/read-image-tool.mjs";
+import { createScreenTool } from "./screen-tools/screen-tool.mjs";
+import { createListWindowsTool } from "./screen-tools/list-windows-tool.mjs";
+import { toolText } from "./tool-result.mjs";
+import { createShellTools } from "../shell/tools.mjs";
+import { initImageGen } from "../image-gen/index.mjs";
+import { createSuperGrokTool } from "../supergrok/tool.mjs";
+
+export function createMarchCustomTools({ cwd, engine, ui, memoryTools = [], shellRuntime = null, lspService = null, mcpTools = [], webTools = [], permissionController = null, authStorage = null, projectMarchDir = null, getCurrentModel = null }) {
+  const commandExecTool = createCommandExecTool({ cwd });
+  const contextStatsTool = createContextStatsTool({ engine });
+  const editFileTool = createEditFileTool({ engine, ui, lspService });
+  const readFileTool = createReadFileTool({ engine });
+  const readImageTool = createReadImageTool({ engine, getCurrentModel });
+  const screenTool = createScreenTool({ getCurrentModel });
+  const listWindowsTool = createListWindowsTool();
+
+  const tools = [
+    readFileTool,
+    readImageTool,
+    screenTool,
+    listWindowsTool,
+    contextStatsTool,
+    commandExecTool,
+    editFileTool,
+    ...createShellTools(shellRuntime),
+    ...memoryTools,
+    ...mcpTools,
+    ...webTools,
+    ...(authStorage ? [createSuperGrokTool({ authStorage, projectMarchDir })] : []),
+    ...(authStorage ? initImageGen({ authStorage, projectMarchDir }) : []),
+  ];
+
+  if (!permissionController) return tools;
+
+  return tools.map((tool) => {
+    const execute = tool.execute;
+    if (!execute) return tool;
+    const wrapped = async (toolCallId, params, signal, onUpdate) => {
+      const decision = await permissionController.requestApproval(
+        tool.name,
+        params,
+        ui.requestPermission
+          ? (ctx) => ui.requestPermission(ctx)
+          : null,
+      );
+      if (decision.behavior === "deny") {
+        return toolText(`Permission denied: ${decision.message}`, { error: true, permissionDenied: true });
+      }
+      return execute(toolCallId, params, signal, onUpdate);
+    };
+    return { ...tool, execute: wrapped };
+  });
+}

package/src/agent/turn/turn-events.mjs

@@ -1,111 +1,111 @@
-import { formatToolStartLine, formatToolSuccessSummary } from "../tool-summary.mjs";
-
-export function createTurnEventState() {
-  return {
-    draft: "",
-    thinkingText: "",
-    thinkingAccumulator: "",
-    recallCursor: { draftLength: 0, thinkingLength: 0 },
-    assistantReplyOpen: false,
-    assistantContextParts: [],
-    activeToolContextPart: null,
-  };
-}
-
-export function handleRunnerSessionEvent(event, { ui, engine, state }) {
-  if (event.type === "message_update" && event.assistantMessageEvent) {
-    handleAssistantMessageEvent(event.assistantMessageEvent, { ui, state });
-  }
-  if (event.type === "tool_execution_start") {
-    closeAssistantReply({ ui, state });
-    appendToolStartContext(state, event.toolName, event.args);
-    ui.toolStart(event.toolName, event.args);
-  }
-  if (event.type === "tool_execution_end") {
-    updateToolEndContext(state, event.toolName, event.isError, event.result);
-    ui.toolEnd(event.toolName, event.isError, event.result);
-  }
-  if (event.type === "auto_retry_start") {
-    ui.retryStart?.({
-      attempt: event.attempt,
-      maxAttempts: event.maxAttempts,
-      delayMs: event.delayMs,
-      errorMessage: event.errorMessage,
-    });
-  }
-  if (event.type === "auto_retry_end") {
-    ui.retryEnd?.({
-      success: event.success,
-      attempt: event.attempt,
-      finalError: event.finalError,
-    });
-  }
-}
-
-export function closeAssistantReply({ ui, state }) {
-  if (!state.assistantReplyOpen) return;
-  ui.assistantReplyEnd?.();
-  state.assistantReplyOpen = false;
-}
-
-function handleAssistantMessageEvent(event, { ui, state }) {
-  if (event.type === "text_delta") {
-    state.draft += event.delta;
-    appendAssistantContextText(state, event.delta, "output");
-    state.assistantReplyOpen = true;
-    ui.textDelta(event.delta);
-  }
-  if (event.type === "thinking_start") {
-    state.thinkingText = "";
-    ui.thinkingStart();
-  }
-  if (event.type === "thinking_delta") {
-    state.thinkingText += event.delta;
-    appendAssistantContextText(state, event.delta, "thinking");
-    ui.thinkingDelta(event.delta);
-  }
-  if (event.type === "thinking_end" && state.thinkingText) {
-    const tokens = Math.round(state.thinkingText.length / 4);
-    ui.thinkingEnd(tokens);
-    state.thinkingAccumulator += state.thinkingText;
-    state.thinkingText = "";
-  }
-}
-
-export function compactAssistantContext(state) {
-  return (state?.assistantContextParts ?? [])
-    .map((part) => part?.text ?? "")
-    .join("")
-    .replace(/[ \t]+\n/g, "\n")
-    .replace(/\n{3,}/g, "\n\n")
-    .trim();
-}
-
-function appendAssistantContextText(state, text, type) {
-  if (!text) return;
-  const parts = state.assistantContextParts;
-  const last = parts.at(-1);
-  if (last?.type === type) {
-    last.text += text;
-    return;
-  }
-  if (last && !last.text.endsWith("\n")) last.text += "\n";
-  parts.push({ type, text });
-}
-
-function appendToolStartContext(state, name, args) {
-  const parts = state.assistantContextParts;
-  const last = parts.at(-1);
-  if (last && !last.text.endsWith("\n")) last.text += "\n";
-  const part = { type: "tool", name, text: `${formatToolStartLine(name, args)}\n` };
-  parts.push(part);
-  state.activeToolContextPart = part;
-}
-
-function updateToolEndContext(state, name, isError, result) {
-  const part = state.activeToolContextPart;
-  if (!part || part.name !== name) return;
-  const summary = isError ? "failed" : formatToolSuccessSummary(name, result, "");
-  if (summary && summary !== "done") part.text = `${part.text.trimEnd()} (${summary})\n`;
-  state.activeToolContextPart = null;
-}
+import { formatToolStartLine, formatToolSuccessSummary } from "../tool-summary.mjs";
+
+export function createTurnEventState() {
+  return {
+    draft: "",
+    thinkingText: "",
+    thinkingAccumulator: "",
+    recallCursor: { draftLength: 0, thinkingLength: 0 },
+    assistantReplyOpen: false,
+    assistantContextParts: [],
+    activeToolContextPart: null,
+  };
+}
+
+export function handleRunnerSessionEvent(event, { ui, engine, state }) {
+  if (event.type === "message_update" && event.assistantMessageEvent) {
+    handleAssistantMessageEvent(event.assistantMessageEvent, { ui, state });
+  }
+  if (event.type === "tool_execution_start") {
+    closeAssistantReply({ ui, state });
+    appendToolStartContext(state, event.toolName, event.args);
+    ui.toolStart(event.toolName, event.args);
+  }
+  if (event.type === "tool_execution_end") {
+    updateToolEndContext(state, event.toolName, event.isError, event.result);
+    ui.toolEnd(event.toolName, event.isError, event.result);
+  }
+  if (event.type === "auto_retry_start") {
+    ui.retryStart?.({
+      attempt: event.attempt,
+      maxAttempts: event.maxAttempts,
+      delayMs: event.delayMs,
+      errorMessage: event.errorMessage,
+    });
+  }
+  if (event.type === "auto_retry_end") {
+    ui.retryEnd?.({
+      success: event.success,
+      attempt: event.attempt,
+      finalError: event.finalError,
+    });
+  }
+}
+
+export function closeAssistantReply({ ui, state }) {
+  if (!state.assistantReplyOpen) return;
+  ui.assistantReplyEnd?.();
+  state.assistantReplyOpen = false;
+}
+
+function handleAssistantMessageEvent(event, { ui, state }) {
+  if (event.type === "text_delta") {
+    state.draft += event.delta;
+    appendAssistantContextText(state, event.delta, "output");
+    state.assistantReplyOpen = true;
+    ui.textDelta(event.delta);
+  }
+  if (event.type === "thinking_start") {
+    state.thinkingText = "";
+    ui.thinkingStart();
+  }
+  if (event.type === "thinking_delta") {
+    state.thinkingText += event.delta;
+    appendAssistantContextText(state, event.delta, "thinking");
+    ui.thinkingDelta(event.delta);
+  }
+  if (event.type === "thinking_end" && state.thinkingText) {
+    const tokens = Math.round(state.thinkingText.length / 4);
+    ui.thinkingEnd(tokens);
+    state.thinkingAccumulator += state.thinkingText;
+    state.thinkingText = "";
+  }
+}
+
+export function compactAssistantContext(state) {
+  return (state?.assistantContextParts ?? [])
+    .map((part) => part?.text ?? "")
+    .join("")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function appendAssistantContextText(state, text, type) {
+  if (!text) return;
+  const parts = state.assistantContextParts;
+  const last = parts.at(-1);
+  if (last?.type === type) {
+    last.text += text;
+    return;
+  }
+  if (last && !last.text.endsWith("\n")) last.text += "\n";
+  parts.push({ type, text });
+}
+
+function appendToolStartContext(state, name, args) {
+  const parts = state.assistantContextParts;
+  const last = parts.at(-1);
+  if (last && !last.text.endsWith("\n")) last.text += "\n";
+  const part = { type: "tool", name, text: `${formatToolStartLine(name, args)}\n` };
+  parts.push(part);
+  state.activeToolContextPart = part;
+}
+
+function updateToolEndContext(state, name, isError, result) {
+  const part = state.activeToolContextPart;
+  if (!part || part.name !== name) return;
+  const summary = isError ? "failed" : formatToolSuccessSummary(name, result, "");
+  if (summary && summary !== "done") part.text = `${part.text.trimEnd()} (${summary})\n`;
+  state.activeToolContextPart = null;
+}

package/src/agent/turn/turn-logging.mjs

@@ -1,30 +1,30 @@
-import { createHeartbeat, formatError } from "../../debug/logger.mjs";
-
-export function beginLoggedTurn({ logger, engine, modelId, provider, contextMode, userMessage, userRecallHints, startedAt = Date.now() } = {}) {
-  const turnId = `${startedAt.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
-  let phase = "starting";
-  const turnLogger = logger?.child?.({ turnId, sessionName: engine?.sessionName, modelId, provider });
-  const heartbeat = createHeartbeat({
-    logger: turnLogger,
-    event: "turn.heartbeat",
-    getFields: () => ({ phase, elapsedMs: Date.now() - startedAt }),
-  });
-  turnLogger?.event("turn.start", {
-    userMessageLength: String(userMessage ?? "").length,
-    contextMode,
-    userRecallHintCount: userRecallHints?.length ?? 0,
-  });
-  return {
-    turnId,
-    logger: turnLogger,
-    setPhase(value) { phase = value; },
-    endSuccess(result) {
-      heartbeat.stop();
-      turnLogger?.event("turn.end", { status: "success", durationMs: Date.now() - startedAt, draftLength: result?.draft?.length ?? 0 });
-    },
-    endError(err) {
-      heartbeat.stop();
-      turnLogger?.error("turn.error", { durationMs: Date.now() - startedAt, phase, error: formatError(err) });
-    },
-  };
-}
+import { createHeartbeat, formatError } from "../../debug/logger.mjs";
+
+export function beginLoggedTurn({ logger, engine, modelId, provider, contextMode, userMessage, userRecallHints, startedAt = Date.now() } = {}) {
+  const turnId = `${startedAt.toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  let phase = "starting";
+  const turnLogger = logger?.child?.({ turnId, sessionName: engine?.sessionName, modelId, provider });
+  const heartbeat = createHeartbeat({
+    logger: turnLogger,
+    event: "turn.heartbeat",
+    getFields: () => ({ phase, elapsedMs: Date.now() - startedAt }),
+  });
+  turnLogger?.event("turn.start", {
+    userMessageLength: String(userMessage ?? "").length,
+    contextMode,
+    userRecallHintCount: userRecallHints?.length ?? 0,
+  });
+  return {
+    turnId,
+    logger: turnLogger,
+    setPhase(value) { phase = value; },
+    endSuccess(result) {
+      heartbeat.stop();
+      turnLogger?.event("turn.end", { status: "success", durationMs: Date.now() - startedAt, draftLength: result?.draft?.length ?? 0 });
+    },
+    endError(err) {
+      heartbeat.stop();
+      turnLogger?.error("turn.error", { durationMs: Date.now() - startedAt, phase, error: formatError(err) });
+    },
+  };
+}