@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/workflows/src/extension/runtime.ts

@@ -13,17 +13,15 @@
 import { createRegistry } from "../workflows/registry.js";
 import type { WorkflowRegistry } from "../workflows/registry.js";
 import {
-  INTERACTIVE_WORKFLOW_POLICY,
   type WorkflowDefinition,
   type WorkflowPersistencePort,
   type WorkflowMcpPort,
   type WorkflowRuntimeConfig,
-  type WorkflowDetails,
   type WorkflowModelCatalogPort,
   type WorkflowExecutionPolicy,
 } from "../shared/types.js";
 import type { StageAdapters } from "../runs/foreground/stage-runner.js";
-import { resolveAndValidateInputs, runChain, runParallel, runTask, type RunOpts } from "../runs/foreground/executor.js";
+import { resolveAndValidateInputs, type RunOpts } from "../runs/foreground/executor.js";
 import type { Store } from "../shared/store.js";
 import type { RunSnapshot } from "../shared/store-types.js";
 import type { CancellationRegistry } from "../runs/background/cancellation-registry.js";
@@ -31,24 +29,14 @@ import { store as defaultStore } from "../shared/store.js";
 import { dispatch } from "./dispatcher.js";
 import type { WorkflowToolArgs } from "./index.js";
 import type { WorkflowToolResult } from "./render-result.js";
-import {
-  emitWorkflowControlIntercom,
-  emitWorkflowResultIntercom,
-  workflowIntercomAvailable,
-  type WorkflowIntercomDelivery,
-  type WorkflowResultIntercomPort,
-} from "../intercom/result-intercom.js";
-import { validateWorkflowModels } from "../runs/shared/model-fallback.js";
-import { runDetached } from "../runs/background/runner.js";
+import { launchDetachedUntilStartup, workflowStartupFailureMessage } from "../runs/background/startup-admission.js";
 import type { JobTracker } from "../runs/background/job-tracker.js";
-import { appendRunEnd } from "../shared/persistence-session-entries.js";
-import { classifyWorkflowFailure } from "../shared/workflow-failures.js";
-import { initializeDbosDurableBackendFromEnv } from "../durable/factory.js";
-import { directMode, directModelRequests, directOptions, directProgressTotal } from "./runtime-direct.js";
+import { getDurableBackend, initializeDurableBackend } from "../durable/factory.js";
 import {
   createDurableResumeRuntime,
   type DurableResumeRuntime,
 } from "./runtime-durable-resume.js";
+import { claimActiveBlockedResume, discardFailedActiveBlockedContinuation, finalizeResumedActiveBlockedSourceRun, releaseActiveBlockedClaim } from "./runtime-active-block-claim.js";
 
 // ---------------------------------------------------------------------------
 // Options
@@ -76,8 +64,6 @@ export interface ExtensionRuntimeOpts {
   persistence?: WorkflowPersistencePort;
   /** MCP scope-gating port forwarded to the executor. */
   mcp?: WorkflowMcpPort;
-  /** Workflow-native pi-intercom result/control event delivery. */
-  intercom?: WorkflowResultIntercomPort;
   /**
    * Resolved runtime configuration. Injected by the composition root after
    * merging file config with defaults. Forwarded to dispatch → run/runDetached.
@@ -108,15 +94,13 @@ export interface ExtensionRuntime extends DurableResumeRuntime {
 
   /**
    * Dispatch a `list`, `inputs`, or `run` action.
-   * For `status`, `kill`, and `resume` use the runs/background/status module directly.
+   * Status and run-control actions use the dedicated control modules directly.
    */
   dispatch(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowToolResult>;
 
-  /** Execute direct single/parallel/chain workflow tool modes. */
-  runDirect(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowDetails>;
 
   /** Start a linked continuation for a failed resumable named workflow run. */
-  resumeFailedRun(sourceRunId: string, stageId?: string, options?: RuntimeDispatchOptions): ResumeFailedRunResult;
+  resumeFailedRun(sourceRunId: string, stageId?: string, options?: RuntimeDispatchOptions): Promise<ResumeFailedRunResult>;
 
 }
 export interface RuntimeDispatchOptions {
@@ -147,30 +131,17 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
   const persistence = opts.persistence;
   const mcp = opts.mcp;
   const config = opts.config;
-  const intercom = opts.intercom;
   const models = opts.models;
   const jobs = opts.jobs;
   const runtimeCwd = opts.cwd ?? process.cwd();
   const resolveDefaultStageSessionDir = opts.resolveDefaultStageSessionDir;
-  const dbosReady = initializeDbosDurableBackendFromEnv().catch((err) => process.emitWarning(`Atomic workflow DBOS durability unavailable; using file-backed durability: ${err instanceof Error ? err.message : String(err)}`));
-  const ensureDbosReady = async (): Promise<void> => { await dbosReady; };
+  let dbosReady: Promise<void> | undefined;
+  const ensureDbosReady = async (): Promise<void> => {
+    dbosReady ??= initializeDurableBackend().then(() => undefined);
+    await dbosReady;
+  };
 
-  function runOptions(args: WorkflowToolArgs, policy?: WorkflowExecutionPolicy): RunOpts {
-    const argConcurrency =
-      typeof args.concurrency === "number" && Number.isFinite(args.concurrency)
-        ? Math.max(1, Math.floor(args.concurrency))
-        : undefined;
-    const effectiveConfig =
-      argConcurrency === undefined
-        ? config
-        : {
-            maxDepth: config?.maxDepth ?? 4,
-            defaultConcurrency: argConcurrency,
-            persistRuns: config?.persistRuns ?? true,
-            statusFile: config?.statusFile ?? false,
-            ...(config?.statusFilePath !== undefined ? { statusFilePath: config.statusFilePath } : {}),
-            resumeInFlight: config?.resumeInFlight ?? "ask",
-          };
+  function runOptions(policy?: WorkflowExecutionPolicy): RunOpts {
     const defaultSessionDir = resolveDefaultStageSessionDir?.();
     return {
       adapters,
@@ -178,7 +149,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       cancellation,
       persistence,
       mcp,
-      config: effectiveConfig,
+      config,
       models,
       ...(defaultSessionDir !== undefined ? { defaultSessionDir } : {}),
       ...(policy !== undefined ? { executionMode: policy.mode } : {}),
@@ -186,83 +157,6 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       cwd: runtimeCwd,
     };
   }
-  function explicitIntercomDelivery(args: WorkflowToolArgs): WorkflowIntercomDelivery | undefined {
-    if (args.intercom?.enabled === false) return "off";
-    if (args.intercom?.delivery !== undefined) return args.intercom.delivery;
-    if (args.intercom?.enabled === true) return "control-and-result";
-    return undefined;
-  }
-  function effectiveIntercomDelivery(args: WorkflowToolArgs, mode: WorkflowDetails["mode"]): WorkflowIntercomDelivery {
-    const explicit = explicitIntercomDelivery(args);
-    if (explicit !== undefined) return explicit;
-    if (
-      args.async === true &&
-      workflowIntercomAvailable(intercom) &&
-      (mode === "parallel" || mode === "chain")
-    ) {
-      return "control-and-result";
-    }
-    return "off";
-  }
-  function intercomParentSession(args: WorkflowToolArgs): string | undefined {
-    if (args.intercom?.parentSession !== undefined) return args.intercom.parentSession;
-    if (typeof intercom?.parentSession === "function") return intercom.parentSession();
-    return intercom?.parentSession;
-  }
-
-  function withIntercomSummary(
-    details: WorkflowDetails,
-    delivery: WorkflowIntercomDelivery,
-    parentSession?: string,
-  ): WorkflowDetails {
-    if (delivery === "off") return details;
-    return {
-      ...details,
-      intercom: {
-        enabled: workflowIntercomAvailable(intercom),
-        delivery,
-        ...(parentSession !== undefined ? { parentSession } : {}),
-      },
-    };
-  }
-
-  function emitDirectIntercom(details: WorkflowDetails, delivery: WorkflowIntercomDelivery, parentSession?: string): void {
-    if (delivery === "off") return;
-    const summarized = withIntercomSummary(details, delivery, parentSession);
-    emitWorkflowControlIntercom(
-      intercom,
-      summarized,
-      `workflow ${summarized.status}: ${summarized.runId ?? "unknown run"}`,
-      { delivery: delivery === "result" ? "result" : delivery, parentSession },
-    );
-    emitWorkflowResultIntercom(intercom, summarized, {
-      delivery: delivery === "notify" ? "notify" : delivery,
-      parentSession,
-    });
-  }
-
-  function runDirectForeground(
-    args: WorkflowToolArgs,
-    runId?: string,
-    policy?: WorkflowExecutionPolicy,
-  ): Promise<WorkflowDetails> {
-    const directRunOptions = directOptions(args);
-    const baseRunOptions = runOptions(args, policy);
-    const effectiveRunOptions = runId === undefined
-      ? baseRunOptions
-      : { ...baseRunOptions, runId };
-
-    if (Array.isArray(args.chain)) {
-      return runChain(args.chain, directRunOptions, effectiveRunOptions);
-    }
-    if (Array.isArray(args.tasks)) {
-      return runParallel(args.tasks, directRunOptions, effectiveRunOptions);
-    }
-    if (args.task !== undefined && typeof args.task === "object") {
-      return runTask(args.task, directRunOptions, effectiveRunOptions);
-    }
-    throw new Error("WorkflowRuntime.runDirect: no direct execution mode supplied");
-  }
 
   function matchesResumeStageIdentifier(stage: RunSnapshot["stages"][number], identifier: string): boolean {
     return stage.id === identifier || stage.name === identifier || stage.id.startsWith(identifier);
@@ -305,31 +199,7 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     return { ok: true, stageId: failedStageId };
   }
 
-  function finalizeResumedActiveBlockedSourceRun(source: RunSnapshot, continuationRunId: string): void {
-    const errorMessage = source.error ?? source.failureMessage ?? `workflow resumed in new run ${continuationRunId}`;
-    const metadata = {
-      ...(source.failureKind !== undefined ? { failureKind: source.failureKind } : {}),
-      ...(source.failureCode !== undefined ? { failureCode: source.failureCode } : {}),
-      failureRecoverability: "non_recoverable",
-      failureDisposition: "terminal_killed",
-      ...(source.failureMessage !== undefined ? { failureMessage: source.failureMessage } : {}),
-      ...(source.failedStageId !== undefined ? { failedStageId: source.failedStageId } : {}),
-      resumable: false,
-      ...(source.retryAfterMs !== undefined ? { retryAfterMs: source.retryAfterMs } : {}),
-    } as const;
-    const recorded = activeStore.recordRunEnd(source.id, "killed", undefined, errorMessage, metadata);
-    if (recorded && persistence !== undefined) {
-      appendRunEnd(persistence, {
-        runId: source.id,
-        status: "killed",
-        error: errorMessage,
-        ...metadata,
-        ts: Date.now(),
-      });
-    }
-  }
-
-  function resumeFailedRun(sourceRunId: string, stageId?: string, options?: RuntimeDispatchOptions): ResumeFailedRunResult {
+  async function resumeFailedRun(sourceRunId: string, stageId?: string, options?: RuntimeDispatchOptions): Promise<ResumeFailedRunResult> {
     const source = activeStore.runs().find((run) => run.id === sourceRunId);
     if (source === undefined) {
       return { ok: false, reason: "run_not_found", message: `run not found: ${sourceRunId}` };
@@ -353,73 +223,68 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
     } catch (err) {
       return { ok: false, reason: "insufficient_state", message: `insufficient_state: ${err instanceof Error ? err.message : String(err)}` };
     }
-    const accepted = runDetached(def, sourceInputs, {
-      ...runOptions({ workflow: def.name, inputs: sourceInputs }, options?.policy),
+    const stageMessage = (verb: string, runId: string): string =>
+      `${verb} workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (run ${runId.slice(0, 8)}).`;
+    const launchContinuation = () => launchDetachedUntilStartup(def, sourceInputs, {
+      ...runOptions(options?.policy),
       continuation: { source, resumeFromStageId: resolvedStage.stageId },
+      ...(jobs !== undefined ? { jobs } : {}),
     });
     if (isActiveBlockedResumable) {
-      finalizeResumedActiveBlockedSourceRun(source, accepted.runId);
+      // Keep the durable blocked source recoverable until fresh-ID startup admission succeeds.
+      if (!claimActiveBlockedResume(getDurableBackend(), source.id)) {
+        return { ok: false, reason: "not_resumable", message: `run ${source.id} is already being resumed in this session` };
+      }
+      let launch: ReturnType<typeof launchContinuation>;
+      try {
+        launch = launchContinuation();
+      } catch (error) {
+        releaseActiveBlockedClaim(source.id);
+        return { ok: false, reason: "insufficient_state", message: `failed to resume run ${source.id}: ${error instanceof Error ? error.message : String(error)}` };
+      }
+      const { accepted } = launch;
+      const admission = await launch.wait;
+      if (!admission.started) {
+        const startupError = workflowStartupFailureMessage(admission, activeStore.runs().find((run) => run.id === accepted.runId)?.error, `workflow run ${accepted.runId} ended before startup admission`);
+        try {
+          await discardFailedActiveBlockedContinuation(getDurableBackend(), accepted.runId, activeStore);
+        } catch (error) {
+          releaseActiveBlockedClaim(source.id);
+          return { ok: false, reason: "insufficient_state", message: `continuation for run ${source.id} failed to start (${startupError}) and cleanup failed: ${error instanceof Error ? error.message : String(error)}; source left resumable` };
+        }
+        releaseActiveBlockedClaim(source.id);
+        return { ok: false, reason: "insufficient_state", message: `continuation for run ${source.id} failed to start: ${startupError}; source left resumable` };
+      }
+      try {
+        finalizeResumedActiveBlockedSourceRun(source, accepted.runId, activeStore, persistence);
+      } catch (error) {
+        releaseActiveBlockedClaim(source.id);
+        return { ok: false, reason: "insufficient_state", message: `failed to finalize resumed source ${source.id}: ${error instanceof Error ? error.message : String(error)}` };
+      }
+      releaseActiveBlockedClaim(source.id);
+      return { ok: true, runId: accepted.runId, sourceRunId: source.id, resumeFromStageId: resolvedStage.stageId, message: stageMessage("Resuming blocked", accepted.runId) };
     }
-    return {
-      ok: true,
-      runId: accepted.runId,
-      sourceRunId: source.id,
-      resumeFromStageId: resolvedStage.stageId,
-      message: isActiveBlockedResumable
-        ? `Resuming blocked workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (new run ${accepted.runId}).`
-        : `Resuming failed workflow "${def.name}" from run ${source.id.slice(0, 8)} at stage ${resolvedStage.stageId.slice(0, 8)} (new run ${accepted.runId}).`,
-    };
-  }
-
-  async function runDirectAsync(args: WorkflowToolArgs, policy?: WorkflowExecutionPolicy): Promise<WorkflowDetails> {
-    await ensureDbosReady();
-    const runId = crypto.randomUUID();
-    const mode = directMode(args);
-    const delivery = effectiveIntercomDelivery(args, mode);
-    const parentSession = intercomParentSession(args);
-    let warnings: readonly string[] = [];
+    let launch: ReturnType<typeof launchContinuation>;
     try {
-      warnings = await validateWorkflowModels({
-        requests: directModelRequests(args),
-        catalog: models,
-      });
-    } catch (error: unknown) {
-      return withIntercomSummary({
-        mode,
-        action: "run",
-        runId,
-        status: "failed",
-        progress: { completed: 0, total: directProgressTotal(args) },
-        error: classifyWorkflowFailure(error).userMessage,
-      }, delivery, parentSession);
+      launch = launchContinuation();
+    } catch (error) {
+      return { ok: false, reason: "insufficient_state", message: `failed to resume run ${source.id}: ${error instanceof Error ? error.message : String(error)}` };
     }
-    const background = runDirectForeground(args, runId, policy);
-    void background.then(
-      (details) => {
-        emitDirectIntercom(details, delivery, parentSession);
-      },
-      (error: unknown) => {
-        const details: WorkflowDetails = withIntercomSummary({
-          mode,
-          action: "run",
-          runId,
-          status: "failed",
-          progress: { completed: 0, total: directProgressTotal(args) },
-          error: classifyWorkflowFailure(error).userMessage,
-        }, delivery, parentSession);
-        emitDirectIntercom(details, delivery, parentSession);
-      },
-    );
-    return withIntercomSummary({
-      mode,
-      action: "run",
-      runId,
-      status: "accepted",
-      progress: { completed: 0, total: directProgressTotal(args) },
-      ...(warnings.length > 0 ? { warnings: [...warnings] } : {}),
-    }, delivery, parentSession);
+    const { accepted } = launch;
+    const admission = await launch.wait;
+    if (!admission.started) {
+      const startupError = workflowStartupFailureMessage(admission, activeStore.runs().find((run) => run.id === accepted.runId)?.error, `workflow run ${accepted.runId} ended before startup admission`);
+      try {
+        await discardFailedActiveBlockedContinuation(getDurableBackend(), accepted.runId, activeStore);
+      } catch (error) {
+        return { ok: false, reason: "insufficient_state", message: `continuation for run ${source.id} failed to start (${startupError}) and cleanup failed: ${error instanceof Error ? error.message : String(error)}` };
+      }
+      return { ok: false, reason: "insufficient_state", message: `continuation for run ${source.id} failed to start: ${startupError}` };
+    }
+    return { ok: true, runId: accepted.runId, sourceRunId: source.id, resumeFromStageId: resolvedStage.stageId, message: stageMessage("Resuming failed", accepted.runId) };
   }
 
+
   return {
     get registry(): WorkflowRegistry {
       return registry;
@@ -444,21 +309,6 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       });
     },
 
-    async runDirect(args: WorkflowToolArgs, options?: RuntimeDispatchOptions): Promise<WorkflowDetails> {
-      await ensureDbosReady();
-      const policy = options?.policy ?? INTERACTIVE_WORKFLOW_POLICY;
-      if (args.async === true && policy.awaitTerminalRun !== true) {
-        return runDirectAsync(args, policy);
-      }
-      const mode = directMode(args);
-      const delivery = effectiveIntercomDelivery(args, mode);
-      const parentSession = intercomParentSession(args);
-      return runDirectForeground(args, undefined, policy).then((details) => {
-        const summarized = withIntercomSummary(details, delivery, parentSession);
-        emitDirectIntercom(summarized, delivery, parentSession);
-        return summarized;
-      });
-    },
 
     resumeFailedRun,
     ...createDurableResumeRuntime({
@@ -468,7 +318,8 @@ export function createExtensionRuntime(opts: ExtensionRuntimeOpts = {}): Extensi
       runtimeCwd,
       ensureReady: ensureDbosReady,
       resolveDefaultStageSessionDir,
-      baseRunOpts: (policy) => runOptions({ workflow: "", inputs: {} }, policy),
+      baseRunOpts: (policy) => runOptions(policy),
+      ...(jobs !== undefined ? { jobs } : {}),
     }),
 
   };

package/dist/builtin/workflows/src/extension/ui-surface.ts

@@ -130,6 +130,22 @@ export interface PiCustomOverlayOptions {
   onHandle?: (handle: PiOverlayHandle) => void;
 }
 
+/**
+ * Optional remote-control capability exposed on `PiCustomOverlayFactoryTui.terminal`.
+ *
+ * In isolated interactive mode the workflow extension runs inside the engine
+ * child, whose stdout is the JSONL transport rather than a TTY — writing raw
+ * mouse/autowrap escape sequences to `process.stdout` there is a no-op. The
+ * host instead exposes these typed setters on the factory TUI's terminal so the
+ * overlay can drive host-TTY modes over the allowlisted engine protocol. Absent
+ * on non-isolated hosts and test seams, where the overlay falls back to writing
+ * escape sequences to its local `process.stdout`.
+ */
+export interface PiRemoteTerminalControl {
+  setMouseScrollTracking(enabled: boolean): void;
+  setAutowrap(enabled: boolean): void;
+}
+
 /**
  * Surface of the Pi `TUI` instance exposed to overlay factories. The
  * `terminal` accessor is optional because some host implementations and
@@ -137,7 +153,12 @@ export interface PiCustomOverlayOptions {
  */
 export interface PiCustomOverlayFactoryTui {
   requestRender?: () => void;
-  terminal?: { rows?: number; columns?: number };
+  terminal?: {
+    rows?: number;
+    columns?: number;
+    setMouseScrollTracking?: (enabled: boolean) => void;
+    setAutowrap?: (enabled: boolean) => void;
+  };
   setFocus?: (target: unknown) => void;
   start?: () => void;
   stop?: () => void;
@@ -159,6 +180,86 @@ export type PiCustomOverlayFunction = (
   options: PiCustomOverlayOptions,
 ) => Promise<unknown> | unknown;
 
+export interface PiHostInputFormField {
+  name: string;
+  type: "string" | "text" | "number" | "integer" | "boolean" | "select";
+  description?: string;
+  required?: boolean;
+  choices?: string[];
+  placeholder?: string;
+  initialValue: string;
+}
+
+export interface PiHostInputFormRequest {
+  title: string;
+  fields: PiHostInputFormField[];
+}
+
+export type PiHostInputFormFunction = (
+  request: PiHostInputFormRequest,
+) => Promise<Record<string, string> | undefined>;
+
+/**
+ * JSON-safe session-selector row for the host-native session picker
+ * capability. Structural mirror of @bastani/atomic `HostSessionPickerRow` —
+ * `SessionInfo` with `created`/`modified` flattened to epoch millis.
+ */
+export interface PiHostSessionPickerRow {
+  path: string;
+  id: string;
+  cwd: string;
+  /** Creation time in epoch milliseconds. */
+  createdAt: number;
+  /** Last-modified time in epoch milliseconds. */
+  modifiedAt: number;
+  messageCount: number;
+  firstMessage: string;
+  allMessagesText?: string;
+  name?: string;
+  /** Optional semantic color for synthetic selector rows. */
+  messageColor?: "success" | "warning" | "accent" | "error";
+}
+
+/** Request accepted by the host-native session picker capability. */
+export interface PiHostSessionPickerRequest {
+  /** Rows shown in the first frame; push later rows via the handle's `update()`. */
+  sessions: PiHostSessionPickerRow[];
+  /** Show the rename keybinding hint in the picker header. Defaults to false. */
+  showRenameHint?: boolean;
+  /**
+   * Invoked after the user confirms a Ctrl+D delete on a row. The host never
+   * removes the row itself; reply with `update()` (row removed) or `error()`.
+   */
+  onDelete?: (path: string) => void | Promise<void>;
+}
+
+/** Live control surface for an open host-native session picker. */
+export interface PiHostSessionPickerHandle {
+  /** Resolves with the selected row's `path`, or `undefined` on cancel/close. */
+  result: Promise<string | undefined>;
+  /** Replace the picker rows; host-side navigation/search state is preserved. */
+  update(sessions: PiHostSessionPickerRow[]): void;
+  /** Surface a transient error message in the picker header. */
+  error(message: string): void;
+  /** Close the picker; `result` resolves `undefined`. Idempotent. */
+  close(): void;
+}
+
+/**
+ * Host-native session-list picker capability (`ctx.ui.hostSessionPicker`).
+ * Every interactive Atomic host implements it with one identical API: the
+ * terminal host mounts the real `SessionSelectorComponent` natively —
+ * directly (no IPC) in non-isolated mode, over the engine session-picker
+ * protocol channel in isolated mode — so picker navigation and search are
+ * zero-IPC and only open/update/select/delete/cancel cross a process
+ * boundary. Absent only on non-interactive surfaces (headless RPC, print)
+ * and mismatched hosts; callers fail with an actionable error there rather
+ * than degrade. The workflow resume picker REQUIRES this capability.
+ */
+export type PiHostSessionPickerFunction = (
+  request: PiHostSessionPickerRequest,
+) => PiHostSessionPickerHandle;
+
 /**
  * Structural shape of pi's custom editor component. Interactive mode
  * currently installs extension editors through `InteractiveMode.setEditorComponent`,
@@ -243,6 +344,10 @@ export interface PiUISurface {
   setTitle?: (title: string) => void;
   /** Show a custom component or overlay. */
   custom?: PiCustomOverlayFunction;
+  /** Host-native session-list picker (all interactive hosts; absent headless). */
+  hostSessionPicker?: PiHostSessionPickerFunction;
+  /** Host-native inline input form (all current interactive Atomic hosts). */
+  hostInputForm?: PiHostInputFormFunction;
   /** Get host-owned inline custom UI focus state, if exposed by the host. */
   getHostCustomUiState?: () => PiHostCustomUiState;
   /** Observe host-owned inline custom UI focus state changes, if exposed by the host. */
@@ -274,8 +379,7 @@ export interface PiUISurface {
 
 /**
  * Runtime surface that includes the optional UI dialog surface.
- * Used by command/overlay code (slash command kill confirm, graph overlay
- * mount, picker overlays) to interact with `pi.ui.custom`, `pi.ui.confirm`,
+ * Used by command/overlay code (graph mounts and picker overlays) to interact with `pi.ui.custom`, `pi.ui.confirm`,
  * etc. Workflow-level HIL routing — `ctx.ui.input/confirm/select/editor`
  * inside a workflow body — stays in the store-backed background adapter.
  * In-stage `ask_user_question` uses this surface to bind the live pi UI into