@bastani/atomic 0.7.17 → 0.8.0

package/dist/builtin/workflows/src/extension/background-ui-adapter.ts

@@ -0,0 +1,168 @@
+/**
+ * Background workflow HIL adapter — bridges `ctx.ui.input/confirm/select/editor`
+ * to store-backed pending prompts instead of pi.ui modal dialogs.
+ *
+ * Detached runs use this adapter so the main chat editor stays usable while
+ * a workflow is in flight. HIL surfaces through the graph viewer overlay:
+ *
+ *   1. Stage calls `ctx.ui.editor(prefill)`
+ *   2. Adapter records a `PendingPrompt` on the run via the store
+ *   3. Adapter awaits resolution (Promise stays pending; chat editor is free)
+ *   4. User presses F2 / `/workflow connect <id>` — graph viewer mounts
+ *   5. Graph viewer shows the prompt card; user types + submits
+ *   6. Graph viewer calls `store.resolvePendingPrompt(runId, promptId, value)`
+ *   7. Adapter promise resolves; workflow body continues
+ *
+ * If the run terminates (kill / abort) before the user responds, the awaiter
+ * rejects via `recordRunEnd` so the executor can finalise cleanly — no leaked
+ * pending promises.
+ *
+ * cross-ref:
+ *   src/shared/store-types.ts PendingPrompt
+ *   src/shared/store.ts recordPendingPrompt / resolvePendingPrompt / awaitPendingPrompt
+ *   src/tui/graph-view.ts pending-prompt rendering + key handling
+ */
+
+import type { Store } from "../shared/store.js";
+import type {
+  PendingPrompt,
+  PromptKind,
+} from "../shared/store-types.js";
+import type { WorkflowUIAdapter } from "../shared/types.js";
+
+interface PromptDescriptor {
+  readonly kind: PromptKind;
+  readonly message: string;
+  readonly choices?: readonly string[];
+  readonly initial?: string;
+}
+
+function nextPromptId(): string {
+  // Crypto-strong is overkill here; runId already provides isolation. A short
+  // random suffix keeps the id readable in debug logs.
+  return `hil-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function ask(
+  store: Store,
+  runId: string,
+  descriptor: PromptDescriptor,
+  signal: AbortSignal | undefined,
+): Promise<unknown> {
+  if (signal?.aborted) {
+    // Pre-aborted: don't record a prompt that won't be answered. Resolve to
+    // a kind-appropriate default so the workflow body unwinds without
+    // throwing — the executor's post-body abort check finalises as "killed".
+    return Promise.resolve(fallbackForKind(descriptor));
+  }
+  const prompt: PendingPrompt = {
+    id: nextPromptId(),
+    kind: descriptor.kind,
+    message: descriptor.message,
+    ...(descriptor.choices !== undefined ? { choices: descriptor.choices } : {}),
+    ...(descriptor.initial !== undefined ? { initial: descriptor.initial } : {}),
+    createdAt: Date.now(),
+  };
+  const accepted = store.recordPendingPrompt(runId, prompt);
+  if (!accepted) {
+    // Run missing, terminal, or already has a pending prompt. Resolve with a
+    // safe default rather than throwing — workflow authors don't need to
+    // defensively try/catch every HIL call.
+    return Promise.resolve(fallbackForKind(descriptor));
+  }
+  const waiter = store.awaitPendingPrompt(runId, prompt.id);
+  if (!signal) return waiter;
+  // Race against abort so kill() doesn't leave the workflow body wedged on
+  // a HIL await nobody will answer. We also forward a default response into
+  // the store so any concurrent observer sees the prompt cleared.
+  return new Promise<unknown>((resolve, reject) => {
+    const onAbort = (): void => {
+      store.resolvePendingPrompt(runId, prompt.id, fallbackForKind(descriptor));
+      reject(
+        signal.reason instanceof Error
+          ? signal.reason
+          : new Error("pi-workflows: HIL aborted"),
+      );
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    waiter.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (err: unknown) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(err);
+      },
+    );
+  });
+}
+
+function fallbackForKind(descriptor: PromptDescriptor): unknown {
+  switch (descriptor.kind) {
+    case "input":
+    case "editor":
+      return descriptor.initial ?? "";
+    case "confirm":
+      return false;
+    case "select":
+      return descriptor.choices?.[0] ?? "";
+  }
+}
+
+/**
+ * Build a `WorkflowUIAdapter` whose methods record prompts on `runId` via
+ * the store and await user response through the graph viewer.
+ *
+ * This is the only HIL surface a workflow body sees — `pi.ui.editor`,
+ * `pi.ui.confirm`, etc. are intentionally never invoked from inside a run.
+ * The chat editor stays free; the user attends to prompts via F2 / the
+ * `/workflow connect` overlay.
+ *
+ * `signal` is the run's `AbortController.signal`; when fired (e.g. via
+ * `/workflow interrupt <id>`), any HIL waiter rejects so the workflow body
+ * unwinds instead of hanging. Pass `undefined` only in tests where you
+ * drive resolution directly via `store.resolvePendingPrompt`.
+ */
+export function buildBackgroundUIAdapter(
+  store: Store,
+  runId: string,
+  signal?: AbortSignal,
+): WorkflowUIAdapter {
+  return {
+    async input(prompt: string): Promise<string> {
+      const response = await ask(store, runId, { kind: "input", message: prompt }, signal);
+      return typeof response === "string" ? response : String(response ?? "");
+    },
+
+    async confirm(message: string): Promise<boolean> {
+      const response = await ask(store, runId, { kind: "confirm", message }, signal);
+      return response === true;
+    },
+
+    async select<T extends string>(
+      message: string,
+      options: readonly T[],
+    ): Promise<T> {
+      const response = await ask(store, runId, {
+        kind: "select",
+        message,
+        choices: options,
+      }, signal);
+      if (typeof response === "string" && (options as readonly string[]).includes(response)) {
+        return response as T;
+      }
+      return options[0];
+    },
+
+    async editor(initial?: string): Promise<string> {
+      const response = await ask(store, runId, {
+        kind: "editor",
+        message: "Edit and save to continue.",
+        initial,
+      }, signal);
+      if (typeof response === "string") return response;
+      return initial ?? "";
+    },
+  };
+}

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

@@ -0,0 +1,210 @@
+/**
+ * Companion-package detection helpers.
+ *
+ * Why this exists:
+ *   `@bastani/workflows` orchestrates a few first-party pi packages
+ *   at runtime (delegation, MCP access, HIL bridge, web fetch). They are
+ *   installed independently of workflows so pi's npm-identity
+ *   dedup can share them with any other extensions the user already has
+ *   (see pi docs/packages.md → "Scope and Deduplication"). Bundling them
+ *   via `bundledDependencies` produced a parallel "local-path" identity
+ *   that bypassed dedup and yielded `Tool "mcp" conflicts with ...` /
+ *   `Tool "subagent" conflicts with ...` errors on load.
+ *
+ *   The trade-off of independent installs is that we cannot reach in and
+ *   require() them — we instead **detect** their presence by inspecting
+ *   pi's slash-command and tool registries.
+ *
+ * Detection is intentionally best-effort and structural:
+ *   1. Path hints (preferred): `pi.getCommands()[].sourceInfo.path` /
+ *      `.baseDir` typically include the package name (e.g.
+ *      `.../node_modules/pi-subagents/...`). This survives command/tool
+ *      renames in upstream packages.
+ *   2. Command-name hints (fallback): a distinctive slash command
+ *      registered by the companion.
+ *   3. Tool-name hints (fallback): a registered tool name (e.g. `mcp`).
+ *
+ * Any match counts as "installed".
+ *
+ * cross-ref:
+ *  - pi docs/packages.md → "Scope and Deduplication"
+ */
+
+import type { ExtensionAPI } from "./index.js";
+
+// ---------------------------------------------------------------------------
+// Companion catalogue
+// ---------------------------------------------------------------------------
+
+/** One entry per companion pi package workflows can use at runtime. */
+export interface CompanionSpec {
+  /** Display name, e.g. `pi-subagents`. */
+  readonly name: string;
+  /** Install spec used for setup hints: `npm:pi-subagents`. */
+  readonly installSpec: string;
+  /** One-line description shown beside the status. */
+  readonly purpose: string;
+  /**
+   * Path-fragment hints matched against `sourceInfo.path` / `.baseDir`.
+   * First match wins. Prefer this over name hints — surviving renames.
+   */
+  readonly pathHints: readonly string[];
+  /** Slash-command names registered by the package (without the leading `/`). */
+  readonly commandHints: readonly string[];
+  /** Registered tool names (matched against `pi.getAllTools()[].name`). */
+  readonly toolHints: readonly string[];
+}
+
+/**
+ * Ordered companion catalogue. Order is preserved across detection
+ * outputs so any UI surfacing companions can render a stable layout.
+ */
+export const COMPANIONS: readonly CompanionSpec[] = [
+  {
+    name: "pi-subagents",
+    installSpec: "npm:pi-subagents",
+    purpose: "delegate stages to focused child agents",
+    pathHints: ["/pi-subagents/", "/pi-subagents-", "/pi-subagents."],
+    commandHints: ["subagents-doctor", "run", "chain", "parallel", "run-chain"],
+    toolHints: ["subagent"],
+  },
+  {
+    name: "pi-mcp-adapter",
+    installSpec: "npm:pi-mcp-adapter",
+    purpose: "MCP servers through one proxy tool (no context bloat)",
+    pathHints: ["/pi-mcp-adapter/", "/pi-mcp-adapter-", "/pi-mcp-adapter."],
+    commandHints: ["mcp"],
+    toolHints: ["mcp"],
+  },
+  {
+    name: "pi-web-access",
+    installSpec: "npm:pi-web-access",
+    purpose: "fetch and search the web from inside a stage",
+    pathHints: ["/pi-web-access/", "/pi-web-access-", "/pi-web-access."],
+    commandHints: ["web", "web-access"],
+    toolHints: ["web_fetch", "web_search", "web"],
+  },
+  {
+    name: "pi-intercom",
+    installSpec: "npm:pi-intercom",
+    purpose: "child agents talk back to the parent session (HIL)",
+    pathHints: ["/pi-intercom/", "/pi-intercom-", "/pi-intercom."],
+    commandHints: ["intercom"],
+    toolHints: ["intercom", "contact_supervisor"],
+  },
+] as const;
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+export interface CompanionStatus {
+  readonly companion: CompanionSpec;
+  readonly installed: boolean;
+  /** Human-readable signal that drove the verdict — empty when missing. */
+  readonly evidence?: string;
+}
+
+/**
+ * Surface used for detection. Kept narrow so tests can stub it without
+ * the full `ExtensionAPI`.
+ */
+export interface CompanionProbeApi {
+  readonly getCommands?: () => ReadonlyArray<CommandProbe>;
+  readonly getAllTools?: () => ReadonlyArray<ToolProbe>;
+}
+
+interface CommandProbe {
+  readonly name: string;
+  readonly sourceInfo?: { readonly path?: string; readonly baseDir?: string };
+}
+
+interface ToolProbe {
+  readonly name: string;
+  readonly sourceInfo?: { readonly path?: string; readonly baseDir?: string };
+}
+
+/**
+ * Inspect pi's registries and return one status per companion in the
+ * catalogue order. Pure of side effects.
+ */
+export function detectCompanions(pi: ExtensionAPI | CompanionProbeApi): readonly CompanionStatus[] {
+  const probe = pi as CompanionProbeApi;
+  const commands = safeProbeList(probe.getCommands);
+  const tools = safeProbeList(probe.getAllTools);
+
+  return COMPANIONS.map((companion) => detectOne(companion, commands, tools));
+}
+
+function detectOne(
+  companion: CompanionSpec,
+  commands: readonly CommandProbe[],
+  tools: readonly ToolProbe[],
+): CompanionStatus {
+  // 1. Path hints — most reliable (survives upstream renames).
+  const pathHit = findPathHit(commands, tools, companion.pathHints);
+  if (pathHit) return { companion, installed: true, evidence: `path ${pathHit}` };
+
+  // 2. Command-name hints.
+  for (const name of companion.commandHints) {
+    if (commands.some((c) => c.name === name)) {
+      return { companion, installed: true, evidence: `command /${name}` };
+    }
+  }
+
+  // 3. Tool-name hints.
+  for (const name of companion.toolHints) {
+    if (tools.some((t) => t.name === name)) {
+      return { companion, installed: true, evidence: `tool ${name}` };
+    }
+  }
+
+  return { companion, installed: false };
+}
+
+function findPathHit(
+  commands: readonly CommandProbe[],
+  tools: readonly ToolProbe[],
+  hints: readonly string[],
+): string | undefined {
+  const haystacks: string[] = [];
+  for (const c of commands) {
+    if (c.sourceInfo?.path) haystacks.push(c.sourceInfo.path);
+    if (c.sourceInfo?.baseDir) haystacks.push(c.sourceInfo.baseDir);
+  }
+  for (const t of tools) {
+    if (t.sourceInfo?.path) haystacks.push(t.sourceInfo.path);
+    if (t.sourceInfo?.baseDir) haystacks.push(t.sourceInfo.baseDir);
+  }
+  for (const hint of hints) {
+    const hit = haystacks.find((p) => p.includes(hint));
+    if (hit) return shortenForEvidence(hit);
+  }
+  return undefined;
+}
+
+function safeProbeList<T>(probe: undefined | (() => ReadonlyArray<T>)): readonly T[] {
+  if (typeof probe !== "function") return [];
+  try {
+    const result = probe();
+    return Array.isArray(result) ? result : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Shorten a node_modules path so the evidence row stays readable.
+ * `…/node_modules/pi-subagents/dist/extension.ts` → `pi-subagents/dist/extension.ts`.
+ */
+function shortenForEvidence(p: string): string {
+  const marker = "/node_modules/";
+  const idx = p.lastIndexOf(marker);
+  if (idx >= 0) return p.slice(idx + marker.length);
+  // Some installs (git, local) land under `~/.atomic/extensions/<name>` —
+  // surface the trailing `extensions/<name>/…` segment instead.
+  const extMarker = "/extensions/";
+  const extIdx = p.lastIndexOf(extMarker);
+  if (extIdx >= 0) return p.slice(extIdx + 1);
+  return p;
+}