@visual-z/xeno 0.2.1 → 0.3.0

package/src/runtime/exec-sessions.ts

@@ -11,18 +11,22 @@
  * Every call still ends in one tool_result, so the log records each
  * observation in order (log-as-truth). What the log cannot hold is the
  * process itself: sessions belong to this OS process and die with it, and a
- * restarted xeno reports an unknown session instead of pretending to resume.
+ * restarted xeno recovers observations from the log without reattaching a PID.
  *
  * Output is spooled to a file as it arrives. Each call archives exactly the
- * bytes since the previous call as an observation blob (D8), so memory stays
- * bounded by the preview and nothing the process printed is lost.
+ * bytes since the previous call as an observation blob (D8), without keeping
+ * cumulative output strings. Capture errors are explicit partial observations.
  */
 import { open, mkdir, rm, type FileHandle } from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
-import { commandEnvironment } from "../store/command.ts";
+import { commandArgv, commandEnvironment, COMMAND_TERMINATION_GRACE_MS } from "../core/command-contract.ts";
 import { archiveObservation, type ArchivedObservation } from "../store/observations.ts";
+import { ToolFault, NOT_STARTED } from "../core/tool-failure.ts";
+import { processReceipt, retainProcessReceipts, type ProcessReceipt, type ProcessSource } from "../core/process-receipt.ts";
+import type { CommandArtifactObserver } from "./command-artifacts.ts";
+import type { CommandArtifactReceipt } from "../core/command-artifacts.ts";
 
 /** Codex's default: long enough for most commands to finish in one call. */
 export const DEFAULT_YIELD_MS = 10_000;
@@ -35,34 +39,55 @@ export const MAX_YIELD_MS = 30_000;
  * well before it exhausts the machine.
  */
 export const MAX_SESSIONS = 16;
-const TERMINATION_GRACE_MS = 200;
-/** After exit, how long silence must last before the output is final. */
-const EXIT_IDLE_MS = 100;
+/** Assumed drain bound for descendants which escaped the owned group; never claim EOF on expiry. */
+const EXIT_DRAIN_MS = 1_000;
+/** Disposable acceleration only. Original log receipts outlive these assumed memory bounds. */
+export const CLOSED_RECEIPT_LIMIT = 64;
+export const CLOSED_RECEIPT_AGE_MS = 10 * 60_000;
+
+type TakenOutput = {
+  stored: ArchivedObservation; receipt: ProcessReceipt; wallMs: number;
+  exit: number | null; stopped?: "timeout" | "cancelled";
+};
+type ClosedSession = { owner?: string; id: number; endedAt: number; receipt: ProcessReceipt };
 
 interface Session {
+  owner?: string;
   id: number;
   command: string;
   cwd: string;
   tty: boolean;
+  source: ProcessSource;
+  artifactObserver?: CommandArtifactObserver;
+  artifacts?: Promise<CommandArtifactReceipt>;
   started: number;
   pid: number;
   spool: FileHandle;
   spoolPath: string;
   queue: Promise<unknown>;
+  operations: Promise<unknown>;
+  final?: TakenOutput;
+  captureError?: string;
   written: number;
   read: number;
-  lastData: number;
   exit: number | null;
-  stopped?: "timeout";
+  stopped?: "timeout" | "cancelled";
+  escalation?: ReturnType<typeof setTimeout>;
   timeoutMs: number;
   exited: Promise<void>;
+  drained: Promise<void>;
+  finishing?: Promise<void>;
+  closeCapture(): Promise<void>;
+  alive(): boolean;
   write(chars: string): void;
   kill(signal: NodeJS.Signals): void;
   timer: ReturnType<typeof setTimeout>;
 }
 
 const sessions = new Map<number, Session>();
-let nextId = 1;
+const closedSessions = new Map<number, ClosedSession>();
+// O.14: a restarted process must not accidentally reuse an old poll capability.
+let nextId = Number.parseInt(randomUUID().replaceAll("-", "").slice(0, 12), 16);
 let hooked = false;
 
 function killGroup(pid: number, signal: NodeJS.Signals): void {
@@ -77,32 +102,55 @@ function killGroup(pid: number, signal: NodeJS.Signals): void {
 export function killAllExecSessions(): void {
   for (const session of sessions.values()) {
     clearTimeout(session.timer);
-    session.kill("SIGKILL");
+    clearTimeout(session.escalation);
+    if (session.exit === null) session.kill("SIGKILL");
     void session.spool.close().catch(() => {});
     void rm(session.spoolPath, { force: true });
   }
   sessions.clear();
+  closedSessions.clear();
+}
+
+export function runningSessions(owner?: string): { id: number; command: string; exit: number | null }[] {
+  return [...sessions.values()].filter(session => session.owner === owner).map(({ id, command, exit }) => ({ id, command, exit }));
 }
 
-export function runningSessions(): { id: number; command: string }[] {
-  return [...sessions.values()].map(({ id, command }) => ({ id, command }));
+function pruneClosed(now: number): void {
+  const retained = retainProcessReceipts([...closedSessions.values()], now, CLOSED_RECEIPT_AGE_MS, CLOSED_RECEIPT_LIMIT);
+  closedSessions.clear();
+  for (const item of retained) closedSessions.set(item.id, item);
+}
+
+export function closedSession(id: number, owner?: string): ClosedSession | undefined {
+  pruneClosed(performance.now());
+  const item = closedSessions.get(id);
+  return item?.owner === owner ? item : undefined;
 }
 
 function append(session: Session, chunk: Uint8Array): void {
-  session.lastData = performance.now();
   const bytes = chunk.slice();
   session.queue = session.queue.then(async () => {
-    await session.spool.write(bytes, 0, bytes.length, session.written);
-    session.written += bytes.length;
+    let offset = 0;
+    while (offset < bytes.length) {
+      const { bytesWritten } = await session.spool.write(bytes, offset, bytes.length - offset, session.written);
+      if (bytesWritten < 1) throw new Error("process output spool made no write progress");
+      offset += bytesWritten; session.written += bytesWritten;
+    }
+  }).catch(error => {
+    session.captureError = `process output capture failed: ${String(error)}`;
+    stopSession(session, "cancelled");
   });
 }
 
 export async function startSession(input: {
-  command: string; cwd: string; tty: boolean; timeoutMs: number; spoolDir: string;
+  command: string; cwd: string; tty: boolean; timeoutMs: number; spoolDir: string; source: ProcessSource; owner?: string;
+  artifactObserver?: CommandArtifactObserver;
+  /** Internal literal launch capability; model exec_command remains a Bash contract. */
+  argv?: readonly string[];
 }): Promise<Session | { error: string }> {
   if (sessions.size >= MAX_SESSIONS) {
-    const list = runningSessions().map((s) => `${s.id}: ${s.command}`).join("; ");
-    return { error: `refused: ${MAX_SESSIONS} sessions are already running (${list}); stop one with write_stdin chars="\\u0003" or kill it with bash` };
+    const list = runningSessions(input.owner).map((s) => s.id).join(", ");
+    return { error: `refused: managed process capacity ${MAX_SESSIONS} reached; your handles: ${list || "none"}; finish or cancel an owned process before starting another` };
   }
   if (!hooked) { hooked = true; process.once("exit", killAllExecSessions); }
   await mkdir(input.spoolDir, { recursive: true });
@@ -112,27 +160,35 @@ export async function startSession(input: {
   let resolveExit!: () => void;
   const exited = new Promise<void>((resolve) => { resolveExit = resolve; });
   const session = {
-    id: nextId++, command: input.command, cwd: input.cwd, tty: input.tty, started: performance.now(),
-    spool, spoolPath, queue: Promise.resolve(), written: 0, read: 0, lastData: performance.now(),
-    exit: null, timeoutMs: input.timeoutMs, exited,
+    id: nextId++, ...(input.owner === undefined ? {} : { owner: input.owner }), command: input.command, cwd: input.cwd, tty: input.tty, source: input.source, started: performance.now(),
+    spool, spoolPath, queue: Promise.resolve(), operations: Promise.resolve(), written: 0, read: 0,
+    exit: null, timeoutMs: input.timeoutMs, exited, drained: Promise.resolve(),
+    ...(input.artifactObserver ? { artifactObserver: input.artifactObserver } : {}),
   } as Omit<Session, "pid" | "write" | "kill" | "timer"> as Session;
 
-  if (input.tty) {
+  try { if (input.tty) {
     // A PTY: the line discipline turns ^C into SIGINT for the foreground job,
     // which is what an interactive program expects. Bun ships the PTY.
-    const proc = Bun.spawn(["bash", "-lc", input.command], {
+    let drained!: () => void;
+    session.drained = new Promise<void>(resolve => { drained = resolve; });
+    const proc = Bun.spawn(input.argv ? [...input.argv] : commandArgv(input.command), {
       cwd: input.cwd, env,
-      terminal: { cols: 120, rows: 40, data: (_terminal, data) => append(session, data) },
+      terminal: { cols: 120, rows: 40, data: (_terminal, data) => append(session, data),
+        // This callback closes the stream; only proc.exited supplies the command exit.
+        exit: (_terminal, code) => { if (code !== 0) session.captureError = "PTY output stream closed with a read error"; drained(); } },
     });
     session.pid = proc.pid;
+    session.alive = () => proc.exitCode === null;
     session.write = (chars) => { proc.terminal?.write(chars); };
     session.kill = (signal) => killGroup(proc.pid, signal);
-    void proc.exited.then((code) => { session.exit = code; resolveExit(); });
+    session.closeCapture = async () => { proc.terminal?.close(); drained(); };
+    void proc.exited.then((code) => { session.exit = code; resolveExit(); void drainExitedSession(session); });
   } else {
-    const proc = Bun.spawn(["bash", "-lc", input.command], {
+    const proc = Bun.spawn(input.argv ? [...input.argv] : commandArgv(input.command), {
       cwd: input.cwd, env, stdin: "pipe", stdout: "pipe", stderr: "pipe", detached: true,
     });
     session.pid = proc.pid;
+    session.alive = () => proc.exitCode === null;
     // Without a terminal there is no line discipline, so the two control
     // characters a model reaches for are mapped by hand: ^C interrupts the
     // group, ^D closes stdin.
@@ -144,44 +200,85 @@ export async function startSession(input: {
       }
     };
     session.kill = (signal) => killGroup(proc.pid, signal);
+    const readers: ReadableStreamDefaultReader<Uint8Array>[] = [];
     const pump = async (stream: ReadableStream<Uint8Array>) => {
       const reader = stream.getReader();
-      try { for (;;) { const { done, value } = await reader.read(); if (done) return; append(session, value); } }
-      catch { /* the stream closed under us; the exit code is what matters */ }
+      readers.push(reader);
+      try { for (;;) { const { done, value } = await reader.read(); if (done) return; append(session, value); await session.queue; } }
+      catch (error) { session.captureError = `process output stream failed: ${String(error)}`; }
       finally { reader.releaseLock(); }
     };
-    void pump(proc.stdout);
-    void pump(proc.stderr);
-    void proc.exited.then((code) => { session.exit = code; resolveExit(); });
+    session.closeCapture = async () => { await Promise.allSettled(readers.map(reader => reader.cancel())); };
+    session.drained = Promise.all([pump(proc.stdout), pump(proc.stderr)]).then(() => {});
+    void proc.exited.then((code) => { session.exit = code; resolveExit(); void drainExitedSession(session); });
+  } } catch (error) {
+    await spool.close(); await rm(spoolPath, { force: true });
+    const os = (error as { code?: string }).code;
+    throw new ToolFault(os === "ENOENT" || os === "ENOTDIR" ? "environment_missing" : os === "EACCES" || os === "EPERM" ? "permission_denied" : "execution_failed", String(error), NOT_STARTED);
   }
-  session.timer = setTimeout(() => {
-    session.stopped = "timeout";
-    session.kill("SIGTERM");
-    setTimeout(() => session.kill("SIGKILL"), TERMINATION_GRACE_MS);
-  }, input.timeoutMs);
+  session.timer = setTimeout(() => stopSession(session, "timeout"), input.timeoutMs);
   sessions.set(session.id, session);
   return session;
 }
 
-export function findSession(id: number): Session | undefined {
-  return sessions.get(id);
+export function findSession(id: number, owner?: string): Session | undefined {
+  const session = sessions.get(id);
+  return session?.owner === owner ? session : undefined;
+}
+
+function stopSession(session: Session, reason: "timeout" | "cancelled"): void {
+  if (session.stopped !== undefined || session.exit !== null) return;
+  session.stopped = reason;
+  clearTimeout(session.timer);
+  session.kill("SIGTERM");
+  session.escalation = setTimeout(() => session.kill("SIGKILL"), COMMAND_TERMINATION_GRACE_MS);
+}
+
+/** A managed group is owned for its foreground command lifetime, never silently detached. */
+function drainExitedSession(session: Session): Promise<void> {
+  // Once only: a later artifact retry must not signal a potentially reused PID/group.
+  session.finishing ??= (async () => {
+    try { await finishCapture(session); } catch (error) { session.captureError = `output drain failed: ${String(error)}`; }
+    // The exit owns this observation even if no model polls until files change again.
+    if (session.artifactObserver && session.exit !== null) {
+      session.artifacts = session.artifactObserver.finish({ exit: session.exit,
+        ...(session.stopped ? { stopped: session.stopped } : {}), capture: session.captureError ? "partial" : "complete" });
+      await session.artifacts;
+    }
+  })();
+  return session.finishing;
+}
+async function finishCapture(session: Session): Promise<void> {
+  session.kill("SIGKILL");
+  clearTimeout(session.escalation);
+  clearTimeout(session.timer);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<false>(resolve => { timer = setTimeout(() => resolve(false), EXIT_DRAIN_MS); });
+  const complete = await Promise.race([session.drained.then(() => true), deadline]);
+  clearTimeout(timer);
+  if (!complete) {
+    session.captureError = "output drain deadline reached; a descendant may have escaped the owned group";
+    await session.closeCapture();
+  }
+  await session.queue;
 }
 
 /** Wait for exit, the yield deadline or cancellation, whichever is first. */
-export async function waitSession(session: Session, yieldMs: number, signal?: AbortSignal): Promise<void> {
-  const deadline = new Promise<void>((resolve) => setTimeout(resolve, yieldMs));
+async function waitSession(session: Session, yieldMs: number, signal?: AbortSignal): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const deadline = new Promise<void>((resolve) => { timer = setTimeout(resolve, yieldMs); });
   const aborted = new Promise<void>((resolve) => {
     if (signal === undefined) return;
+    onAbort = resolve;
     if (signal.aborted) resolve();
-    signal.addEventListener("abort", () => resolve(), { once: true });
+    else signal.addEventListener("abort", onAbort, { once: true });
   });
-  await Promise.race([session.exited, deadline, aborted]);
-  if (session.exit !== null) {
-    // Output written just before exit can still be in flight; wait until it goes quiet.
-    const until = performance.now() + 1_000;
-    while (performance.now() - session.lastData < EXIT_IDLE_MS && performance.now() < until) await Bun.sleep(EXIT_IDLE_MS / 2);
-    await Bun.sleep(20);
-  }
+  try { await Promise.race([session.exited, deadline, aborted]); }
+  finally { clearTimeout(timer); if (onAbort) signal?.removeEventListener("abort", onAbort); }
+  if (signal?.aborted) stopSession(session, "cancelled");
+  if (session.stopped !== undefined) await session.exited;
+  if (session.exit !== null) await drainExitedSession(session);
   await session.queue;
 }
 
@@ -189,26 +286,74 @@ export async function waitSession(session: Session, yieldMs: number, signal?: Ab
  * Bytes printed since the previous call, archived in full. A session whose
  * exit has now been reported is closed.
  */
-export async function takeOutput(session: Session, outputStore: string, previewBytes: number): Promise<{
-  stored: ArchivedObservation; exit: number | null; stopped?: "timeout"; wallMs: number;
-}> {
+async function takeOutput(session: Session, outputStore: string, previewBytes: number): Promise<TakenOutput> {
+  if (session.exit !== null) await drainExitedSession(session);
   await session.queue;
+  if (session.exit !== null) await drainExitedSession(session);
   const from = session.read, to = session.written;
-  session.read = to;
+  // Snapshot exit before async archival: a later exit belongs to the next observation.
+  const exit = session.exit;
   const path = session.spoolPath;
-  async function* range(): AsyncGenerator<Uint8Array> {
-    if (to <= from) return;
-    for await (const chunk of createReadStream(path, { start: from, end: to - 1 })) yield chunk as Uint8Array;
+  async function* range(start: number): AsyncGenerator<Uint8Array> {
+    if (to <= start) return;
+    for await (const chunk of createReadStream(path, { start, end: to - 1 })) yield chunk as Uint8Array;
   }
-  const stored = await archiveObservation(outputStore, range(), previewBytes);
-  const exit = session.exit;
+  const stored = await archiveObservation(outputStore, range(from), previewBytes);
+  const full = exit === null ? undefined : from === 0 ? stored : await archiveObservation(outputStore, range(0), previewBytes);
+  const artifacts = exit === null ? session.artifactObserver?.pending : await session.artifacts;
+  // Neither the cursor nor the handle advances until every referenced artifact exists.
+  session.read = to;
+  const taken: TakenOutput = { stored, exit, ...(session.stopped ? { stopped: session.stopped } : {}), wallMs: performance.now() - session.started,
+    receipt: processReceipt({ session: session.id, source: session.source, exit, output: stored.ref, start: from, end: to,
+      ...(session.stopped ? { stopped: session.stopped } : {}), ...(full ? { fullOutput: full.ref } : {}),
+      ...(artifacts ? { artifacts } : {}),
+      ...(session.captureError ? { capture: "partial" } : exit !== null ? { capture: "complete" } : {}) }) };
   if (exit !== null) {
     clearTimeout(session.timer);
+    clearTimeout(session.escalation);
     sessions.delete(session.id);
-    // A background child the command started deliberately (`nohup server &`)
-    // is left running, as bash leaves it: only a timeout kills the group.
+    session.final = taken;
+    closedSessions.set(session.id, { ...(session.owner === undefined ? {} : { owner: session.owner }), id: session.id,
+      endedAt: performance.now(), receipt: taken.receipt });
+    pruneClosed(performance.now());
+    await session.closeCapture();
     await session.spool.close().catch(() => {});
     await rm(path, { force: true });
   }
-  return { stored, exit, ...(session.stopped ? { stopped: session.stopped } : {}), wallMs: performance.now() - session.started };
+  return taken;
+}
+
+/** One lease covers stdin, waiting, archival and cursor commit; cancellation can interrupt a queued wait. */
+export async function pollSession(session: Session, outputStore: string, previewBytes: number, yieldMs: number,
+  chars = "", signal?: AbortSignal): Promise<TakenOutput> {
+  const cancel = () => stopSession(session, "cancelled");
+  if (signal?.aborted) cancel(); else signal?.addEventListener("abort", cancel, { once: true });
+  const result = session.operations.then(async () => {
+    if (session.final) {
+      if (chars.length > 0) throw new ToolFault("not_found", "process is closed; input was not sent", NOT_STARTED);
+      return { ...session.final, receipt: { ...session.final.receipt, replayed: true } };
+    }
+    if (chars.length > 0) {
+      if (session.exit !== null) throw new ToolFault("not_found", "process has exited; input was not sent; poll with empty chars", NOT_STARTED);
+      session.write(chars);
+    }
+    await waitSession(session, yieldMs, signal);
+    return takeOutput(session, outputStore, previewBytes);
+  });
+  session.operations = result.catch(() => {});
+  try { return await result; }
+  finally { signal?.removeEventListener("abort", cancel); }
+}
+
+/** Stop only this owner, drain its actual exit and preserve every unread byte (D8). */
+export async function disposeExecSessions(owner: string, outputStore: string, previewBytes: number) {
+  const owned = [...sessions.values()].filter(session => session.owner === owner);
+  const results = await Promise.all(owned.map(async session => {
+    stopSession(session, "cancelled");
+    const output = await pollSession(session, outputStore, previewBytes, 0);
+    if (output.exit === null) throw new Error("disposed process has no exit observation");
+    if (output.receipt.replayed) return null;
+    return { session: session.id, command: session.command, exit: output.exit, output: output.stored.ref, receipt: output.receipt };
+  }));
+  return results.filter(item => item !== null);
 }

package/src/runtime/execution-control.ts

@@ -25,6 +25,7 @@ export class ExecutionControl {
   cancel(): void { this.active?.controller.abort(); }
   whenIdle(): Promise<void> { return this.active?.done ?? Promise.resolve(); }
   get running(): boolean { return this.active !== null; }
+  get signal(): AbortSignal | undefined { return this.active?.controller.signal; }
 }
 
 /** Only for admission waits: an unstarted action has no effect to drain. */

package/src/runtime/extension-ui.ts

@@ -1,52 +1,44 @@
-/** Structural Pi UI contract; the runtime never constructs or owns a terminal (D19). */
-import type { TUI, OverlayHandle, OverlayOptions } from "../vendor/pi-tui/tui.ts";
-import type { EditorComponent } from "../vendor/pi-tui/editor-component.ts";
-import type { EditorTheme } from "../vendor/pi-tui/components/editor.ts";
-import type { AutocompleteProvider } from "../vendor/pi-tui/autocomplete.ts";
-import type { KeybindingsManager } from "../vendor/pi-tui/keybindings.ts";
+/**
+ * What an extension may do to the interactive UI (D20). The runtime never
+ * constructs a terminal; the app supplies an implementation.
+ *
+ * Deliberately small. Extensions describe content (`render(width): string[]`
+ * ANSI lines) and ask for decisions (select / confirm / input); they do not
+ * own focus, overlays or the composer. That keeps a misbehaving extension
+ * from wedging input, and keeps the UI framework replaceable without
+ * breaking extensions again.
+ */
 import type { Theme } from "../core/theme.ts";
 
-export interface ExtensionComponent { render(width: number): string[]; invalidate?(): void; handleInput?(data: string): void; dispose?(): void; focused?: boolean }
+/** A block of ANSI lines that may depend on width. */
+export interface ExtensionComponent { render(width: number): string[]; dispose?(): void }
+
 export interface ExtensionTheme extends Theme {
   fg(color: string, text: string): string; bg(color: string, text: string): string;
   bold(text: string): string; italic(text: string): string; underline(text: string): string; dim(text: string): string; inverse(text: string): string; strikethrough(text: string): string;
-  getFgAnsi(color: string): string; getBgAnsi(color: string): string;
-  getColorMode(): "truecolor"; getThinkingBorderColor(level: string): (text: string) => string; getBashModeBorderColor(): (text: string) => string;
 }
-export type WidgetFactory = (tui: TUI, theme: ExtensionTheme) => ExtensionComponent;
-export type EditorFactory = (tui: TUI, theme: EditorTheme, bindings: KeybindingsManager) => EditorComponent & { dispose?(): void; focused?: boolean };
-export type AutocompleteFactory = (base: AutocompleteProvider) => AutocompleteProvider;
-export interface FooterData { getGitBranch(): string | undefined; getExtensionStatuses(): ReadonlyMap<string, string>; onBranchChange(callback: () => void): () => void }
-export type FooterFactory = (tui: TUI, theme: ExtensionTheme, data: FooterData) => ExtensionComponent;
+
 export interface DialogOptions { signal?: AbortSignal; timeout?: number }
-export interface CustomOptions extends DialogOptions { overlay?: boolean; overlayOptions?: OverlayOptions | (() => OverlayOptions); onHandle?: (handle: OverlayHandle) => void }
-export type InputHandler = (data: string) => { consume?: boolean; data?: string } | undefined;
+
 export interface ExtensionUI {
   select(title: string, options: string[], opts?: DialogOptions): Promise<string | undefined>;
   confirm(title: string, message: string, opts?: DialogOptions): Promise<boolean>;
   input(title: string, placeholder?: string, opts?: DialogOptions): Promise<string | undefined>;
-  editor(title: string, prefill?: string): Promise<string | undefined>;
-  custom<T>(factory: (tui: TUI, theme: ExtensionTheme, bindings: KeybindingsManager, done: (result: T) => void) => ExtensionComponent | Promise<ExtensionComponent>, options?: CustomOptions): Promise<T>;
+  /** Read-only block in a dialog; resolves when the user closes it. */
+  show(title: string, component: ExtensionComponent): Promise<void>;
   notify(message: string, type?: "info" | "warning" | "error"): void;
-  onTerminalInput(handler: InputHandler): () => void;
   setStatus(key: string, text: string | undefined): void;
-  setWorkingMessage(message?: string): void; setWorkingVisible(visible: boolean): void;
-  setWorkingIndicator(options?: { frames?: string[]; intervalMs?: number }): void;
+  /** Lines shown above the composer, keyed so an extension can replace or clear its own. */
+  setWidget(key: string, lines: string[] | undefined): void;
+  setWorkingMessage(message?: string): void;
   setHiddenThinkingLabel(label?: string): void;
-  setWidget(key: string, content: string[] | WidgetFactory | undefined, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
-  setFooter(factory: FooterFactory | undefined): void; setHeader(factory: WidgetFactory | undefined): void;
   setTitle(title: string): void;
-  pasteToEditor(text: string): void; setEditorText(text: string): void; getEditorText(): string;
-  addAutocompleteProvider(factory: AutocompleteFactory): void;
-  setEditorComponent(factory: EditorFactory | undefined): void; getEditorComponent(): EditorFactory | undefined;
+  getEditorText(): string; setEditorText(text: string): void; pasteToEditor(text: string): void;
   readonly theme: ExtensionTheme;
-  getAllThemes(): { name: string; path: string | undefined }[];
-  getTheme(name: string): ExtensionTheme | undefined;
-  setTheme(theme: string | ExtensionTheme): { success: boolean; error?: string };
   getToolsExpanded(): boolean; setToolsExpanded(expanded: boolean): void;
 }
 
-/** Headless extensions can notify and inspect capability; interactive requests fail explicitly. */
+/** Headless extensions can notify; interactive requests fail explicitly. */
 export function headlessUI(notify: ExtensionUI["notify"]): ExtensionUI {
   return new Proxy({ notify }, { get(target, key) {
     if (key === "notify") return target.notify;