Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++
87.0 KB
Raw Blame
/**
 * The agent bridge: Strata chats as Harness sessions.
 *
 * What it owns
 *   - the pinned Harness process (one, lazily started, restarted only when a route it needs changed);
 *   - the stable Strata-chat -> Harness-session map, persisted next to the host's other state;
 *   - one `session/follow` stream per live turn, projected into the NDJSON frames the chat UI renders;
 *   - approvals: the Harness `approval/request` waterfall in, the user's Approve/Deny back out;
 *   - Stop: `session/cancel` for exactly one session, resolved only once the turn has really ended.
 *
 * What it deliberately does not do
 *   - it never falls back to another model: a chat picks a route (local instance or saved API
 *     connection) and a missing route is a typed error;
 *   - it never implements Stop by killing the Harness (that would cancel every other chat);
 *   - it never holds a secret outside the environment of the agent process it starts.
 */
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { homedir, tmpdir } from 'node:os';
import { fileURLToPath } from 'node:url';
import { randomUUID } from 'node:crypto';
import { GatewayClient } from './gateway-client.mjs';
import { HarnessProcess, resolveHarness, redact, stopStaleAgent } from './harness-runtime.mjs';
import { StatusReporter } from './status.mjs';
import { buildProfile, routeFor, MODE_PRESETS, modeOf, effortOf, localOutputBudget, compactionHeadroom } from './profile.mjs';
import { TurnProjector, parseArguments as parseArgs } from './events.mjs';
import { ChildProjector } from './children.mjs';
import { nearestBudget } from './llm-shape.mjs';
import { DeliverableTracker, ActivityGroups } from './deliverables.mjs';
import { SkillsUsed, skillInfoFrom } from './skills-used.mjs';
import { turnEngineSpeed } from './engine-speed.mjs';
import { TurnGuard, guardNote, GUARD_NOTES } from './turn-guard.mjs';
import { BASE_TOKENS, COUNT_ABOVE_CHARS, FIT_TEXT, countTokens, decideFit, fill, grouped } from './context-fit.mjs';
import { PlanStore, planPrompt, parsePlan, parsePoints, stepObjective, stepLine, firstSentence, stepSummary, planAsPrompt, editedSteps, planView, researchPrompt, researchWritePrompt, RESEARCH_NUDGE, parseSources } from './plan.mjs';

/**
 * A failure the person can read. `message` is a plain sentence with the next step; `details` keeps the technical
 * text for the Details disclosure (experts), already free of secrets.
 */
export class AgentUnavailable extends Error {
  constructor(message, code = 'agent-unavailable', details = null) { super(message); this.name = 'AgentUnavailable'; this.code = code; this.details = details; }
}

/** The plain sentence for a raw agent failure text, whatever produced it. */
export function plainAgentFailure(raw) {
  const text = String(raw ?? '');
  if (/did not print its address|exited during start|could not start|ECONNREFUSED.*127\.0\.0\.1|refused the launch token|socket/i.test(text)) return 'The coding assistant could not start. Try again. If it keeps happening, close and reopen Strata.';
  if (/process stopped|lost the session stream|stream did not open|session stream/i.test(text)) return 'The coding assistant stopped unexpectedly, so this answer is incomplete. Send your message again.';
  if (/did not accept the message/i.test(text)) return 'The coding assistant did not take this message. Send it again in a moment.';
  return text;
}

/**
 * A failure thrown while a turn starts, as `{ message, details, code }` for the chat's error card. The agent's own errors read like
 * `session/create: tool-bash (...): waiting for shell ...` (a plugin chain that never started): never shown raw. The plain sentence
 * goes in `message`; the technical text goes in `details`, which the app shows only behind Details.
 */
export function plainTurnFailure(err) {
  const raw = String(err?.message ?? err ?? '');
  const details = typeof err?.details === 'string' && err.details ? err.details : raw;
  if (err instanceof AgentUnavailable) return { message: err.message, details, code: err.code ?? 'AGENT_ERROR' };
  if (err?.code === 'agent-preset/invalid' || /waiting for (shell|subprocess|ptcRuntime|workflowEngine|sandbox)|failed to import|did not activate/i.test(raw)) {
    return { message: 'The coding assistant is missing a part it needs, so it cannot work on files yet. Close and reopen Strata. If it keeps happening, reinstall Strata. Chatting without tools still works.', details, code: 'AGENT_INCOMPLETE' };
  }
  if (/^[a-z][a-z-]*\/[a-z][a-z-]*: /i.test(raw) || /^(gateway|rpc)/i.test(raw)) {
    return { message: 'The coding assistant could not start this message. Try again. If it keeps happening, close and reopen Strata.', details, code: err?.code ?? 'AGENT_ERROR' };
  }
  return { message: plainAgentFailure(raw), details, code: err?.code ?? 'AGENT_ERROR' };
}

/** The Harness's plugins start one after another: until they are all up, session/create answers "<plugin>: waiting for <service>". */
const STARTING_UP = /waiting for (shell|subprocess|ptcRuntime|workflowEngine|sandbox)/i;

/**
 * Create a Harness session, waiting for its plugins to finish starting. Right after the app opens (or the Harness restarts) the first
 * message can arrive before they are up: that is retried every `retryMs` for up to `readyMs` (`onWait` tells the page "Starting the assistant…")
 * instead of failing the first chat. Any other error is thrown at once; a start that never finishes is a plain AGENT_NOT_READY error
 * with the Harness's text kept for Details. Returns null when `cancelled()` turns true while waiting.
 */
export async function createSessionWhenReady(create, { readyMs = 60_000, retryMs = 1_500, onWait = () => {}, cancelled = () => false, now = Date.now } = {}) {
  const until = now() + readyMs;
  for (;;) {
    try { return await create(); } catch (e) {
      const text = String(e?.message ?? e ?? '');
      if (!STARTING_UP.test(text)) throw e;
      if (now() >= until) throw new AgentUnavailable('The assistant could not start. Try again in a moment.', 'AGENT_NOT_READY', text);
      onWait();
      await new Promise(r => setTimeout(r, retryMs));
      if (cancelled()) return null;
    }
  }
}

/** Attached pictures (data addresses) as the Harness's image prompt parts. */
export function imageParts(images) {
  return (Array.isArray(images) ? images : []).map(i => {
    const m = /^data:(image\/(?:png|jpeg|webp));base64,(.+)$/.exec(String(i?.url ?? ''));
    return m ? { type: 'image', mediaType: m[1], data: m[2], name: String(i.name ?? 'Picture').slice(0, 120) } : null;
  }).filter(Boolean);
}

/** A timer that never keeps the process alive by itself. */
const after = (ms, fn) => { const t = setTimeout(fn, ms); t.unref?.(); return t; };
/** The app's own host folder: never a place an answer's files can be (this file lives in <host>/server/agent). */
const HOST_DIR = fileURLToPath(new URL('../..', import.meta.url));

const deferred = () => { let resolve; const promise = new Promise(r => { resolve = r; }); return { promise, resolve }; };

/**
 * @param {object} options
 * @param {string} options.dataDir                      the host's data directory (agent state lives in `<dataDir>/agent`)
 * @param {string|null} [options.componentsDir]         where installed components live
 * @param {() => Array} options.localInstances          ready local instances (see profile.mjs)
 * @param {() => Array} options.connections             saved API connections WITH their keys (host-internal)
 * @param {() => (string|null)} [options.defaultLocalId]  the local instance the chat runs on: its tool servers are the agent's (T5)
 * @param {NodeJS.ProcessEnv} [options.env]
 * @param {string} [options.nodePath]                   the Node runtime that runs the Harness
 * @param {(line:string)=>void} [options.log]
 */
export function createAgentBridge({ dataDir, componentsDir = null, bundledDir = null, gate = true, localInstances, connections, tools = () => undefined, defaultLocalId = () => null, skillsDir = () => null, onGoal = () => {}, onPlan = () => {}, onQueue = () => {}, proxyBase = null, searchMock = null, expertSampling = () => null, engineProgress = () => null, engineGraceMs = 30 * 60_000, stallMs = 4 * 60_000, stallToolMs = 20 * 60_000, env = process.env, nodePath = process.execPath, log = () => {}, startTimeoutMs = 120_000, sessionReadyMs = 60_000, sessionRetryMs = 1_500 }) {
  const root = join(dataDir, 'agent');
  const home = join(root, 'home');
  const sessionsFile = join(root, 'sessions.json');
  mkdirSync(root, { recursive: true });

  /**
   * Where the turn's file tracker must never look (deliverables.mjs): the app, the engine and its components, Strata's own data, AppData
   * and temp. `forbid` ones also switch tracking off when the chat's folder is one of them or inside one.
   */
  function trackerFolders() {
    const user = env.USERPROFILE ?? env.HOME ?? homedir();
    const forbid = [HOST_DIR, componentsDir, bundledDir].filter(Boolean);
    const exclude = [dataDir, tmpdir(), env.LOCALAPPDATA, env.APPDATA, env.ProgramData, env.ProgramFiles, env['ProgramFiles(x86)'], env.TEMP, env.TMP,
      join(user, 'AppData'), join(user, '.cache'), join(user, '.config'), join(user, '.local'), join(user, 'Library')].filter(Boolean);
    return { forbid, exclude };
  }

  /** chatId -> { sessionId, cwd, createdAt } */
  let sessionMap = {};
  if (existsSync(sessionsFile)) {
    try { sessionMap = JSON.parse(readFileSync(sessionsFile, 'utf8')) ?? {}; } catch { sessionMap = {}; }
  }
  const persist = () => {
    const temp = `${sessionsFile}.${randomUUID()}.tmp`;
    writeFileSync(temp, JSON.stringify(sessionMap, null, 2));
    renameSync(temp, sessionsFile);
  };

  /** @type {{hp:HarnessProcess, gw:GatewayClient, profile:object, clientId:string|null, generation:number, events:object}|null} */
  let rt = null;
  let generation = 0;
  let lastError = null;
  let starting = null;
  const chats = new Map();         // chatId -> { turn, route, routeGeneration }
  const plans = new PlanStore(join(root, 'plans.json'));
  /** chatId -> messages the person typed while a goal ran: [{ id, text, at, deliverAt }]; delivered between steps or when the goal ends */
  const queues = new Map();
  const queueView = chatId => (queues.get(chatId) ?? []).map(({ id, text, at, deliverAt }) => ({ id, text, at, deliverAt }));
  const pending = new Map();       // `${sessionId}:${callId}` -> { eventId, sessionId, callId, at }
  const idleWaiters = new Set();

  const chat = id => { let c = chats.get(id); if (!c) { c = { id, turn: null, route: null, routeGeneration: -1 }; chats.set(id, c); } return c; };
  const activeTurns = () => [...chats.values()].filter(c => c.turn).length;
  const notifyIdle = () => { if (activeTurns() === 0) { for (const w of idleWaiters) w(); idleWaiters.clear(); } };
  const waitIdle = (signal, ms) => new Promise((resolve, reject) => {
    if (activeTurns() === 0) return resolve();
    const timer = setTimeout(() => { idleWaiters.delete(done); reject(new AgentUnavailable('Another chat is still working and the list of models changed. Try again when it finishes.', 'agent-busy')); }, ms);
    const done = () => { clearTimeout(timer); resolve(); };
    idleWaiters.add(done);
    signal?.addEventListener('abort', () => { clearTimeout(timer); idleWaiters.delete(done); reject(signal.reason ?? new Error('aborted')); }, { once: true });
  });

  /** The agent's profile now, plus where its shaped routes really lead (read by the forwarding endpoint). */
  let shapeTargets = {};
  function buildProfileNow() {
    const profile = buildProfile({ local: localInstances(), connections: connections(), gate, tools: tools(), skillsDir: skillsDir(), proxyBase, searchMock, defaultLocalId: defaultLocalId() });
    shapeTargets = profile.shapeTargets ?? {};
    return profile;
  }
  const llmTarget = key => shapeTargets[key] ?? null;

  function harnessInfo() { return resolveHarness({ env, componentsDir, bundledDir }); }
  /** Where the agent component is (the browser tool server lives inside it), or null. */
  const harnessDir = () => { const h = harnessInfo(); return h.ok ? h.dir : null; };

  /** The capability state the app shows. Never carries a token or a key. */
  function status() {
    const h = harnessInfo();
    if (!h.ok) return { state: 'unavailable', reason: 'The coding assistant isn’t installed on this computer yet. Chat works without it.', detail: h.reason, code: 'component-missing' };
    const profile = buildProfileNow();
    return {
      state: rt?.hp.running ? 'ready' : starting ? 'starting' : lastError ? 'error' : 'idle',
      reason: lastError ? plainAgentFailure(lastError) === lastError ? 'The coding assistant could not start. Try again.' : plainAgentFailure(lastError) : null,
      detail: lastError ?? null,
      harness: { version: h.version },
      runtime: rt?.hp.running ? { pid: rt.hp.pid, generation: rt.generation } : null,
      routes: profile.routes.map(({ route, kind, modelId, name, contextWindow }) => ({ route, kind, modelId, name, contextWindow })),
      // tool servers that could not be wired (a name the rule does not allow, no program or address): the chat says so
      skippedServers: profile.mcpSkipped ?? [],
      activeTurns: activeTurns(),
      pendingApprovals: pending.size,
    };
  }

  async function startRuntime(profile) {
    const h = harnessInfo();
    if (!h.ok) throw new AgentUnavailable('The coding assistant isn’t installed on this computer yet. Chat works without it.', 'component-missing', h.reason);
    mkdirSync(home, { recursive: true });
    const stale = stopStaleAgent(join(root, 'harness.pid'));
    if (stale) log(`agent · stopped a leftover Harness process (pid ${stale}) from an earlier run`);
    const patchFile = join(root, `profile-${profile.signature}.patch.yml`);
    writeFileSync(patchFile, profile.patch);
    const workdir = join(root, 'run');
    const hp = new HarnessProcess({
      harness: h, home, patchFile, cwd: workdir, env: profile.env, nodePath, logFile: join(root, 'harness.log'), pidFile: join(root, 'harness.pid'),
      onExit: exit => {
        log(`agent · the Harness process exited (code ${exit.code})`);
        if (rt?.hp === hp) { lastError = 'The agent process stopped.'; rt = null; }
        for (const c of chats.values()) c.turn?.abortFromRuntime('The agent process stopped before this turn finished.');
      },
    });
    const info = await hp.start({ timeoutMs: startTimeoutMs });
    const gw = new GatewayClient({ baseUrl: info.baseUrl, token: info.token });
    await gw.connect();
    const next = { hp, gw, profile, clientId: null, generation: ++generation, events: null };
    next.events = gw.openStream('$events', {}, {
      onItem: value => onHostEvent(next, value),
      onError: e => log(`agent · event stream: ${redact(e.message, Object.values(profile.env))}`),
    });
    rt = next;
    lastError = null;
    log(`agent · Harness ${h.version ?? ''} ready (pid ${hp.pid}, ${profile.routes.length} route(s))`);
    return next;
  }

  /** The local engine's own speed for this turn's requests (null when it cannot be read: the stream's estimate stays). */
  async function engineSpeedOf(route, projector) {
    const inst = localInstances().find(i => i.id === route.instanceId);
    if (!inst) return null;
    return turnEngineSpeed({ baseUrl: inst.baseUrl, key: inst.key, since: projector.startedAt, attempts: projector.streams.size, timeoutMs: 800 });
  }

  /** Make sure a runtime exists that knows the route this turn needs. */
  async function ensureRuntime(choice, signal) {
    for (;;) {
      if (starting) { await starting.catch(() => {}); continue; }
      const profile = buildProfileNow();
      const route = routeFor(profile, choice);
      if (!route) {
        throw new AgentUnavailable(choice?.connectionId
          ? 'This API model is no longer available. Choose another model in the chat picker.'
          : 'No local model is ready for the agent. Load a model in Models, or choose an API model.', 'model-unavailable');
      }
      const known = rt?.hp.running && rt.profile.toolsSignature === profile.toolsSignature && rt.profile.routes.some(r => r.route === route.route && r.modelId === route.modelId && r.fp === route.fp);
      if (known) return { rt, route };
      starting = (async () => {
        if (rt?.hp.running) {
          await waitIdle(signal, 120_000);
          const old = rt; rt = null;
          old.events?.close(); old.gw.close(); await old.hp.stop();
        }
        try { return await startRuntime(profile); } catch (e) {
          lastError = redact(String(e.message ?? e), Object.values(profile.env));
          throw e instanceof AgentUnavailable ? e : new AgentUnavailable(plainAgentFailure(lastError) === lastError ? 'The coding assistant could not start. Try again. If it keeps happening, close and reopen Strata.' : plainAgentFailure(lastError), 'agent-start-failed', lastError);
        }
      })();
      try { await starting; } finally { starting = null; }
    }
  }

  function onHostEvent(runtime, value) {
    if (value.type === 'ready') { runtime.clientId = value.clientId; return; }
    if (value.type === 'waterfall' && value.event === 'approval/request') {
      const r = value.request ?? {};
      if (!r.callId) return;
      pending.set(`${value.agentId}:${r.callId}`, { eventId: value.eventId, sessionId: value.agentId, callId: r.callId, tool: r.toolName, reason: r.reason ?? null, at: Date.now(), clientId: runtime.clientId });
    } else if (value.type === 'waterfall' && value.event === 'user-questions/request') {
      // The app has no surface for the agent's own questions yet. Declaring that nobody can answer makes
      // the tool return an error the model reads and carries on from, instead of a turn that waits forever.
      void runtime.gw.answerEvent({ clientId: runtime.clientId, eventId: value.eventId, outcome: 'next' }).catch(() => {});
    } else if (value.type === 'cancel') {
      for (const [k, v] of pending) if (v.eventId === value.eventId) pending.delete(k);
    }
  }

  async function sessionFor(c, cwd, runtime, { onWait = () => {} } = {}) {
    let known = sessionMap[c.id];
    // The chat's folder changed: the agent's working folder and sandbox are fixed when its session starts, so the chat gets a new session
    // in the new folder (the earlier conversation is carried into its first message, as for any fresh session).
    if (known && cwd && known.cwd && resolve(known.cwd) !== resolve(cwd)) { delete sessionMap[c.id]; persist(); known = null; }
    if (known) return { sessionId: known.sessionId, fresh: false };
    const created = await createSessionWhenReady(() => runtime.gw.rpc('session/create', { request: { cwd } }), { readyMs: sessionReadyMs, retryMs: sessionRetryMs, onWait, cancelled: () => c.cancelStart });
    if (!created) return null;
    sessionMap[c.id] = { sessionId: created.sessionId, cwd, createdAt: new Date().toISOString() };
    persist();
    return { sessionId: created.sessionId, fresh: true };
  }

  /**
   * Put the session into the preset of the chat's mode, through the Harness's own `/permission` command, and
   * check that it took. A turn never starts in a mode other than the one asked for: if the switch cannot be
   * confirmed the turn fails closed with a typed error instead of running with unknown permissions.
   */
  async function applyMode(runtime, sessionId, mode) {
    const want = MODE_PRESETS[mode].key;
    const read = async () => {
      const r = await runtime.gw.rpc('session/projections', { request: { sessionId, keys: ['permissions'] } });
      return r?.values?.permissions?.currentValue ?? null;
    };
    try {
      if (await read() !== want) {
        const done = await runtime.gw.rpc('commands/execute', { agentId: sessionId, line: `/permission ${want}`, submittedAttachments: [] });
        if (done?.result?.kind !== 'success') throw new Error(done?.result?.text ?? 'the agent did not recognise the command');
        const now = await read();
        if (now !== want) throw new Error(`the session reports "${now}" instead of "${want}"`);
      }
    } catch (e) {
      throw new AgentUnavailable(`Strata could not set this chat to ${MODE_PRESETS[mode].name} mode, so nothing ran. Try again.`, 'mode-unavailable', e.message);
    }
    // Manual leaves the sandbox open and relies on the Strata gate to ask first. Without the gate it must not start.
    if (mode === 'manual' && !runtime.gateChecked) {
      try {
        const probe = await runtime.gw.rpc('commands/execute', { agentId: sessionId, line: '/strata-gate', submittedAttachments: [] });
        if (probe?.result?.kind !== 'success' || !String(probe.result.text ?? '').includes('strata-gate active')) throw new Error('the approval gate is not loaded');
        runtime.gateChecked = true;
      } catch (e) {
        throw new AgentUnavailable('Strata could not make sure the coding assistant asks before changing anything, so nothing ran. Close and reopen Strata, then try again.', 'mode-unavailable', e.message);
      }
    }
  }

  /**
   * Run one agent turn for a Strata chat and stream it as frames.
   * `signal` means the client went away: the turn keeps running (that is not Stop).
   */
  async function runTurn(options) {
    const c = chat(options.chatId);
    if (c.turn || c.starting) throw new AgentUnavailable('This chat is still working. Stop it or wait for it to finish.', 'turn-active');
    // From here until the Harness has the prompt, Stop has no session to cancel; it cancels the start.
    c.starting = true; c.cancelStart = false;
    try { return await runTurnInner(c, options); } finally { c.starting = false; }
  }

  async function runTurnInner(c, { chatId, message, workspacePath, choice = null, mode = null, history = [], onFrame, requestId = `req-${randomUUID()}`, signal, goal = null, thinking = null, thinkingBudget = 0, images = [], planTask = null, planRun = null, researchTopic = null }) {
    let send = onFrame; let attached = true;
    // A research run gathers first; what the assistant writes while gathering is notes, not the answer, so it is not shown.
    let hideDeltas = !!researchTopic;
    signal?.addEventListener('abort', () => { send = () => {}; attached = false; }, { once: true });
    // What the assistant itself wrote in this run (not our own step lines): a plan turn reads its plan from it, a step reads its summary.
    const written = { all: '', step: '' };
    // The turn guard (turn-guard.mjs): counts failing searches, searches, plan rewrites and a nearly full context. Set up once the route is known.
    let guard = null;
    const raw = frame => { try { send(frame); } catch { send = () => {}; attached = false; } };
    // What the turn made (files) and compact activity lines (notes-split-agent8.md): derived from the cards the turn already sends.
    const tracker = new DeliverableTracker(workspacePath, trackerFolders());
    let toolsRan = false;   // a turn that ran no tool wrote nothing, so there is nothing to look for at its end
    try { tracker.snapshot(); } catch { /* a folder that cannot be read has no deliverables */ }
    const groups = new ActivityGroups({ emit: raw });
    const skills = new SkillsUsed({ emit: raw, info: skillInfoFrom(skillsDir()) });
    const emit = frame => {
      if (frame.type === 'delta' && !frame.own) { written.all += frame.text; written.step += frame.text; if (guard) trip(guard.text(frame.text)); if (hideDeltas) return; }
      if (frame.own) { const { own, ...rest } = frame; frame = rest; }
      if (frame.type === 'delta' && frame.text) groups.text();
      if (frame.type === 'agent-tool' && frame.tool) {
        if (['done', 'error'].includes(frame.tool.state) && !['read', 'read_image', 'glob', 'grep', 'web_fetch', 'web_search'].includes(frame.tool.name)) toolsRan = true;
        let made = null;
        if (frame.tool.state === 'done' && (frame.tool.name === 'write' || frame.tool.name === 'edit')) { try { made = tracker.check(frame.tool.args?.file_path ?? frame.tool.args?.path); } catch { made = null; } }
        raw(frame);
        if (made) raw(made);
        if (guard) trip(guard.card(frame.tool));
        groups.card(frame.tool, made);
        skills.card(frame.tool);
        return;
      }
      raw(frame);
    };
    // What the assistant is doing right now, one small frame (status.mjs). Cleared before the final frame of the turn.
    const reporter = new StatusReporter({ emit });

    emit({ type: 'queued', requestId });
    reporter.set({ phase: 'starting', code: 'starting', text: 'Starting…' });
    const { rt: runtime, route } = await ensureRuntime(choice, signal);
    const made = await sessionFor(c, workspacePath, runtime, { onWait: () => reporter.set({ phase: 'starting', code: 'assistant-starting', text: 'Starting the assistant…' }) });
    const { sessionId, fresh } = made ?? {};
    const cancelled = () => { reporter.clear(); emit({ type: 'done', finishReason: 'aborted', cancelled: true, tokensIn: null, tokensOut: null, usageSource: 'unavailable', durationMs: 0, model: route.name, contextMax: route.contextWindow }); return { cancelled: true }; };
    if (c.cancelStart || !made) return cancelled();

    // The model and the chat's thinking level (the Reasoning menu) are sent to the Harness when either changed. A level the route does
    // not have (an API model with its own vocabulary) is dropped and the model's own default stands: never an error for the person.
    const level = effortOf(thinking ?? 'Medium');   // the menu's default is Medium
    // Response settings the Harness cannot send itself (the thinking budget, the Expert sampling) go through this host's forwarding
    // endpoint, on a copy of the route; with every setting at its default the route is used directly, as before.
    const budget = level === 'off' ? 0 : nearestBudget(thinkingBudget);
    const sampling = proxyBase && route.shaped ? expertSampling() : null;
    const provider = route.shaped && (budget || sampling) ? route.shaped[budget] : route.route;
    const wanted = `${provider}/${route.modelId}/${level ?? ''}`;
    if (c.route !== wanted || c.routeGeneration !== runtime.generation) {
      const select = effort => runtime.gw.rpc('session/selectModel', { request: { sessionId, provider, model: route.modelId, ...(effort ? { reasoningEffort: effort } : {}) } });
      try {
        try { await select(level); } catch (e) { if (!level || e.code === 'session/not-found') throw e; await select(null); }
      } catch (e) {
        if (e.code === 'session/not-found') { delete sessionMap[c.id]; persist(); }
        throw new AgentUnavailable(`The coding assistant could not use ${route.name}. Pick the model again and retry.`, 'model-unavailable', e.message);
      }
      c.route = wanted; c.routeGeneration = runtime.generation;
    }

    // The chat's permission mode is read once, here, for this whole turn. A change the user makes while the
    // turn runs applies to the next one, so a running turn never sees its permissions move under it.
    const appliedMode = planTask ? 'plan' : modeOf(mode);
    await applyMode(runtime, sessionId, appliedMode);

    // Does the message fit the model's window? Asked before anything is sent, with the model server's own count (context-fit.mjs). A message
    // that fits once the older messages are a summary is sent after a summary; one that can never fit is not sent, and the person is told
    // plainly and offered the two ways out. Whatever cannot be counted goes through: the Harness recovers from a refusal by itself.
    if (!goal && route.kind === 'local') {
      const fit = await fitCheck({ runtime, route, sessionId, fresh, history, message }).catch(() => null);
      if (fit?.action === 'too-large') {
        reporter.clear();
        const values = [grouped(fit.tokens), grouped(fit.window)];
        const text = fill(FIT_TEXT.tooLarge, values);
        emit({ type: 'error', message: text, key: FIT_TEXT.tooLarge, values, code: 'CONTEXT_MESSAGE_TOO_LARGE', tokens: fit.tokens, window: fit.window });
        return { error: text };
      }
      if (fit?.action === 'summarize') {
        reporter.set({ phase: 'compacting', code: 'compacting', text: FIT_TEXT.summarizing, key: FIT_TEXT.summarizing, values: [] });
        const done = await compactChat(runtime, sessionId);
        reporter.clear();
        if (done.ok) emit(summarizedNote(done.before, done.after, fit.window));
      }
    }

    const projector = new TurnProjector({ policy: MODE_PRESETS[appliedMode].approval, window: route.contextWindow });
    if (!goal) guard = new TurnGuard({ plan: !!planTask, contextMax: route.kind === 'local' ? route.contextWindow : 0 });   // a saved connection's window is often only assumed: never judged by a guess
    projector.onStatus = update => { if (!turn?.parentOpen && turn?.children.size && [...turn.children.values()].some(h => !h.done) && update.phase === 'waiting') return; reporter.set(update); };
    const turn = {
      sessionId, projector, route, requestId, live: false, lastSeq: -1,
      ended: deferred(), follow: null, snapshot: deferred(), finished: false, prompted: false, stopBeforePrompt: false,
      abortFromRuntime: reason => finishTurn(reason), finish: failure => finishTurn(failure),
      // Helper agents (subagents) the Harness started for this chat, and the state of the run around them.
      children: new Map(), subagentCalls: new Map(), parentOpen: false, stopping: false, settleTimer: null, mode: appliedMode,
      plan: null, advancing: false, goalRun: false, lastActivity: Date.now(), heard: Date.now(), engineMark: null, watchdog: null,
      research: researchTopic ? { phase: 'gather', nudged: false, waitingStart: false } : null,
    };
    c.turn = turn;
    /**
     * A turn must always end. If the Harness sends nothing at all for a while (a tool that never returns, a model server that went
     * quiet, a lost event) the turn is stopped and ended with a plain message instead of showing "thinking" forever. A running tool gets
     * a longer allowance than a quiet model (a build can be silent for minutes). Whatever the assistant finished is kept.
     */
    turn.watchdog = setInterval(() => {
      if (turn.finished || turn.stopping) return;
      const toolRunning = [...projector.tools.values()].some(x => x.card?.state === 'running' || x.card?.state === 'proposed') || pending.size > 0 && pendingFor(chatId).length > 0;
      const limit = toolRunning ? stallToolMs : stallMs;
      // A local engine reading a long prompt sends the Harness nothing for minutes (#3623). Its /metrics progress counts as activity,
      // for at most engineGraceMs after the Harness last spoke: progress for another chat cannot keep a lost turn alive forever.
      if (turn.route?.kind === 'local' && Date.now() - turn.heard < engineGraceMs) {
        let mark = null;
        try { mark = engineProgress(turn.route.instanceId); } catch { /* no progress known: the Harness alone decides */ }
        if (mark != null && mark !== turn.engineMark) { turn.engineMark = mark; turn.lastActivity = Date.now(); return; }
      }
      if (Date.now() - turn.lastActivity < limit) return;
      turn.stalledFor = Math.round((Date.now() - turn.lastActivity) / 1000);
      turn.stopping = true;
      void runtime.gw.rpc('session/cancel', { request: { sessionId } }).catch(() => {});
      for (const h of turn.children.values()) if (!h.done) void runtime.gw.rpc('subagents/interruptByParent', { childSessionId: h.id, parentSessionId: sessionId, mode: 'continuable' }).catch(() => {});
      const mins = Math.max(1, Math.round(turn.stalledFor / 60));
      turn.finish(`The assistant stopped answering for ${mins > 1 ? mins + ' minutes' : 'a minute'}, so I ended this turn. Anything it already finished is kept. Send your message again to go on.`);
    }, Math.min(15_000, Math.max(200, Math.floor(stallMs / 4))));
    turn.watchdog.unref?.();
    async function finishTurn(failure) {
      if (turn.finished) return;
      turn.finished = true;
      clearTimeout(turn.settleTimer);
      clearInterval(turn.watchdog);
      turn.follow?.close();
      for (const child of turn.children.values()) child.follow?.close();
      if (turn.stopping && !failure) projector.ended = turn.guard ? { kind: 'completed' } : { kind: 'aborted', reason: { kind: 'user' } };
      reporter.clear();
      const extra = [];
      try { if (toolsRan) for (const d of tracker.sweep()) { emit(d); groups.addFile(d); } } catch { /* never blocks the end of a turn */ }
      groups.end();
      if (researchTopic && !failure && !turn.stopping) { const sources = parseSources(written.all); if (sources.length) extra.push({ type: 'research', topic: researchTopic, sources }); }
      try { extra.push(...settlePlan(failure)); } catch { /* a plan frame must never break the end of a turn */ }
      // The turn guard: a turn the app stopped, or one that ended with no words, always ends with one plain message (a plan card carries it itself).
      let noteReason = turn.guard ?? null;
      if (!noteReason && guard && !failure && !turn.stopping && !turn.goalRun) {
        noteReason = guard.silent({ ended: projector.ended, wrote: projector.emittedAny === true, acted: projector.tools.size > 0, contextTokens: projector.contextTokens });
      }
      if (noteReason && !extra.some(f => f.type === 'plan' && f.event === 'proposed')) { const note = guardNote(noteReason); if (note) extra.push(note); }
      for (const f of extra) emit(f);
      // The answer speed of a turn on this computer is the engine's own (tokens it produced over its decode time, as the Monitor shows it).
      const engine = !failure && route.kind === 'local' ? await engineSpeedOf(route, projector) : null;
      const frames = failure ? [{ type: 'error', message: plainAgentFailure(failure), details: failure, code: 'AGENT_STOPPED' }] : projector.finish({ model: route.name, contextMax: route.contextWindow, engine });
      for (const f of frames.slice(0, -1)) emit(f);
      // Messages typed while the goal ran and not delivered between steps go back to the page now, to be sent as ordinary messages.
      if (turn.goalRun && attached) {
        const left = queueView(chatId);
        if (left.length) { queues.delete(chatId); onQueue(chatId, []); emit({ type: 'queued-release', messages: left.map(({ id, text }) => ({ id, text })) }); }
      }
      for (const f of frames.slice(-1)) emit(f);
      c.turn = null;
      turn.ended.resolve({ reason: projector.ended, failure: failure ?? null });
      notifyIdle();
      // A turn that filled the context, or that the guard stopped, leaves a long history behind: summarise the older part now so the next message has room.
      if (noteReason === 'context' || noteReason === 'searches' || noteReason === 'searches-failed' || noteReason === 'rewrites' || /context window|too long|exceeds/i.test(String(projector.ended?.error?.message ?? ''))) void compactSession(runtime, sessionId);
    }

    emit({ type: 'start', model: route.name, contextMax: route.contextWindow, demo: false, remoteModel: route.kind === 'api', agent: true, mode: appliedMode, sessionId, requestId, skills: [], ...(planTask ? { planning: true } : {}) });

    turn.follow = runtime.gw.openStream('session/follow', { request: { address: { kind: 'session', sessionId }, assistantStream: true } }, {
      onItem: item => {
        if (item.type === 'snapshot') {
          if (turn.lastSeq < 0) turn.lastSeq = item.cursor;
          else for (const r of item.records ?? []) if (r.type === 'event' && r.event.seq > turn.lastSeq) handle({ type: 'event', event: r.event });
          turn.snapshot.resolve();
          return;
        }
        handle(item);
      },
      onError: e => finishTurn(`The agent lost the session stream: ${e.message}`),
    });

    /** The guard says stop: end the turn the way Stop does, but as a normal end with a plain message (finishTurn). */
    function trip(reason) {
      if (!reason || turn.guard || turn.finished || turn.stopping) return;
      turn.guard = reason;
      log(`agent · turn guard: ${reason} (searches ${guard?.searches ?? 0}, failed in a row ${guard?.failedInARow ?? 0}, plan rewrites ${guard?.rewrites ?? 0})`);
      void stop(chatId).catch(() => {});
    }

    function handle(item) {
      if (turn.finished) return;
      turn.lastActivity = Date.now();
      turn.heard = turn.lastActivity;
      if (item.type === 'event') {
        const e = item.event;
        if (e.seq <= turn.lastSeq) return;
        turn.lastSeq = e.seq;
        // The turn is ours from the user message that carries our request id. Until then an older,
        // detached turn on the same session may still be finishing; its events are not ours.
        if (!turn.live) {
          if (e.type === 'user/message' && e.data?.source?.rpcId === requestId) turn.live = true;
          return;
        }
      } else if (!turn.live) return;
      for (const f of projector.consume(item)) emit(f);
      if (guard && projector.contextTokens != null) trip(guard.context(projector.contextTokens));
      if (item.type === 'event') watchParent(item.event);
    }

    // -- helper agents ---------------------------------------------------------------------------------------

    const rowFrame = child => ({ type: 'agent', agent: child.cp.agent() });
    const emitRow = (child, force = false) => {
      const now = Date.now();
      if (!force && now - child.lastRow < 400) { child.rowPending = true; return; }
      child.lastRow = now; child.rowPending = false;
      emit(rowFrame(child));
      const working = [...turn.children.values()].filter(h => !h.done).length;
      if (working && !turn.parentOpen) reporter.set({ phase: 'helpers', code: 'helpers', text: `Helpers are working (${working})…`, key: 'Helpers are working ({0})…', values: [working], args: { n: working } });
    };

    function openChild(d) {
      const id = d.childId;
      if (!id || turn.children.has(id)) return;
      const cp = new ChildProjector({ id, name: d.label || 'Helper' });
      const child = { id, cp, follow: null, noticed: false, done: false, lastRow: 0, rowPending: false, endedAt: 0 };
      turn.children.set(id, child);
      emitRow(child, true);
      const fold = item => {
        if (turn.finished) return;
        turn.lastActivity = turn.heard = Date.now();
        // A helper that finishes before its throttled "working" row went out would show queued -> completed and never "working": send the held row first.
        if (item.type === 'event' && item.event.type === 'turn/end' && child.rowPending) emitRow(child, true);
        const { frames, row } = cp.consume(item);
        for (const f of frames) emit(f);
        if (item.type === 'event' && item.event.type === 'turn/end') { child.done = true; child.endedAt = Date.now(); emitRow(child, true); armSettle(); return; }
        if (item.type === 'event' && child.done && cp.status === 'working') { child.done = false; }
        if (row) emitRow(child);
      };
      child.follow = runtime.gw.openStream('session/follow', {
        request: { address: { kind: 'subagent', parentSessionId: sessionId, childSessionId: id, mode: d.mode ?? 'unknown' }, assistantStream: true },
      }, {
        onItem: item => {
          if (item.type === 'snapshot') { for (const r of item.records ?? []) if (r.type === 'event') fold({ type: 'event', event: r.event }); return; }
          fold(item);
        },
        onError: e => {
          log(`agent · helper stream ended: ${e.message}`);
          if (!child.done) { child.done = true; child.endedAt = Date.now(); cp.status = 'failed'; cp.failure = 'Lost contact with this helper.'; cp.endedAt = Date.now(); emitRow(child, true); armSettle(); }
        },
      });
      // A late reader still gets the final row: flush any row held back by the throttle.
      child.flush = after(500, function tick() { if (!turn.finished && child.rowPending) emitRow(child, true); if (!turn.finished && !child.done) child.flush = after(500, tick); });
    }

    function watchParent(e) {
      const d = e.data ?? {};
      switch (e.type) {
        case 'turn/start':
          turn.parentOpen = true;
          if (turn.research) turn.research.waitingStart = false;
          clearTimeout(turn.settleTimer);
          // After Stop, a helper's report would start a new turn that nobody asked for.
          if (turn.stopping) void runtime.gw.rpc('session/cancel', { request: { sessionId } }).catch(() => {});
          break;
        case 'turn/end':
          turn.parentOpen = false;
          armSettle();
          break;
        // The first turn of a prompt may have started before this follow stream attached (no turn/start seen): any step of the parent is proof that it is
        // still working. Without this a helper that finished while the parent was still answering ended the run early ("The agent turn was interrupted").
        case 'step/start':
          if (!turn.parentOpen) { turn.parentOpen = true; clearTimeout(turn.settleTimer); }
          break;
        case 'tool/call':
          if (d.name === 'subagent' || d.name === 'subagent_fork') turn.subagentCalls.set(d.callId, parseArgs(d.arguments));
          break;
        case 'subagent/catalog':
          openChild(d);
          break;
        case 'tool/result': {
          const call = turn.subagentCalls.get(d.message?.toolCallId);
          const text = (d.message?.content ?? []).map(p => p.text ?? '').join(' ');
          const started = /started subagent ([0-9a-f-]{36})/i.exec(text);
          const child = started ? turn.children.get(started[1]) : null;
          if (call && child) { child.cp.task = String(call.prompt ?? call.description ?? '').replace(/\s+/g, ' ').trim().slice(0, 140); emitRow(child, true); }
          break;
        }
        case 'user/message':
          if (d.source?.kind === 'goal' && Number.isInteger(d.source.round)) { turn.goalRound = d.source.round; void announceGoal(); }
        // falls through
        case 'agent/inbox/spliced': {
          const hit = JSON.stringify(d);
          if (!/Background subagent/.test(hit)) break;
          for (const child of turn.children.values()) if (hit.includes(child.id)) child.noticed = true;
          break;
        }
        default:
          break;
      }
    }

    // -- plans and goal steps ----------------------------------------------------------------------------------

    const planFrame = (event, plan, extra = {}) => ({ type: 'plan', event, plan: planView(plan), ...extra });
    const publishPlan = (event, plan) => { onPlan(chatId, event, planView(plan)); return planFrame(event, plan); };
    const stepFrame = (plan, index) => {
      const st = plan.steps[index];
      return { type: 'plan-step', planId: plan.id, stepId: st.id, index: index + 1, total: plan.steps.length, state: st.state, text: st.text, summary: st.summary ?? null, line: stepLine(index, plan.steps.length, st.text, st.state === 'running' ? 'started' : st.state) };
    };
    const currentStep = plan => plan.steps.findIndex(x => x.state !== 'done' && x.state !== 'skipped');

    /** What the end of the turn means for the plan: a plan turn makes one; a step run records where it stopped. */
    function settlePlan(failure) {
      if (planTask) {
        if (failure || (turn.stopping && !turn.guard)) return [];
        const parsed = parsePlan(written.all, planTask);
        if (!parsed) return [];
        const plan = plans.create(chatId, { title: parsed.title, steps: parsed.steps, request: planTask, ...(turn.guard ? { caution: GUARD_NOTES[turn.guard] } : {}) });
        return [publishPlan('proposed', plan)];
      }
      const run = turn.plan;
      if (!run) return [];
      const plan = plans.get(chatId);
      if (!plan || plan.id !== run.id) return [];
      if (plan.state !== 'running') return [];
      const out = [];
      const at = currentStep(plan);
      plans.update(chatId, p => {
        if (at < 0) { p.state = 'done'; return; }
        // The step that was running goes back to waiting, so Resume runs it again.
        p.steps[at].state = 'pending';
        p.state = 'paused';
      });
      const updated = plans.get(chatId);
      if (at >= 0) out.push(stepFrame(updated, at));
      out.push(publishPlan(updated.state === 'done' ? 'done' : 'paused', updated));
      return out;
    }

    /** The goal the Harness runs for the plan's next waiting step, and the frames that say so. */
    async function startStep(plan, index) {
      plans.update(chatId, p => { p.state = 'running'; p.goalStarted = true; p.steps[index].state = 'running'; });
      const now = plans.get(chatId);
      await runtime.gw.rpc('goals/create', { agentId: sessionId, request: { objective: stepObjective(now, index) } });
      written.step = ''; written.stepAt = Date.now();
      emit(stepFrame(now, index));
      emit(publishPlan('step', now));
      const st = now.steps[index];
      reporter.set({ phase: 'goal', code: 'goal-step', text: stepLine(index, now.steps.length, st.text, 'started'), key: '{0}', values: [st.text], args: { step: index + 1, steps: now.steps.length } });
    }

    /** One goal step finished: say so, hand over queued messages, and begin the next step (or end the plan). */
    async function advancePlan() {
      const run = turn.plan;
      const plan = plans.get(chatId);
      if (!run || !plan || plan.id !== run.id) return false;
      const at = currentStep(plan);
      if (at < 0) return false;
      const cards = [...projector.tools.values()].filter(x => x.calledAt >= (written.stepAt ?? 0) - 50 && x.card?.state === 'done').map(x => x.card);
      const summary = stepSummary(cards, written.step.split(/\n\s*\n/).filter(Boolean).at(-1) ?? written.step);
      plans.update(chatId, p => { p.steps[at].state = 'done'; p.steps[at].summary = summary; });
      let now = plans.get(chatId);
      emit(stepFrame(now, at));
      emit({ type: 'delta', own: true, text: `\n\n${stepLine(at, now.steps.length, now.steps[at].text, 'done')}\n` });
      const next = currentStep(now);
      emit(publishPlan(next < 0 ? 'done' : 'step', next < 0 ? (plans.update(chatId, p => { p.state = 'done'; }), plans.get(chatId)) : now));
      await deliverQueued(at + 1);
      if (turn.stopping || turn.finished) return true;
      if (next < 0) return false;
      // One step per turn (Time-skip): the plan stays open for the next step, which starts in a session of its own so the conversation never grows across steps.
      if (run.once) { plans.update(chatId, p => { p.state = 'approved'; }); emit(publishPlan('step', plans.get(chatId))); return false; }
      await startStep(plans.get(chatId), next);
      void announceGoal();
      return true;
    }

    /** Hand the person's queued messages to the assistant, one at a time, each answered before the next. */
    async function deliverQueued(afterStep) {
      const list = queues.get(chatId) ?? [];
      while (list.length && !turn.stopping && !turn.finished) {
        const item = list.shift();
        if (!list.length) queues.delete(chatId);
        onQueue(chatId, queueView(chatId));
        emit({ type: 'queued-message', state: 'delivered', message: { id: item.id, text: item.text, at: item.at, deliverAt: item.deliverAt }, afterStep, queue: queueView(chatId) });
        try { await runtime.gw.rpc('session/prompt', { request: { requestId: `queued-${randomUUID()}`, sessionId, mode: 'queue', content: [{ type: 'text', text: item.text }] } }); }
        catch { emit({ type: 'queued-release', messages: [{ id: item.id, text: item.text }] }); continue; }
        // Wait for the answer: the parent opens a turn for it and closes it again.
        const t0 = Date.now();
        while (!turn.parentOpen && Date.now() - t0 < 4000 && !turn.finished) await new Promise(r => setTimeout(r, 50));
        while (turn.parentOpen && !turn.finished && !turn.stopping) await new Promise(r => setTimeout(r, 100));
      }
    }

    /**
     * The run is over when the parent is idle and every helper has finished and reported back. A helper's report
     * wakes the parent a moment after the helper ends, so a helper that ended but has not reported yet keeps the run
     * open (for a few seconds at most); after Stop nobody waits for reports.
     */
    function armSettle() {
      clearTimeout(turn.settleTimer);
      if (turn.finished) return;
      turn.settleTimer = after(turn.stopping ? 1200 : turn.children.size ? 600 : 0, async () => {
        if (turn.finished || turn.parentOpen || turn.advancing) return;
        const open = [...turn.children.values()];
        if (open.some(c => !c.done)) return;
        if (!turn.stopping) {
          if (open.some(c => !c.noticed && Date.now() - c.endedAt < 8000)) { armSettle(); return; }
          // An armed goal starts its next round as soon as the agent is idle: the run is not over until the goal stops.
          const current = await goalGet();
          if (turn.finished || turn.parentOpen) return;
          if (current && current.phase === 'active' && current.activation === 'armed') { turn.settleTimer = after(700, armSettle); return; }
          // Research: gather (search and read pages), then write the answer in the fixed shape. A step that did not open pages is sent back once.
          if (turn.research && !turn.stopping) {
            const r = turn.research;
            if (r.waitingStart) { turn.settleTimer = after(300, armSettle); return; }
            const opened = [...projector.tools.values()].filter(x => x.card?.name === 'web_fetch' && x.card.state === 'done').length;
            const prompt = r.phase === 'write' ? null : (opened < 2 && !r.nudged) ? RESEARCH_NUDGE : researchWritePrompt(researchTopic);
            if (prompt) {
              if (prompt !== RESEARCH_NUDGE) { r.phase = 'write'; hideDeltas = false; written.all = ''; reporter.set({ phase: 'waiting', code: 'research-writing', text: 'Writing the answer…', key: 'Writing the answer…', values: [], args: {} }); } else r.nudged = true;
              r.waitingStart = true;
              try { await runtime.gw.rpc('session/prompt', { request: { requestId: `research-${randomUUID()}`, sessionId, mode: 'queue', content: [{ type: 'text', text: prompt }] } }); }
              catch { r.waitingStart = false; hideDeltas = false; finishTurn(null); return; }
              turn.settleTimer = after(500, armSettle);
              return;
            }
          }
          // A plan step's goal is complete: record it, deliver queued messages, start the next step.
          if (turn.plan && current && current.phase === 'complete' && !turn.advancing) {
            turn.advancing = true;
            let more = false;
            try { more = await advancePlan(); } catch (e) { emit({ type: 'delta', own: true, text: `\n\nThe plan stopped: ${plainGoalError(e)}\n` }); }
            turn.advancing = false;
            if (more && !turn.finished && !turn.stopping) { turn.settleTimer = after(700, armSettle); return; }
          }

          if (turn.goalRun && current) { const line = goalEnding(current); if (line) emit({ type: 'delta', text: line }); }
          if (turn.goalRun) await announceGoal(true);
        }
        finishTurn(null);
      });
    }
    const goalGet = () => runtime.gw.rpc('goals/get', { agentId: sessionId }).catch(() => undefined);
    /** The goal's state to the page: a `goal` frame, the SSE event for the bar, and (while a round runs) the status line. */
    async function announceGoal(final = false) {
      const view = await goalGet();
      if (turn.finished && !final) return;
      const goal = goalObject(view, chatId);
      emit({ type: 'goal', goal });
      onGoal(chatId, goal);
      if (!final && goal && goal.phase === 'active' && turn.goalRound) reporter.set({ phase: 'goal', code: 'goal-step', text: 'Working on the goal…', args: { round: turn.goalRound, max: goal.maxRounds } });
    }
    turn.announceGoal = announceGoal;
    turn.announceQueue = frame => emit(frame);

    const snapshotTimer = {};
    await Promise.race([turn.snapshot.promise, new Promise((_, rej) => { snapshotTimer.t = after(20_000, () => rej(new Error('the session stream did not open'))); })])
      .catch(e => { finishTurn(e.message); })
      .finally(() => clearTimeout(snapshotTimer.t));
    if (turn.finished) return { error: true };
    if (turn.stopBeforePrompt || c.cancelStart) { projector.ended = { kind: 'aborted', reason: { kind: 'user' } }; finishTurn(null); return { cancelled: true }; }

    if (goal) {
      // A goal run has no prompt of its own: the Harness's goal driver starts the rounds. Everything from now on is ours.
      turn.live = true; turn.goalRun = true;
      try {
        if (planRun) {
          const plan = plans.get(chatId);
          if (!plan || plan.id !== planRun.planId) throw new AgentUnavailable('That plan is no longer there. Ask for a new one with /plan.', 'plan-gone');
          turn.plan = { id: plan.id, once: !!planRun.once };
          const at = currentStep(plan);
          if (at < 0) throw new AgentUnavailable('Every step of this plan is already done.', 'plan-done');
          if (goal.action === 'resume' && plan.goalStarted) {
            plans.update(chatId, p => { p.state = 'running'; p.steps[at].state = 'running'; });
            await startGoal(runtime, sessionId, goal);
            emit(publishPlan('step', plans.get(chatId)));
          } else await startStep(plan, at);
        } else {
          await startGoal(runtime, sessionId, goal);
        }
      } catch (e) { finishTurn(e instanceof AgentUnavailable ? e.message : plainGoalError(e)); return { error: true }; }
      reporter.set({ phase: 'waiting', code: 'reading-prompt', text: 'Reading your message…' });
      void announceGoal();
    } else {
      let prompt = message;
      if (fresh && history.length) prompt = withEarlierConversation(history, message);
      try {
        await runtime.gw.rpc('session/prompt', { request: { requestId, sessionId, mode: 'queue', content: [{ type: 'text', text: prompt }, ...imageParts(images)] } });
      } catch (e) {
        finishTurn(`The agent did not accept the message: ${e.message}`);
        return { error: true };
      }
    }
    if (!goal) reporter.set({ phase: 'waiting', code: 'reading-prompt', text: 'Reading your message…' });
    turn.prompted = true;
    if (turn.stopBeforePrompt) {
      // Stop landed in the instant between 'prompt sent' and 'prompt accepted'. A cancel before the turn
      // starts arms nothing, so wait for the turn to be ours, then cancel it.
      for (let i = 0; i < 100 && !turn.live && !turn.finished; i++) await new Promise(r => setTimeout(r, 50));
      if (!turn.finished) await runtime.gw.rpc('session/cancel', { request: { sessionId } }).catch(() => {});
    }

    // Wait for the turn, or for the client to leave. Leaving does not stop the turn.
    const gone = new Promise(r => signal?.addEventListener('abort', () => r('detached'), { once: true }));
    const outcome = await Promise.race([turn.ended.promise, gone]);
    if (outcome === 'detached') return { detached: true, sessionId, ended: turn.ended.promise.then(r => ({ ...r, tokensOut: projector.tokensOut })) };
    return { sessionId, reason: outcome.reason, tokensIn: projector.tokensIn, tokensOut: projector.tokensOut };
  }

  // -- /goal -----------------------------------------------------------------------------------------------

  /** Create or resume the chat's goal; the Harness's goal driver then runs the rounds by itself. */
  async function startGoal(runtime, sessionId, goal) {
    if (goal.action === 'create') {
      const request = { objective: goal.objective, ...(goal.maxRounds ? { maxGoalRounds: goal.maxRounds } : {}) };
      await runtime.gw.rpc('goals/create', { agentId: sessionId, request });
      return;
    }
    const current = await runtime.gw.rpc('goals/get', { agentId: sessionId });
    if (!current) throw new AgentUnavailable('There is no goal to continue. Start one with /goal followed by what you want done.', 'goal-none');
    await runtime.gw.rpc('goals/resume', { agentId: sessionId, ref: { id: current.id, revision: current.revision } });
  }

  async function pauseGoal(runtime, sessionId, chatId = null) {
    try {
      const current = await runtime.gw.rpc('goals/get', { agentId: sessionId });
      if (current && current.phase === 'active') {
        await runtime.gw.rpc('goals/pause', { agentId: sessionId, ref: { id: current.id, revision: current.revision } });
        if (chatId) onGoal(chatId, goalObject(await runtime.gw.rpc('goals/get', { agentId: sessionId }).catch(() => undefined)));
      }
    } catch { /* no goal service, or nothing to pause */ }
  }

  /** The goal as the page and the goal bar see it (notes-split-agent3.md), or null. */
  function goalObject(view, chatId = null) {
    if (!view) return null;
    const phase = ['active', 'paused', 'complete', 'blocked'].includes(view.phase) ? view.phase : 'blocked';
    // A goal that is running a plan (or the points of a goal) shows the plan's title and which step it is on.
    const plan = chatId ? plans.get(chatId) : null;
    const running = plan && plan.goalStarted && ['running', 'paused'].includes(plan.state) ? plan : null;
    const at = running ? running.steps.findIndex(x => x.state !== 'done' && x.state !== 'skipped') : -1;
    const step = running && at >= 0 ? { index: at + 1, total: running.steps.length, text: running.steps[at].text } : null;
    return { objective: step ? running.title : String(view.objective ?? ''), ...(step ? { step } : {}), phase, round: view.roundsStarted ?? 0, maxRounds: view.maxGoalRounds ?? null, ...(phase === 'blocked' ? { blocked: plainBlocker(view.blockedReason) } : {}) };
  }

  /** The goal of a chat now, from the Harness (null: none, or the agent is not running). */
  async function goalState(chatId) {
    const known = sessionMap[chatId]?.sessionId;
    if (!known || !rt?.hp.running) return null;
    return goalObject(await rt.gw.rpc('goals/get', { agentId: known }).catch(() => undefined), chatId);
  }

  /** Pause, edit or remove the goal from the goal bar. Instant; resume runs rounds and goes through the chat stream. */
  async function goalControl({ chatId, action, text }) {
    const known = sessionMap[chatId]?.sessionId;
    if (!known || !rt?.hp.running) throw new AgentUnavailable('There is no goal in this chat yet.', 'goal-none');
    const current = await rt.gw.rpc('goals/get', { agentId: known }).catch(() => undefined);
    if (!current) throw new AgentUnavailable('There is no goal in this chat yet.', 'goal-none');
    const ref = { id: current.id, revision: current.revision };
    try {
      if (action === 'pause') { if (current.phase === 'active') await rt.gw.rpc('goals/pause', { agentId: known, ref }); }
      else if (action === 'clear') await rt.gw.rpc('goals/clear', { agentId: known, ref });
      else if (action === 'edit') {
        const objective = String(text ?? '').trim().slice(0, 4000);
        if (!objective) throw new AgentUnavailable('A goal needs a few words about what you want done.', 'goal-text');
        await rt.gw.rpc('goals/edit', { agentId: known, ref, request: { objective } });
      } else throw new AgentUnavailable('That goal action is not known.', 'goal-action');
    } catch (e) { throw e instanceof AgentUnavailable ? e : new AgentUnavailable(plainGoalError(e), 'goal-failed', e.message); }
    if (action === 'clear') { const plan = plans.get(chatId); if (plan && ['running', 'paused'].includes(plan.state)) { plans.update(chatId, p => { p.state = 'stopped'; for (const st of p.steps) if (st.state === 'running') st.state = 'pending'; }); onPlan(chatId, 'stopped', planView(plans.get(chatId))); } }
    const goal = action === 'clear' ? null : goalObject(await rt.gw.rpc('goals/get', { agentId: known }).catch(() => undefined), chatId);
    onGoal(chatId, goal);
    return { goal };
  }

  /** The goal's state in plain words. */
  function describeGoal(view) {
    if (!view) return 'No goal is set. Start one with /goal followed by what you want done.';
    const what = `"${view.objective}"`;
    if (view.phase === 'active') return `Working on the goal ${what}.`;
    if (view.phase === 'paused') return `The goal ${what} is paused. Type /goal resume to go on.`;
    if (view.phase === 'complete') return `The goal ${what} is complete.`;
    return `The goal ${what} stopped: ${plainBlocker(view.blockedReason)}`;
  }

  /**
   * Handle a "/goal ..." line for a chat, as the Harness's own /goal command reads it: nothing = show the goal,
   * clear, pause, resume, edit <text>, or any other text = a new goal. Starting or resuming runs the rounds and
   * streams them like a chat turn (Stop pauses the goal); every other verb answers at once.
   */
  async function goalCommand(options) {
    const { chatId, line, onFrame } = options;
    const text = String(line ?? '').trim();
    const verb = text.split(/\s+/)[0]?.toLowerCase() ?? '';
    const rest = text.slice(verb.length).trim();
    const say = reply => {
      onFrame({ type: 'queued', requestId: `goal-${randomUUID()}` });
      onFrame({ type: 'start', model: '', contextMax: 0, demo: false, remoteModel: false, agent: true, mode: modeOf(options.mode), skills: [] });
      onFrame({ type: 'delta', text: reply });
      onFrame({ type: 'done', finishReason: 'stop', tokensIn: null, tokensOut: null, usageSource: 'unavailable', durationMs: 0 });
      return { goal: true };
    };
    if (tools()?.off?.has('goals')) return say('Goals are turned off. You can turn them back on in Settings, Tools.');
    const known = sessionMap[chatId]?.sessionId;
    const quick = ['', 'clear', 'pause', 'edit', 'complete'].includes(verb) || (verb === 'status');
    let runtime = rt;
    if (quick) {
      if (!known || !runtime?.hp.running) return say(verb === '' || verb === 'status' ? describeGoal(null) : 'There is no goal in this chat yet.');
      const current = await runtime.gw.rpc('goals/get', { agentId: known }).catch(() => undefined);
      const ref = current ? { id: current.id, revision: current.revision } : null;
      try {
        if (verb === '' || verb === 'status') return say(describeGoal(current));
        if (!ref) return say('There is no goal in this chat yet.');
        if (verb === 'clear') { await runtime.gw.rpc('goals/clear', { agentId: known, ref }); return say('The goal is cleared.'); }
        if (verb === 'pause') {
          if (current.phase === 'active') await runtime.gw.rpc('goals/pause', { agentId: known, ref });
          return say(describeGoal(await runtime.gw.rpc('goals/get', { agentId: known })));
        }
        if (verb === 'complete') { await runtime.gw.rpc('goals/complete', { agentId: known, ref }); return say('The goal is marked complete.'); }
        if (verb === 'edit') {
          if (!rest) return say('Type /goal edit followed by the new wording of the goal.');
          await runtime.gw.rpc('goals/edit', { agentId: known, ref, request: { objective: rest } });
          return say(`The goal now reads: "${rest}".`);
        }
      } catch (e) { return say(plainGoalError(e)); }
    }
    if (verb === 'resume') {
      const plan = plans.get(chatId);
      const goalPlan = plan && plan.goalStarted && plan.state === 'paused' ? { planId: plan.id } : null;
      return runTurn({ ...options, goal: { action: 'resume' }, ...(goalPlan ? { planRun: goalPlan } : {}) });
    }
    // A goal whose own words hold numbered points ("1. ... 2. ... 3. ...") runs point by point, each one reported.
    const points = parsePoints(text);
    if (points) {
      const plan = plans.create(chatId, { title: points.title, steps: points.steps, request: text, source: 'goal', state: 'approved' });
      onPlan(chatId, 'approved', planView(plan));
      return runTurn({ ...options, goal: { action: 'create', objective: text }, planRun: { planId: plan.id } });
    }
    // Any other text is a new goal. One unfinished goal at a time (the Harness's rule): say so in plain words.
    return runTurn({ ...options, goal: { action: 'create', objective: text } });
  }

  // -- /plan -----------------------------------------------------------------------------------------------

  /** A short answer in the chat that the page translates (the sentence is in the interface catalog, "values" fill its slots). */
  function sayKey(options, template, values = []) {
    const { onFrame } = options;
    onFrame({ type: 'queued', requestId: 'compact-' + randomUUID() });
    onFrame({ type: 'start', model: '', contextMax: 0, demo: false, remoteModel: false, agent: true, mode: modeOf(options.mode), skills: [] });
    onFrame({ type: 'delta', text: fill(template, values), key: template, values });
    onFrame({ type: 'done', finishReason: 'stop', tokensIn: null, tokensOut: null, usageSource: 'unavailable', durationMs: 0 });
    return { compact: true };
  }

  /** A short answer in the chat (no model): the same frames a turn sends. */
  function sayOnce(options, reply) {
    const { onFrame } = options;
    onFrame({ type: 'queued', requestId: `plan-${randomUUID()}` });
    onFrame({ type: 'start', model: '', contextMax: 0, demo: false, remoteModel: false, agent: true, mode: modeOf(options.mode), skills: [] });
    onFrame({ type: 'delta', text: reply });
    onFrame({ type: 'done', finishReason: 'stop', tokensIn: null, tokensOut: null, usageSource: 'unavailable', durationMs: 0 });
    return { plan: true };
  }

  /**
   * "/plan <what you want>": the assistant looks around (the chat is put in Plan mode for this turn, so nothing can change), writes the
   * plan, and the host sends it as a `plan` frame. Nothing runs until the person approves it.
   */
  async function planCommand(options) {
    const task = String(options.line ?? '').trim();
    if (!task) {
      const open = plans.get(options.chatId);
      return sayOnce(options, open && ['proposed', 'approved'].includes(open.state)
        ? 'A plan is waiting for you above. Approve it, edit it or reject it, or type /plan followed by something else to make a new one.'
        : 'Type /plan followed by what you want done, for example: /plan build a small pagoda page. I will look around and write a plan; nothing changes until you approve it.');
    }
    return runTurn({ ...options, message: planPrompt(task), planTask: task, mode: 'plan' });
  }

  /**
   * "/research <topic>": the assistant searches the web, opens and reads pages, and writes a short structured answer (Summary, Key findings,
   * Sources). The host also sends the sources as a `research` frame before the end of the turn. Needs web search turned on.
   */
  async function researchCommand(options) {
    const topic = String(options.line ?? '').trim();
    if (!topic) return sayOnce(options, 'Type /research followed by what you want to know, for example: /research how do heat pumps compare with gas boilers. I will search the web, read the pages and answer with sources.');
    if (tools()?.off?.has('search')) return sayOnce(options, 'Research needs web search, which is turned off. Turn it on in Settings, Tools (DuckDuckGo needs no key), then try again.');
    return runTurn({ ...options, message: researchPrompt(topic), researchTopic: topic });
  }

  const planGone = () => new AgentUnavailable('There is no plan waiting in this chat. Ask for one with /plan followed by what you want done.', 'plan-gone');
  function planOf(chatId, planId) {
    const plan = plans.get(chatId);
    if (!plan || (planId && plan.id !== planId)) throw planGone();
    return plan;
  }
  const mustBeOpen = plan => { if (plan.state !== 'proposed' && plan.state !== 'approved') throw new AgentUnavailable('This plan has already been used. Ask for a new one with /plan.', 'plan-used'); };

  /** A short note added to every step of the chat's plan (the Time-skip B path: where its work comes from). */
  function setPlanBriefing(chatId, text) { plans.update(chatId, p => { p.briefing = String(text ?? '').slice(0, 600); }); }

  /** The plan of a chat, or null. */
  const planState = chatId => planView(plans.get(chatId));

  /** Approve, edit or reject the plan; instant. Approve also returns the message that carries the plan out as an ordinary turn. */
  function planControl({ chatId, planId, action, steps, title }) {
    const plan = planOf(chatId, planId);
    if (action === 'edit') {
      mustBeOpen(plan);
      const next = editedSteps(steps, plan.steps);
      const t = String(title ?? '').replace(/\s+/g, ' ').trim().slice(0, 80);
      plans.update(chatId, p => { p.steps = next; if (t) p.title = t; p.state = 'proposed'; });
      onPlan(chatId, 'edited', planView(plans.get(chatId)));
      return { plan: planView(plans.get(chatId)) };
    }
    if (action === 'approve') {
      mustBeOpen(plan);
      plans.update(chatId, p => { p.state = 'approved'; });
      const approved = plans.get(chatId);
      onPlan(chatId, 'approved', planView(approved));
      return { plan: planView(approved), prompt: planAsPrompt(approved) };
    }
    if (action === 'reject') {
      mustBeOpen(plan);
      plans.update(chatId, p => { p.state = 'rejected'; });
      onPlan(chatId, 'rejected', planView(plans.get(chatId)));
      return { plan: planView(plans.get(chatId)) };
    }
    throw new AgentUnavailable('That plan action is not known.', 'plan-action');
  }

  /** "Start as goal": each step of the plan becomes a goal step, run one after another and reported. Streams like a chat turn. */
  async function planGoal(options) {
    const { chatId, planId } = options;
    let plan;
    try { plan = planOf(chatId, planId); } catch (e) { return sayOnce(options, e.message); }
    if (modeOf(options.mode) === 'plan') return sayOnce(options, 'Plan mode only looks, so it cannot carry out a plan. Switch this chat to Manual or Bypass, then start it again.');
    if (plan.state === 'paused' && plan.goalStarted) return goalCommand({ ...options, line: 'resume' });
    try { mustBeOpen(plan); } catch (e) { return sayOnce(options, e.message); }
    if (tools()?.off?.has('goals')) return sayOnce(options, 'Goals are turned off. You can turn them back on in Settings, Tools.');
    plans.update(chatId, p => { p.state = 'approved'; });
    onPlan(chatId, 'approved', planView(plans.get(chatId)));
    return runTurn({ ...options, goal: { action: 'create', objective: plan.title }, planRun: { planId: plan.id, once: options.once === true } });
  }

  /** A paused plan becomes open again (a step that did not finish is tried again in a fresh session). */
  function reopenPlan(chatId) { const p = plans.get(chatId); if (p && p.state === 'paused') { plans.update(chatId, x => { x.state = 'approved'; }); onPlan(chatId, 'approved', planView(plans.get(chatId))); } }

  /** Give up on one step with a plain note (a check that cannot be done here) so the rest of the plan can go on. */
  function skipStep(chatId, index, note) { plans.update(chatId, p => { const st = p.steps[index]; if (st) { st.state = 'skipped'; st.summary = String(note ?? 'Skipped.').slice(0, 140); } if (p.state === 'paused') p.state = 'approved'; }); onPlan(chatId, 'step', planView(plans.get(chatId))); }

  /** Forget the chat's agent session (not its plan): the next turn starts a fresh one in the same folder. */
  function resetSession(chatId) {
    if (chats.get(chatId)?.turn || chats.get(chatId)?.starting) throw new AgentUnavailable('This chat is still working.', 'turn-active');
    delete sessionMap[chatId]; persist();
  }

  // -- messages typed while a goal runs ----------------------------------------------------------------------

  /** Queue a message for the running goal. It is delivered between steps, or handed back to the page when the goal ends or pauses. */
  function queueMessage({ chatId, text }) {
    const turn = chats.get(chatId)?.turn;
    if (!turn || !turn.goalRun || turn.stopping || turn.finished) throw new AgentUnavailable('No goal is running in this chat, so there is nothing to queue behind. Send the message as usual.', 'queue-idle');
    const clean = String(text ?? '').trim().slice(0, 8000);
    if (!clean) throw new AgentUnavailable('Type a few words to queue.', 'queue-empty');
    const list = queues.get(chatId) ?? [];
    if (list.length >= 20) throw new AgentUnavailable('Twenty messages are already waiting. Wait for some to be delivered.', 'queue-full');
    const item = { id: randomUUID(), text: clean, at: new Date().toISOString(), deliverAt: turn.plan ? 'step' : 'end' };
    list.push(item); queues.set(chatId, list);
    const message = { id: item.id, text: item.text, at: item.at, deliverAt: item.deliverAt };
    onQueue(chatId, queueView(chatId));
    turn.announceQueue?.({ type: 'queued-message', state: 'queued', message, queue: queueView(chatId) });
    return { message, queue: queueView(chatId) };
  }

  /** Take a queued message back (the x on it). A message already being delivered cannot be taken back. */
  function cancelQueued({ chatId, id }) {
    const list = queues.get(chatId) ?? [];
    const at = list.findIndex(m => m.id === id);
    if (at < 0) throw new AgentUnavailable('That message was already sent or removed.', 'queue-gone');
    const [item] = list.splice(at, 1);
    if (!list.length) queues.delete(chatId);
    onQueue(chatId, queueView(chatId));
    chats.get(chatId)?.turn?.announceQueue?.({ type: 'queued-message', state: 'cancelled', message: { id: item.id, text: item.text, at: item.at, deliverAt: item.deliverAt }, queue: queueView(chatId) });
    return { queue: queueView(chatId) };
  }

  /** Messages waiting for a chat, and (after a goal ended while the page was away) the ones it should now send. */
  function takeQueue(chatId, { release = false } = {}) {
    const turn = chats.get(chatId)?.turn;
    const list = queueView(chatId);
    if (release && !turn && list.length) { queues.delete(chatId); onQueue(chatId, []); return { queue: [], released: list.map(({ id, text }) => ({ id, text })) }; }
    return { queue: list, released: [] };
  }

  /**
   * The person changed the chat's mode while a turn (a goal and its helpers included) is running. The new preset
   * is put on the session at once, the running turn's own bookkeeping follows, and questions already waiting are
   * settled the way the new mode would have settled them: Bypass allows them, Plan rejects them.
   */
  async function setMode(chatId, mode) {
    const want = modeOf(mode);
    const c = chats.get(chatId);
    const sessionId = sessionMap[chatId]?.sessionId;
    if (!rt || !sessionId) return { applied: false, mode: want, reason: 'no session yet' };
    if (c?.turn && c.turn.mode === want) return { applied: true, mode: want, settled: 0 };
    await applyMode(rt, sessionId, want);
    let settled = 0;
    if (c?.turn) {
      c.turn.mode = want;
      c.turn.projector.policy = MODE_PRESETS[want].approval;
      if (want !== 'manual') {
        const helpers = c.turn.children;
        for (const [key, entry] of [...pending.entries()]) {
          if (entry.sessionId !== sessionId && !helpers?.has(entry.sessionId)) continue;
          pending.delete(key);
          try { await rt.gw.answerEvent({ clientId: entry.clientId ?? rt.clientId, eventId: entry.eventId, outcome: want === 'bypass' ? 'allowed-once' : 'rejected' }); settled++; } catch { /* already answered */ }
        }
      }
    }
    return { applied: true, mode: want, settled };
  }

  /** Answer one pending approval. `decision` is `approve` or `deny`. */
  async function approve({ chatId, callId, decision }) {
    const sessionId = sessionMap[chatId]?.sessionId;
    // A helper agent's question carries the helper's session id in front of its call id. Only a helper that belongs to
    // THIS chat's run can be answered from this chat.
    const [maybeChild] = String(callId).split(':');
    const ownHelper = callId.includes(':') && chats.get(chatId)?.turn?.children.has(maybeChild);
    const key = ownHelper ? callId : `${sessionId}:${callId}`;
    // The durable `approval/asked` (which makes the card say "needs approval") and the waterfall frame
    // (which makes it answerable) travel on different streams; a fast click can beat the second one.
    let entry = sessionId ? pending.get(key) : null;
    for (let i = 0; !entry && sessionId && i < 40; i++) {
      await new Promise(r => setTimeout(r, 50));
      entry = pending.get(key);
    }
    if (!entry) throw new AgentUnavailable('That question is no longer waiting for an answer.', 'approval-gone');
    if (!rt?.hp.running) throw new AgentUnavailable('That question expired because the coding assistant restarted. Ask again.', 'approval-gone');
    pending.delete(key);
    try {
      await rt.gw.answerEvent({ clientId: entry.clientId ?? rt.clientId, eventId: entry.eventId, outcome: decision === 'approve' ? 'allowed-once' : 'rejected' });
    } catch (e) {
      throw new AgentUnavailable('Your answer could not be delivered. Ask again.', 'approval-gone', e.message);
    }
    return { ok: true };
  }

  /**
   * Stop one chat's turn. Resolves only once the turn has ended (or the wait times out), because the
   * Harness acknowledges a cancel as admitted, not as done.
   */
  /** What the chat holds now and the model's window, as the context plugin measures them (null when it cannot be read). */
  async function contextOf(runtime, sessionId) {
    try {
      const r = await runtime.gw.rpc('commands/execute', { agentId: sessionId, line: '/strata-context', submittedAttachments: [] });
      if (r?.result?.kind !== 'success') return null;
      const v = JSON.parse(String(r.result.text));
      return Number.isFinite(v.tokens) ? { tokens: Math.round(v.tokens), window: Number(v.window) > 0 ? Math.round(v.window) : 0 } : null;
    } catch { return null; }
  }

  /** The decision of context-fit.mjs for the message about to be sent, or null when the model server cannot count it. */
  async function fitCheck({ runtime, route, sessionId, fresh, history, message }) {
    const inst = localInstances().find(i => i.id === route.instanceId);
    if (!inst || !(route.contextWindow > 0)) return null;
    const carried = fresh && history.length ? withEarlierConversation(history, message) : message;
    if (carried.length < COUNT_ABOVE_CHARS) return null;
    const count = text => countTokens({ baseUrl: inst.baseUrl, key: inst.key, model: inst.modelId, text });
    let tokens = await count(carried);
    if (tokens == null) return null;
    const now = fresh ? null : await contextOf(runtime, sessionId);
    const window = now?.window || route.contextWindow;
    const pressure = now?.tokens ?? 0;
    // Where the Harness starts summarising by itself on this window (profile.mjs: the reply keeps its room, then the headroom).
    const reply = localOutputBudget(window);
    const threshold = Math.floor(Math.min(window * 0.8, window - reply - compactionHeadroom(window, reply)));
    let verdict = decideFit({ window, pressure, messageTokens: tokens, threshold });
    // The earlier conversation carried into a fresh session is what pushed it over: send the message alone instead.
    if (verdict.action === 'too-large' && carried !== message) {
      const alone = await count(message);
      if (alone != null) { tokens = alone; verdict = decideFit({ window, pressure, messageTokens: alone, threshold }); }
    }
    return { ...verdict, tokens, window, pressure };
  }

  /**
   * Summarise the older part of a chat with the Harness's /compact and say what happened. Never throws.
   * ok:true carries the figures before and after; ok:false says why (nothing to summarise, busy, failed).
   */
  async function compactChat(runtime, sessionId) {
    const before = await contextOf(runtime, sessionId);
    let result;
    try { result = (await runtime.gw.rpc('commands/execute', { agentId: sessionId, line: '/compact', submittedAttachments: [] }))?.result; }
    catch (e) { return { ok: false, reason: /not.found|no such/i.test(String(e.message)) ? 'nothing' : 'failed', before, text: String(e.message ?? e) }; }
    const text = String(result?.text ?? '');
    log('agent · compact: ' + (result?.kind ?? 'none') + ' ' + text.slice(0, 140));
    if (result?.kind === 'success' && /^Compacted/i.test(text)) return { ok: true, before, after: await contextOf(runtime, sessionId) };
    if (result?.kind === 'success') return { ok: false, reason: 'nothing', before, text };
    if (/active compaction|not idle/i.test(text)) return { ok: false, reason: 'busy', before, text };
    // The Harness cannot make a summary smaller than what is left when the chat holds little beyond its first prompt: that is nothing to summarise, not a failure.
    const little = before && before.window > 0 && before.tokens - BASE_TOKENS < before.window * 0.25;
    return { ok: false, reason: little && /useful summary|not smaller/i.test(text) ? 'nothing' : 'failed', before, text };
  }

  /** The line in the chat that explains why the context meter fell: how full it was and how full it is. */
  function summarizedNote(before, after, window) {
    const w = after?.window || before?.window || window || 0;
    const pct = v => Math.max(0, Math.min(100, Math.round(100 * v.tokens / w)));
    const known = w > 0 && before && after;
    const template = known ? FIT_TEXT.summarized : FIT_TEXT.summarizedShort;
    const values = known ? [pct(before), pct(after)] : [];
    return { type: 'delta', own: true, text: '\n\n' + fill(template, values), key: template, values, noteReason: 'compacted' };
  }

  /** "/compact": summarise the older messages of this chat now, and say in plain words what happened. */
  async function compactCommand(options) {
    const { chatId, choice, signal } = options;
    const c = chat(chatId);
    const say = (template, values = []) => sayKey(options, template, values);
    if (c.turn || c.starting) return say(FIT_TEXT.compactBusy);
    const known = sessionMap[chatId]?.sessionId;
    if (!known) return say(FIT_TEXT.noChatYet);
    let runtime;
    try { ({ rt: runtime } = await ensureRuntime(choice, signal)); } catch { return say(FIT_TEXT.compactFailed); }
    const done = await compactChat(runtime, known);
    if (done.ok) {
      const note = summarizedNote(done.before, done.after, 0);
      return say(note.key, note.values);
    }
    if (done.reason === 'busy') return say(FIT_TEXT.compactBusy);
    if (done.reason === 'nothing') {
      const w = done.before?.window || 0;
      const pct = w > 0 && done.before ? Math.round(100 * done.before.tokens / w) : 0;
      return say(pct >= 60 ? FIT_TEXT.nothingFull : FIT_TEXT.nothingToSummarize, pct >= 60 ? [pct] : []);
    }
    return say(FIT_TEXT.compactFailed);
  }

  /** Summarise the older part of a session with the Harness's own /compact. Best effort: the next message compacts again by itself when it must. */
  async function compactSession(runtime, sessionId) {
    try {
      const r = await runtime.gw.rpc('commands/execute', { agentId: sessionId, line: '/compact', submittedAttachments: [] });
      log(`agent · compact after a stopped turn: ${r?.result?.kind ?? 'done'} ${String(r?.result?.text ?? '').slice(0, 120)}`);
    } catch (e) { log(`agent · compact after a stopped turn failed: ${e.message}`); }
  }

  async function stop(chatId, { waitMs = 20_000 } = {}) {
    const c = chats.get(chatId);
    const turn = c?.turn;
    if (!turn && c?.starting) { c.cancelStart = true; return { stopped: true, ended: 'cancelled-before-start', ms: 0 }; }
    if (!turn || !rt) return { stopped: false, reason: 'no active turn' };
    const t0 = Date.now();
    if (!turn.prompted) {
      // The Harness has not been given the prompt yet, so there is nothing to cancel there.
      turn.stopBeforePrompt = true;
      const early = await Promise.race([turn.ended.promise, new Promise(r => setTimeout(() => r(null), 100))]);
      if (early) return { stopped: true, ended: early.reason?.kind ?? 'aborted', ms: Date.now() - t0 };
    }
    turn.stopping = true;
    await pauseGoal(rt, turn.sessionId, chatId);
    // Helpers first: a helper still working would otherwise report back and wake the parent again.
    await Promise.allSettled([...turn.children.values()].filter(h => !h.done).map(h => rt.gw.rpc('subagents/interruptByParent', { childSessionId: h.id, parentSessionId: turn.sessionId, mode: 'continuable' })));
    await rt.gw.rpc('session/cancel', { request: { sessionId: turn.sessionId } }).catch(e => { if (turn.parentOpen) throw e; });
    // Nothing is running in the parent (it was waiting for its helpers): the run ends once they are all down.
    if (!turn.parentOpen) { clearTimeout(turn.settleTimer); turn.settleTimer = after(300, () => { if (!turn.finished && !turn.parentOpen && [...turn.children.values()].every(h => h.done)) turn.finish(null); }); }
    let timer; const result = await Promise.race([turn.ended.promise, new Promise(r => { timer = after(waitMs, () => r(null)); })]);
    clearTimeout(timer);
    if (!result) return { stopped: false, pending: true, reason: 'the turn is still stopping' };
    return { stopped: true, ended: result.reason?.kind ?? 'unknown', ms: Date.now() - t0 };
  }

  function pendingFor(chatId) {
    const sessionId = sessionMap[chatId]?.sessionId;
    const helpers = chats.get(chatId)?.turn?.children;
    return [...pending.values()].filter(p => p.sessionId === sessionId || helpers?.has(p.sessionId))
      .map(p => (p.sessionId === sessionId ? p : { ...p, callId: `${p.sessionId}:${p.callId}` })).map(({ callId, tool, reason, at }) => ({ callId, tool, reason, at }));
  }

  /** Every chat that has an approval waiting, for the task board: the chat, its working folder and what is waiting (same items as pendingFor). */
  function pendingAll() {
    if (!pending.size) return [];
    return Object.keys(sessionMap).map(chatId => ({ chatId, folder: sessionMap[chatId]?.cwd ?? null, pending: pendingFor(chatId) })).filter(c => c.pending.length);
  }

  async function close() {
    const r = rt; rt = null;
    if (r) { r.events?.close(); r.gw.close(); await r.hp.stop(); }
  }

  /** Let go of a chat's Harness session mapping (a task starts every run in a session of its own). */
  function forget(chatId) { if (chats.get(chatId)?.turn) return; delete sessionMap[chatId]; chats.delete(chatId); persist(); }

  return { compactCommand, goalState, goalControl, harnessDir, status, runTurn, goalCommand, planCommand, researchCommand, llmTarget, setPlanBriefing, resetSession, reopenPlan, skipStep, planGoal, planControl, planState, queueMessage, cancelQueued, takeQueue, forget, approve, setMode, stop, pendingFor, pendingAll, close, sessionOf: chatId => sessionMap[chatId]?.sessionId ?? null, workingFolder: chatId => sessionMap[chatId]?.cwd ?? null, isRunning: chatId => !!chats.get(chatId)?.turn, _debug: () => ({ rt, sessionMap }) };
}

/** A goal that stopped by itself, in words. */
export function plainBlocker(reason) {
  if (!reason) return 'it could not go on.';
  if (reason.code === 'round-limit') return 'it worked for the most steps it was allowed. Type /goal clear, then start a new goal to go on.';
  return String(reason.message ?? 'it could not go on.');
}

/** What a goal run says when it ends. */
export function goalEnding(view) {
  if (view.phase === 'complete') return '\n\n*The goal is complete.*';
  if (view.phase === 'blocked') return `\n\n*The goal stopped: ${plainBlocker(view.blockedReason)}*`;
  if (view.phase === 'paused') return '\n\n*The goal is paused. Type /goal resume to go on.*';
  return '';
}

/** A goal request the Harness refused, as a sentence. */
export function plainGoalError(e) {
  const message = String(e?.message ?? e);
  if (/already|unfinished|current goal/i.test(message)) return 'This chat already has a goal that is not finished. Type /goal edit to change it, /goal clear to remove it, or /goal to see it.';
  if (/GOAL_NONE|no goal/i.test(message) || e?.code === 'goal-none') return 'There is no goal to continue. Start one with /goal followed by what you want done.';
  if (/objective/i.test(message)) return 'A goal needs a few words about what you want done, for example: /goal make every test pass.';
  return 'The goal could not be changed right now. Try again in a moment.';
}

/** The Harness session of a chat that existed before the agent did knows nothing; carry a bounded summary. */
export function withEarlierConversation(history, message) {
  const rows = history.filter(m => (m.role === 'user' || m.role === 'assistant') && typeof m.content === 'string' && m.content.trim()).slice(-12);
  if (!rows.length) return message;
  const text = rows.map(m => `${m.role}: ${m.content.length > 1500 ? `${m.content.slice(0, 1499)}…` : m.content}`).join('\n');
  return `Earlier in this conversation, before you were given tools:\n${text}\n\nCurrent message:\n${message}`;
}