mindweave 2.5.1 → 3.0.0

package/dist/core/turnRunner.js

@@ -10,19 +10,35 @@
  * so a tool call reads the same way in every surface) with no Ink, no pacing, no
  * terminal assumptions. A GUI or a server can drive a session with just this file.
  */
-import { respond } from "../dynamo/engine.js";
+import { compactNow, respond } from "../dynamo/engine.js";
+import { startMarathon, resumeMarathon, clearMarathon, describeMarathonEvent, verifyGoal, } from "../dynamo/marathon.js";
+export { clearMarathon, describeMarathonEvent, MAX_MARATHON_VERIFY_FAILS } from "../dynamo/marathon.js";
+/** How full the context is against the auto-compaction bar, for a context meter. */
+export { contextFill } from "../dynamo/engine.js";
 import { createSession, resumeSession, reloadProjectMemory } from "../memory/session.js";
 import { saveSession, listSessions as listSessionsRaw } from "../memory/store.js";
-import { toolDisplay, isGroupable } from "../cli/toolDisplay.js";
-import { accessRefusal, providerOutage } from "../drivers/providerError.js";
+import { toolDisplay, isGroupable, narrationShown, noteReads } from "../cli/toolDisplay.js";
+import { accessRefusal, providerOutage, statusOf } from "../drivers/providerError.js";
+import { failoverKey, noteKeyWorked } from "./providerKeys.js";
 import { providerOf, modelLabel, refreshModels, DISCOVERY_TTL_MS, withModel, saveModelConfig, thinkLevels, thinkLabel } from "../dynamo/model.js";
 import { allProviders, modelsOf } from "../drivers/registry.js";
 import { errText } from "../tools/editTarget.js";
 import { loadConfig, hasApiKey, saveApiKey, removeApiKey } from "../cli/bootstrap.js";
 import { describeImage, isRejection } from "../memory/images.js";
-import { stat } from "node:fs/promises";
+import { resolveAttachments, stripAttachments, attachedFiles, hideAttachedNames } from "../cli/attachments.js";
+export { attachedFiles, hideAttachedNames } from "../cli/attachments.js";
+import { isRewindPoint } from "../memory/rewind.js";
+export { rewindPoints, rewindTo, pasteSlot } from "../memory/rewind.js";
+import { wrapPastedText, collapsePastes } from "../memory/pastedText.js";
+import { manifestForModel } from "../drivers/registry.js";
+import { stat, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { NOTES_FILE } from "../memory/projectNotes.js";
+import { writeFileAtomic } from "../tools/atomicWrite.js";
 import { RECAP_STUB } from "../memory/compaction.js";
 import { stopChassis } from "../alternator/lane.js";
+import { stopUi } from "../tools/ui.js";
+import { runCommand } from "../tools/runCommand.js";
 import { APPROVAL_TEXT, APPROVAL_DISMISSED } from "../tools/approval.js";
 import { MODES, DEFAULT_MODE, modeById, modeFromFlags } from "../cli/modes.js";
 /**
@@ -38,12 +54,73 @@ export { MODES, DEFAULT_MODE, modeById, modeFromFlags };
  * resolve to `APPROVAL_DISMISSED` exactly, never an empty string or a thrown error.
  */
 export { APPROVAL_TEXT, APPROVAL_DISMISSED };
+/** The typed-answer row exit_plan offers. A front end compares against it to know an
+ *  approval is a PLAN (shown in full) rather than a question, without matching prose. */
+export { PLAN_FEEDBACK } from "../tools/exitPlan.js";
+/** The user's machine-wide profile (what to call them), shared with the CLI. */
+export { readProfile, saveProfile } from "../memory/profile.js";
+/** Feedback to the maintainer: the CLI's /feedback, same payload, same checks. */
+export { buildFeedback, refuseReason, sendFeedback, ISSUES_URL, MAX_MESSAGE } from "../cli/feedback.js";
+/** The anonymous usage count: the same id, on/off flag and ping the CLI uses. */
+export { analyticsEnabled, setAnalyticsEnabled, sendAnalyticsPing } from "../cli/analytics.js";
+export { appVersion } from "../cli/version.js";
+/** Permissions: protected files, blocked commands and MCP tools, Sentinel allowances,
+ *  default mode — per project or for every project. */
+export { permissionsView, addPermission, removePermission, movePermission, revokeSessionGrant, setDefaultMode, defaultModeFor, } from "./permissions.js";
+/** The user's own auto-compaction bar: this project's, all-projects', or Mindweave's
+ *  own model-anchored default (with a one-line reason why it's what it is). */
+export { contextView, contextRecommendationFor, setContextOverride, resetContextOverride, CONTEXT_PRESETS, CONTEXT_MIN_TOKENS, } from "./contextSettings.js";
+/** Tokens spent so far, across every project this machine has state for — by model
+ *  and by day/week/month. Read-only; tokens only, no dollar figure. */
+export { spendView } from "./spendView.js";
+export { limitsView, saveLimitsFromPanel, analyzeForPanel } from "./limitsView.js";
+/** Rules and skills as files, for this project or all projects. */
+export { listRulesSkills, readRuleSkill, saveRuleSkill, createRuleSkill, deleteRuleSkill, moveRuleSkill, importRuleSkill, } from "./rulesSkills.js";
+/** MCP servers: list, add/edit, remove, enable/disable, reconnect, sign in/out. */
+export { listMcpServers, mcpServerDetail, saveMcpServer, removeMcpServer, setMcpServerDisabled, reconnectMcpServer, signInMcpServer, signOutMcpServer, allowChangedMcpTools, onMcpChange, } from "./mcpServers.js";
+/** Several keys per provider: add, edit, name, switch off, make default, auto-switch. */
+export { providerKeys, addProviderKey, editProviderKey, removeProviderKey, useProviderKey, makeDefaultProviderKey, renameProviderKey, setProviderKeyDisabled, setProviderAutoSwitch, } from "./providerKeys.js";
 /**
  * Load the API key(s) into process.env — the same global `~/.mindweave/.env` /
  * project `.env` / shell-env layering the CLI uses (see cli/bootstrap.ts). Call
  * this once, at startup, before the first `startSession`.
  */
 export { loadConfig };
+/**
+ * One provider's models with what each costs and can do, for a detail screen. Read from
+ * the same manifests the engine bills and routes by, so the screen can never show a
+ * price the cost math does not use. Null for an unknown provider id.
+ */
+export function providerDetail(id) {
+    const p = allProviders().find((m) => m.id === id);
+    if (!p)
+        return null;
+    return {
+        id: p.id,
+        label: p.label,
+        apiKeyEnv: p.apiKeyEnv,
+        keysUrl: p.keysUrl,
+        connected: hasApiKey(p.apiKeyEnv),
+        local: !!p.local,
+        models: modelsOf(p).map((m) => {
+            const manifest = manifestForModel(m.id);
+            const price = manifest.price(m.id);
+            return {
+                id: m.id,
+                label: m.label,
+                description: m.description,
+                price: {
+                    input: price.cacheMiss,
+                    output: price.output,
+                    cacheRead: price.cacheHit,
+                    cacheWrite: price.cacheWrite ?? null,
+                },
+                acceptsImages: manifest.acceptsImages?.(m.id) ?? false,
+                thinks: manifest.thinkLevels(m.id).some((l) => l.thinking),
+            };
+        }),
+    };
+}
 /**
  * Every installed provider — the real registry (drivers/registry.ts), not a
  * decorative list — with whether a key is already on file for it and the
@@ -57,6 +134,7 @@ export function providerSummaries() {
         apiKeyEnv: p.apiKeyEnv,
         keysUrl: p.keysUrl,
         connected: hasApiKey(p.apiKeyEnv),
+        local: !!p.local,
         models: modelsOf(p).map((m) => ({ id: m.id, label: m.label, description: m.description })),
     }));
 }
@@ -164,31 +242,59 @@ function splitExpiredImages(content) {
  */
 export function replayHistory(session) {
     const calls = new Map();
+    const readThisTurn = new Set(); // for narrationShown, as live
     const out = [];
-    for (const entry of session.transcript) {
+    // What compaction took out comes first, so the chat shows the whole conversation.
+    // None of it can be rewound to: it is no longer part of the conversation.
+    const earlier = new Set(session.earlier ?? []);
+    for (const entry of [...earlier, ...session.transcript]) {
         if (entry.role === "user") {
             if (!entry.synthetic)
-                out.push({ type: "userMessage", ...splitExpiredImages(entry.content) });
+                readThisTurn.clear();
+            // Shown as typed: file bodies hidden and pastes collapsed, the same as it looked live.
+            if (!entry.synthetic) {
+                const paths = (entry.images ?? []).map((i) => i.path);
+                const files = attachedFiles(entry.content, session.cwd);
+                const shown = splitExpiredImages(displayText(entry.content));
+                out.push({
+                    ...shown,
+                    type: "userMessage",
+                    text: hideAttachedNames(shown.text, [...paths, ...files]),
+                    ...(paths.length ? { images: paths } : {}),
+                    ...(files.length ? { files } : {}),
+                    // Typed mid-turn, or from before messages were stamped: nothing to go back to.
+                    ...(isRewindPoint(entry) && !earlier.has(entry) ? {} : { noRewind: true }),
+                });
+            }
         }
         else if (entry.role === "assistant") {
+            // Words that led only to unseen tools were left out live, and are left out here too.
+            const stepCalls = (entry.toolCalls ?? []).map((c) => ({ name: c.name, args: safeParseArgs(c.arguments) }));
+            const shown = stepCalls.length === 0 || narrationShown(stepCalls, readThisTurn);
+            noteReads(stepCalls, readThisTurn);
             // RECAP_STUB is compaction's note to the MODEL that an old status reply was
             // condensed; it is not something the agent said, so it is never shown.
-            if (entry.content.trim() && entry.content !== RECAP_STUB)
+            if (shown && entry.content.trim() && entry.content !== RECAP_STUB)
                 out.push({ type: "assistantMessage", text: entry.content });
             for (const call of entry.toolCalls ?? [])
                 calls.set(call.id, call);
         }
         else if (entry.role === "tool") {
             const call = calls.get(entry.toolCallId);
-            if (entry.quiet)
+            // Quiet results, and loading a tool even from sessions saved before it was quiet. A search
+            // is quiet too, but it is still replayed (marked quiet): a front end may list what was searched.
+            if (call?.name === "find_tools")
+                continue;
+            if (entry.quiet && call?.name !== "search")
                 continue;
             // The same display name a live toolStart carries ("Run", "Read"), not the raw
             // tool id — a reopened session was showing `run_command` where the live one said Run.
             let name = entry.displayName ?? call?.name ?? "tool";
             let arg;
             let kind = entry.displayKind ?? "meta";
+            const callArgs = call ? safeParseArgs(call.arguments) : undefined;
             if (call) {
-                const d = toolDisplay(call.name, safeParseArgs(call.arguments));
+                const d = toolDisplay(call.name, callArgs ?? {});
                 if (!entry.displayName)
                     name = d.name;
                 arg = d.arg;
@@ -198,12 +304,17 @@ export function replayHistory(session) {
             out.push({
                 type: "toolReplay",
                 name,
+                ...(call ? { tool: call.name, args: clipArgs(callArgs) } : {}),
                 arg,
                 kind,
                 ok: !entry.isError,
                 summary: entry.summary ?? entry.content,
                 detail: entry.detail,
                 detailKind: entry.detailKind,
+                ...(entry.imagePaths?.length ? { images: entry.imagePaths } : {}),
+                ...(entry.web ? { web: entry.web } : {}),
+                ...(entry.ui ? { ui: entry.ui } : {}),
+                ...(entry.quiet ? { quiet: true } : {}),
             });
         }
         else if (entry.role === "summary") {
@@ -256,6 +367,20 @@ export function attachHandlers(session, handlers) {
         session.toolContext.interrupt = handlers.interrupt;
     if (handlers.onModeChange)
         session.toolContext.onModeChange = handlers.onModeChange;
+    if (handlers.onLive)
+        session.toolContext.onLive = handlers.onLive;
+}
+/**
+ * Esc: stop everything the agent has running. The caller aborts the turn itself; this
+ * stops what outlives a turn: every background command (and so any app one launched)
+ * and the app being tested with its live view. Background commands are stopped as by
+ * the USER, so the model is told they were stopped rather than woken to restart them.
+ */
+export async function stopEverything(session) {
+    const mgr = session.toolContext.backgroundShells;
+    for (const sh of mgr?.running() ?? [])
+        mgr?.kill(sh.id, "user");
+    await stopUi(session.toolContext);
 }
 /** The mode a session's CURRENT flags amount to — read after load, or after
  *  `onModeChange` fires, to show the UI what's actually active. */
@@ -282,13 +407,78 @@ export function applySessionMode(session, id) {
  */
 export async function runTurn(session, message, handlers) {
     await reloadProjectMemory(session).catch(() => { });
-    const images = await resolveImages(message.imagePaths ?? [], handlers.onEvent);
+    const images = [...(message.images ?? []), ...(await resolveImages(message.imagePaths ?? [], handlers.onEvent))];
+    await recordUserMessage(session, message.content, images, message.arrival);
+    await streamTurn(session, handlers);
+}
+/**
+ * Adds the user's message to the conversation and writes it to disk at once, before any model
+ * call. The first save of a turn used to come after the model's first step, so a kill or a crash
+ * during a slow first answer lost the message the user had just sent.
+ */
+export async function recordUserMessage(session, content, images = [], arrival) {
     session.transcript.push({
         role: "user",
-        content: message.content,
+        content,
+        // Sent by stopping the turn that was running (the app's "Send now"): the model is
+        // told it was stopped on purpose, as the CLI tells it after Esc.
+        ...(arrival ? { arrival } : {}),
         ...(images.length > 0 ? { images } : {}),
     });
-    await streamTurn(session, handlers);
+    await saveSession(session);
+}
+/**
+ * A reply that was being written when the app died. A front end that kept the streamed words
+ * hands them here on the next start; they join the conversation, marked as cut off, so the
+ * user (and the model) can see what had been said. Nothing is added if a saved reply already
+ * holds those words: the kill may have come just after the step was saved.
+ */
+export async function appendInterruptedReply(session, text) {
+    const words = text.trim();
+    if (!words)
+        return false;
+    const recent = session.transcript.slice(-4).filter((e) => e.role === "assistant" && typeof e.content === "string").map((e) => e.content.trim());
+    if (recent.some((c) => c && (c.includes(words.slice(0, 160)) || words.startsWith(c))))
+        return false;
+    session.transcript.push({ role: "assistant", content: `${words}\n\n(interrupted)` });
+    await saveSession(session);
+    return true;
+}
+/**
+ * What was typed, plus files added through the UI and long pastes, turned into what the
+ * model gets and what the chat shows. Shared by a fresh send and a message queued into a
+ * running turn, so the two can't resolve the same message differently.
+ *
+ * Files go through the CLI's own `resolveAttachments`, exactly as if they had been
+ * dropped into the prompt as quoted paths: images take the vision path when the running
+ * model can see them, text files arrive as `<attached_file>` blocks, binaries are skipped
+ * with a note. Pastes are wrapped with the CLI's `wrapPastedText`. So a message reads the
+ * same to the model whichever front end it was typed in.
+ */
+export async function prepareMessage(session, input, onEvent) {
+    const paths = input.filePaths ?? [];
+    const withPaths = paths.length
+        ? `${input.text}${input.text ? "\n" : ""}${paths.map((p) => `"${p}"`).join(" ")}`
+        : input.text;
+    const model = session.modelConfig.model;
+    const canSee = manifestForModel(model).acceptsImages?.(model) ?? false;
+    const resolved = await resolveAttachments(withPaths, session.cwd, canSee);
+    // Only what went wrong is news; "attached a.ts (+40 lines)" is already on screen as a chip.
+    for (const note of resolved.notes) {
+        if (/^skipped |can't see images/.test(note))
+            onEvent({ type: "activity", line: note, error: true });
+    }
+    const pastes = (input.pastes ?? []).filter((p) => p.trim().length > 0);
+    const content = pastes.length
+        ? `${resolved.modelText}${resolved.modelText ? "\n\n" : ""}${pastes.map(wrapPastedText).join("\n\n")}`
+        : resolved.modelText;
+    const imagePaths = resolved.images.map((i) => i.path);
+    const files = attachedFiles(content, session.cwd);
+    return { content, images: resolved.images, imagePaths, files, displayText: hideAttachedNames(displayText(content), [...imagePaths, ...files]) };
+}
+/** A user message as the chat shows it: attached file bodies hidden, pastes as their chip. */
+function displayText(content) {
+    return collapsePastes(stripAttachments(content));
 }
 /**
  * Continue a session with NO new message — the engine notices what changed on its
@@ -296,6 +486,19 @@ export async function runTurn(session, message, handlers) {
  * CLI's `reactToBackground`: it calls the exact same `streamRespond` a typed message
  * would, just without anything new having been said.
  */
+/**
+ * Compact the conversation now, whatever its size: the app's button, the CLI's /compact.
+ * It sends the same compaction events an automatic one does inside a turn, then saves.
+ */
+export async function compactSession(session, onEvent) {
+    await compactNow(session, {
+        onActivity: (line, opts) => onEvent({ type: "activity", line, error: opts?.error }),
+        onCompaction: (report) => onEvent({ type: "compaction", before: report.before, after: report.after, window: report.window }),
+        onCompactionStart: () => onEvent({ type: "compactionStart" }),
+        onCompactionEnd: () => onEvent({ type: "compactionEnd" }),
+    });
+    await saveSession(session);
+}
 export function continueTurn(session, handlers) {
     return streamTurn(session, handlers);
 }
@@ -303,64 +506,254 @@ export function continueTurn(session, handlers) {
  *  boolean out, no Ink involved — so a caller can reuse the exact same rule for when a
  *  finished background command is worth waking the model for. */
 export { shouldReactToBackground } from "../cli/backgroundWake.js";
+/** A tool call's arguments for display: long strings (a whole file being written) are cut, since a front end
+ *  that wants the file reads it from disk. */
+const ARG_TEXT_MAX = 2000;
+export function clipArgs(args) {
+    const clip = (v) => typeof v === "string" ? (v.length > ARG_TEXT_MAX ? v.slice(0, ARG_TEXT_MAX) : v)
+        : Array.isArray(v) ? v.map(clip)
+            : v && typeof v === "object" ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, clip(x)]))
+                : v;
+    return clip(args ?? {});
+}
+/**
+ * One engine event, as the plain TurnEvent a front end draws. Shared by an ordinary turn
+ * and a Marathon run so a tool call, a task list or a token reads identically in both.
+ */
+export function forwardEngineEvent(e, onEvent) {
+    if (e.type === "text") {
+        onEvent({ type: "text", delta: e.delta });
+    }
+    else if (e.type === "reasoning") {
+        onEvent({ type: "reasoning", delta: e.delta });
+    }
+    else if (e.type === "todos") {
+        onEvent({ type: "todos", items: e.items });
+    }
+    else if (e.type === "narration") {
+        onEvent({ type: "narration", shown: e.shown });
+    }
+    else if (e.type === "replyReset") {
+        onEvent({ type: "replyReset" });
+    }
+    else if (e.type === "tool" && e.phase === "start") {
+        // The spawn is rendered by the subagentStart block; loading a tool is never shown.
+        if (e.name === "spawn_subagent" || e.name === "find_tools")
+            return;
+        const d = toolDisplay(e.name, e.args);
+        if (e.agent) {
+            onEvent({ type: "subToolStart", agentId: e.agent, toolId: e.id, name: d.name, arg: d.arg, kind: d.kind });
+        }
+        else {
+            onEvent({ type: "toolStart", id: e.id, name: d.name, arg: d.arg, kind: d.kind, tool: e.name, group: isGroupable(e.name), args: clipArgs(e.args), ...(d.covers ? { covers: d.covers } : {}) });
+        }
+    }
+    else if (e.type === "tool" && e.phase === "end") {
+        if (e.name === "spawn_subagent" || e.name === "find_tools")
+            return;
+        if (e.agent) {
+            onEvent({ type: "subToolEnd", agentId: e.agent, toolId: e.id, ok: !e.error, summary: e.summary });
+        }
+        else {
+            onEvent({ type: "toolEnd", id: e.id, ok: !e.error, summary: e.summary, detail: e.detail, detailFull: e.detailFull, detailKind: e.detailKind, quiet: e.quiet, ...(e.images?.length ? { images: e.images } : {}), ...(e.web ? { web: e.web } : {}), ...(e.ui ? { ui: e.ui } : {}) });
+        }
+    }
+    else if (e.type === "tool" && e.phase === "progress") {
+        // What a call that takes a while is doing meanwhile (the ui tool waiting for an
+        // app to finish building). Latest-wins text, not a log.
+        if (!e.agent)
+            onEvent({ type: "toolProgress", id: e.id, text: e.text });
+    }
+    else if (e.type === "subagent" && e.phase === "start") {
+        onEvent({ type: "subagentStart", id: e.id, task: e.task, readOnly: e.readOnly });
+    }
+    else if (e.type === "subagent" && e.phase === "end") {
+        onEvent({ type: "subagentEnd", id: e.id, ok: !e.error, summary: e.summary });
+    }
+    else if (e.type === "usage") {
+        onEvent({ type: "usage", promptTokens: e.promptTokens, completionTokens: e.completionTokens, totalTokens: e.totalTokens });
+    }
+}
+/**
+ * A key refused for credit, a rate limit or rejection: when the user allowed it, move to
+ * their next key so the caller can carry on from where the turn stopped. A refusal happens
+ * on the status line, before any reply arrived, so nothing is half-written to resume over.
+ * True when it switched; false leaves the error for the caller to report.
+ */
+function tryFailover(session, error, signal, triedKeys, onEvent) {
+    const provider = providerOf(session.modelConfig.model);
+    const status = statusOf(error);
+    if (status === null || signal?.aborted || !accessRefusal(error, provider.label, false))
+        return false;
+    const moved = failoverKey(manifestForModel(session.modelConfig.model).apiKeyEnv, status, triedKeys);
+    if (!moved)
+        return false;
+    const why = moved.reason === "no-credit" ? "is out of credit" : moved.reason === "rate-limited" ? "hit its rate limit" : "was rejected";
+    onEvent({ type: "activity", line: `${provider.label} key ${moved.from} ${why}, switched to ${moved.to}` });
+    return true;
+}
 async function streamTurn(session, handlers) {
     const { onEvent, steer, signal } = handlers;
+    // Keys already refused in THIS turn, so switching can't go round in a circle.
+    const triedKeys = new Set();
+    for (;;) {
+        try {
+            await respond(session, {
+                steer,
+                signal,
+                onActivity: (line, opts) => onEvent({ type: "activity", line, error: opts?.error }),
+                onCompaction: (report) => onEvent({ type: "compaction", before: report.before, after: report.after, window: report.window }),
+                onCompactionStart: () => onEvent({ type: "compactionStart" }),
+                onCompactionEnd: () => onEvent({ type: "compactionEnd" }),
+                onEvent: (e) => forwardEngineEvent(e, onEvent),
+                persist: () => saveSession(session),
+            });
+            noteKeyWorked(manifestForModel(session.modelConfig.model).apiKeyEnv);
+            onEvent({ type: "done" });
+            await saveSession(session);
+            return;
+        }
+        catch (error) {
+            if (tryFailover(session, error, signal, triedKeys, onEvent))
+                continue;
+            reportFailure(session, error, onEvent);
+            onEvent({ type: "done" });
+            await saveSession(session);
+            return;
+        }
+    }
+}
+/** A turn that ended in an error, as a notice (a refusal or an outage the user can act on)
+ *  or a plain error line. */
+function reportFailure(session, error, onEvent) {
+    const refusal = accessRefusal(error, providerOf(session.modelConfig.model).label, false) ??
+        providerOutage(error, providerOf(session.modelConfig.model).label, modelLabel(session.modelConfig.model));
+    if (refusal)
+        onEvent({ type: "notice", title: refusal.title, body: refusal.body });
+    else
+        onEvent({ type: "error", text: errText(error) });
+}
+/**
+ * Run a Marathon for a front end: the same events an ordinary turn streams, plus the
+ * run's own progress and the live task list, with the same key failover and error
+ * reporting. `run` is the start/resume call; `override` swaps the engine calls for a fake
+ * in a test.
+ */
+async function driveMarathon(session, handlers, run, override = {}) {
+    const { onEvent, steer, signal } = handlers;
+    const triedKeys = new Set();
+    const deps = {
+        // Every turn of the run gets the failover an ordinary turn gets.
+        respond: async (s, options) => {
+            for (;;) {
+                try {
+                    return await respond(s, options);
+                }
+                catch (error) {
+                    if (tryFailover(s, error, signal, triedKeys, onEvent))
+                        continue;
+                    throw error;
+                }
+            }
+        },
+        verify: verifyGoal,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        ...override,
+    };
+    let state = null;
     try {
-        await respond(session, {
-            steer,
+        state = await run({
             signal,
+            ...(steer ? { steer } : {}),
+            ...(handlers.limits ? { limits: handlers.limits } : {}),
             onActivity: (line, opts) => onEvent({ type: "activity", line, error: opts?.error }),
             onCompaction: (report) => onEvent({ type: "compaction", before: report.before, after: report.after, window: report.window }),
-            onEvent: (e) => {
-                if (e.type === "text") {
-                    onEvent({ type: "text", delta: e.delta });
-                }
-                else if (e.type === "tool" && e.phase === "start") {
-                    if (e.name === "spawn_subagent")
-                        return; // rendered by the subagentStart block, not a raw row
-                    const d = toolDisplay(e.name, e.args);
-                    if (e.agent) {
-                        onEvent({ type: "subToolStart", agentId: e.agent, toolId: e.id, name: d.name, arg: d.arg, kind: d.kind });
-                    }
-                    else {
-                        onEvent({ type: "toolStart", id: e.id, name: d.name, arg: d.arg, kind: d.kind, group: isGroupable(e.name), ...(d.covers ? { covers: d.covers } : {}) });
-                    }
-                }
-                else if (e.type === "tool" && e.phase === "end") {
-                    if (e.name === "spawn_subagent")
-                        return;
-                    if (e.agent) {
-                        onEvent({ type: "subToolEnd", agentId: e.agent, toolId: e.id, ok: !e.error, summary: e.summary });
-                    }
-                    else {
-                        onEvent({ type: "toolEnd", id: e.id, ok: !e.error, summary: e.summary, detail: e.detail, detailFull: e.detailFull, detailKind: e.detailKind, quiet: e.quiet });
-                    }
-                }
-                else if (e.type === "subagent" && e.phase === "start") {
-                    onEvent({ type: "subagentStart", id: e.id, task: e.task, readOnly: e.readOnly });
-                }
-                else if (e.type === "subagent" && e.phase === "end") {
-                    onEvent({ type: "subagentEnd", id: e.id, ok: !e.error, summary: e.summary });
-                }
-                else if (e.type === "usage") {
-                    onEvent({ type: "usage", promptTokens: e.promptTokens, completionTokens: e.completionTokens, totalTokens: e.totalTokens });
-                }
-            },
+            onCompactionStart: () => onEvent({ type: "compactionStart" }),
+            onCompactionEnd: () => onEvent({ type: "compactionEnd" }),
+            onEvent: (e) => forwardEngineEvent(e, onEvent),
+            onMarathon: (event) => onEvent({ type: "marathon", event, text: describeMarathonEvent(event) }),
             persist: () => saveSession(session),
-        });
-        onEvent({ type: "done" });
+        }, deps);
+        noteKeyWorked(manifestForModel(session.modelConfig.model).apiKeyEnv);
     }
     catch (error) {
-        const refusal = accessRefusal(error, providerOf(session.modelConfig.model).label, false) ??
-            providerOutage(error, providerOf(session.modelConfig.model).label, modelLabel(session.modelConfig.model));
-        if (refusal)
-            onEvent({ type: "notice", title: refusal.title, body: refusal.body });
-        else
-            onEvent({ type: "error", text: errText(error) });
-        onEvent({ type: "done" });
+        // The run stays "running" on the session, so it can be resumed once the cause is fixed.
+        reportFailure(session, error, onEvent);
+    }
+    onEvent({ type: "done" });
+    await saveSession(session);
+    return state;
+}
+/**
+ * Start a Marathon on `goal`: the user armed it and sent their goal. Replaces any
+ * Marathon the session already holds. Resolves when the run reaches an outcome or is
+ * stopped (the same signal that stops a turn); a stopped run stays resumable.
+ */
+export async function startMarathonRun(session, goal, handlers, override) {
+    // Same preparation as the first message of any turn: the project's notes re-read, and
+    // attached images resolved (and rejected loudly) the way `runTurn` does it.
+    const message = typeof goal === "string" ? { content: goal } : goal;
+    await reloadProjectMemory(session).catch(() => { });
+    const goalImages = [
+        ...(("images" in message && message.images) || []),
+        ...(await resolveImages(("imagePaths" in message && message.imagePaths) || [], handlers.onEvent)),
+    ];
+    return driveMarathon(session, handlers, (options, deps) => startMarathon(session, message.content, { ...options, ...(goalImages.length ? { goalImages } : {}) }, deps), override);
+}
+/** Carry on a Marathon that was stopped, or that a restart interrupted. Resolves null
+ *  when there is nothing to resume. */
+export function resumeMarathonRun(session, handlers, override) {
+    return driveMarathon(session, handlers, (options, deps) => resumeMarathon(session, options, deps), override);
+}
+/** Close a Marathon for good: dropped from the session AND from its saved file, so
+ *  reopening the session later does not bring a dismissed run back. */
+export async function dismissMarathon(session) {
+    clearMarathon(session);
+    await saveSession(session);
+}
+/** The session's Marathon, if it has one — running, stopped, or finished. */
+export function marathonOf(session) {
+    return session.marathon ?? null;
+}
+/**
+ * Start a command the USER asked for (the app's Run button) as a background shell, through
+ * the same run_command tool the agent uses, so it lands in the same shell list, the agent
+ * can read its output, and stopping it is the same kill. The click is the approval, so no
+ * gate is asked. `notify: "never"` because the user starting their own app is not an event
+ * to wake the model for. Returns the shell id, or an error message.
+ */
+export async function startUserCommand(session, command, cwd) {
+    // A fresh context: the session's may still carry the last turn's (aborted) signal.
+    // `cwd` is for an app that lives in a subfolder of the project.
+    const ctx = { ...session.toolContext, abortSignal: undefined, cwd: cwd ?? session.toolContext.cwd };
+    // hidden: false because the user pressed Run to see their app, whatever its script says.
+    const result = await runCommand.execute({ command, run_in_background: true, notify: "never", hidden: false }, ctx);
+    const id = /shell #(\d+)/.exec(`${result.summary ?? ""} ${result.output}`)?.[1];
+    if (result.isError || !id)
+        return { error: result.output || "Could not start the command." };
+    return { id: Number(id) };
+}
+/** The project's MINDWEAVE.md (in the project root, the notebook the agent keeps) and
+ *  what it says. A missing file is empty, not an error. */
+export async function readProjectNotes(cwd) {
+    const path = join(cwd, NOTES_FILE);
+    try {
+        const [text, info] = await Promise.all([readFile(path, "utf8"), stat(path)]);
+        return { path, text, exists: true, modifiedAt: info.mtimeMs };
     }
-    finally {
-        await saveSession(session);
+    catch {
+        return { path, text: "", exists: false, modifiedAt: null };
     }
 }
+/**
+ * Replace the project's MINDWEAVE.md, then re-read it into the live session so the NEXT
+ * message already follows it. That costs one prompt-cache rebuild, which is what an edit
+ * the user made on purpose is worth; the model's own mid-session edits keep the cheaper
+ * deferred path.
+ */
+export async function saveProjectNotes(cwd, text, session) {
+    await writeFileAtomic(join(cwd, NOTES_FILE), text);
+    if (session)
+        await reloadProjectMemory(session, { force: true });
+}
 //# sourceMappingURL=turnRunner.js.map