@plannotator/ui 0.50.0 → 0.52.0

package/themes/gruvbox.css

@@ -30,6 +30,10 @@
 
   --code-bg: #32302f;
   --focus-highlight: #83a598;
+
+  /* The gruvbox Shiki theme sets the git "added" colour to the text colour,
+     so @pierre/diffs would draw added lines grey. Use gruvbox green. */
+  --diffs-addition-color-override: #b8bb26;
 }
 
 .theme-gruvbox.light {
@@ -59,4 +63,6 @@
 
   --code-bg: #ebdbb2;
   --focus-highlight: #076678;
+
+  --diffs-addition-color-override: #79740e;
 }

package/types.ts

@@ -188,6 +188,10 @@ export interface HtmlElementContext {
   component?: string;
   /** Live-app sessions only: the route the element was seen on and the page title. */
   page?: { url: string; title?: string };
+  /** Media elements only: the file the element shows, resolved by the bridge
+   *  exactly as the composer quote names it (src, data-src, srcset,
+   *  <picture>/<source>, poster), query and fragment scrubbed. */
+  sourceName?: string;
 }
 
 export type AlertKind = 'note' | 'tip' | 'warning' | 'caution' | 'important';
@@ -446,6 +450,15 @@ export interface AIQuestion {
     label?: string;
     text?: string;
     sourcePath?: string;
+    /** Agent-facing identity of the selected element(s) (raw-HTML / live-app
+     *  pinpoints): sent with the question, never shown in the chat. */
+    detail?: string;
+    /** 1-based source lines of a text selection in a markdown document (the
+     *  enclosing block's span, or first to last block for a selection over
+     *  several). `buildDefaultPrompt` appends them to the `Source:` line
+     *  (`, line 41` / `, lines 41–44`). Optional: absent prints no lines. */
+    lineStart?: number;
+    lineEnd?: number;
   };
   /** undefined = general question (no file scope) */
   filePath?: string;
@@ -466,6 +479,12 @@ export interface AIResponse {
   errorCode?: string;
   /** "Ask this session": the question is waiting for a busy session, or interrupting it. */
   status?: 'waiting' | 'interrupting';
+  /**
+   * "Ask this session": a note shown under the answer (not an error). Set when
+   * the person typed into the session while it answered, so the answer stops
+   * where their prompt took the turn over.
+   */
+  notice?: string;
   createdAt: number;
 }
 

package/utils/agentClosed.ts

@@ -0,0 +1,33 @@
+/**
+ * Copy for a review the agent closed (`POST /api/host/close`,
+ * packages/shared/host-control.ts). The tab learns it from the
+ * `session-closed` event on the external-annotation stream.
+ *
+ * The close keeps the draft; what brings it back depends on the draft's key,
+ * so the copy names the case:
+ *  - `file` / `folder`: a local file's draft follows its PATH as well as its
+ *    text (packages/shared/annotate-draft.ts), so it comes back even after
+ *    the file was edited. A folder's files each carry their own copy.
+ *  - `document`: a URL or an agent message is keyed by its content only, so
+ *    only the same, unchanged document brings it back.
+ *  - `app`: a live app is keyed by its address.
+ *  - `changes`: code review, keyed by the patch (or the PR).
+ */
+
+export const AGENT_CLOSED_TITLE = 'Closed by the Agent';
+
+export type AgentClosedSurface = 'file' | 'folder' | 'document' | 'app' | 'changes';
+
+const RESTORE: Record<AgentClosedSurface, string> = {
+  file: 'Opening the file again brings it back, even after it is edited.',
+  folder: 'Opening the folder or its files again brings it back, even after they are edited.',
+  document: 'Reopening the same document, unchanged, brings it back.',
+  app: 'Opening the same app again brings it back.',
+  changes: 'Reopening a review of the same changes brings it back.',
+};
+
+export function agentClosedSubtitle(unsentAnnotations: number, surface: AgentClosedSurface = 'document'): string {
+  if (unsentAnnotations <= 0) return 'The agent closed this review.';
+  const comments = unsentAnnotations === 1 ? 'Your comment is' : `Your ${unsentAnnotations} comments are`;
+  return `The agent closed this review. ${comments} saved as a draft. ${RESTORE[surface]}`;
+}

package/utils/agentToolAnnouncement.ts

@@ -0,0 +1,109 @@
+/**
+ * One-time gate for the "turn the agent tool on" offer. The `plannotator`
+ * agent tool is off by default on Pi and OpenCode 2 (a full tool definition
+ * in every request), so those sessions get one offer explaining what turning
+ * it on does. Cookie-backed like the other announcement gates, so a dismissal
+ * survives Plannotator's random localhost ports, and shared by the plan
+ * editor, the annotate surfaces and the code review editor.
+ *
+ * A plain storage key rather than a settings-registry entry for the same
+ * reason as terminalToolsAnnouncement.ts: configStore seeds every registry
+ * default into a cookie on first access, so a registry flag could not tell
+ * "never seen" from "seeded default".
+ */
+
+import type { AgentToolSetting } from './agentToolSetting';
+import { storage } from './storage';
+import { needsTerminalToolsAnnouncement } from './terminalToolsAnnouncement';
+
+const STORAGE_KEY = 'plannotator-announce-agent-tool-seen';
+// Bump to re-offer after a meaningful revision.
+const CURRENT_VERSION = '1';
+
+export function needsAgentToolAnnouncement(): boolean {
+  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+}
+
+export function markAgentToolAnnouncementSeen(): void {
+  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+}
+
+/**
+ * Whether this page load may show the offer, latched at mount by the Apps.
+ * False while the terminal-tools announcement is still pending: that one
+ * takes this load. The "Ask this session" announcement is ordered ahead of
+ * this one per load instead (see `earlierAnnouncementMayShow`), because it
+ * only shows in a connected session and a reader who never has one must
+ * still get this offer.
+ */
+export function agentToolAnnouncementPendingThisLoad(): boolean {
+  return needsAgentToolAnnouncement() && !needsTerminalToolsAnnouncement();
+}
+
+/**
+ * The offer describes something the reader can actually do here: a host
+ * whose tool is off by default (Pi, OpenCode 2), still off for the next
+ * session, never chosen in config.json (someone who turned it off in Settings
+ * is not asked again), and not decided by PLANNOTATOR_AGENT_TOOL (a toggle
+ * cannot change that).
+ */
+export function agentToolOfferApplies(setting: AgentToolSetting | undefined): setting is AgentToolSetting {
+  return (
+    setting !== undefined &&
+    (setting.host === 'pi' || setting.host === 'opencode') &&
+    !setting.enabled &&
+    !setting.configured &&
+    setting.env === undefined
+  );
+}
+
+/**
+ * The host an open offer names, or null where there is never an offer. Read
+ * from the host alone: after "Turn it on" succeeds the setting is on, and the
+ * open dialog must stay to say so.
+ */
+export function agentToolOfferHostOf(setting: AgentToolSetting | undefined): 'pi' | 'opencode' | null {
+  return setting?.host === 'pi' || setting?.host === 'opencode' ? setting.host : null;
+}
+
+export interface AgentToolAnnouncementGateState {
+  /** Latched at mount from agentToolAnnouncementPendingThisLoad(). */
+  readonly announcementPending: boolean;
+  /** The app has not finished loading its initial payload. */
+  readonly isLoading: boolean;
+  /** parseAgentToolSetting() of the session's serverConfig. */
+  readonly setting: AgentToolSetting | undefined;
+  /**
+   * Archive browsing, a read-only shared plan, or no Plannotator server
+   * (nothing could write config.json). Deferred, not consumed.
+   */
+  readonly readOnlySession: boolean;
+  /** Plannotator's compact touch shell. Deferred, not consumed. */
+  readonly compact: boolean;
+  /** Any other first-run dialog is on screen. The chain dialogs never stack. */
+  readonly otherFirstRunDialogVisible: boolean;
+  /**
+   * The "Ask this session" announcement is pending and may still take this
+   * load (its capabilities answer is outstanding, or it is eligible). The
+   * offer then waits for a later load: never two announcements on one load.
+   */
+  readonly earlierAnnouncementMayShow: boolean;
+}
+
+/**
+ * Whether the offer may open now. LAST in each app's first-run chain, after
+ * the terminal-tools and "Ask this session" announcements. The Apps pass this
+ * through useFirstRunAnnouncementWindow, so it only opens before the reader
+ * has started working.
+ */
+export function agentToolAnnouncementEligible(state: AgentToolAnnouncementGateState): boolean {
+  return (
+    state.announcementPending &&
+    !state.isLoading &&
+    agentToolOfferApplies(state.setting) &&
+    !state.readOnlySession &&
+    !state.compact &&
+    !state.otherFirstRunDialogVisible &&
+    !state.earlierAnnouncementMayShow
+  );
+}

package/utils/agentToolSetting.ts

@@ -0,0 +1,108 @@
+/**
+ * The `plannotator` agent tool switch as the UI sees it: what the server
+ * reports in `serverConfig` (packages/shared/config.ts getServerConfig) and
+ * the POST /api/config write that changes it.
+ *
+ * Only a Plannotator server that knows the session's tool host sends
+ * `agentToolHost` (the Claude Code mod, Pi, OpenCode 2). Everything else, an
+ * older server, OpenCode 1, Codex, a `@plannotator/ui` host such as
+ * Workspaces, parses to undefined, and no toggle or offer is shown.
+ */
+
+/** The hosts that register the `plannotator` agent tool. */
+export type AgentToolHost = 'claude-code' | 'pi' | 'opencode';
+
+export interface AgentToolSetting {
+  readonly host: AgentToolHost;
+  /** The value the NEXT session uses (env, then config file, then the host default). */
+  readonly enabled: boolean;
+  /** config.json holds an explicit choice (false: the host default applies). */
+  readonly configured: boolean;
+  /** PLANNOTATOR_AGENT_TOOL, when it overrides the file. A toggle cannot change it. */
+  readonly env?: boolean;
+}
+
+function isAgentToolHost(value: unknown): value is AgentToolHost {
+  return value === 'claude-code' || value === 'pi' || value === 'opencode';
+}
+
+/** Reads the agent tool fields out of a `serverConfig` payload, or undefined when the server reports no tool host. */
+export function parseAgentToolSetting(serverConfig: unknown): AgentToolSetting | undefined {
+  if (typeof serverConfig !== 'object' || serverConfig === null) return undefined;
+  const sc = serverConfig as Record<string, unknown>;
+  if (!isAgentToolHost(sc.agentToolHost) || typeof sc.agentToolEnabled !== 'boolean') return undefined;
+  return {
+    host: sc.agentToolHost,
+    enabled: sc.agentToolEnabled,
+    configured: sc.agentToolConfigured === true,
+    ...(typeof sc.agentToolEnv === 'boolean' ? { env: sc.agentToolEnv } : {}),
+  };
+}
+
+/** The setting after a successful write of `value` (an env override still decides). */
+export function withSavedAgentTool(setting: AgentToolSetting, value: boolean): AgentToolSetting {
+  return { ...setting, enabled: setting.env ?? value, configured: true };
+}
+
+/**
+ * Writes `{ agentTool }` to config.json through POST /api/config. Resolves
+ * once the server confirms the file holds the value; rejects with a readable
+ * message otherwise (the server answers 500 when the write did not land).
+ * Not debounced and not best-effort like the settings registry's write-back:
+ * the offer and the switch must know whether it worked.
+ */
+export async function saveAgentToolSetting(
+  value: boolean,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  let response: Response;
+  try {
+    response = await fetchImpl('/api/config', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ agentTool: value }),
+    });
+  } catch {
+    throw new Error('Could not reach Plannotator. Nothing was changed.');
+  }
+  if (response.ok) return;
+  let detail = '';
+  try {
+    const body = (await response.json()) as { error?: unknown };
+    if (typeof body.error === 'string') detail = body.error;
+  } catch {
+    // No JSON body: the status line below is all there is.
+  }
+  throw new Error(detail || `Plannotator answered ${response.status}. Nothing was changed.`);
+}
+
+const HOST_NAMES: Record<AgentToolHost, string> = {
+  'claude-code': 'Claude Code',
+  pi: 'Pi',
+  opencode: 'OpenCode',
+};
+
+export function agentToolHostName(host: AgentToolHost): string {
+  return HOST_NAMES[host];
+}
+
+/**
+ * When a change takes effect on this host: the tool list is part of the
+ * model's prompt, so each host reads the setting once. Pi reads it per
+ * session; the Claude Code mod and the OpenCode plugin decide once per
+ * process (when the module or plugin loads), so those take a restart.
+ */
+export function agentToolAppliesWhen(host: AgentToolHost): string {
+  return host === 'pi' ? 'the next Pi session' : `the next time ${HOST_NAMES[host]} starts`;
+}
+
+/**
+ * What the tool costs in context. Pi and OpenCode send its full definition
+ * with every request; Claude Code defers it behind tool search, so it costs
+ * about its name until it is used.
+ */
+export function agentToolCostNote(host: AgentToolHost): string {
+  return host === 'claude-code'
+    ? 'Claude Code loads it only when needed.'
+    : 'Adds about 780 tokens to every request.';
+}

package/utils/aiProvider.ts

@@ -45,6 +45,8 @@ export const SESSION_ASK_ERROR_CODES = {
   agentBusy: 'agent_busy',
   blocked: 'session_blocked',
   gone: 'session_gone',
+  /** The person typed into the session while it answered: a note under the partial answer, not an error. */
+  takenOver: 'session_taken_over',
 } as const;
 
 export function isSessionBridgeProvider(provider: Pick<AIProviderOption, 'name' | 'sessionBridge'> | null | undefined): boolean {
@@ -52,18 +54,12 @@ export function isSessionBridgeProvider(provider: Pick<AIProviderOption, 'name'
 }
 
 /**
- * The "Ask this session" provider when it can answer here: present, the
- * session not gone, and not blocked unless it offers a transient answer.
+ * The "Ask this session" provider, whatever its status. A server that has one
+ * offers nothing else (the session that opened Plannotator is the only thing
+ * Ask AI talks to), so when it is present it is the selection.
  */
-export function findUsableSessionBridge(providers: AIProviderOption[]): AIProviderOption | null {
-  for (const provider of providers) {
-    const bridge = provider.sessionBridge;
-    if (!bridge) continue;
-    if (bridge.status === 'gone') continue;
-    if (bridge.status === 'blocked' && !bridge.modes.transient) continue;
-    return provider;
-  }
-  return null;
+export function findSessionBridge(providers: AIProviderOption[]): AIProviderOption | null {
+  return providers.find(isSessionBridgeProvider) ?? null;
 }
 
 export interface AIProviderSettings {
@@ -192,20 +188,14 @@ export function resolveAIProviderSelection(options: {
   const byId = (id: string | null | undefined) =>
     id ? providers.find(provider => provider.id === id) ?? null : null;
 
-  // An explicit saved pick wins, then "Ask this session" whenever the host
-  // session can answer, then the origin's own SDK provider and the older
-  // fallbacks. Without a usable bridge this is exactly the previous order.
-  const sessionBridge = findUsableSessionBridge(providers);
-  const explicitPick = sessionBridge
-    ? byId(originHasDedicatedAIProvider(origin)
-        ? (origin ? settings.providerByOrigin[origin] : null)
-        : settings.providerId)
-    : null;
-
+  // "Ask this session" is the only choice when the server offers it, even when
+  // the session is busy, blocked or gone: a saved pick never routes a question
+  // anywhere else (and is not rewritten, so it still applies to sessions with
+  // no bridge). Without a bridge this is the previous order.
+  const sessionBridge = findSessionBridge(providers);
   const provider =
-    explicitPick ??
-    byId(origin ? settings.providerByOrigin[origin] : null) ??
     sessionBridge ??
+    byId(origin ? settings.providerByOrigin[origin] : null) ??
     findOriginAIProvider(providers, origin) ??
     byId(settings.providerId) ??
     byId(serverDefaultProvider) ??
@@ -218,23 +208,6 @@ export function resolveAIProviderSelection(options: {
   };
 }
 
-/**
- * Where "Ask a separate AI instead" goes when "Ask this session" cannot
- * answer: the selection the app would make if the bridge were not there.
- */
-export function resolveSessionBridgeFallback(options: {
-  providers: AIProviderOption[];
-  origin?: Origin | null;
-  settings?: AIProviderSettings;
-  serverDefaultProvider?: string | null;
-}): AIProviderSelection {
-  const providers = options.providers.filter(provider => !isSessionBridgeProvider(provider));
-  const serverDefaultProvider = providers.some(provider => provider.id === options.serverDefaultProvider)
-    ? options.serverDefaultProvider
-    : null;
-  return resolveAIProviderSelection({ ...options, providers, serverDefaultProvider });
-}
-
 export function saveAIProviderSelection(options: {
   providerId: string | null;
   model?: string | null;

package/utils/annotationOwnsHighlight.ts

@@ -0,0 +1,27 @@
+import { QUESTION_ANSWER_ANNOTATION_PREFIX } from '@plannotator/core/question-block';
+import { AnnotationType, type Annotation } from '../types';
+
+/** Ids of checkbox-toggle annotations: keyed by their list item's block,
+ *  quoting raw markdown, and never a text highlight. */
+export const CHECKBOX_ANNOTATION_PREFIX = 'ann-checkbox-';
+
+/**
+ * Whether an annotation is restored as a text highlight in the document view.
+ *
+ * Not: comments made in the plan diff view (`diffContext`, `blockId`
+ * `diff-block-N`, drawn by the diff view), general comments, checkbox
+ * toggles, and answers to `:::question` blocks (drawn by the question card).
+ * Restoring any of those through the highlighter finds no text, so it would
+ * be reported unanchored and its `blockId` rewritten. Every caller that
+ * re-applies a stored list filters with this, and the highlighter skips the
+ * same rows itself.
+ */
+export function annotationOwnsHighlight(
+  annotation: Pick<Annotation, 'id' | 'type' | 'diffContext' | 'questionAnswer'>,
+): boolean {
+  return !annotation.diffContext
+    && annotation.type !== AnnotationType.GLOBAL_COMMENT
+    && !annotation.id.startsWith(CHECKBOX_ANNOTATION_PREFIX)
+    && annotation.questionAnswer == null
+    && !annotation.id.startsWith(QUESTION_ANSWER_ANNOTATION_PREFIX);
+}

package/utils/annotationScope.ts

@@ -87,6 +87,12 @@ export function groupAnnotationsByDocument(
   documents: Iterable<AnnotationDocumentInput>,
   currentPath: string | null,
   roots: readonly string[] = [],
+  /**
+   * A fixed reading order (a review of several files): groups follow it, the
+   * open document included, and documents outside it come after, by path.
+   * Absent: the open document first, the rest by path.
+   */
+  order?: readonly string[] | null,
 ): AnnotationDocumentGroup[] {
   const normalizedCurrent = currentPath ? normalizeBrowserPath(currentPath) : null;
   const groups: AnnotationDocumentGroup[] = [];
@@ -102,6 +108,12 @@ export function groupAnnotationsByDocument(
       isCurrent: path === normalizedCurrent,
     });
   }
+  if (order) {
+    const ranks = new Map(order.map((path, index) => [normalizeBrowserPath(path), index]));
+    const rank = (path: string) => ranks.get(path) ?? order.length;
+    groups.sort((a, b) => rank(a.path) - rank(b.path) || a.path.localeCompare(b.path));
+    return groups;
+  }
   groups.sort((a, b) => {
     if (a.isCurrent !== b.isCurrent) return a.isCurrent ? -1 : 1;
     return a.path.localeCompare(b.path);
@@ -124,6 +136,8 @@ export function buildAnnotationDocumentGroups(input: {
   cached: Iterable<readonly [string, readonly Annotation[]]>;
   current: { key: string; label?: string; annotations: readonly Annotation[] };
   roots?: readonly string[];
+  /** A fixed reading order; see groupAnnotationsByDocument. */
+  order?: readonly string[] | null;
 }): AnnotationDocumentGroup[] {
   const byPath = new Map<string, readonly Annotation[]>();
   for (const [path, annotations] of input.cached) byPath.set(path, annotations);
@@ -136,6 +150,7 @@ export function buildAnnotationDocumentGroups(input: {
     })),
     input.current.key,
     input.roots ?? [],
+    input.order,
   );
 }
 

package/utils/askSessionAnnouncement.ts

@@ -0,0 +1,107 @@
+/**
+ * One-time gate for the "Ask this session" announcement: Ask AI answered by
+ * the agent session that opened Plannotator, and reviews that no longer hold
+ * that session. Cookie-backed like the other announcement gates, so a
+ * dismissal survives Plannotator's random localhost ports, and shared by the
+ * plan editor, the annotate surfaces and the code review editor: dismissing it
+ * anywhere retires it everywhere.
+ *
+ * A plain storage key rather than a settings-registry entry for the same reason
+ * as terminalToolsAnnouncement.ts: configStore seeds every registry default
+ * into a cookie on first access, so a registry flag could not tell "never seen"
+ * from "seeded default".
+ */
+
+import { isSessionBridgeProvider, type AIProviderOption } from './aiProvider';
+import { storage } from './storage';
+import { needsTerminalToolsAnnouncement } from './terminalToolsAnnouncement';
+
+const STORAGE_KEY = 'plannotator-announce-ask-session-seen';
+// Bump to re-announce after a meaningful revision.
+const CURRENT_VERSION = '1';
+
+export function needsAskSessionAnnouncement(): boolean {
+  return storage.getItem(STORAGE_KEY) !== CURRENT_VERSION;
+}
+
+export function markAskSessionAnnouncementSeen(): void {
+  storage.setItem(STORAGE_KEY, CURRENT_VERSION);
+}
+
+/**
+ * Whether this page load may show the announcement, latched at mount by the
+ * Apps. False while the terminal-tools announcement is still pending: that one
+ * takes this load, and this one waits for the next, so a reader never gets two
+ * announcements back to back. A reader who dismissed the terminal-tools
+ * announcement on an earlier load gets this one on the next load.
+ */
+export function askSessionAnnouncementPendingThisLoad(): boolean {
+  return needsAskSessionAnnouncement() && !needsTerminalToolsAnnouncement();
+}
+
+/** The hosts whose sessions answer Ask AI through the session bridge. */
+export type AskSessionAgent = 'claude-code' | 'pi' | 'opencode';
+
+function askSessionAgentForHost(host: string | undefined): AskSessionAgent | null {
+  return host === 'claude-code' || host === 'pi' || host === 'opencode' ? host : null;
+}
+
+/**
+ * The agent whose session is connected to THIS Plannotator session right now:
+ * the server lists the "Ask this session" provider and its session is not
+ * gone. Null everywhere the feature is not live (remote, --tailscale, Windows,
+ * the Claude Code mod turned off, `-p`, Pi's event-API path, OpenCode 1, an
+ * older CLI): the announcement only describes what the reader can use here.
+ */
+export function connectedAskSessionAgent(
+  providers: ReadonlyArray<Pick<AIProviderOption, 'name' | 'sessionBridge'>>,
+): AskSessionAgent | null {
+  const bridge = providers.find(isSessionBridgeProvider)?.sessionBridge;
+  if (!bridge || bridge.status === 'gone') return null;
+  return askSessionAgentForHost(bridge.host);
+}
+
+export interface AskSessionAnnouncementGateState {
+  /** Latched at mount from askSessionAnnouncementPendingThisLoad(). */
+  readonly announcementPending: boolean;
+  /** The app has not finished loading its initial payload. */
+  readonly isLoading: boolean;
+  /**
+   * connectedAskSessionAgent() of the capabilities answer. Null while that
+   * answer is pending and whenever the session is not connected: deferred,
+   * never consumed, so the reader sees it in a session where it is true.
+   */
+  readonly connectedAgent: AskSessionAgent | null;
+  /**
+   * Ask AI is actually reachable on this surface (the plan editor's canUseAI,
+   * not taken over by the annotate agent terminal; code review's AI button),
+   * so "Open Ask AI to try it" never points at nothing.
+   */
+  readonly askAIUsable: boolean;
+  /** Archive browsing, a read-only shared plan, or no Plannotator server. Deferred, not consumed. */
+  readonly readOnlySession: boolean;
+  /** Plannotator's compact touch shell. Deferred, not consumed. */
+  readonly compact: boolean;
+  /** Any other first-run dialog is on screen. The chain dialogs never stack. */
+  readonly otherFirstRunDialogVisible: boolean;
+}
+
+/**
+ * Whether the announcement may open now. LAST in each app's first-run chain,
+ * after the terminal-tools announcement (see askSessionAnnouncementPendingThisLoad)
+ * and behind every dialog that asks the user to decide something, for the
+ * reasons terminalToolsAnnouncementCanShow gives. The Apps pass this through
+ * useFirstRunAnnouncementWindow, which only lets it open before the reader has
+ * started working.
+ */
+export function askSessionAnnouncementEligible(state: AskSessionAnnouncementGateState): boolean {
+  return (
+    state.announcementPending &&
+    !state.isLoading &&
+    state.connectedAgent !== null &&
+    state.askAIUsable &&
+    !state.readOnlySession &&
+    !state.compact &&
+    !state.otherFirstRunDialogVisible
+  );
+}