@bastani/atomic 0.8.31-alpha.5 → 0.9.0-alpha.1

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

@@ -21,16 +21,19 @@
  *            pi docs/sdk.md createAgentSession
  */
 
-import { basename } from "node:path";
 import type {
-  ChatMessageRenderOptions,
   CreateAgentSessionOptions,
   DefaultResourceLoaderInheritanceSnapshot,
-  PackageSource,
 } from "@bastani/atomic";
 import type { StageAdapters, StageSessionCreateResult, StageSessionRuntime } from "../runs/foreground/stage-runner.js";
 import type { StageExecutionMeta, StageOptions } from "../shared/types.js";
 import { stageUiBroker, type StageUiBroker } from "../shared/stage-ui-broker.js";
+import { prepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
+import type { PiCodingAgentSdk, PrepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
+export { prepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
+export type { AtomicCreateAgentSessionOptions, PiCodingAgentSdk, PiSdkResourceLoader, PiSdkSettingsManager, PrepareAtomicStageSessionOptions } from "./atomic-stage-session.js";
+import type { PiCustomOverlayFactory, PiCustomOverlayOptions, PiUISurface } from "./ui-surface.js";
+export type { PiCustomComponent, PiCustomOverlayFactory, PiCustomOverlayFactoryTui, PiCustomOverlayFunction, PiCustomOverlayOptions, PiEditorComponent, PiEditorFactory, PiHostCustomUiState, PiHostCustomUiStateListener, PiKeybindings, PiOverlayHandle, PiOverlayOptions, PiTheme, PiUIDialogOptions, PiUISurface, UIWiringSurface } from "./ui-surface.js";
 
 // ---------------------------------------------------------------------------
 // Minimal pi surface
@@ -85,193 +88,6 @@ function isTestContext(): boolean {
   return process.env["NODE_TEST_CONTEXT"] !== undefined || process.env["NODE_ENV"] === "test";
 }
 
-/**
- * Lazily-resolved pi SDK session factory. Imported from
- * `@bastani/atomic` on first use so the heavy SDK module
- * (filesystem discovery, resource loader, model registry) is not loaded
- * until an actual workflow stage runs. This is the canonical production
- * default — the modern pi SDK (≥ 0.74) exposes `createAgentSession` as a
- * top-level package export and does NOT inject it onto the ExtensionAPI,
- * so the workflow extension must reach into the SDK directly.
- *
- * cross-ref: node_modules/@bastani/atomic/docs/sdk.md
- *            node_modules/@bastani/atomic/dist/core/sdk.d.ts
- */
-export interface PiSdkSettingsManager {
-  getCodexFastModeSettings(): { readonly chat: boolean; readonly workflow: boolean };
-}
-export interface PiSdkResourceLoader {
-  reload(): Promise<void>;
-}
-interface PiSdkSessionManager {
-  getCwd(): string;
-}
-export interface PiCodingAgentSdk {
-  getAgentDir(): string;
-  getBuiltinPackagePaths?: () => string[];
-  SettingsManager: {
-    create(cwd?: string, agentDir?: string, options?: { projectTrusted?: boolean }): PiSdkSettingsManager;
-  };
-  DefaultResourceLoader: new (options: {
-    cwd: string;
-    agentDir: string;
-    settingsManager?: PiSdkSettingsManager;
-    builtinPackagePaths?: PackageSource[];
-    resourceLoaderInheritanceSnapshot?: DefaultResourceLoaderInheritanceSnapshot;
-  }) => PiSdkResourceLoader;
-  createAgentSession(options?: AtomicCreateAgentSessionOptions): Promise<{ session: StageSessionRuntime }>;
-}
-type AtomicCreateAgentSessionOptions = Omit<CreateAgentSessionOptions, "settingsManager" | "resourceLoader" | "sessionManager"> & {
-  settingsManager?: PiSdkSettingsManager;
-  resourceLoader?: PiSdkResourceLoader;
-  sessionManager?: PiSdkSessionManager;
-};
-
-export interface PrepareAtomicStageSessionOptions {
-  resourceLoaderInheritanceSnapshot?: DefaultResourceLoaderInheritanceSnapshot;
-}
-
-function resolveSessionCwd(options: AtomicCreateAgentSessionOptions | undefined): string {
-  return options?.cwd ?? options?.sessionManager?.getCwd() ?? process.cwd();
-}
-
-/**
- * Prepare Atomic SDK stage-session options with Atomic-first resource loading.
- *
- * The Atomic SDK's documented defaults are intentionally significant:
- * omitted `agentDir` means credentials/models/settings can be read from the
- * primary `~/.atomic/agent` paths first while still considering legacy
- * `~/.pi/agent` compatibility paths when the SDK supports multiple config
- * directories. Passing the computed default back as an explicit `agentDir`
- * would accidentally turn that multi-dir behavior into a single-dir override.
- *
- * A user-supplied `agentDir` is still preserved exactly and remains an
- * explicit override. A user-supplied `resourceLoader` is also preserved; in
- * that case cwd/agentDir no longer control resource discovery and only affect
- * session naming/tool path resolution, matching the pi SDK docs.
- */
-export async function prepareAtomicStageSessionOptions(
-  options: CreateAgentSessionOptions | undefined,
-  sdk: PiCodingAgentSdk,
-  prepareOptions: PrepareAtomicStageSessionOptions = {},
-): Promise<AtomicCreateAgentSessionOptions | undefined> {
-  const atomicOptions = options as AtomicCreateAgentSessionOptions | undefined;
-  if (atomicOptions?.resourceLoader !== undefined) return atomicOptions;
-
-  const inheritanceSnapshot = prepareOptions.resourceLoaderInheritanceSnapshot;
-  const cwd = resolveSessionCwd(atomicOptions);
-  const hasAgentDirOverride = atomicOptions?.agentDir !== undefined;
-  const agentDir = atomicOptions?.agentDir ?? sdk.getAgentDir();
-  const settingsManager =
-    atomicOptions?.settingsManager ?? sdk.SettingsManager.create(
-      cwd,
-      agentDir,
-      inheritanceSnapshot?.projectTrusted === undefined
-        ? undefined
-        : { projectTrusted: inheritanceSnapshot.projectTrusted },
-    );
-  const inheritedBuiltinPackagePaths = inheritanceSnapshot?.builtinPackagePaths;
-  const builtinPackagePaths = inheritedBuiltinPackagePaths === undefined
-    ? sdk.getBuiltinPackagePaths?.() ?? []
-    : [...inheritedBuiltinPackagePaths];
-  const resourceLoader = new sdk.DefaultResourceLoader({
-    cwd,
-    agentDir,
-    settingsManager,
-    resourceLoaderInheritanceSnapshot: inheritanceSnapshot,
-    builtinPackagePaths: stageBuiltinPackagePaths(builtinPackagePaths),
-  });
-  await reloadWorkflowStageResources(resourceLoader);
-
-  return {
-    ...atomicOptions,
-    cwd,
-    ...(hasAgentDirOverride ? { agentDir } : {}),
-    settingsManager,
-    resourceLoader,
-  };
-}
-
-function clonePackageSource(source: PackageSource): PackageSource {
-  if (typeof source === "string") return source;
-  return {
-    source: source.source,
-    ...(source.extensions === undefined ? {} : { extensions: [...source.extensions] }),
-    ...(source.skills === undefined ? {} : { skills: [...source.skills] }),
-    ...(source.prompts === undefined ? {} : { prompts: [...source.prompts] }),
-    ...(source.themes === undefined ? {} : { themes: [...source.themes] }),
-    ...(source.workflows === undefined ? {} : { workflows: [...source.workflows] }),
-  };
-}
-
-function packageSourcePath(source: PackageSource): string {
-  return typeof source === "string" ? source : source.source;
-}
-
-function disablePackageExtensions(source: PackageSource): PackageSource {
-  if (typeof source === "string") return { source, extensions: [] };
-  return { ...source, extensions: [] };
-}
-
-function stageBuiltinPackagePaths(paths: readonly PackageSource[]): PackageSource[] {
-  // Workflow stages are child AgentSessions owned by the workflow extension.
-  // Loading the workflows extension again inside that child session replays its
-  // `session_start` lifecycle and clears/kills the parent workflow store. Keep
-  // the workflows package itself so its bundled skills/prompts/resources remain
-  // available, but disable only its extension entry for stage sessions.
-  return paths.map((path) => {
-    const cloned = clonePackageSource(path);
-    return basename(packageSourcePath(cloned)) === "workflows"
-      ? disablePackageExtensions(cloned)
-      : cloned;
-  });
-}
-
-const SUBAGENT_CHILD_EXTENSION_ENV_KEYS = [
-  "ATOMIC_SUBAGENT_CHILD",
-  "ATOMIC_SUBAGENT_FANOUT_CHILD",
-  "PI_SUBAGENT_CHILD",
-  "PI_SUBAGENT_FANOUT_CHILD",
-] as const;
-
-let workflowStageResourceReloadQueue: Promise<void> = Promise.resolve();
-
-async function reloadWorkflowStageResources(resourceLoader: PiSdkResourceLoader): Promise<void> {
-  const queuedReload = workflowStageResourceReloadQueue.then(() =>
-    reloadWorkflowStageResourcesWithEnvIsolation(resourceLoader),
-  );
-  workflowStageResourceReloadQueue = queuedReload.catch(() => undefined);
-  return queuedReload;
-}
-
-async function reloadWorkflowStageResourcesWithEnvIsolation(resourceLoader: PiSdkResourceLoader): Promise<void> {
-  // Workflow stage sessions are already governed by an orchestration context
-  // that disables recursive workflow tools and caps nested subagent depth. When
-  // a workflow itself runs inside a subagent child process, inherited subagent
-  // child env flags would otherwise make the bundled subagents extension skip
-  // registering its `subagent` tool before the stage session exists. Isolate
-  // extension discovery from those parent-process flags so an explicit
-  // `tools: ["subagent"]` allowlist works the same in workflow stages everywhere.
-  // The isolation mutates process-global env, so serialize the full
-  // save/delete/reload/restore section. Without this queue, overlapping workflow
-  // stage session creation can snapshot an already-cleared env and restore that
-  // stale snapshot after another reload restores the real parent values.
-  const previousValues = new Map<string, string | undefined>();
-  for (const key of SUBAGENT_CHILD_EXTENSION_ENV_KEYS) {
-    previousValues.set(key, process.env[key]);
-    delete process.env[key];
-  }
-  try {
-    await resourceLoader.reload();
-  } finally {
-    for (const key of SUBAGENT_CHILD_EXTENSION_ENV_KEYS) {
-      const previousValue = previousValues.get(key);
-      if (previousValue === undefined) delete process.env[key];
-      else process.env[key] = previousValue;
-    }
-  }
-}
-
 async function createPiSdkAgentSession(
   options?: CreateAgentSessionOptions,
   prepareOptions?: PrepareAtomicStageSessionOptions,
@@ -505,288 +321,3 @@ export function buildRuntimeAdapters(
 
   return adapters;
 }
-
-// ---------------------------------------------------------------------------
-// UI adapter — maps pi ctx.ui dialog surface to WorkflowUIAdapter
-// ---------------------------------------------------------------------------
-
-/**
- * Subset of pi's ExtensionUIDialogOptions consumed by the adapter.
- * Structurally matched against @bastani/atomic
- * ExtensionUIDialogOptions.
- */
-export interface PiUIDialogOptions {
-  /** AbortSignal to programmatically dismiss the dialog. */
-  signal?: AbortSignal;
-  /** Timeout in milliseconds. */
-  timeout?: number;
-}
-
-/**
- * Structural subset of pi-tui's `OverlayOptions` that this extension
- * consumes when mounting overlays via `ctx.ui.custom(factory, options)`.
- * Mirrors @earendil-works/pi-tui dist/tui.d.ts `OverlayOptions`.
- *
- * Only the fields actually forwarded by this extension are typed. Pi may
- * accept additional fields in the future; values pass through verbatim.
- */
-export interface PiOverlayOptions {
-  /** Overlay width — number = columns, "N%" = percent of terminal columns. */
-  width?: number | string;
-  /** Minimum overlay width in columns. */
-  minWidth?: number;
-  /** Overlay maximum height — number = rows, "N%" = percent of terminal rows. */
-  maxHeight?: number | string;
-  /** Anchor edge / corner. Pi-tui accepts named anchors like "center". */
-  anchor?: string;
-  /** Horizontal offset (columns) applied after anchor resolution. */
-  offsetX?: number;
-  /** Vertical offset (rows) applied after anchor resolution. */
-  offsetY?: number;
-  /** Explicit overlay top row (0-indexed) — overrides anchor vertical. */
-  row?: number;
-  /** Explicit overlay left column (0-indexed) — overrides anchor horizontal. */
-  col?: number;
-  /** Margin inset, scalar or per-edge object. */
-  margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
-  /** Responsive visibility predicate. */
-  visible?: boolean | ((terminal: { rows: number; columns: number }) => boolean);
-  /** When `true`, overlay does not capture focus. */
-  nonCapturing?: boolean;
-}
-
-export interface PiCustomComponent {
-  render(width: number): string[];
-  handleInput?: (data: string) => void;
-  invalidate?: () => void;
-  dispose?: () => void;
-}
-
-/**
- * Handle exposed by pi's TUI for controlling a live overlay. Mirrors the
- * shape from @earendil-works/pi-tui `OverlayHandle` — `setHidden(true)`
- * temporarily hides the overlay (cheap to flip on/off, used for a
- * show/hide toggle), `hide()` permanently dismisses it.
- */
-export interface PiOverlayHandle {
-  hide(): void;
-  setHidden(hidden: boolean): void;
-  isHidden(): boolean;
-  focus(): void;
-  unfocus(): void;
-  isFocused(): boolean;
-}
-
-/**
- * Options accepted by Pi/pi's real `ctx.ui.custom(factory, options)`
- * overlay primitive. Aligned with the shape documented in
- * `@bastani/atomic docs/tui.md` and
- * `@earendil-works/pi-tui dist/tui.d.ts`.
- *
- * Host-compatibility note: pi's interactive
- * `ExtensionUiController.custom` hardcodes the overlay geometry when
- * `overlay: true` to `{ anchor: "bottom-center", width: "100%",
- * maxHeight: "100%", margin: 0 }`, and does NOT forward this object's
- * `overlayOptions` field. Consumers MUST NOT rely on `overlayOptions`
- * for actual placement in interactive pi mode — the field is
- * retained for forward-compatibility (future hosts and the test seam
- * may consume it).
- *
- * Workflow pickers (`session-overlays.ts`, `inputs-overlay.ts`) mount
- * with `overlay: false`, which causes the host to REPLACE the editor
- * with the picker inline at the editor's natural position — see
- * those files for rationale and `ui/workflows/Screenshot 2026-05-13
- * at 1.11.49 AM.png` for the target spacing.
- *
- * `onHandle` is honoured today only by the full-screen graph overlay
- * (`overlay-adapter.ts`); inline pickers leave it unset and dismiss
- * via the factory `done()` callback.
- */
-export interface PiHostCustomUiState {
-  blockingInlineCustomUiDepth: number;
-  blockingInlineCustomUiActive: boolean;
-  blockingInlineCustomUiFocusDeferred?: boolean;
-}
-
-export type PiHostCustomUiStateListener = (state: PiHostCustomUiState) => void;
-
-export interface PiCustomOverlayOptions {
-  /**
-   * `true` mounts a floating popup; `false` mounts a focused
-   * full-screen pi-tui pane that takes keyboard focus and renders in
-   * place of the editor until the factory's `done()` callback fires.
-   */
-  overlay: boolean;
-  /** Keep host inline custom UI pending in the background while this overlay is visible. */
-  deferInlineCustomUiFocus?: boolean;
-  /**
-   * Geometry / anchoring intended for pi-tui's `resolveOverlayLayout`.
-   * NOT forwarded by current pi interactive `custom()` — see
-   * the host-compatibility note above. Treat as advisory metadata
-   * until the host wires it through.
-   */
-  overlayOptions?: PiOverlayOptions;
-  /**
-   * Optional callback invoked with the OverlayHandle once pi-tui
-   * mounts the overlay. Use to drive show/hide toggles without
-   * re-mounting. Only the full-screen graph overlay path consumes
-   * this today; inline pickers leave it unset and dismiss via the
-   * factory `done()` callback.
-   */
-  onHandle?: (handle: PiOverlayHandle) => void;
-}
-
-/**
- * Surface of the Pi `TUI` instance exposed to overlay factories. The
- * `terminal` accessor is optional because some host implementations and
- * test mocks do not surface it; consumers must handle `undefined`.
- */
-export interface PiCustomOverlayFactoryTui {
-  requestRender?: () => void;
-  terminal?: { rows?: number; columns?: number };
-  setFocus?: (target: unknown) => void;
-  start?: () => void;
-  stop?: () => void;
-  [key: string]: unknown;
-}
-
-export type PiTheme = unknown;
-export type PiKeybindings = unknown;
-
-export type PiCustomOverlayFactory<T = unknown> = (
-  tui: PiCustomOverlayFactoryTui,
-  theme: PiTheme,
-  keybindings: PiKeybindings,
-  done: (result: T) => void,
-) => PiCustomComponent | Promise<PiCustomComponent>;
-
-export type PiCustomOverlayFunction = (
-  factory: PiCustomOverlayFactory,
-  options: PiCustomOverlayOptions,
-) => Promise<unknown> | unknown;
-
-/**
- * Structural shape of pi's custom editor component. Interactive mode
- * currently installs extension editors through `InteractiveMode.setEditorComponent`,
- * which expects the richer `CustomEditor` surface and configures these methods
- * before mounting. Keep the extra methods optional for lightweight tests and
- * non-interactive shims, but real custom editors should implement them.
- *
- * The resize-handler contract (`setTopBorder` / `getTopBorderAvailableWidth`)
- * is invoked unconditionally by `InteractiveMode`'s `process.stdout` "resize"
- * listener — any custom editor mounted via `setEditorComponent` MUST provide
- * them or the host throws `TypeError` on the first terminal resize.
- */
-export interface PiEditorComponent {
-  focused?: boolean;
-  getText(): string;
-  setText(text: string): void;
-  handleInput(data: string): void;
-  render(width: number): string[];
-  invalidate?(): void;
-  dispose?(): void;
-  onSubmit?: (text: string) => void | Promise<void>;
-  onChange?: (text: string) => void;
-  onAutocompleteCancel?: () => void;
-  onAutocompleteUpdate?: () => void;
-  setUseTerminalCursor?(useTerminalCursor: boolean): void;
-  getUseTerminalCursor?(): boolean;
-  setAutocompleteMaxVisible?(maxVisible: number): void;
-  getAutocompleteMaxVisible?(): number;
-  setMaxHeight?(maxHeight: number | undefined): void;
-  setHistoryStorage?(storage: object): void;
-  setActionKeys?(action: string, keys: readonly string[]): void;
-  setCustomKeyHandler?(key: string, handler: () => void): void;
-  removeCustomKeyHandler?(key: string): void;
-  clearCustomKeyHandlers?(): void;
-  setAutocompleteProvider?(provider: object): void;
-  addToHistory?(text: string): void;
-  insertTextAtCursor?(text: string): void;
-  getExpandedText?(): string;
-  setPaddingX?(padding: number): void;
-  setTopBorder?(content: unknown): void;
-  getTopBorderAvailableWidth?(terminalWidth: number): number;
-}
-
-export type PiEditorFactory = (
-  tui: { requestRender?: () => void },
-  theme: unknown,
-  keybindings: unknown,
-) => PiEditorComponent;
-
-/**
- * Structural type for the pi UI dialog surface.
- * Matches @bastani/atomic ExtensionUIContext dialog methods.
- * All fields optional — presence is checked at runtime before building adapter.
- */
-export interface PiUISurface {
-  /** Show a text input dialog. Returns undefined when user dismisses. */
-  input?: (title: string, placeholder?: string, opts?: PiUIDialogOptions) => Promise<string | undefined>;
-  /** Show a confirmation dialog. */
-  confirm?: (title: string, message: string, opts?: PiUIDialogOptions) => Promise<boolean>;
-  /** Show a selector and return the user's choice. Returns undefined when user dismisses. */
-  select?: (title: string, options: string[], opts?: PiUIDialogOptions) => Promise<string | undefined>;
-  /** Show a multi-line editor. Returns undefined when user dismisses. */
-  editor?: (title: string, prefill?: string) => Promise<string | undefined>;
-  notify?: (message: string, type?: "info" | "warning" | "error") => void;
-  onTerminalInput?: (handler: unknown) => () => void;
-  setStatus?: (key: string, text: string | undefined) => void;
-  setWorkingMessage?: (message?: string) => void;
-  setWorkingVisible?: (visible: boolean) => void;
-  setWorkingIndicator?: (options?: unknown) => void;
-  setHiddenThinkingLabel?: (label?: string) => void;
-  /** Set a live widget above or below the editor. */
-  setWidget?: (
-    key: string,
-    factory:
-      | string[]
-      | ((tui: unknown, theme: unknown) => { render(width: number): string[]; dispose?(): void })
-      | undefined,
-    opts?: { placement?: string },
-  ) => void;
-  setFooter?: (factory: unknown) => void;
-  setHeader?: (factory: unknown) => void;
-  setTitle?: (title: string) => void;
-  /** Show a custom component or overlay. */
-  custom?: PiCustomOverlayFunction;
-  /** 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. */
-  onHostCustomUiStateChange?: (listener: PiHostCustomUiStateListener) => () => void;
-  /** Move focus to a mounted host-owned inline custom UI, if one is pending. */
-  focusHostInlineCustomUi?: () => boolean;
-  pasteToEditor?: (text: string) => void;
-  setEditorText?: (text: string) => void;
-  getEditorText?: () => string;
-  addAutocompleteProvider?: (factory: unknown) => void;
-  /**
-   * Install a custom editor (replaces the bottom input bar) until cleared
-   * with `setEditorComponent(undefined)`. Used by the inline workflow
-   * input form to capture per-field keystrokes.
-   * cross-ref: docs/extensions.md §Custom Editor (pi-coding-agent).
-   */
-  setEditorComponent?: (factory: PiEditorFactory | undefined) => void;
-  /** Return the currently-installed editor factory, or undefined for the default. */
-  getEditorComponent?: () => PiEditorFactory | undefined;
-  /** Current resolved Pi theme and theme helpers, forwarded to stage extensions. */
-  theme?: unknown;
-  getAllThemes?: () => Array<{ name: string; path: string | undefined }>;
-  getTheme?: (name: string) => unknown;
-  setTheme?: (theme: string | unknown) => { success: boolean; error?: string };
-  getToolsExpanded?: () => boolean;
-  setToolsExpanded?: (expanded: boolean) => void;
-  getChatRenderSettings?: () => Partial<Omit<ChatMessageRenderOptions, "ui" | "cwd">> | undefined;
-}
-
-/**
- * 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`,
- * 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
- * SDK stage sessions.
- */
-export interface UIWiringSurface {
-  ui?: PiUISurface;
-}

package/dist/builtin/workflows/src/extension/workflow-command-completions.ts

@@ -0,0 +1,111 @@
+import { schemaChoices, schemaDescription, schemaFieldKind } from "../shared/schema-introspection.js";
+import { store } from "../shared/store.js";
+import { topLevelWorkflowRuns } from "../shared/run-visibility.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import type { PiArgumentCompletion, PiArgumentCompletionResult } from "./public-types.js";
+
+function completeToken(
+  argumentText: string,
+  candidates: PiArgumentCompletion[],
+): PiArgumentCompletionResult {
+  const tokenStart = /\s$/.test(argumentText)
+    ? argumentText.length
+    : Math.max(argumentText.lastIndexOf(" "), argumentText.lastIndexOf("\t")) + 1;
+  const head = argumentText.slice(0, tokenStart);
+  const token = argumentText.slice(tokenStart);
+  const filtered = candidates
+    .filter((candidate) => candidate.value.startsWith(token))
+    .map((candidate) => ({ ...candidate, value: `${head}${candidate.value}` }));
+  return filtered.length > 0 ? filtered : null;
+}
+
+function adminCompletions(): PiArgumentCompletion[] {
+  return [
+    { value: "connect ", label: "connect", description: "Attach to a run (picker if no id)" },
+    { value: "attach ", label: "attach", description: "Open the in-place attach pane on a node" },
+    { value: "list ", label: "list", description: "List registered workflows" },
+    { value: "status ", label: "status", description: "List current-session active and retained terminal runs" },
+    { value: "interrupt ", label: "interrupt", description: "Interrupt a run" },
+    { value: "kill ", label: "kill", description: "Kill and retain a run for inspection" },
+    { value: "pause ", label: "pause", description: "Pause a run or stage" },
+    { value: "resume ", label: "resume", description: "Re-open overlay for a run" },
+    { value: "inputs ", label: "inputs", description: "Show a workflow's input schema" },
+    { value: "reload ", label: "reload", description: "Reload workflow resources" },
+  ];
+}
+
+function workflowNameItems(runtime: ExtensionRuntime): PiArgumentCompletion[] {
+  return runtime.registry.names().map((name) => ({
+    value: `${name} `,
+    label: name,
+    description: `Run workflow: ${name}`,
+  }));
+}
+
+function runIdItems(): PiArgumentCompletion[] {
+  return topLevelWorkflowRuns(store.runs()).map((run) => ({
+    value: `${run.id} `,
+    label: run.id.slice(0, 8),
+    description: `${run.name} — ${run.status}`,
+  }));
+}
+
+export function workflowArgumentCompletions(
+  partial: string,
+  runtime: ExtensionRuntime,
+): PiArgumentCompletionResult {
+  const parts = partial.trim().split(/\s+/).filter(Boolean);
+  const subcommand = parts[0] ?? "";
+  const workflows = () => workflowNameItems(runtime);
+  if (!partial.includes(" ")) {
+    return completeToken(partial, [...adminCompletions(), ...workflows()]);
+  }
+  if (subcommand === "inputs") return completeToken(partial, workflows());
+  if (["status", "connect", "resume", "attach", "pause"].includes(subcommand)) {
+    return completeToken(partial, runIdItems());
+  }
+  if (subcommand === "interrupt" || subcommand === "kill") {
+    const verb = subcommand === "kill" ? "Kill and retain" : "Interrupt";
+    return completeToken(partial, [
+      { value: "--all ", label: "--all", description: `${verb} all in-flight runs` },
+      { value: "--yes ", label: "--yes", description: "Skip confirmation" },
+      { value: "-y ", label: "-y", description: "Skip confirmation" },
+      ...runIdItems(),
+    ]);
+  }
+  if (!subcommand) return completeToken(partial, [...adminCompletions(), ...workflows()]);
+
+  const workflow = runtime.registry.get(subcommand);
+  if (!workflow) return null;
+  const tokenStart = /\s$/.test(partial)
+    ? partial.length
+    : Math.max(partial.lastIndexOf(" "), partial.lastIndexOf("\t")) + 1;
+  const token = partial.slice(tokenStart);
+  const equalsIndex = token.indexOf("=");
+  if (equalsIndex > 0) {
+    const inputName = token.slice(0, equalsIndex);
+    const schema = workflow.inputs[inputName];
+    const schemaChoiceValues = schema === undefined ? undefined : schemaChoices(schema);
+    const schemaKind = schema === undefined ? undefined : schemaFieldKind(schema);
+    if (schemaChoiceValues !== undefined) {
+      return completeToken(
+        partial,
+        schemaChoiceValues.map((choice) => ({ value: `${inputName}=${choice} `, label: choice, description: inputName })),
+      );
+    }
+    if (schemaKind === "boolean") {
+      return completeToken(partial, [
+        { value: `${inputName}=true `, label: "true", description: inputName },
+        { value: `${inputName}=false `, label: "false", description: inputName },
+      ]);
+    }
+    return null;
+  }
+  const inputCompletions: PiArgumentCompletion[] = Object.entries(workflow.inputs)
+    .map(([name, schema]) => ({ value: `${name}=`, label: name, description: schemaDescription(schema) }));
+  return completeToken(partial, [
+    { value: "--no-picker ", label: "--no-picker", description: "Skip interactive input picker" },
+    { value: "--help ", label: "--help", description: "Show this workflow's input schema" },
+    ...inputCompletions,
+  ]);
+}