Skip to content

The open source AI video agent: turns any coding agent into a video agent, with an editor to change anything it makes.

84.7 KB
Raw Blame
/**
 * The chat's agents: the person's own Claude Code, Codex, GitHub Copilot, Cursor, OpenCode, CodeBuddy, Qwen Code,
 * Kimi, MiniMax Code or DeepSeek Harness, driven over the Agent Client Protocol (ACP): a child process speaking
 * JSON-RPC over stdin/stdout.
 * The app is the client: initialize, session/new (or session/resume for a conversation from before), session/prompt;
 * session/update draws the chat, and session/request_permission asks the person in the chat.
 *
 * Claude Code and Codex speak it through their makers' official adapters (`@agentclientprotocol/claude-agent-acp`,
 * `@agentclientprotocol/codex-acp`, Apache-2.0), which the app carries; the others speak it themselves (`qwen --acp`,
 * `opencode acp`, …), as the ACP registry (agentclientprotocol.com/registry) starts them.
 *
 * Why the person's own installation, never one bundled with the app:
 *   · size: each official program is 200–330 MB; the adapters are a few MB and take its path
 *     (`CLAUDE_CODE_EXECUTABLE`, `CODEX_PATH`);
 *   · terms: Anthropic lets people use their own subscription in the unmodified Claude Code, and does not let anyone
 *     else hold or pass on their credentials. The app runs their own program, sign-in is its own (`claude auth login`
 *     in Terminal, or a command window on Windows; Codex in Codex itself), and the app never sees a token.
 *
 * Each uses the account its own program is signed in to, which is not always its maker's app's: Claude Code keeps its
 * own sign-in (`claude auth`), apart from the Claude app's, even the copy inside that app. One with a sign-out command
 * (`logout`) switches account from Settings → Agents (agent-roster.mjs switchAccount); the others in the agent itself,
 * or its maker's app where they share it (Codex, DeepSeek Harness).
 *
 * The agent works the way it would in a terminal: in the project's folder, with the `openfilm` command on its PATH
 * (this app's copy, so its Studio is the one in the window) and a few lines saying where it is (INSTRUCTIONS).
 *
 * Reads no Electron module, so `node --test` can use it.
 */
import { execFile, spawn } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
import { arch, homedir, release, tmpdir } from 'node:os';
import { createRequire } from 'node:module';
import { dirname, isAbsolute, join, win32 } from 'node:path';
import { Readable, Writable } from 'node:stream';
import { fileURLToPath, pathToFileURL } from 'node:url';
import * as acp from '@agentclientprotocol/sdk';
import { PATH_SEP, childEnvironment, lastPathSource, loginShellEnvironment, loginShellVariables, shellSubset } from './environment.mjs';
import { AGENT_PROGRAMS, HOME_BIN_CANDIDATES, chosenProgram, claudeUpdate, claudeVersion, codexAppCopies, codexVersion, desktopApp, detectAgentInstallation, installCommand, laterVersion, notTheAgent, searchReport } from './agent-installation.mjs';
import { logSwitches } from './agent-logs.mjs';
import { afterFirstReading, firstWindowsApps, refreshWindowsApps } from './windows-apps.mjs';
import { mergeConfig, sessionSkills } from './agent-skills.mjs';
import { nodeBinary } from './node-runtime.mjs';
import { outOfBalance } from './pi-config.mjs';
import { AGENT_DEFINITIONS } from './agent-definitions.mjs';

const require = createRequire(import.meta.url);

/**
 * Each agent: through an adapter the app carries (`adapter`, told where the person's program is by `env`), or the
 * person's program itself with `args`. Signed in? `auth` asks the program (its words say); without it, a session is
 * opened and closed (acpSignedIn). `login` is its own sign-in, run in Terminal (none: the program itself, which asks
 * for one on its first run; null: signed in in the program or its maker's app, never from here, so one found is
 * connected). `logout`: its own sign-out, run here with no window (signOutAgent), so Switch account can sign in to
 * another account; none for an agent that has no such command, or one that asks which account (OpenCode).
 * `authenticate`: the ACP auth method that takes up the program's own sign-in.
 * `approve`: it asks permission for what the app lets every agent do (see the chat's AGENT_FORCED_PREFS), so the app
 * answers yes itself. The others are told the app's INSTRUCTIONS in the first message of a session (`systemPrompt`:
 * how Claude Code and Codex are told them instead).
 */
export const AGENTS = Object.freeze({
  claude: {
    label: AGENT_DEFINITIONS.claude.name,
    adapter: '@agentclientprotocol/claude-agent-acp',
    env: (path) => ({ CLAUDE_CODE_EXECUTABLE: path }),
    auth: ['auth', 'status'],
    login: ['auth', 'login'],
    logout: ['auth', 'logout'],
    /* of the shell only its PATH, proxies, config folder and locale, as 0.1.5 had it: a key or
       gateway set there (ANTHROPIC_*) would take the place of the person's Claude subscription */
    fromShell: shellSubset,
    /* signed in to the person's Claude subscription, the way its adapter offers it (ACP terminal auth), in Terminal */
    acpSignIn: 'claude-ai-login',
    systemPrompt: true,
  },
  codex: {
    label: AGENT_DEFINITIONS.codex.name,
    adapter: '@agentclientprotocol/codex-acp',
    env: (path) => codexLaunchEnv(path),
    /* asked only for whose account it is: Codex is signed in in Codex (its app, or `codex login`) */
    auth: ['login', 'status'],
    login: null,
    systemPrompt: true,
  },
  copilot: { label: AGENT_DEFINITIONS.copilot.name, args: ['--acp', '--allow-all'], login: ['login'], approve: true },
  cursor: { label: AGENT_DEFINITIONS.cursor.name, args: ['--force', 'acp'], auth: ['status'], login: ['login'], logout: ['logout'], authenticate: 'cursor_login', approve: true },
  opencode: { label: AGENT_DEFINITIONS.opencode.name, args: ['acp'], login: ['auth', 'login'], approve: true },
  /* CodeBuddy is the China edition unless the person's shell says otherwise: the program itself defaults to the
     international site (www.codebuddy.ai) whichever site it was signed in on, out of reach from China */
  codebuddy: { label: AGENT_DEFINITIONS.codebuddy.name, args: ['--acp', '--permission-mode', 'bypassPermissions'], login: [], approve: true,
    defaults: { CODEBUDDY_INTERNET_ENVIRONMENT: 'internal' } },
  qwen: { label: AGENT_DEFINITIONS.qwen.name, args: ['--acp', '--approval-mode', 'yolo'], login: [], approve: true },
  kimi: { label: AGENT_DEFINITIONS.kimi.name, args: ['acp'], login: ['login'], approve: true },
  minimax: { label: AGENT_DEFINITIONS.minimax.name, args: ['acp'], login: ['login'], logout: ['logout'], approve: true },
  /* DeepSeek Harness (`dsh`) speaks ACP as its `acp` profile. It has no sign-in command: the person signs in to their
     DeepSeek account in its desktop app, or sets DEEPSEEK_API_KEY, so one found is connected. It reports every tool
     as kind `other`, titled by its name: `toolKinds` gives each the kind it is (see withToolKind) */
  deepseek: { label: AGENT_DEFINITIONS.deepseek.name, args: ['--profile', 'acp'], login: null, approve: true,
    toolKinds: {
      bash: 'execute', pwsh: 'execute',
      read: 'read', read_image: 'read',
      write: 'edit', edit: 'edit', str_replace_editor: 'edit',
      grep: 'search', glob: 'search',
      web_search: 'fetch', web_fetch: 'fetch',
    } },
});

/**
 * A tool call with the kind its name says (`toolKinds`), for an agent that reports every tool as `other`. The chat
 * draws an `other` call as the passing "Working" status, not a step: without its kind, a turn shows no step until
 * it ends.
 */
export function withToolKind(update, toolKinds) {
  if (!toolKinds || update?.sessionUpdate !== 'tool_call' || (update.kind ?? 'other') !== 'other') return update;
  const kind = Object.hasOwn(toolKinds, update.title) ? toolKinds[update.title] : null;
  return kind ? { ...update, kind } : update;
}

export const isAgentId = (id) => typeof id === 'string' && Object.hasOwn(AGENTS, id);

/** The variables an agent is started with (`defaults`) that the person's shell does not set itself. */
export function agentDefaults(id, shell = {}) {
  return Object.fromEntries(Object.entries(AGENTS[id]?.defaults ?? {}).filter(([key]) => !Object.hasOwn(shell, key)));
}

/** The app's own agent: Pi (pi-agent.mjs), on the person's own key (agent-roster.mjs). */
export const HARNESS_AGENTS = Object.freeze(['byok']);
export const isChatAgent = (id) => isAgentId(id) || HARNESS_AGENTS.includes(id);

/** How the person points at things in Studio, and how the agent points back: told to every agent, the app's own too. */
export const STUDIO_REFERENCES = `When the person mentions something in Studio, they may name a clip, a page or a moment (as seconds); find it in
film.html and the project's files.

In your replies you can point at things in Studio for the person: [[clip:ID]] (a clip, by its id in film.html),
[[t:SECONDS]] (a moment), [[range:START-END]] (a stretch, in seconds), [[track:N]] (a track, 0 is the first) and
[[file:PATH]] (a file of the project). They show as links that open it in Studio.`;

/** What the agent is told about where it is, on top of its own instructions. */
export const INSTRUCTIONS = `You are working inside OpenFilm, a desktop app for making videos. Beside this chat the person sees OpenFilm Studio,
the video editor, showing the project in your working directory; it updates live as you save files.

The project is an OpenFilm film: pages with window.film, cut together by film.html. Before you change anything, run
\`openfilm\` with no arguments and read the manual it prints; follow it. Use the \`openfilm\` command on your PATH (this
app's own, on the Studio beside you), not \`npx openfilm\`, whatever a skill says. Studio is already open on this
project: you never need \`openfilm open\` and never open Studio in a browser. Run \`openfilm look\` after each change
to see what you made. Render the MP4 only when the person asks for it; they can also export from Studio. Reply in the
language the person writes in.

${STUDIO_REFERENCES}`;

/**
 * The app's own agent's whole system prompt, in place of Pi's (a coding assistant's, with Pi's own docs): who it is,
 * where it is and how it works with the person (agent-prompt.md: written for it, so not INSTRUCTIONS, which tell
 * another agent to go and read the manual), how the person points at Studio (STUDIO_REFERENCES), and the manual
 * `openfilm` prints, so it starts knowing it. Each thing is said once: what the manual says (`openfilm get`'s
 * services, rendering, the person's changes) and what Pi's tools say of themselves are not said again.
 */
export function ownAgentPrompt() {
  const prompt = readFileSync(new URL('./agent-prompt.md', import.meta.url), 'utf8').trim();
  const manual = readFileSync(join(dirname(require.resolve('openfilm/package.json')), 'MANUAL.md'), 'utf8').replaceAll('npx openfilm', 'openfilm').trim();
  return `${prompt}\n\n## Pointing at Studio\n\n${STUDIO_REFERENCES}\n\n<manual>\n${manual}\n</manual>`;
}

/**
 * The person's own `developer_instructions` in Codex's config.toml (top level), or null: the app's instructions go to
 * Codex in the same place, which would otherwise take the place of theirs, so theirs come first. Read for the basic
 * and literal strings TOML has, on one line or several; anything else (a profile's, a key it cannot read) is left.
 */
export function codexDeveloperInstructions(toml) {
  const top = String(toml ?? '').split(/^\s*\[/m)[0];
  const m = /^[ \t]*developer_instructions[ \t]*=[ \t]*("""|'''|"|')/m.exec(top);
  if (!m) return null;
  const quote = m[1];
  const rest = top.slice(m.index + m[0].length);
  /* a basic string on one line ends at its first quote not escaped; the others at their closing quotes */
  const end = quote === '"' ? (/^(?:[^"\\\n]|\\.)*"/.exec(rest)?.[0].length ?? 0) - 1 : rest.indexOf(quote);
  if (end < 0) return null;
  let text = rest.slice(0, end);
  if (quote.length === 3) text = text.replace(/^\r?\n/, '');
  if (quote.startsWith('"')) {
    text = text.replace(/\\(?:u([0-9a-fA-F]{4})|(.))/g, (_, hex, c) => (hex ? String.fromCharCode(parseInt(hex, 16))
      : ({ n: '\n', t: '\t', r: '\r', '"': '"', '\\': '\\' })[c] ?? c));
  }
  return text.trim() || null;
}

/** Codex's config.toml: in CODEX_HOME when the person's shell sets it, else ~/.codex. */
function codexConfigText(shell) {
  try { return readFileSync(join(shell.CODEX_HOME || join(homedir(), '.codex'), 'config.toml'), 'utf8'); } catch { return ''; }
}

/** The programs the person chose for their agents (Settings → Agents → Locate, agent-roster.mjs), by agent. */
let chosenPaths = {};
export function setChosenPaths(paths) {
  chosenPaths = Object.fromEntries(Object.entries(paths ?? {}).filter(([id, path]) => isAgentId(id) && typeof path === 'string' && path));
}

const windows = process.platform === 'win32';

/**
 * How the Codex adapter is told where Codex is. On Windows it starts it through cmd.exe, whose own messages (a program
 * not found, access refused) are in the console's code page, which the adapter reads as UTF-8: on a Chinese Windows
 * the reason came out as `������`. There Codex is started through a script that turns the console to UTF-8 first, made
 * on disk (the app's own files are in an archive cmd.exe cannot run from); Codex's own messages are UTF-8 already.
 */
export const CODEX_UTF8_CMD = '@echo off\r\nchcp 65001 >nul\r\n"%OPENFILM_CODEX%" %*\r\n';
export function codexLaunchEnv(/** @type {string} */ path, { win = windows, dir = join(tmpdir(), 'openfilm-codex') } = {}) {
  if (!win) return { CODEX_PATH: path };
  try {
    const script = join(dir, 'codex-utf8.cmd');
    if (!existsSync(script) || readFileSync(script, 'utf8') !== CODEX_UTF8_CMD) {
      mkdirSync(dir, { recursive: true });
      writeFileSync(script, CODEX_UTF8_CMD);
    }
    return { CODEX_PATH: script, OPENFILM_CODEX: path };
  } catch {
    /* no room for the script: Codex as before, its reasons maybe unreadable */
    return { CODEX_PATH: path };
  }
}
/** what the slower search found last (Windows): npm's global folder */
let slowFound = { npmPrefix: null };
let slowCache = null;
const SLOW_FOR_MS = 10 * 60_000;

/**
 * Windows only, and only when an agent is not found the quick way: where npm puts global commands (a prefix of the
 * person's own that is not on their PATH). Asked again after ten minutes, or at once with `fresh`.
 */
function windowsSlowSearch({ fresh = false } = {}) {
  if (!windows) return Promise.resolve(slowFound);
  if (slowCache && !fresh && Date.now() - slowCache.at < SLOW_FOR_MS) return slowCache.value;
  const value = (async () => {
    const env = childEnvironment({ shell: await loginShellEnvironment() });
    const npm = await run(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', 'npm prefix -g'], 15_000, { env });
    const prefix = npm.ok ? npm.stdout.trim().split(/\r?\n/).pop()?.trim() : null;
    slowFound = { npmPrefix: prefix && isAbsolute(prefix) ? prefix : null };
    return slowFound;
  })().catch(() => slowFound);
  slowCache = { at: Date.now(), value };
  return value;
}

/**
 * The slower search and the apps Windows has registered, waited for three seconds at most: what comes later is there on
 * the next look. The first reading of the registrations is waited for however long it takes (it holds nothing): the
 * chat asks for the agents once as it loads, and one known only from its registration would stay not installed there.
 */
const windowsSlowerLook = () => Promise.all([
  firstWindowsApps(),
  Promise.race([Promise.all([windowsSlowSearch(), refreshWindowsApps()]), new Promise((done) => setTimeout(done, 3000).unref?.())]),
]);

/** Where this agent was looked for, beyond the PATH. */
const searchDirs = () => [...HOME_BIN_CANDIDATES(), ...(slowFound.npmPrefix ? [slowFound.npmPrefix] : [])];

/**
 * The person's program for this agent: the one they chose; else on their login shell's PATH (on Windows, the PATH the
 * registry has now), in the folders installers use, or inside the maker's app. `source`: chosen · path · app.
 */
export function resolveAgentCli(id, { pathDirs = [] } = {}) {
  if (!isAgentId(id)) return null;
  const found = detectAgentInstallation(id, {
    env: { PATH: pathDirs.join(PATH_SEP) },
    pathDirs: searchDirs(),
    chosen: chosenPaths[id] ?? null,
  });
  return found.cli ? { path: found.cli, source: found.source } : null;
}

/** resolveAgentCli, for starting, signing in or out: right after launch, it waits for Windows' registrations when the program is not found without them. */
const findAgentCli = (id, options) => afterFirstReading(() => resolveAgentCli(id, options));

function run(cmd, args, timeoutMs = 10_000, { cwd, env, options } = {}) {
  return new Promise((resolve) => {
    try {
      execFile(cmd, args, { timeout: timeoutMs, encoding: 'utf8', windowsHide: true, ...options, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}) }, (error, stdout, stderr) => {
        resolve({ ok: !error, out: `${stdout ?? ''}\n${stderr ?? ''}`, stdout: stdout ?? '' });
      });
    } catch (e) {
      /* a program Windows cannot start that way (EINVAL) */
      resolve({ ok: false, out: e instanceof Error ? e.message : String(e), stdout: '' });
    }
  });
}

/**
 * One word of a cmd.exe command line: quoted when it has to be. cmd.exe expands `%NAME%` inside quotes too, so each `%`
 * is closed out of the quotes and escaped (`"^%"`): the program is given the word as it was, with no variable's value
 * in it.
 */
export const winArg = (a) => (/^[\w.:\\/=+@-]+$/.test(a) ? a : `"${String(a).replace(/"/g, '""').replace(/%/g, '"^%"')}"`);

/** The app's own Node running a script, through as-node.mjs: what the script starts does not run Electron as Node. */
const AS_NODE = fileURLToPath(new URL('./as-node.mjs', import.meta.url));
/** The words before a script that start it on the app's own Node: as-node.mjs first, the script as the main module. */
const asNode = (/** @type {string} */ script) => ['--import', pathToFileURL(AS_NODE).href, script];

/**
 * How to start a program found for an agent: itself, a script with the app's own Node (an npm install on Windows), or
 * a `.cmd` shim whose target could not be told, through cmd.exe. `options` go to spawn.
 */
function starting(cliPath, args) {
  if (/\.(?:c|m)?js$/i.test(cliPath)) return { cmd: nodeBinary(), args: [...asNode(cliPath), ...args], env: { ELECTRON_RUN_AS_NODE: '1' }, options: {} };
  if (windows && /\.(?:cmd|bat)$/i.test(cliPath)) {
    return { cmd: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', `"${[cliPath, ...args].map(winArg).join(' ')}"`], env: {}, options: { windowsVerbatimArguments: true } };
  }
  return { cmd: cliPath, args, env: {}, options: {} };
}

/** Why a program is not the agent (notTheAgent), in words. */
const NOT_THE_AGENT = Object.freeze({
  app: 'This is an editor or a desktop app, not the agent\'s command-line program.',
  'not-cursor-agent': 'This is not Cursor\'s command-line agent, which installs in a cursor-agent folder.',
});

/**
 * A program the person chose for an agent, tried: it has to start and answer `--version`. `{ ok, version }`, or why
 * not: `code` 'not-a-program' (nothing there this computer can start), 'app' or 'not-cursor-agent' (not the agent:
 * an editor or a desktop app, never started) or 'did-not-start' (with what it said).
 */
export async function checkAgentProgram(id, path) {
  const spec = AGENTS[id];
  if (!spec) return { ok: false, error: `No agent ${id}`, code: 'not-a-program' };
  const cli = chosenProgram(path, { names: AGENT_PROGRAMS[id]?.names ?? [id] });
  if (!cli) return { ok: false, error: 'That is not a program this computer can start.', code: 'not-a-program' };
  const refused = notTheAgent(id, cli, { chosen: path });
  if (refused) return { ok: false, error: NOT_THE_AGENT[refused], code: refused };
  const how = starting(cli, ['--version']);
  const r = await run(how.cmd, how.args, 20_000, { env: childEnvironment({ shell: await loginShellVariables(), extra: how.env }), options: how.options });
  if (!r.ok) return { ok: false, error: r.out.trim().slice(0, 400), code: 'did-not-start' };
  return { ok: true, path: cli, version: r.stdout.trim().split(/\r?\n/)[0] ?? '' };
}

/** Where in WSL (Linux on Windows) one of these programs is, or null: there the app cannot use it. */
async function inWsl(names) {
  const wsl = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'wsl.exe');
  if (!existsSync(wsl)) return null;
  const r = await run(wsl, ['-e', 'bash', '-lic', names.map((n) => `command -v ${n}`).join(' || ')], 15_000);
  return r.stdout.replace(/\0/g, '').split(/\r?\n/).map((l) => l.trim()).find((l) => /^\/\S+$/.test(l)) ?? null;
}

/**
 * Why an agent is or is not found, for the person to read or send with an issue: the PATH and where it came from, the
 * program chosen, every folder searched, each file there with the agent's name and what it runs; on Windows, npm's
 * global folder and whether it is in WSL instead. `hint`, when it is not found: chosen-missing (the program chosen is
 * gone) · wsl (only in WSL) · unusable (files with its name, none that starts) · none.
 */
export async function diagnoseAgent(id, { appVersion = '' } = {}) {
  const spec = AGENTS[id];
  if (!spec) return null;
  const shell = await loginShellEnvironment({ maxAgeMs: 0 });
  const [slow] = await Promise.all([windowsSlowSearch({ fresh: true }), refreshWindowsApps({ maxAge: 0 })]);
  const pathDirs = shell.PATH.split(PATH_SEP);
  const found = resolveAgentCli(id, { pathDirs });
  const names = AGENT_PROGRAMS[id]?.names ?? [id];
  const report = searchReport(id, { env: { PATH: shell.PATH }, pathDirs: searchDirs() });
  const wsl = windows && !found ? await inWsl(names) : null;
  const chosen = chosenPaths[id] ?? null;
  const hint = found ? null : chosen ? 'chosen-missing' : wsl ? 'wsl' : report.files.length ? 'unusable' : 'none';
  const lines = [
    `OpenFilm ${appVersion}`.trim(),
    `Agent: ${spec.label} (${names.join(', ')})`,
    `System: ${process.platform} ${release()} ${arch()}`,
    `PATH from: ${lastPathSource() ?? 'unknown'}`,
    `Chosen: ${chosen ?? '(none)'}`,
    `Found: ${found ? `${found.path} (${found.source})` : '(not found)'}`,
    `Desktop app: ${desktopApp(id) ?? '(not found)'}`,
    ...(windows ? [
      `npm global folder: ${slow.npmPrefix ?? '(unknown)'}`,
      ...(id === 'codex' ? [`Codex the Codex app starts: ${codexAppCopies()[0] ?? '(none)'}`] : []),
      `In WSL: ${found ? '(not checked)' : wsl ?? '(no)'}`,
    ] : []),
    '',
    `Files named ${names.join(', ')}:`,
    ...(report.files.length ? report.files.map((f) => `  ${f.file}${f.runs && f.runs !== f.file ? ` -> ${f.runs}` : ''}${f.refused ? ` (not the agent: ${f.refused})` : f.usable ? '' : ' (cannot be started)'}`) : ['  (none)']),
    '',
    `Folders searched (${report.searched.length}):`,
    ...report.searched.map((d) => `  ${d}`),
  ];
  return { found: found?.path ?? null, program: names[0], hint, text: lines.join('\n') };
}

/**
 * Signed in? Asked of the program itself: true / false, or null when it cannot say (an older version). One that has
 * no command for it is asked by opening a session (acpSignedIn).
 */
export async function agentSignedIn(id, cliPath) {
  return (await agentStatus(id, cliPath)).signedIn;
}

/**
 * Signed in, and as whom, asked of the program: `account` is what it says of its sign-in (Claude Code: email,
 * organization, plan; Codex: how, ChatGPT or an API key), never a key or a token.
 * @returns {Promise<{ signedIn: boolean | null, account: AgentAccount | null, problem?: string }>}
 */
export async function agentStatus(id, cliPath, { fresh = false } = {}) {
  const spec = AGENTS[id];
  if (!spec || !cliPath) return { signedIn: null, account: null };
  if (!spec.auth) return { signedIn: await acpSignedIn(id, { fresh }), account: null };
  const how = starting(cliPath, spec.auth);
  const r = await run(how.cmd, how.args, 10_000, { env: childEnvironment({ shell: agentShell(id, await loginShellVariables()), extra: how.env }), options: how.options });
  return readAgentStatus(id, r.stdout, r.out);
}

/**
 * @typedef {{ method: 'claude.ai' | 'console' | 'api-key' | 'chatgpt' | 'other', email?: string, org?: string, plan?: string }} AgentAccount
 * What a sign-in status says: Claude Code's JSON, Codex's words. @param {string} id @param {string} stdout @param {string} out
 * `problem`: why it could not say, when that is something the person can fix (its settings it cannot read).
 * @returns {{ signedIn: boolean | null, account: AgentAccount | null, problem?: string }}
 */
export function readAgentStatus(id, stdout, out) {
  if (id === 'claude') {
    try {
      const s = JSON.parse(stdout);
      if (typeof s.loggedIn !== 'boolean') return { signedIn: null, account: null };
      if (!s.loggedIn) return { signedIn: false, account: null };
      const method = s.authMethod === 'claude.ai' ? 'claude.ai' : /api.?key/i.test(String(s.authMethod)) ? 'api-key' : s.authMethod === 'console' ? 'console' : 'other';
      const text = (/** @type {unknown} */ v) => (typeof v === 'string' && v.trim() ? v.trim() : undefined);
      return { signedIn: true, account: { method, email: text(s.email), org: text(s.orgName), plan: text(s.subscriptionType) } };
    } catch { /* not JSON: read the words */ }
  }
  /* settings it cannot read (a value only a later version knows): it can't say, nor start a session, until fixed */
  const broken = /error loading config(?:uration)?\b[:\s]*(.*)/i.exec(out);
  if (broken) return { signedIn: null, account: null, problem: broken[0].trim().slice(0, 500) };
  if (/\bnot logged in\b/i.test(out)) return { signedIn: false, account: null };
  if (/\blogged in\b/i.test(out)) {
    const method = /chatgpt/i.test(out) ? 'chatgpt' : /api key/i.test(out) ? 'api-key' : 'other';
    /* Cursor: "✓ Logged in as [email protected]" */
    const email = /\blogged in as\s+([^\s@]+@[^\s@]+\.[^\s@]+)/i.exec(out)?.[1];
    return { signedIn: true, account: { method, ...(email ? { email } : {}) } };
  }
  return { signedIn: null, account: null };
}

/**
 * What a session opened only to ask found, for a while: the roster asks again every few seconds. Signed in is kept
 * longer: each ask starts the agent (CodeBuddy leaves a stale file for each one it is stopped at once), and a sign-out
 * is learnt anyway, from a message refused for it (noteSignedOut) or when the person signs in from Settings.
 */
const asked = new Map();
/** Explicit settings refresh: the next sign-in/options check must read the current configuration. */
export function forgetAgentStatus(id) { asked.delete(id); }
const ASKED_FOR_MS = 15_000;
const SIGNED_IN_FOR_MS = 10 * 60_000;

/**
 * The folder a session opened only to ask (signed in? its options?) runs in: an empty one of the app's, the same each
 * time. Not the home folder: an agent takes the folder it runs in for a project, keeping a record of it and reading
 * its instructions files.
 */
export function probeFolder() {
  const dir = join(tmpdir(), 'openfilm-agent-probe');
  mkdirSync(dir, { recursive: true });
  return dir;
}

/**
 * Signed in, for an agent with no command that says: a session opened (in an empty folder of the app's) and closed.
 * One it refuses for its sign-in (ACP's auth_required) is signed out; one that opens, signed in; anything else, null.
 */
export function acpSignedIn(id, { fresh = false } = {}) {
  const kept = asked.get(id);
  // A sign-in just completed in Terminal: bypass a cached negative result, but share an in-flight probe.
  if (kept && (kept.pending || ((!fresh || kept.signedIn) && Date.now() - kept.at < (kept.signedIn ? SIGNED_IN_FOR_MS : ASKED_FOR_MS)))) return kept.answer;
  const answer = (async () => {
    const session = new AgentSession({ agent: id, cwd: probeFolder() });
    try {
      let timeout;
      try { await Promise.race([session.start(), new Promise((_, fail) => { timeout = setTimeout(() => fail(new Error('timed out')), 30_000); })]); }
      finally { clearTimeout(timeout); }
      return true;
    } catch (e) {
      return e?.code === 'sign-in' ? false : null;
    } finally {
      session.close();
    }
  })();
  const entry = { at: Date.now(), answer, signedIn: false, pending: true };
  asked.set(id, entry);
  void answer.then((yes) => { entry.signedIn = yes === true; entry.pending = false; entry.at = Date.now(); });
  return answer;
}

/**
 * A message refused for the agent's sign-in (Kimi opens a session signed out, and says so only when it is spoken to):
 * signed out from now on, until its sign-in is opened.
 */
function noteSignedOut(id) {
  asked.set(id, { at: Infinity, answer: Promise.resolve(false) });
}

const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;

/**
 * The AppleScript that has Terminal run one command in a new window, in `cwd` when given (SIGN_IN_DIR: not the home
 * folder a new window opens in).
 */
export function signInScript(cliPath, args, { cwd, track = false } = {}) {
  return terminalScript(`${cwd ? `cd ${shq(cwd)} && ` : ''}${[cliPath, ...args].map(shq).join(' ')}`, { track });
}

/** The AppleScript that has Terminal run a command line, as it is, in a new window. */
export function terminalScript(command, { track = false } = {}) {
  return `tell application "Terminal"\nactivate\n${track ? 'set loginTab to ' : ''}do script "${command.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"\n${track ? 'return tty of loginTab\n' : ''}end tell`;
}

/** Check the exact login tab, including when other Terminal windows remain open. Never launch Terminal to check. */
export function terminalTabOpenScript(tty) {
  if (!/^\/dev\/tty[\w]+$/.test(tty)) throw new Error('Invalid terminal tty');
  return `if application "Terminal" is not running then return "closed"
tell application "Terminal"
repeat with terminalWindow in windows
repeat with terminalTab in tabs of terminalWindow
if tty of terminalTab is "${tty}" then return "open"
end repeat
end repeat
end tell
return "closed"`;
}

/**
 * A PowerShell script that names its window and runs one program (`& 'program' 'arg'…`, each in single quotes, as
 * PowerShell quotes): Windows sign-in. With a BOM, so Windows PowerShell reads a path with Chinese in it as UTF-8.
 */
export function powerShellScript(title, cmd, args) {
  return powerShellLine(title, `& ${[cmd, ...args].map(psq).join(' ')}`);
}

/** The same for a command line as it is (an installer's). */
export function powerShellLine(title, line) {
  return `\ufeff$Host.UI.RawUI.WindowTitle = ${psq(title)}\r\n${line}\r\n`;
}
const psq = (s) => `'${String(s).replace(/'/g, "''")}'`;

/**
 * How a PowerShell window of its own is opened on Windows for a script file: through cmd.exe's `start`, which gives
 * it a console. Started straight from the app, `detached` makes it a DETACHED_PROCESS with no console at all, and
 * PowerShell quits at once without running the script.
 */
export function powerShellWindowLaunch(file, { comSpec = process.env.ComSpec || 'cmd.exe', systemRoot = process.env.SystemRoot ?? 'C:\\Windows', wait = false } = {}) {
  /* a Windows path wherever it is worked out (the tests run on every system) */
  const powershell = win32.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
  const line = ['start', '""', ...(wait ? ['/wait'] : []), ...[powershell, '-NoLogo', '-NoExit', '-ExecutionPolicy', 'Bypass', '-File', file].map(winArg)].join(' ');
  return { cmd: comSpec, args: ['/d', '/s', '/c', `"${line}"`], options: { windowsVerbatimArguments: true, windowsHide: true } };
}

/**
 * A PowerShell window of its own running a script (a sign-in, an installer), left open so what it says can be read
 * and answered.
 */
async function powerShellWindow(name, script, env, { track = false } = {}) {
  const dir = SIGN_IN_DIR();
  mkdirSync(dir, { recursive: true });
  const file = join(dir, track ? `${randomUUID()}-${name}` : name);
  writeFileSync(file, script, 'utf8');
  const how = powerShellWindowLaunch(file, { wait: track });
  const child = spawn(how.cmd, how.args, { cwd: dir, detached: true, stdio: 'ignore', env, ...how.options });
  await new Promise((done, fail) => { child.once('spawn', done); child.once('error', fail); });
  if (track) child.once('exit', () => { try { unlinkSync(file); } catch { /* already removed */ } });
  child.unref();
  return child;
}

/** The person's shell variables as this agent is given them (`fromShell`; all of them, for most). */
export function agentShell(id, shell) {
  return AGENTS[id]?.fromShell?.(shell) ?? shell;
}

/**
 * The ways an agent's adapter offers to sign in in a terminal (ACP terminal auth; Claude Code's: its subscription and
 * Anthropic Console). `[{ id, name, description?, args, env }]`, asked of the adapter as it shakes hands; none for an
 * agent signed in its own way (no `acpSignIn`) or one that cannot be started.
 */
export async function agentSignInMethods(id) {
  const spec = AGENTS[id];
  if (!spec?.acpSignIn) return [];
  const shell = agentShell(id, await loginShellVariables());
  const cli = await findAgentCli(id, { pathDirs: shell.PATH.split(PATH_SEP) });
  if (!cli) return [];
  const launch = adapterLaunch(id, cli.path);
  const child = spawn(launch.cmd, launch.args, { ...OWN_GROUP, env: childEnvironment({ shell, extra: launch.env }), stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
  child.once('error', () => {});
  try {
    const conn = acp.client({ name: 'openfilm-desktop' }).connect(acp.ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout)));
    const init = await Promise.race([
      conn.agent.request(acp.methods.agent.initialize, { protocolVersion: acp.PROTOCOL_VERSION, clientCapabilities: CLIENT_CAPABILITIES, clientInfo: CLIENT_INFO }),
      new Promise((_, fail) => setTimeout(() => fail(new Error('timed out')), 30_000)),
    ]);
    return (init.authMethods ?? []).filter((m) => m?.type === 'terminal' && m.id && m.name).map((m) => ({
      id: String(m.id), name: String(m.name), ...(m.description ? { description: String(m.description) } : {}),
      args: Array.isArray(m.args) ? m.args.map(String) : [], env: m.env && typeof m.env === 'object' ? m.env : {},
    }));
  } catch {
    return [];
  } finally {
    stopTree(child);
  }
}

/**
 * Where a sign-in in Terminal runs: an empty folder of the app's own. A program whose sign-in is the program itself
 * (CodeBuddy, Qwen Code) first asks whether to trust the folder it is in, and in the home folder a new Terminal window
 * opens in, warns that it may hold sensitive files; trusted once, this folder is not asked about again.
 */
const SIGN_IN_DIR = () => join(tmpdir(), 'openfilm-sign-in');

/**
 * Sign in: Terminal runs the program's own sign-in, which opens the maker's own page. The app touches nothing. One
 * signed in the way its adapter offers (`acpSignIn`, that way's id) runs the adapter with that way's arguments, as ACP
 * has a client do it. `track` adds an `isOpen` check for the roster, kept inside the main process.
 */
export async function openAgentSignIn(id, { track = false } = {}) {
  const spec = AGENTS[id];
  const pathDirs = (await loginShellEnvironment()).PATH.split(PATH_SEP);
  const cli = spec ? await findAgentCli(id, { pathDirs }) : null;
  if (!spec || !cli) return { ok: false, error: `${spec?.label ?? id} is not installed on this computer.` };
  if (spec.login === null) return { ok: false, error: `Sign in in ${spec.label} itself.` };
  asked.delete(id);
  let how = null;
  if (spec.acpSignIn) {
    const way = (await agentSignInMethods(id)).find((w) => w.id === spec.acpSignIn);
    if (!way) return { ok: false, error: `${spec.label} did not offer a way to sign in.` };
    const launch = adapterLaunch(id, cli.path);
    how = { cmd: launch.cmd, args: [...launch.args, ...way.args], env: { ...launch.env, ...way.env } };
  }
  /* signed in as it will be started (agentDefaults: CodeBuddy's China edition) */
  const defaults = agentDefaults(id, agentShell(id, await loginShellVariables()));
  if (!how && Object.keys(defaults).length && process.platform !== 'win32') how = { cmd: cli.path, args: spec.login, env: defaults };
  if (process.platform === 'win32') {
    /* a PowerShell window of its own running a script: no command line for cmd.exe to unquote (a path
       with a space in it), and left open so its sign-in can be read and answered (it runs a shim itself) */
    how ??= /\.(?:cmd|bat)$/i.test(cli.path) ? { cmd: cli.path, args: spec.login, env: {} } : starting(cli.path, spec.login);
    how = { ...how, env: { ...defaults, ...how.env } };
    try {
      const child = await powerShellWindow(`${id}.ps1`, powerShellScript(`${spec.label} sign-in`, how.cmd, how.args),
        childEnvironment({ shell: agentShell(id, await loginShellVariables()), extra: how.env }), { track });
      return { ok: true, ...(track ? { isOpen: async () => child.exitCode === null && child.signalCode === null } : {}) };
    } catch (e) { return { ok: false, error: e instanceof Error ? e.message : String(e) }; }
  }
  const cwd = SIGN_IN_DIR();
  try { mkdirSync(cwd, { recursive: true }); } catch { /* signed in from the home folder, as before */ }
  const where = { ...(existsSync(cwd) ? { cwd } : {}), track };
  const script = how
    ? signInScript('/usr/bin/env', [...Object.entries(how.env).map(([k, v]) => `${k}=${v}`), how.cmd, ...how.args], where)
    : signInScript(cli.path, spec.login, where);
  const r = await run('/usr/bin/osascript', ['-e', script], 15_000);
  if (!r.ok) return { ok: false, error: r.out.trim() || 'Terminal did not open.' };
  const tty = r.stdout.trim();
  return { ok: true, ...(track && /^\/dev\/tty[\w]+$/.test(tty) ? {
    isOpen: async () => {
      const checked = await run('/usr/bin/osascript', ['-e', terminalTabOpenScript(tty)], 5000);
      if (!checked.ok) return null;
      const state = checked.stdout.trim();
      return state === 'open' ? true : state === 'closed' ? false : null;
    },
  } : {}) };
}

/**
 * Sign out of an agent with its own command (`logout`), run here with no window: Switch account signs out, then opens
 * the agent's sign-in (openAgentSignIn). What it said is the error when it fails. Whether it is signed in is asked
 * afresh from then on.
 */
export async function signOutAgent(id) {
  const spec = AGENTS[id];
  if (!spec?.logout) return { ok: false, error: `${spec?.label ?? id} has no sign-out command: switch accounts in ${spec?.label ?? id} itself.` };
  const cli = await findAgentCli(id, { pathDirs: (await loginShellEnvironment()).PATH.split(PATH_SEP) });
  if (!cli) return { ok: false, error: `${spec.label} is not installed on this computer.` };
  const shell = agentShell(id, await loginShellVariables());
  const how = starting(cli.path, spec.logout);
  const r = await run(how.cmd, how.args, 30_000, { cwd: probeFolder(), env: childEnvironment({ shell, extra: { ...agentDefaults(id, shell), ...how.env } }), options: how.options });
  asked.delete(id);
  return r.ok ? { ok: true } : { ok: false, error: `${spec.label} did not sign out. ${r.out.trim().slice(0, 500)}`.trim() };
}

/**
 * Install an agent with its maker's official installer (installCommand), in a window the person sees: Terminal on a
 * Mac, PowerShell on Windows. The person agreed to that exact command in Settings → Agents first. Whether it worked is
 * learnt by looking for the agent again (agent-roster.mjs).
 */
export async function openAgentInstaller(id) {
  const spec = AGENTS[id];
  const command = spec ? installCommand(id) : null;
  if (!command) return { ok: false, error: `${spec?.label ?? id} has no installer to run here.` };
  if (windows) {
    try {
      await powerShellWindow(`${id}-install.ps1`, powerShellLine(`${spec.label} install`, command), childEnvironment({ shell: await loginShellVariables() }));
      return { ok: true };
    } catch (e) { return { ok: false, error: e instanceof Error ? e.message : String(e) }; }
  }
  const r = await run('/usr/bin/osascript', ['-e', terminalScript(command)], 15_000);
  return r.ok ? { ok: true } : { ok: false, error: r.out.trim() || 'Terminal did not open.' };
}

/**
 * The agents as they are on this machine, for the chat's picker. `setupRequired: 'code-tab'`: the Claude app is
 * here but has not downloaded Claude Code yet (opening its Code tab does). One not found: `app`, the maker's desktop
 * app when it is here without the agent's program; `installer`, the official command that installs it, when it has one.
 */
export async function listAgents({ ids = Object.keys(AGENTS), statusIds = ids, fresh = false, onAgent = () => {} } = {}) {
  const wanted = [...new Set(ids)].filter((id) => Object.hasOwn(AGENTS, id));
  if (!wanted.length) return [];
  /* looked at as the person comes back from installing one: a PATH from a few seconds ago at most */
  const pathDirs = (await loginShellEnvironment({ maxAgeMs: fresh ? 0 : 10_000 })).PATH.split(PATH_SEP);
  /* the slower search (Windows): waited for, a few seconds at most, when one is not found the quick way. What it finds
     later is there on the next look */
  return Promise.all(wanted.map(async (id) => {
    const checkSignIn = statusIds.includes(id);
    // Enabled agents start first. Background discovery never opens a disabled agent's ACP/auth session.
    if (!checkSignIn) await new Promise((done) => setImmediate(done));
    if (windows && !resolveAgentCli(id, { pathDirs })) {
      await windowsSlowerLook();
    }
    const agent = await agentOnComputer(id, pathDirs, { fresh, checkSignIn });
    onAgent(agent);
    return agent;
  }));
}

/** One agent as listAgents has it, asked alone when connecting, diagnosing or waiting for sign-in. */
export async function localAgent(id, { fresh = false } = {}) {
  if (!isAgentId(id)) throw new Error(`No agent ${id}`);
  const pathDirs = (await loginShellEnvironment({ maxAgeMs: 10_000 })).PATH.split(PATH_SEP);
  if (windows && !resolveAgentCli(id, { pathDirs })) {
    await windowsSlowerLook();
  }
  return agentOnComputer(id, pathDirs, { fresh });
}

async function agentOnComputer(id, pathDirs, { fresh = false, checkSignIn = true } = {}) {
  const cli = resolveAgentCli(id, { pathDirs });
  const install = AGENT_DEFINITIONS[id]?.install ?? null;
  const app = cli ? null : desktopApp(id);
  const claudeApp = id === 'claude' && Boolean(app);
  return {
    id,
    label: AGENTS[id].label,
    cli: cli ? { path: cli.path, source: cli.source } : null,
    chosen: chosenPaths[id] ?? null,
    ...(cli && checkSignIn ? ownSignIn(AGENTS[id], await agentStatus(id, cli.path, { fresh })) : { signedIn: null, account: null }),
    /* it signs out with its own command: Switch account signs in to another account from Settings */
    ...(cli && AGENTS[id].logout ? { signOut: true } : {}),
    /* older than the chat was tried with: Settings › Agents says so, with how to update it */
    ...(cli && id === 'claude' ? { outdated: claudeOutdated(cli.path) } : {}),
    install,
    setupRequired: claudeApp ? 'code-tab' : null,
    ...(cli ? {} : { app: claudeApp ? null : app, installer: installCommand(id) }),
  };
}

/** An agent signed in in its own program (`login: null`) is never signed out here: its account, if it says one. */
export function ownSignIn(spec, status) {
  return spec.login === null && status.signedIn === false ? { ...status, signedIn: null } : status;
}

/** The adapter's command line (its package's `bin`), run with Electron's own Node. */
function adapterScript(pkg) {
  const manifest = require.resolve(`${pkg}/package.json`);
  const json = JSON.parse(readFileSync(manifest, 'utf8'));
  const bin = typeof json.bin === 'string' ? json.bin : Object.values(json.bin ?? {})[0];
  return join(dirname(manifest), bin ?? json.main ?? 'index.js');
}

/** How an agent's adapter starts: the app's Node running its script (on Electron, through as-node.mjs), told where the person's program is. */
function adapterLaunch(id, cliPath) {
  const spec = AGENTS[id];
  const node = nodeRuntime();
  return {
    cmd: node.command,
    args: node.env.ELECTRON_RUN_AS_NODE ? asNode(adapterScript(spec.adapter)) : [adapterScript(spec.adapter)],
    env: { ...node.env, ...spec.env(cliPath) },
  };
}

function nodeRuntime() {
  return process.versions.electron
    ? { command: nodeBinary(), env: { ELECTRON_RUN_AS_NODE: '1' } }
    : { command: process.execPath, env: {} };
}

/* ── the agents' own questions to the person (ACP form elicitation) ──
 *
 * Claude Code's AskUserQuestion and Codex's request_user_input both arrive as a form: one field per question (a
 * choice is a `oneOf` of `{ const, title, description }`), maybe beside a field for an answer in the person's own
 * words — Claude's marked `_meta._askUserQuestionCustomAnswer.questionId`, Codex's `_meta.codex.role === 'user_note'`.
 * Read into a list of questions for the chat; the answers are put back in the fields they came from. A form that is
 * not one of these (numbers, booleans, nesting) is declined: the agent takes it as skipped and carries on. */

/** A form, as questions; null when it is not one this chat can show. */
export function formQuestions(params) {
  if (params?.mode !== undefined && params.mode !== 'form') return null;
  const properties = params?.requestedSchema?.properties;
  if (!properties || typeof properties !== 'object') return null;
  const entries = Object.entries(properties);
  const customOf = new Map();
  for (const [id, prop] of entries) {
    const target = prop?._meta?._askUserQuestionCustomAnswer?.questionId
      ?? (prop?._meta?.codex?.role === 'user_note' ? prop._meta.codex.questionId : undefined);
    if (typeof target === 'string' && properties[target]) customOf.set(target, id);
  }
  const custom = new Set(customOf.values());
  const fields = entries.filter(([id]) => !custom.has(id));
  if (fields.length === 0) return null;
  const questions = [];
  for (const [id, prop] of fields) {
    const multi = prop?.type === 'array';
    const choices = multi ? (prop.items?.anyOf ?? prop.items?.oneOf) : (prop?.oneOf ?? prop?.anyOf);
    const options = Array.isArray(choices)
      ? choices.filter((c) => typeof c?.const === 'string').map((c) => ({ label: c.const, ...(c.description ? { description: String(c.description) } : {}) }))
      : Array.isArray(prop?.enum) ? prop.enum.filter((v) => typeof v === 'string').map((label) => ({ label })) : [];
    if (prop?.type !== 'string' && !multi) return null;
    if (multi && options.length === 0) return null;
    /* Codex: the title is the question, the description its heading. Claude: with one question it is in `message`,
       with several in the description; the title is the heading. */
    const codex = Boolean(prop?._meta?.codex);
    const title = typeof prop?.title === 'string' && prop.title ? prop.title : null;
    const description = typeof prop?.description === 'string' && prop.description ? prop.description : null;
    const question = codex
      ? title ?? description ?? params.message ?? id
      : description ?? (fields.length === 1 && params.message ? params.message : title ?? params.message ?? id);
    const header = codex ? description : title;
    questions.push({ id, question: String(question), header: header && header !== question ? header : null, options, customId: customOf.get(id) ?? null, multi });
  }
  return questions;
}

/** The chat's answers, as the form's content. `answers[id]` is `{ label }` (a choice) or `{ text }` (own words). */
export function formContent(questions, answers) {
  const content = {};
  for (const q of questions) {
    const a = answers?.[q.id];
    if (!a) continue;
    if (typeof a.label === 'string' && q.options.some((o) => o.label === a.label)) {
      content[q.id] = q.multi ? [a.label] : a.label;
    } else if (typeof a.text === 'string' && a.text.trim()) {
      const text = a.text.trim();
      if (q.customId) content[q.customId] = text;
      else if (q.options.length === 0) content[q.id] = text;
    }
  }
  return content;
}

/** What the app tells each agent, as it shakes hands, that the chat can do. */
export const CLIENT_CAPABILITIES = {
  fs: { readTextFile: false, writeTextFile: false }, terminal: false, elicitation: { form: {} },
  /* the person signs in in Terminal, the way the agent offers (agentSignInMethods) */
  auth: { terminal: true },
  /* the agent's own warnings (Codex: "Falling back from WebSockets…") come as notices, not as words in its reply */
  session: { notices: {} },
  /* Cursor exposes model parameters (effort, speed, context) only to clients with its advanced picker.
     Claude Code's recommended-value extension names the current model and effort without a Default row. */
  _meta: { parameterizedModelPicker: true, jetbrains: { air: { version: 1, capabilities: ['recommendedValue'] } } },
};

const CLIENT_INFO = { name: 'openfilm-desktop', title: 'OpenFilm', version: '0.1.0' };

/** How long an agent may wait on its model with nothing coming before the turn is stopped. */
const MODEL_STALL_MS = 5 * 60_000;

/** Where an agent says it is in its turn (CodeBuddy's `codebuddy.ai/agentPhase`: model_requesting, retrying…), or null. */
export function agentPhase(update) {
  const meta = update?._meta;
  if (!meta || typeof meta !== 'object') return null;
  const phase = Object.entries(meta).find(([k]) => /(?:^|[/.])agentPhase$/.test(k))?.[1]?.phase;
  return typeof phase === 'string' ? phase : null;
}

function stallError(label, ms) {
  const minutes = Math.max(1, Math.round(ms / 60_000));
  return Object.assign(new Error(`${label} heard nothing back from its model for ${minutes} minute${minutes === 1 ? '' : 's'}: its connection may be blocked. The turn was stopped; send your message again to retry.`), { code: 'agent-stalled' });
}

/** What an agent sends while it answers or works: a turn with none of these said nothing. */
const SPOKE = new Set(['agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update', 'plan']);

/** ACP's auth_required: the agent wants its own sign-in first. */
const AUTH_REQUIRED = -32000;

/** The oldest Codex the chat was tried with: an older one may have an app server the adapter can't talk to. */
export const CODEX_TESTED = '0.132.0';

/**
 * The oldest Claude Code the chat was tried with. An older one lists only the models it knows: 2.1.288 has no Haiku
 * 5.5, which 2.1.308 has (#230), and the person takes that for OpenFilm's or the service's doing. Never above npm's
 * `stable`, which the Claude app, the Homebrew cask and `claude update` follow: else most are told to update with
 * nothing to update to.
 */
export const CLAUDE_TESTED = '2.1.308';

/**
 * A Claude Code older than CLAUDE_TESTED, for Settings › Agents to say so: its version, the one tried, the command that
 * updates it (null when it has none), and `app` for the Claude app's own copy, which the app updates. Null when it is not
 * older, or its version can't be told.
 * @param {string} path @param {{ versionOf?: (file: string) => string | null, updateOf?: (file: string) => { command: string } | { app: true } | null }} [o]
 */
export function claudeOutdated(path, { versionOf = claudeVersion, updateOf = claudeUpdate } = {}) {
  const version = versionOf(path);
  if (!version || !laterVersion(CLAUDE_TESTED, version)) return null;
  const how = updateOf(path);
  return { version, tested: CLAUDE_TESTED, update: how && 'command' in how ? how.command : null, ...(how && 'app' in how ? { app: true } : {}) };
}

/**
 * A Codex that did not start, older than the ones tried: its reason, and that updating it is the likely fix (an old
 * one's app server goes away as the session opens, "connection got disposed", and says nothing more).
 * @param {string} agent @param {string | undefined} path @param {any} e @param {(file: string) => string | null} [versionOf]
 */
export function codexTooOld(agent, path, e, versionOf = codexVersion) {
  if (agent !== 'codex' || !path || e?.code === 'sign-in' || e?.code === 'not-installed') return e;
  const version = versionOf(path);
  if (!version || !laterVersion(CODEX_TESTED, version)) return e;
  const why = e instanceof Error ? e.message : String(e);
  return Object.assign(new Error(`Codex ${version} is older than OpenFilm needs (${CODEX_TESTED} or later): update Codex, then try again. ${why}`.trim()), { code: 'outdated' });
}

/** ACP's internal error: what an agent's own failures come as. */
const INTERNAL_ERROR = -32603;

/**
 * A session refused for the agent's sign-in, said so (`code: 'sign-in'`). One refused in ACP's sign-in terms for the
 * person's plan instead (Kimi 2.2: "Authentication required: 403 Your current subscription does not have access to Kimi
 * Code…") is the agent's own words (`code: 'agent-error'`): signing in again would not help, and the agent is not taken
 * for signed out. Any other error with its reason (errorCause).
 */
export function signInError(label, e, { own = false } = {}) {
  if (e?.code === AUTH_REQUIRED) {
    const plan = planProblem(e?.message);
    if (plan) return Object.assign(new Error(`${label}: ${plan}`), { code: 'agent-error' });
    return Object.assign(new Error(`${label} is not signed in. ${own ? `Sign in in ${label}, then try again.` : 'Sign in under Settings → Agents.'}`), { code: 'sign-in' });
  }
  return errorCause(e);
}

/**
 * An error the agent sends as just "Internal error" or "Invalid params" with its reason: the reason is in its `data`, as a string or its
 * `message` or `details` (the ACP SDK puts a thrown Error's text there; Codex its settings it cannot read). The error
 * it came as stays its `cause`.
 */
export function errorCause(e) {
  if (!((e?.code === INTERNAL_ERROR && String(e.message ?? '').trim() === 'Internal error')
    || (e?.code === -32602 && String(e.message ?? '').trim() === 'Invalid params'))) return e;
  const data = e.data;
  const why = typeof data === 'string' ? data : [data?.message, data?.details].find((v) => typeof v === 'string') ?? '';
  return why.trim() ? Object.assign(new Error(why.trim(), { cause: e }), { code: e.code }) : e;
}

/**
 * The model service's refusal, when that is what a reply's words are: Codex's adapter sends an error from OpenAI as
 * the reply (`{"type":"error","status":400,"error":{"message":…}}`), and the turn ends as if answered. Its message
 * and status, or null for anything else.
 * @returns {{ message: string, status: number | null } | null}
 */
export function codexServiceError(update) {
  if (update?.sessionUpdate !== 'agent_message_chunk' || update.content?.type !== 'text') return null;
  const text = String(update.content.text ?? '').trim();
  if (!text.startsWith('{"type":"error"')) return null;
  try {
    const said = JSON.parse(text);
    const message = typeof said?.error?.message === 'string' ? said.error.message.trim() : '';
    return said?.type === 'error' && message ? { message, status: Number.isInteger(said.status) ? said.status : null } : null;
  } catch {
    return null;
  }
}

/**
 * The turn's error for a refusal. A model "not supported when using Codex" is one this Codex is too old for (Codex
 * lists models it cannot use yet): updating it, or another model, is the fix.
 * @param {{ message: string }} refused @param {string | undefined} path @param {(file: string) => string | null} [versionOf]
 */
export function codexRefusal(refused, path, versionOf = codexVersion) {
  if (!/not supported when using Codex/i.test(refused.message)) return new Error(refused.message);
  const version = path ? versionOf(path) : null;
  return Object.assign(new Error(`${refused.message} Update Codex${version ? ` (this one is ${version})` : ''}, or choose another model.`), { code: 'outdated' });
}

/**
 * Codex's reconnects and retries ("Reconnecting... 2/5", "waiting for network"), and an error of a turn not running
 * now: its adapter puts them in a session_info_update's `_meta.codex.error`, which says nothing in the chat. As the
 * notice the chat shows (its words, then what it adds), or null.
 */
export function codexNotice(update) {
  const error = update?.sessionUpdate === 'session_info_update' ? update._meta?.codex?.error : null;
  const title = typeof error?.message === 'string' ? error.message.trim() : '';
  if (!title) return null;
  const details = typeof error.additionalDetails === 'string' ? error.additionalDetails.trim() : '';
  return { sessionUpdate: 'notice', severity: error.willRetry ? 'warning' : 'error', title, ...(details ? { description: details } : {}) };
}

/** where each step of a session is, in words */
const STEP_WORDS = Object.freeze({
  start: 'as it started', initialize: 'as it started', authenticate: 'while signing in',
  'session/new': 'while opening the session', 'session/prompt': 'while answering',
});

/** what an agent says when it says nothing: an error with no reason, or its process gone mid-request */
const SAYS_NOTHING = /^(?:internal error|internal server error|unknown error|(?:acp )?connection closed|pending response rejected since connection got disposed)\.?$/i;

/* stderr lines that never say why: a stack frame, a caret, a brace, a property of the error printed, Node's banner
   and its "Emitted 'error' event" */
const NOISE = /^(?:at\s|\^+$|[{}]$|[a-z]+: [-'\w]+,?$|Node\.js v|node:|throw\s|Emitted '\w+' event)/;
const REASON = /error|fail|cannot|can't|refused|denied|not found|panic|timed? ?out|unable/i;

/** What the last of an agent's stderr says: its last lines that name an error, else its last lines; at most 600 characters. */
export function stderrReason(stderr = '') {
  const lines = stderr.split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !NOISE.test(l));
  const reasons = lines.filter((l) => REASON.test(l));
  return [...new Set((reasons.length ? reasons : lines).slice(-3))].join(' | ').slice(-600);
}

/* one word of a command as the chat shows it: quoted when it has a space */
const shownArg = (/** @type {string} */ a) => (a && !/[\s"]/.test(a) ? a : `"${a}"`);

/**
 * An agent's failure as it is: what it said when it said why; else the step it stopped at, how its process ended (the
 * command it ran and its code) and the last it wrote to stderr; with neither, while its process still runs, that an
 * agent which cannot reach its service stops like this. A process that ended is not the network.
 * @param {any} e @param {{ label: string, step?: string | null, stderr?: string, exited?: { code: number | null } | null, command?: string[] | null }} at
 */
export function explainFailure(e, { label, step = null, stderr = '', exited = null, command = null }) {
  const said = (e instanceof Error ? e.message : String(e ?? '')).trim();
  const bare = !said || SAYS_NOTHING.test(said);
  if (!bare && !exited) return e;
  const tail = stderrReason(stderr);
  const where = step && STEP_WORDS[step] ? ` ${STEP_WORDS[step]}` : '';
  const ran = command?.length ? ` (${command.map(shownArg).join(' ')})` : '';
  const ended = exited ? ` Its process${ran} ended${exited.code == null ? '' : ` with code ${exited.code}`}.` : '';
  const message = [
    bare ? `${label} stopped${where} without saying why.` : said,
    ended.trim(),
    tail ? `It last wrote: ${tail}` : bare && !exited ? 'If it cannot reach its service, check the network or proxy, then try again.' : '',
  ].filter(Boolean).join(' ');
  return Object.assign(new Error(message, { cause: e }), { ...(e?.code !== undefined ? { code: e.code } : {}), ...(step ? { step } : {}) });
}

/** What an agent's sign-in refusal says when it is about the person's plan, not their sign-in, or null. */
export function planProblem(message) {
  const text = String(message ?? '').replace(/^\s*Authentication required[:.]?\s*/i, '').trim();
  return /\b(?:403|subscriptions?|plans?|upgrade|quota|billing|credits?|balance)\b/i.test(text) ? text.slice(0, 1000) : null;
}

/**
 * Why a turn ended, as the agent says it beside the turn's result (`_meta`, under a key ending in `errorMessage`:
 * CodeBuddy's `codebuddy.ai/errorMessage`, itself JSON with a `message`), or null.
 */
export function turnError(result) {
  const meta = result?._meta;
  if (!meta || typeof meta !== 'object') return null;
  const raw = Object.entries(meta).find(([k, v]) => /(?:^|[/.])errorMessage$/.test(k) && typeof v === 'string' && v.trim())?.[1];
  if (!raw) return null;
  let text = raw.trim();
  try { const said = JSON.parse(text); if (typeof said?.message === 'string' && said.message.trim()) text = said.message.trim(); } catch { /* plain words */ }
  return text.slice(0, 1000);
}

/** The answer that lets it go ahead (for good, where it offers that), or null when none does. */
export function allowOption(params) {
  const options = params?.options ?? [];
  return (options.find((o) => o.kind === 'allow_always') ?? options.find((o) => o.kind === 'allow_once'))?.optionId ?? null;
}

/** The older session lists (`models`, `modes`) as the config options the chat's menu reads. */
export function legacyOptions(session) {
  const out = [];
  if (session.models?.availableModels?.length) {
    out.push({ id: 'model', name: 'Model', category: 'model', type: 'select', currentValue: session.models.currentModelId,
      options: session.models.availableModels.map((m) => ({ value: m.modelId, name: m.name, ...(m.description ? { description: m.description } : {}) })) });
  }
  if (session.modes?.availableModes?.length) {
    out.push({ id: 'mode', name: 'Mode', category: 'mode', type: 'select', currentValue: session.modes.currentModeId,
      options: session.modes.availableModes.map((m) => ({ value: m.id, name: m.name, ...(m.description ? { description: m.description } : {}) })) });
  }
  return out;
}

/**
 * Config options with each choice once: an agent may list the same value twice (GitHub Copilot's model list has
 * "Auto" twice), which the menu would show twice, both ticked. The first of each is kept; anything else as it was.
 * Choices in groups (DeepSeek Harness groups its models by where they run: its API, the person's DeepSeek account)
 * are listed one after another, each named by itself, then its group's name ("DeepSeek-V4-Pro · DeepSeek Account"):
 * the menu's button shows the part before the dot, the model.
 */
export function distinctOptions(configOptions) {
  if (!Array.isArray(configOptions)) return configOptions;
  return configOptions.map((o) => {
    if (!Array.isArray(o?.options)) return o;
    const seen = new Set();
    const choices = o.options.flatMap((c) => (Array.isArray(c?.options) && !('value' in c)
      ? c.options.map((g) => (g && typeof c.name === 'string' && c.name ? { ...g, name: `${g.name} · ${c.name}` } : g))
      : [c]));
    return { ...o, options: choices.filter((c) => !c || !('value' in c) || (!seen.has(c.value) && seen.add(c.value))) };
  });
}

/** A menu probe asks the selected model for its own dependent options, without sending a prompt. */
export async function optionsForModel(session, info, model) {
  if (model == null) return info;
  const option = info.configOptions?.find((o) => o.category === 'model');
  if (!option?.options?.some((choice) => choice.value === model)) throw new Error('The agent does not offer this model.');
  if (option.currentValue === model) return info;
  const result = await session.setConfigOption(option.id, model);
  const options = result?.configOptions ?? info.configOptions.map((o) => o.id === option.id ? { ...o, currentValue: model } : o);
  if (options.find((o) => o.category === 'model')?.currentValue !== model) throw new Error('The agent did not accept the selected model.');
  return { ...info, configOptions: options };
}

/**
 * One conversation: one ACP session on one adapter process.
 *
 * `onUpdate(update)` hears each session/update as it comes; `onPermission(params)` answers an optionId, or null to
 * refuse (with no handler everything is refused: permission is never given for the person).
 */
export class AgentSession {
  /**
   * `harness` (for 'byok'): agent-roster.mjs's `harness(id)`, Pi's folder, the person's models (each its own service)
   * and the one it starts on.
   * @param {{ agent: string, cwd: string, resume?: string | null, binDir?: string | null, fallbackDir?: string | null,
   *           harness?: any,
   *           env?: Record<string, string>, logDir?: string | null,
   *           skills?: { dataDir: string, mine?: string, allowed?: string[], mcpAllowed?: string[] } | null,
   *           onUpdate?: (update: any) => void, onPermission?: (params: any) => Promise<string | null>,
   *           onQuestion?: (ask: { message: string, toolCallId: string | null, questions: any[] }) => Promise<Record<string, { label?: string, text?: string }> | null>,
   *           onExit?: (info: { code: number | null, stderr: string }) => void,
   *           onSend?: (sent: { prompt: any[], _meta?: any }) => void, stallMs?: number }} opts
   * `onSend` hears each message as it goes to the agent, whole (the app's words before the first one's, for an agent
   * told them there); `opened`, once started, says what it was started and opened with.
   * `skills`: the session has its maker's skills and MCP servers, OpenFilm's skills, and of the person's own only those
   * let in (`allowed`, `mcpAllowed`), each agent told by its own switch (agent-skills.mjs); `opened.skills` says how.
   * `stallMs`: how long the agent may wait on its model with nothing coming (MODEL_STALL_MS) before the turn is stopped.
   * `logDir` (Developer mode): an agent whose own record lacks what its model got is started with its own logging
   * switch, writing under this folder (agent-logs.mjs); `opened.log` says where.
   */
  constructor(opts) {
    if (!isChatAgent(opts.agent)) throw new Error(`Unknown agent: ${String(opts.agent)}`);
    if (HARNESS_AGENTS.includes(opts.agent) && !opts.harness) throw Object.assign(new Error('Connect this agent in Settings → Agents first.'), { code: 'not-ready' });
    this.opts = opts;
    /* the app's own agent runs Pi (pi-agent.mjs), the person's their own program through its adapter */
    this.spec = HARNESS_AGENTS.includes(opts.agent) ? { label: 'Own key', env: () => ({}) } : AGENTS[opts.agent];
    this.sessionId = null;
    this.info = null;
    this.stderr = '';
    /** while an old session is loaded its history is replayed: the chat already has it */
    this.replaying = false;
  }

  /**
   * Start the adapter, shake hands, open (or resume) the session. The agent gets all the person's login shell sets
   * (their keys, gateways, tokens; Claude Code only its PATH and the like, agentShell), as in their terminal, and the app's
   * `openfilm` first on its PATH; the app's ffmpeg (`fallbackDir`) last, for a computer that has none of its own.
   */
  async start() {
    try {
      const info = await this.open();
      this.step = null;
      return info;
    } catch (e) {
      throw await this.explain(codexTooOld(this.opts.agent, this.cli?.path, e));
    }
  }

  /**
   * An error with what the agent said, or, when it said nothing, where it stopped and what it last wrote. Its process
   * may be ending as the request fails: how it ended is waited for, a second at most.
   */
  async explain(e) {
    if (this.child && !this.exited && this.child.exitCode === null && this.child.signalCode === null) {
      await new Promise((done) => { this.child.once('exit', done); setTimeout(done, 1000).unref?.(); });
    }
    return explainFailure(e, { label: this.spec.label, step: this.step, stderr: this.stderr, exited: this.exited ?? null, command: this.command ?? null });
  }

  /**
   * What a failure needs said for the turn log: the step it stopped at, the program, its adapter, how its process
   * ended, all it wrote to stderr, and where the agent keeps its own logs.
   */
  failure() {
    return {
      step: this.step ?? null,
      program: this.cli?.path ?? null,
      adapter: this.spec.adapter ?? null,
      exit: this.exited ?? null,
      stderr: this.stderr.slice(-8000),
      ...(this.ownLogs ? { ownLogs: this.ownLogs } : {}),
    };
  }

  async open() {
    this.step = 'start';
    const shell = agentShell(this.opts.agent, await loginShellVariables({ staleOk: true }));
    const harness = this.opts.harness ?? null;
    const cli = harness ? null : await findAgentCli(this.opts.agent, { pathDirs: shell.PATH.split(PATH_SEP) });
    if (!harness && !cli) throw Object.assign(new Error(`${this.spec.label} is not installed on this computer.`), { code: 'not-installed' });
    this.cli = cli;
    /* one whose ACP sign-in takes up its own (Cursor's `authenticate`) opens the maker's sign-in page in the browser and
       waits there when it is signed out: its own status says so first, and the person signs in from Settings */
    if (cli && this.spec.authenticate && this.spec.auth && (await agentStatus(this.opts.agent, cli.path)).signedIn === false) {
      throw signInError(this.spec.label, { code: AUTH_REQUIRED });
    }
    const node = nodeRuntime();
    const path = [this.opts.binDir, shell.PATH, this.opts.fallbackDir].filter(Boolean).join(PATH_SEP);
    const instructions = INSTRUCTIONS;
    /* the app's own agent: what Pi runs with (its whole system prompt is ours), and the web search of `openfilm get`
       (OPENFILM_GET_WEB lists it) */
    const own = !harness ? {} : {
      ...harness.env,
      OPENFILM_GET_WEB: '1',
    };
    /* its skills and MCP servers: its maker's, OpenFilm's skills, and the person's own only those let in (agent-skills.mjs) */
    const skills = this.opts.skills
      ? await sessionSkills(this.opts.agent, { cwd: this.opts.cwd, env: shell, ...this.opts.skills }).catch(() => null) : null;
    if (harness) own.OPENFILM_PI = JSON.stringify({ agentDir: harness.home, models: harness.models, model: harness.model, systemPrompt: ownAgentPrompt(), skills: skills?.piSkills ?? null });
    /* Developer mode: the agent's own logging switch, so the turn log has what its model got; none when the person
       set its telemetry themselves (agent-logs.mjs) */
    this.logging = this.opts.logDir && cli && !this.spec.adapter
      ? await logSwitches(this.opts.agent, { base: this.opts.logDir, shell, cwd: this.opts.cwd }).catch(() => null) : null;
    /* an agent that speaks ACP itself: its own program, started as the registry starts it */
    const native = cli && !this.spec.adapter ? starting(cli.path, [...this.spec.args, ...(this.logging?.args ?? []), ...(skills?.args ?? [])]) : null;
    /* what a failure names: the agent's program and its own words, as the person would run it (not our logging or skills) */
    this.command = native ? [cli.path, ...this.spec.args] : null;
    const extra = { ...agentDefaults(this.opts.agent, shell), ...this.opts.env, ...(native ? native.env : node.env), ...(cli && this.spec.env ? this.spec.env(cli.path) : {}), ...own, ...skills?.env, ...this.logging?.env };
    /* OpenCode's inline configuration carries both its skills and, in Developer mode, its logging */
    if (skills?.env?.OPENCODE_CONFIG_CONTENT && this.logging?.env?.OPENCODE_CONFIG_CONTENT) {
      extra.OPENCODE_CONFIG_CONTENT = JSON.stringify(mergeConfig(JSON.parse(skills.env.OPENCODE_CONFIG_CONTENT), JSON.parse(this.logging.env.OPENCODE_CONFIG_CONTENT)));
    }
    const env = childEnvironment({ shell: { ...shell, PATH: path }, extra });
    const claude = this.spec.adapter === AGENTS.claude.adapter;
    if (this.spec.adapter === AGENTS.codex.adapter) {
      this.ownLogs = shell.CODEX_HOME || join(homedir(), '.codex');
      const theirs = codexDeveloperInstructions(codexConfigText(shell));
      env.CODEX_CONFIG = JSON.stringify(mergeConfig({ developer_instructions: theirs ? `${theirs}\n\n${instructions}` : instructions }, skills?.codexConfig ?? {}));
    }
    /* the others have no place for it: the session's first message carries it */
    this.instructions = harness || this.spec.systemPrompt ? null : instructions;

    const script = harness ? fileURLToPath(new URL('./pi-agent.mjs', import.meta.url)) : native ? null : adapterScript(this.spec.adapter);
    this.child = native
      ? spawn(native.cmd, native.args, { ...native.options, ...OWN_GROUP, cwd: this.opts.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
      : spawn(node.command, node.env.ELECTRON_RUN_AS_NODE ? asNode(script) : [script], { ...OWN_GROUP, cwd: this.opts.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
    this.child.stderr.on('data', (d) => { this.stderr = (this.stderr + String(d)).slice(-16_000); });
    LIVE.add(this);
    this.child.once('exit', (code) => { LIVE.delete(this); this.exited = { code }; this.opts.onExit?.({ code, stderr: this.stderr }); });
    this.child.once('error', () => {});

    const stream = acp.ndJsonStream(Writable.toWeb(this.child.stdin), Readable.toWeb(this.child.stdout));
    this.conn = acp.client({ name: 'openfilm-desktop' })
      .onRequest(acp.methods.client.session.requestPermission, async (ctx) => {
        const optionId = (this.spec.approve ? allowOption(ctx.params) : null)
          ?? (this.opts.onPermission ? await this.opts.onPermission(ctx.params) : null);
        return optionId ? { outcome: { outcome: 'selected', optionId } } : { outcome: { outcome: 'cancelled' } };
      })
      .onRequest(acp.methods.client.elicitation.create, async (ctx) => {
        const questions = formQuestions(ctx.params);
        if (!questions || !this.opts.onQuestion) return { action: 'decline' };
        const answers = await this.opts.onQuestion({ message: ctx.params.message ?? '', toolCallId: ctx.params.toolCallId ?? null, questions });
        return answers ? { action: 'accept', content: formContent(questions, answers) } : { action: 'decline' };
      })
      .onNotification(acp.methods.client.session.update, (ctx) => {
        const update = withToolKind(ctx.params.update, this.spec.toolKinds);
        if (SPOKE.has(update?.sessionUpdate)) this.spoke = true;
        this.heard = Date.now();
        const phase = agentPhase(update);
        if (phase) this.phase = phase;
        if (this.replaying) return;
        /* Codex's adapter sends the model service's refusal as the reply's words: kept to fail the turn with */
        const codex = this.spec.adapter === AGENTS.codex.adapter;
        const refused = codex ? codexServiceError(update) : null;
        if (refused) { this.refused = refused; return; }
        this.opts.onUpdate?.(update?.configOptions ? { ...update, configOptions: distinctOptions(update.configOptions) } : update);
        /* and its reconnects and retries, which it says where the chat does not look, as notices (once each) */
        const notice = codex ? codexNotice(update) : null;
        if (notice && notice.title !== this.lastNotice) {
          this.lastNotice = notice.title;
          this.opts.onUpdate?.(notice);
        }
      })
      .connect(stream);

    this.step = 'initialize';
    const init = await this.conn.agent.request(acp.methods.agent.initialize, {
      protocolVersion: acp.PROTOCOL_VERSION,
      clientCapabilities: CLIENT_CAPABILITIES,
      clientInfo: CLIENT_INFO,
    }).catch((e) => { throw signInError(this.spec.label, e, { own: this.spec.login === null }); });

    const params = {
      cwd: this.opts.cwd,
      mcpServers: [],
      ...(skills?.additionalDirectories ? { additionalDirectories: skills.additionalDirectories } : {}),
      ...(claude ? { _meta: { systemPrompt: { append: instructions }, ...(skills?.claude ? { claudeCode: { options: skills.claude } } : {}) } } : {}),
    };
    /* the program's own sign-in, taken up (Cursor asks for this before any session) */
    if (this.spec.authenticate && (init.authMethods ?? []).some((m) => m.id === this.spec.authenticate)) {
      this.step = 'authenticate';
      await this.conn.agent.request(acp.methods.agent.authenticate, { methodId: this.spec.authenticate }).catch((e) => { throw signInError(this.spec.label, e, { own: this.spec.login === null }); });
    }

    this.step = 'session/new';
    let session = null;
    const resume = this.opts.resume;
    const caps = init.agentCapabilities ?? {};
    if (resume && caps.sessionCapabilities?.resume) {
      session = await this.conn.agent.request(acp.methods.agent.session.resume, { ...params, sessionId: resume }).then((r) => ({ ...r, sessionId: resume }), () => null);
    } else if (resume && caps.loadSession) {
      this.replaying = true;
      session = await this.conn.agent.request(acp.methods.agent.session.load, { ...params, sessionId: resume }).then((r) => ({ ...r, sessionId: resume }), () => null);
      this.replaying = false;
    }
    const resumed = Boolean(session);
    session ??= await this.conn.agent.request(acp.methods.agent.session.new, params).catch((e) => { throw signInError(this.spec.label, e, { own: this.spec.login === null }); });
    this.sessionId = session.sessionId;
    /* an agent on the protocol's older model and mode lists: the same choices, as config options */
    this.legacy = !session.configOptions && Boolean(session.models || session.modes);
    if (resumed) this.instructions = null;
    this.info = {
      sessionId: session.sessionId,
      resumed,
      agentInfo: init.agentInfo ?? null,
      models: session.models ?? null,
      modes: session.modes ?? null,
      configOptions: distinctOptions(session.configOptions ?? (this.legacy ? legacyOptions(session) : null)),
      /* what a prompt may carry besides text (pictures, for one): the agent says so as it shakes hands */
      promptCapabilities: caps.promptCapabilities ?? null,
      /* a message sent while it works joins the turn it is in (steer), as in its own chat */
      steering: init._meta?.steering?.supported === true,
    };
    this.noteModel(this.info.configOptions);
    /* what the agent was started and opened with, for the turn log: every word the app adds to its own, and the
       variables the app set (a key's value never: it reads "(hidden)") */
    const secret = new Set(Object.keys(harness?.env ?? {}));
    this.opened = {
      program: harness ? 'pi' : cli.path,
      /* the command line the agent's process was started with: its own program, or the app's Node running its adapter (or Pi) */
      command: native ? [native.cmd, ...native.args] : [node.command, ...(node.env.ELECTRON_RUN_AS_NODE ? asNode(script) : [script])],
      adapter: this.spec.adapter ?? null,
      env: Object.fromEntries(Object.entries(extra).map(([k, v]) => [k, secret.has(k) || /KEY|TOKEN|SECRET|PASSWORD/i.test(k) ? '(hidden)' : k === 'OPENFILM_PI' ? JSON.parse(v) : v])),
      ...(env.CODEX_CONFIG ? { codexConfig: JSON.parse(env.CODEX_CONFIG) } : {}),
      path: { first: this.opts.binDir ?? null, last: this.opts.fallbackDir ?? null },
      fromShell: this.spec.fromShell ? Object.keys(shell).sort() : 'all',
      initialize: { request: { protocolVersion: acp.PROTOCOL_VERSION, clientCapabilities: CLIENT_CAPABILITIES, clientInfo: CLIENT_INFO }, response: init },
      session: { method: !resumed ? 'session/new' : caps.sessionCapabilities?.resume ? 'session/resume' : 'session/load', params: { ...params, ...(resumed ? { sessionId: resume } : {}) } },
      firstMessage: this.instructions,
      log: this.logging?.log ?? null,
      skills: skills?.log ?? null,
    };
    return this.info;
  }

  /**
   * Send a message; resolves with the stopReason when the turn ends. Everything on the way comes from onUpdate.
   * `turnId`: the app's own agent writes each request to its model in that turn's log (chat-store.mjs).
   */
  async prompt(blocks, { turnId } = {}) {
    if (!this.sessionId) throw new Error('The session has not started.');
    const meta = this.opts.harness && turnId ? { _meta: { openfilm: { turnId, cwd: this.opts.cwd } } } : {};
    const told = this.instructions ? [{ type: 'text', text: this.instructions }] : [];
    this.instructions = null;
    /* the message exactly as the agent gets it, for the turn log */
    this.opts.onSend?.({ prompt: [...told, ...blocks], ...meta });
    this.refused = null;
    this.lastNotice = null;
    this.step = 'session/prompt';
    this.spoke = false;
    this.heard = Date.now();
    this.phase = null;
    /* a model asked and never answering (CodeBuddy, its connection hung): the turn is stopped for the person */
    let stalled = false;
    const stallMs = this.opts.stallMs ?? MODEL_STALL_MS;
    let giveUp = () => {};
    const gaveUp = new Promise((_, fail) => { giveUp = fail; });
    gaveUp.catch(() => {});
    const watch = setInterval(() => {
      if (stalled || this.phase !== 'model_requesting' || Date.now() - this.heard < stallMs) return;
      stalled = true;
      void this.cancel();
      /* one that does not stop when asked is left: the chat is not kept waiting on it */
      setTimeout(() => giveUp(stallError(this.spec.label, stallMs)), 10_000).unref?.();
    }, Math.min(15_000, Math.max(50, stallMs / 4)));
    watch.unref?.();
    const asking = this.conn.agent.request(acp.methods.agent.session.prompt, { sessionId: this.sessionId, prompt: [...told, ...blocks], ...meta })
      .catch(async (e) => {
        /* the app's own agent: a service with no balance left is said the same for every service, with its page */
        const own = this.opts.harness?.models?.find((m) => m.id === this.modelNow) ?? this.opts.harness?.models?.[0];
        const broke = own ? outOfBalance({ id: own.name, baseUrl: own.baseUrl }, e) : null;
        if (broke) throw broke;
        if (!isAgentId(this.opts.agent)) throw errorCause(e);
        const said = signInError(this.spec.label, e, { own: this.spec.login === null });
        if (said.code === 'sign-in') noteSignedOut(this.opts.agent);
        throw await this.explain(said);
      });
    const r = await Promise.race([asking, gaveUp]).finally(() => clearInterval(watch));
    if (stalled && r.stopReason === 'cancelled') throw stallError(this.spec.label, stallMs);
    if (this.refused) throw codexRefusal(this.refused, this.cli?.path);
    /* a turn the agent gave up on with its reason beside it, not in its reply (CodeBuddy: a network error): said as
       the turn's error, or the chat would show an empty reply */
    const why = r.stopReason === 'refusal' ? turnError(r) : null;
    if (why) throw Object.assign(new Error(why), { code: 'agent-error' });
    /* a turn ended with nothing said or done (Kimi 0.27 so ends one its plan does not cover): said, not an empty reply */
    if (r.stopReason === 'end_turn' && !this.spoke && isAgentId(this.opts.agent)) {
      throw Object.assign(new Error(`${this.spec.label} ended its turn without replying. If it keeps doing so, try ${this.spec.label} in its own terminal: it may need an update, or a plan that covers it.`), { code: 'empty-turn' });
    }
    this.step = null;
    return r.stopReason;
  }

  /**
   * A message sent while a turn runs, into that turn (ACP's steering extension, `_session/steering`): the agent reads
   * it at its next step, as when the person types while it works in its own chat. → 'injected' when it joined the
   * turn; anything else ('startedNewTurn', 'promptRequired', 'failed') when it did not.
   */
  async steer(blocks) {
    if (!this.sessionId || !this.info?.steering) return 'failed';
    const r = await this.conn.agent.request('_session/steering', { sessionId: this.sessionId, prompt: blocks }).catch(() => null);
    return typeof r?.outcome === 'string' ? r.outcome : 'failed';
  }

  /** Stop this turn (it ends with stopReason 'cancelled'). */
  async cancel() {
    if (this.sessionId) await this.conn.agent.notify(acp.methods.agent.session.cancel, { sessionId: this.sessionId }).catch(() => {});
  }

  /** An option the adapter reports in configOptions: the model, the reasoning effort, the mode. */
  async setConfigOption(configId, value) {
    if (this.legacy && configId === 'mode') return this.setMode(value);
    if (this.legacy && configId === 'model') return this.conn.agent.request('session/set_model', { sessionId: this.sessionId, modelId: value });
    const r = await this.conn.agent.request(acp.methods.agent.session.setConfigOption, { sessionId: this.sessionId, configId, value }).catch((e) => { throw errorCause(e); });
    this.noteModel(r?.configOptions);
    return r?.configOptions ? { ...r, configOptions: distinctOptions(r.configOptions) } : r;
  }

  /** The model the session is on (its `model` option's value): the app's own agent names the service a failure was on by it. */
  noteModel(configOptions) {
    const model = (configOptions ?? []).find((o) => o?.id === 'model');
    if (model) this.modelNow = model.currentValue;
  }

  async setMode(modeId) {
    return this.conn.agent.request(acp.methods.agent.session.setMode, { sessionId: this.sessionId, modeId });
  }

  close() {
    LIVE.delete(this);
    try { this.conn?.close(); } catch { /* gone already */ }
    stopTree(this.child);
    this.logging?.close();
  }
}

/**
 * An agent's process and what it starts (the program under its adapter, its MCP servers, a command it runs) as one:
 * a process group of its own on macOS and Linux. On Windows taskkill follows the tree instead.
 */
export const OWN_GROUP = windows ? {} : { detached: true };

/**
 * Stop a process started with OWN_GROUP and everything it started. Stopping it alone (the adapter, or cmd.exe in front
 * of a .cmd) left the agent's own program and its MCP servers running, on Windows always.
 */
export function stopTree(child, { win = windows } = {}) {
  if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return;
  if (win) {
    try {
      const taskkill = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'taskkill.exe');
      spawn(taskkill, ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }).once('error', () => child.kill());
      return;
    } catch { /* taskkill could not start: the process alone, below */ }
  } else {
    try { process.kill(-child.pid, 'SIGTERM'); return; } catch { /* not a group of its own: the process alone, below */ }
  }
  try { child.kill('SIGTERM'); } catch { /* gone already */ }
}

/** Every agent process this app started and has not closed: a chat's, or one opened only to ask. */
const LIVE = new Set();

/**
 * Close every agent process, a session opened only to ask included (the chat's own are closed by their owner): the
 * app is quitting, and one left would outlive it.
 */
export function closeEverySession() {
  for (const session of [...LIVE]) session.close();
}
/* and as the process ends without quitting the usual way: none outlives it */
process.once('exit', closeEverySession);