@agentswf/engine 0.0.0-stage → 0.1.0-beta.1

package/src/operator-runtime.ts

@@ -0,0 +1,503 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { HarnessAllowance } from "@agentswf/contract/records";
+import type { SandboxEnvironmentKey } from "@agentswf/contract/workflow";
+import {
+  type Absent,
+  type CallerPane,
+  callingSession,
+  createCallerHostFactory,
+  createHeadlessRunHostFactory,
+  createHerdrRunHostFactory,
+  createPlacementHostFactory,
+  createSessionAccounting,
+  findSession,
+  HARNESSES,
+  type Harness,
+  type HerdrConfig,
+  harnessState,
+  isAbsent,
+  type RunProcess,
+  readAllowance,
+  readClaudeBilling,
+  readCodexBilling,
+  readCursorLogin,
+  runProcess,
+  withholding,
+} from "@agentswf/harness";
+import type {
+  AgentRunHostFactory,
+  AgentRuntimeConfig,
+  CallingSession,
+} from "@agentswf/harness/adapter";
+import type { SandboxProviders } from "@agentswf/sandbox";
+import { createDockerProvider, findDocker } from "@agentswf/sandbox/docker";
+import { createSrtProvider, findSrt } from "@agentswf/sandbox/srt";
+import { createOpenRouterProvider } from "./decisions/openrouter";
+import type { DecisionInstallation } from "./decisions/seam";
+import { messageOf } from "./errors";
+import { findOrigin, namedSession, workspaceLock } from "./herdr-placement";
+import {
+  ensureRunSession,
+  parseSessions,
+  type RunSession,
+  runSessionName,
+} from "./herdr-run-session";
+import { markWorkspace } from "./herdr-workspace-marks";
+
+export type { RunSession } from "./herdr-run-session";
+
+import { OPERATOR_ALIASES } from "./operator-aliases";
+
+export type OperatorRuntimeInstallation = {
+  config: AgentRuntimeConfig;
+  /** The sandbox providers this machine has, and the one a spec naming none runs in. */
+  sandboxes?: SandboxProviders;
+  /** The decision models workflows may ask, and their aliases. */
+  decisions?: DecisionInstallation;
+  cleanup(): Promise<void>;
+};
+
+export type OperatorRuntimeOptions = {
+  run?: RunProcess;
+  environment?: Readonly<Record<string, string | undefined>>;
+  /** A tab in the run's workspace for each sandbox's own Herdr. On unless false. */
+  watchSandboxes?: boolean;
+  /** The session `awf run --here` was started from, found in the Herdr session named (ADR 0010). */
+  caller?: { pane: CallerPane; session: string };
+  /**
+   * Where `awf run` was typed: without `--here`, the session it was started from is looked for in
+   * its environment, for a workflow to fork (story 027).
+   */
+  shellCwd?: string;
+  /** The operator's home. */
+  home?: string;
+  /** Told once, when the first pane agent's session is ready. */
+  onRunSession?: (session: RunSession) => void;
+};
+
+/**
+ * One run host for every agent: a Herdr tab for a pane agent, a subprocess per turn for a
+ * headless one. `WITHHELD_ENVIRONMENT` is cleared from both.
+ */
+export async function installOperatorRuntime(
+  timeoutMilliseconds: number,
+  options: OperatorRuntimeOptions = {},
+): Promise<OperatorRuntimeInstallation> {
+  const {
+    run = runProcess,
+    environment = process.env,
+    watchSandboxes = true,
+    caller,
+    shellCwd,
+    home = homedir(),
+    onRunSession,
+  } = options;
+  const unmetered = withholding(run, WITHHELD_ENVIRONMENT);
+  refuseMeteredCredentials(environment);
+  // Checked now, before any stage spends anything; made ready only for the first pane agent.
+  const name = runSessionName(environment);
+  const session = runSessionOnce(() => name, { run, environment, home }, onRunSession);
+  const runConfig = (session: string): HerdrConfig => ({
+    ...herdrConfig(session),
+    commandTimeoutMs: Math.min(timeoutMilliseconds, 150_000),
+    emptyEnvironment: PANE_WITHHELD_ENVIRONMENT,
+    acceptWorkspaceTrust: true,
+    watchSandboxes,
+  });
+  const found = caller && (await handedOver(caller.pane, environment));
+  const calling = caller
+    ? typeof found === "string"
+      ? found
+      : undefined
+    : shellCwd === undefined
+      ? undefined
+      : await startedFrom(environment, shellCwd, unmetered);
+  const host = loginChecked(
+    unmetered,
+    createPlacementHostFactory({
+      // The session is made ready when the first pane agent opens, so an all-headless run never
+      // calls Herdr.
+      pane: {
+        accounting: createSessionAccounting(unmetered),
+        openRun: async (spec) => {
+          const { name } = await session();
+          const mark = await markWorkspace(home, name, spec.label ?? spec.runId);
+          const config: HerdrConfig = {
+            ...runConfig(name),
+            onRunWorkspace: mark.bind,
+            sessionFor: (named) => namedSession(named, { run, environment, home }),
+            origin: () =>
+              findOrigin({
+                run,
+                environment,
+                runSession: name,
+                ...(caller ? { callerPane: caller.pane.paneId } : {}),
+              }),
+            lockWorkspace: workspaceLock(home),
+            onPanes: (session, panes) => void mark.panes(session, panes),
+          };
+          const host = await createHerdrRunHostFactory(config, run)
+            .openRun(spec)
+            .catch(async (error: unknown) => {
+              await mark.release();
+              throw error;
+            });
+          // Kept when the workspace would not close: a dead run's mark is what lets a later run
+          // close it.
+          const close: typeof host.close = async (reason) => {
+            await host.close(reason);
+            await mark.release();
+          };
+          return {
+            openAgent: (request) => host.openAgent(request),
+            inspect: () => host.inspect(),
+            close,
+          };
+        },
+      },
+      headless: createHeadlessRunHostFactory({}, unmetered),
+      ...(caller
+        ? {
+            caller: createCallerHostFactory(
+              runConfig(caller.session),
+              caller.pane,
+              run,
+              typeof found === "object" ? found : undefined,
+            ),
+          }
+        : {}),
+      ...(calling === undefined ? {} : { calling }),
+    }),
+  );
+  return {
+    config: {
+      aliases: OPERATOR_ALIASES,
+      host,
+    },
+    sandboxes: await installSandboxes(environment),
+    decisions: installDecisions({ OPENROUTER_API_KEY: await openRouterKey(environment) }),
+    // Nothing to undo: the agent's `wf` is a launcher the control plane installs beside its own
+    // socket, and the control plane removes both when the run closes.
+    cleanup: async () => undefined,
+  };
+}
+
+/** A session file written longer ago than this names a session that is not the one waiting. */
+const CALLING_QUIET_MS = 10 * 60_000;
+
+/**
+ * The session `awf run` was started from, as a tool call of an agent's: each harness's session
+ * variable this process has, kept where that session's file was written lately, since a terminal
+ * or a Herdr server started from an agent's shell passes on a variable long after its session.
+ * The newest, where more than one is; why none, where none is.
+ */
+async function startedFrom(
+  environment: Readonly<Record<string, string | undefined>>,
+  shellCwd: string,
+  run: RunProcess,
+): Promise<CallingSession | string> {
+  const named = (Object.keys(HARNESSES) as Harness[]).flatMap((harness) => {
+    const variable = HARNESSES[harness].sessionEnv;
+    const session = variable ? environment[variable]?.trim() : undefined;
+    return variable && session ? [{ harness, session, variable }] : [];
+  });
+  if (named.length === 0) return "awf run was not started from an agent's shell";
+  const found = await Promise.all(
+    named.map(async (each) => ({
+      ...each,
+      file: await findSession(each.harness, each.session, shellCwd, environment),
+    })),
+  );
+  const live = found
+    .flatMap(({ file, ...each }) =>
+      file && Date.now() - file.writtenAt <= CALLING_QUIET_MS ? [{ ...each, file }] : [],
+    )
+    .sort((left, right) => right.file.writtenAt - left.file.writtenAt)[0];
+  if (!live) {
+    const names = named.map(({ variable, session }) => `${variable}=${session}`).join(", ");
+    return `no session ${names} names was written in the last ${CALLING_QUIET_MS / 60_000} minutes`;
+  }
+  if (!live.file.model) return noModel(live.harness, live.session);
+  return callingSession(
+    { harness: live.harness, session: live.session, cwd: live.file.cwd },
+    run,
+    undefined,
+    environment,
+  );
+}
+
+/**
+ * Why a session whose files name no model is not forked: in its first turn it holds only the prompt
+ * that ran awf, and an operator's cursor chat records none.
+ */
+function noModel(harness: Harness, session: string): string {
+  return `${harness} session ${session} has nothing to fork: its files hold no request naming a model, as in its first turn`;
+}
+
+/** The id and directory of the session `--here` handed over, where `--here` passed its id. */
+async function handedOver(
+  pane: CallerPane,
+  environment: Readonly<Record<string, string | undefined>>,
+): Promise<{ session: string; cwd: string } | string> {
+  if (!pane.session) return "awf run --here passed no id for the calling session";
+  const file = await findSession(pane.harness, pane.session, pane.cwd, environment);
+  if (!file) return `${pane.harness} has no session ${pane.session} in the operator's home`;
+  if (!file.model) return noModel(pane.harness, pane.session);
+  return { session: pane.session, cwd: file.cwd };
+}
+
+/**
+ * How `awf allowance` reads each harness's plan: run as its agents are, so it reads the login they
+ * get, and a usage screen opens in the Herdr session their panes would.
+ */
+export function allowanceReader(
+  environment: Readonly<Record<string, string | undefined>> = process.env,
+  run: RunProcess = runProcess,
+  signal?: AbortSignal,
+  home: string = homedir(),
+): (harness: Harness) => Promise<HarnessAllowance> {
+  const unmetered = withholding(run, WITHHELD_ENVIRONMENT);
+  const session = runSessionOnce(() => runSessionName(environment), { run, environment, home });
+  return (harness) =>
+    readAllowance(harness, {
+      run: unmetered,
+      now: Date.now,
+      herdr: async () => ({
+        ...herdrConfig((await session()).name),
+        emptyEnvironment: PANE_WITHHELD_ENVIRONMENT,
+      }),
+      ...(signal ? { signal } : {}),
+    });
+}
+
+/** Herdr in session `session`, where awf's runs open their tabs. */
+export function herdrConfig(session: string): HerdrConfig {
+  return { session, workspaceLabel: "awf run", commandTimeoutMs: 10_000 };
+}
+
+/**
+ * The sandbox providers this machine has: srt when its CLI is on `PATH`, docker when its CLI is;
+ * its daemon is first asked when a sandbox opens. srt is the default when installed, as it runs
+ * the project's own toolchain, which an image lacks (story 004), and when it is there but cannot
+ * be set up: a spec naming none then fails saying why, rather than moving to docker unsaid.
+ */
+export async function installSandboxes(
+  environment: Readonly<Record<string, string | undefined>>,
+): Promise<SandboxProviders> {
+  // A provider that cannot be set up fails only the specs that name it, not every run.
+  const unavailable: Partial<Record<SandboxEnvironmentKey, string>> = {};
+  const found = <T>(key: SandboxEnvironmentKey, finding: Promise<T | undefined>) =>
+    finding.catch((error: unknown) => {
+      unavailable[key] = messageOf(error);
+      return undefined;
+    });
+  const [srt, docker] = await Promise.all([
+    found("srt", findSrt(environment, Object.values(harnessState(environment)))),
+    found("docker", findDocker(environment)),
+  ]);
+  const installed = {
+    ...(srt ? { srt: createSrtProvider(srt) } : {}),
+    ...(docker ? { docker: createDockerProvider(docker) } : {}),
+  };
+  const fallback = srt || unavailable.srt ? "srt" : docker ? "docker" : undefined;
+  return {
+    installed,
+    ...(fallback ? { default: fallback } : {}),
+    ...(Object.keys(unavailable).length > 0 ? { unavailable } : {}),
+  };
+}
+
+/**
+ * `OPENROUTER_API_KEY` from the environment, else from `.env` in `cwd`. Only that name is read:
+ * awf runs bun with `--no-env-file`, and bunfig says the same here, because `.env` can hold a
+ * Claude token that would change how every agent logs in.
+ */
+export async function openRouterKey(
+  environment: Readonly<Record<string, string | undefined>>,
+  cwd = process.cwd(),
+): Promise<string | undefined> {
+  if (environment.OPENROUTER_API_KEY?.trim()) return environment.OPENROUTER_API_KEY;
+  const text = await readFile(join(cwd, ".env"), "utf8").catch(() => "");
+  for (const line of text.split("\n")) {
+    const found = /^\s*(?:export\s+)?OPENROUTER_API_KEY\s*=\s*(.*?)\s*$/.exec(line);
+    if (found) return found[1]!.replace(/^(["'])(.*)\1$/, "$2");
+  }
+  return undefined;
+}
+
+/**
+ * Jev through OpenRouter, as `jev`, when `OPENROUTER_API_KEY` is set. The engine holds the key;
+ * no agent's environment has it. Without a usable key, asking for `jev` says why.
+ */
+export function installDecisions(
+  environment: Readonly<Record<string, string | undefined>>,
+): DecisionInstallation {
+  const apiKey = environment.OPENROUTER_API_KEY?.trim();
+  const refused = (reason: string) => ({
+    providers: {},
+    aliases: {},
+    unavailable: { jev: reason },
+  });
+  if (!apiKey) return refused("OPENROUTER_API_KEY is not set");
+  // A key with a space or line break in it would be quoted back by the request that failed on it.
+  if (!/^[\x21-\x7e]+$/.test(apiKey)) {
+    return refused("OPENROUTER_API_KEY is not one token of printable characters");
+  }
+  return {
+    providers: { openrouter: createOpenRouterProvider({ apiKey }) },
+    aliases: { jev: { provider: "openrouter", model: "typesafe/jev-1.13" } },
+  };
+}
+
+/**
+ * The run session, made ready once for everything that asks. A failure is not kept: a run host
+ * opened later, or the next harness's usage screen, asks again.
+ */
+function runSessionOnce(
+  name: () => string,
+  deps: Parameters<typeof ensureRunSession>[1],
+  onReady?: (session: RunSession) => void,
+): () => Promise<RunSession> {
+  let ready: Promise<RunSession> | undefined;
+  return () => {
+    ready ??= Promise.resolve()
+      .then(() => ensureRunSession(name(), deps))
+      .then((session) => {
+        // Saying where the agents are must never fail the agent.
+        try {
+          onReady?.(session);
+        } catch {}
+        return session;
+      })
+      .catch((error: unknown) => {
+        ready = undefined;
+        throw error;
+      });
+    return ready;
+  };
+}
+
+/**
+ * The Herdr session this process's pane is in, which `awf run --here` drives: the one owning
+ * `$HERDR_SOCKET_PATH`. Never `AWF_HERDR_SESSION`, which places a run's agents, not its caller.
+ */
+export async function callerSession(
+  run: RunProcess,
+  environment: Readonly<Record<string, string | undefined>>,
+): Promise<string> {
+  const socket = environment.HERDR_SOCKET_PATH;
+  if (!socket) throw new Error("not in a Herdr pane: HERDR_SOCKET_PATH is not set");
+  const listed = await run({ argv: ["herdr", "session", "list", "--json"], timeoutMs: 10_000 });
+  if (listed.exitCode !== 0) {
+    throw new Error(`herdr session list failed: ${(listed.stderr || listed.stdout).trim()}`);
+  }
+  const name = parseSessions(listed.stdout).find((session) => session.socketPath === socket)?.name;
+  // Guessing would drive a session nobody is looking at.
+  if (name === undefined) {
+    throw new Error(`no Herdr session owns ${socket} (\`herdr session list --json\`)`);
+  }
+  return name;
+}
+
+const METERED_CREDENTIAL_ENVIRONMENT = [
+  ...new Set(Object.values(HARNESSES).flatMap((spec) => spec.meteredCredentials)),
+];
+
+/** What every harness's session sets for the commands it runs, `awf` among them. */
+const CALLING_SESSION_ENVIRONMENT = [
+  ...new Set(
+    Object.values(HARNESSES).flatMap((spec) => [...spec.callingSessionEnv, ...spec.settingsEnv]),
+  ),
+];
+
+/**
+ * Unset for every agent: the metered credentials, which also refuse the run, the engine's own,
+ * which a harness such as pi would otherwise bill against, the calling session's markers and the
+ * ids `--here` passed on, and what would override the settings an agent is launched at.
+ */
+const WITHHELD_ENVIRONMENT = [
+  ...METERED_CREDENTIAL_ENVIRONMENT,
+  "OPENROUTER_API_KEY",
+  ...CALLING_SESSION_ENVIRONMENT,
+  "AWF_CALLER_SESSIONS",
+];
+
+/**
+ * Unset in a run's panes besides: the config the run session's server starts with, which a `herdr`
+ * started in a pane would otherwise read in place of the operator's.
+ */
+const PANE_WITHHELD_ENVIRONMENT = [...WITHHELD_ENVIRONMENT, "HERDR_CONFIG_PATH"];
+
+function refuseMeteredCredentials(environment: Readonly<Record<string, string | undefined>>): void {
+  const configured = METERED_CREDENTIAL_ENVIRONMENT.filter((name) => environment[name]?.trim());
+  if (configured.length > 0) {
+    throw new Error(
+      `subscription runtime refused metered credential environment: ${configured.join(", ")}`,
+    );
+  }
+}
+
+/**
+ * Each harness's subscription login is checked when its first agent opens, once a run: a run that
+ * opens only codex agents needs no claude login, which is what lets one run in a box holding
+ * codex's credential alone.
+ */
+function loginChecked(run: RunProcess, factory: AgentRunHostFactory): AgentRunHostFactory {
+  const checks = new Map<string, Promise<void>>();
+  const check = (harness: string): Promise<void> => {
+    const login = Object.hasOwn(LOGINS, harness) ? LOGINS[harness as Harness] : undefined;
+    if (!login || isAbsent(login)) return Promise.resolve();
+    let checking = checks.get(harness);
+    if (!checking) {
+      checking = login(run);
+      checks.set(harness, checking);
+    }
+    return checking;
+  };
+  return {
+    ...factory,
+    async openRun(spec) {
+      const host = await factory.openRun(spec);
+      return {
+        ...host,
+        async openAgent(request) {
+          // The calling session is logged in as the operator logged it in; awf did not start it.
+          if (!request.execution.caller) await check(request.execution.harness);
+          return host.openAgent(request);
+        },
+        inspect: () => host.inspect(),
+        close: (reason) => host.close(reason),
+      };
+    },
+  };
+}
+
+/** The subscription login each harness's agents need, or why none is checked. */
+const LOGINS: Readonly<Record<Harness, ((run: RunProcess) => Promise<void>) | Absent>> = {
+  async claude(run) {
+    const claude = await readClaudeBilling(run);
+    if (claude !== "subscription") {
+      throw new Error(
+        `Claude subscription authentication is required (claude.ai login or \`claude setup-token\`); \`claude auth status\` reads as ${claude}`,
+      );
+    }
+  },
+  async codex(run) {
+    const codex = await readCodexBilling(run);
+    if (codex !== "subscription") {
+      throw new Error(
+        `Codex subscription authentication is required (ChatGPT login); \`codex login status\` reads as ${codex}`,
+      );
+    }
+  },
+  pi: { absent: "pi's login is per provider, and each agent's model names its own" },
+  async cursor(run) {
+    if (!(await readCursorLogin(run))) {
+      throw new Error(
+        "Cursor authentication is required (`cursor-agent login`); `cursor-agent status` reads as logged out",
+      );
+    }
+  },
+};

package/src/pane-layout.ts

@@ -0,0 +1,125 @@
+import type { KeepPane, PaneLayout, TurnOutcome } from "@agentswf/contract/workflow";
+
+/** A terminal session's name: Herdr makes `sessions/{name}` from it, and a leading `-` reads as an option. */
+export const SESSION_NAME = /^[a-z0-9][a-z0-9-]{0,31}$/;
+
+const SHARE = { min: 0.2, max: 0.8 };
+const NEW_TAB_FIELDS = new Set(["session", "workspace", "tab"]);
+const BESIDE_FIELDS = new Set(["beside", "side", "share"]);
+const KEEP: readonly KeepPane[] = ["never", "on-failure", "always"];
+
+/**
+ * Refuses, before anything is placed, what the agent's own spec fixes about its pane: what a
+ * workflow, untyped at run time, could get wrong in `layout` or `keepPane`, and either on an agent
+ * with no pane of awf's to place (docs/design/pane-layout.md, "Refused at open").
+ */
+export function checkPaneOptions(
+  key: string,
+  spec: { layout?: unknown; keepPane?: unknown },
+  agent: { headless: boolean; sandboxed: boolean },
+): void {
+  const refuse = (why: string): never => {
+    throw new Error(`agent ${key}: ${why}`);
+  };
+  if (spec.layout === undefined && spec.keepPane === undefined) return;
+  if (agent.headless) refuse("layout and keepPane place a pane, and a headless agent has none");
+  if (agent.sandboxed) {
+    refuse(
+      "layout and keepPane are not yet for an agent in a sandbox, whose pane is in its own Herdr",
+    );
+  }
+  if (spec.keepPane !== undefined && !KEEP.includes(spec.keepPane as KeepPane)) {
+    refuse(`keepPane is never, on-failure or always, not ${JSON.stringify(spec.keepPane)}`);
+  }
+  if (spec.layout === undefined) return;
+  const layout = spec.layout;
+  if (typeof layout !== "object" || layout === null || Array.isArray(layout)) {
+    refuse(`a layout is an object, not ${JSON.stringify(layout)}`);
+  }
+  const fields = Object.keys(layout as object).filter(
+    (field) => (layout as Record<string, unknown>)[field] !== undefined,
+  );
+  const given = layout as Record<string, unknown>;
+  if (given.beside !== undefined) {
+    const others = fields.filter((field) => !BESIDE_FIELDS.has(field));
+    if (others.length > 0) {
+      refuse(`a layout beside another pane takes side and share, not ${others.join(", ")}`);
+    }
+    if (typeof given.beside !== "string" || given.beside === "") {
+      refuse(`beside names an agent's key, not ${JSON.stringify(given.beside)}`);
+    }
+    if (given.beside === key) refuse("a pane cannot be placed beside itself");
+    if (given.side !== "right" && given.side !== "below") {
+      refuse(`side is right or below, not ${JSON.stringify(given.side)}`);
+    }
+    const share = given.share;
+    if (
+      share !== undefined &&
+      (typeof share !== "number" || !(share >= SHARE.min && share <= SHARE.max))
+    ) {
+      refuse(`share is from ${SHARE.min} to ${SHARE.max}, not ${JSON.stringify(share)}`);
+    }
+    return;
+  }
+  const others = fields.filter((field) => !NEW_TAB_FIELDS.has(field));
+  if (others.length > 0) {
+    refuse(
+      `a layout takes session, workspace and tab, or beside and side; not ${others.join(", ")}`,
+    );
+  }
+  const { session, workspace, tab } = given;
+  if (session !== undefined && (typeof session !== "string" || !SESSION_NAME.test(session))) {
+    refuse(
+      `session ${JSON.stringify(session)} is not a session name: lowercase letters, digits and -, up to 32, not starting with -`,
+    );
+  }
+  if (session !== undefined && workspace === "origin") {
+    refuse('"origin" is a workspace in its own session, so it takes no session');
+  }
+  if (
+    workspace !== undefined &&
+    workspace !== "run" &&
+    workspace !== "origin" &&
+    !(
+      typeof workspace === "object" &&
+      workspace !== null &&
+      !Array.isArray(workspace) &&
+      Object.keys(workspace).join() === "name" &&
+      nonEmpty((workspace as { name?: unknown }).name)
+    )
+  ) {
+    refuse(`workspace is "run", "origin" or { name }, not ${JSON.stringify(workspace)}`);
+  }
+  if (tab !== undefined && !nonEmpty(tab)) refuse(`tab is a label, not ${JSON.stringify(tab)}`);
+}
+
+/**
+ * A checked layout as it is kept and compared: fields given as `undefined` dropped, so a reopen
+ * that leaves one out matches.
+ */
+export function storedLayout(layout: PaneLayout): PaneLayout {
+  return Object.fromEntries(
+    Object.entries(structuredClone(layout)).filter(([, value]) => value !== undefined),
+  ) as PaneLayout;
+}
+
+function nonEmpty(value: unknown): value is string {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/** The key a layout splits the pane of; absent for a new tab. */
+export function besideOf(layout: PaneLayout | undefined): string | undefined {
+  return layout && "beside" in layout ? layout.beside : undefined;
+}
+
+/**
+ * Whether a done agent's pane stays, by `keepPane` and how its last operation ended: `on-failure`
+ * keeps it unless that was answered, or there was none.
+ */
+export function keepsPane(
+  keepPane: KeepPane | undefined,
+  last: TurnOutcome<never>["kind"] | undefined,
+): boolean {
+  if (keepPane === "always") return true;
+  return keepPane === "on-failure" && last !== undefined && last !== "answered";
+}