@bastani/atomic 0.7.17-1 → 0.8.0-0

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

@@ -0,0 +1,110 @@
+/**
+ * MCP cooperation helpers.
+ *
+ * Responsibilities:
+ *  1. Per-stage server gating: emit `mcp.scope.set` via pi.events so the
+ *     host MCP layer can restrict visible MCP servers while a stage runs.
+ *  2. Always clear scope after stage completion/failure.
+ *
+ * NOTE: This is intentionally event-based. Hosts without `mcp.scope.set`
+ * listeners simply ignore the event, so stage execution remains functional
+ * without a bundled MCP adapter dependency.
+ */
+
+// ---------------------------------------------------------------------------
+// Minimal structural types — no hard imports from host MCP internals
+// ---------------------------------------------------------------------------
+
+/** Minimal pi events bus surface used by this module. */
+export interface PiEventBus {
+  emit: (event: string, payload: Record<string, unknown>) => void;
+}
+
+/** Minimal ExtensionAPI surface expected by mcp integration. */
+export interface PiMcpExtensionAPI {
+  events?: PiEventBus;
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Scope types
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-stage MCP server gating config.
+ * Mirrors the stage-level `mcpServers` declaration in a workflow definition.
+ */
+export interface McpScopeOpts {
+  /**
+   * Stage ID scoping this restriction. The adapter may use this to
+   * namespace the scope so concurrent stages don't interfere.
+   */
+  stageId: string;
+  /**
+   * Server IDs to allow exclusively. When provided, all other servers are
+   * implicitly denied for this stage.
+   */
+  allow?: string[];
+  /**
+   * Server IDs to deny explicitly. Applied after `allow` when both present.
+   */
+  deny?: string[];
+}
+
+/** Payload shape emitted on `mcp.scope.set`. */
+export interface McpScopeSetPayload {
+  stageId: string;
+  allow: string[] | null;
+  deny: string[] | null;
+}
+
+// ---------------------------------------------------------------------------
+// Scope helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Emits `mcp.scope.set` so the host MCP layer can restrict MCP server access
+ * for the named stage. No-op when `pi.events` is absent or when the host has
+ * no scope listener.
+ *
+ * Usage:
+ *   setMcpScope(pi, { stageId, allow: ["github", "fetch"], deny: ["filesystem"] });
+ */
+export function setMcpScope(pi: PiMcpExtensionAPI, opts: McpScopeOpts): void {
+  if (!pi.events) return;
+
+  const payload: McpScopeSetPayload = {
+    stageId: opts.stageId,
+    allow: opts.allow ?? null,
+    deny: opts.deny ?? null,
+  };
+
+  pi.events.emit("mcp.scope.set", payload as unknown as Record<string, unknown>);
+}
+
+/**
+ * Emits `mcp.scope.set` with null allow/deny to restore unrestricted access
+ * after a stage completes. No-op when `pi.events` is absent.
+ *
+ * Usage:
+ *   clearMcpScope(pi, stageId);
+ */
+export function clearMcpScope(pi: PiMcpExtensionAPI, stageId: string): void {
+  if (!pi.events) return;
+
+  const payload: McpScopeSetPayload = {
+    stageId,
+    allow: null,
+    deny: null,
+  };
+
+  pi.events.emit("mcp.scope.set", payload as unknown as Record<string, unknown>);
+}
+
+/**
+ * Returns `true` if MCP scope gating is supported (pi.events present).
+ * When false, per-stage server restrictions silently have no effect.
+ */
+export function isMcpScopeSupported(pi: PiMcpExtensionAPI): boolean {
+  return pi.events !== undefined && pi.events !== null;
+}

package/dist/builtin/workflows/src/extension/render-call.ts

@@ -0,0 +1,39 @@
+/**
+ * Render the workflow tool call as a compact string for display in chat.
+ * cross-ref: pi-subagents src/extension/index.ts renderCall slot
+ */
+
+export interface WorkflowToolArgs {
+  workflow?: string;
+  inputs?: Record<string, unknown>;
+  action?: "run" | "list" | "get" | "status" | "interrupt" | "resume" | "inputs";
+  runId?: string;
+}
+
+/**
+ * Returns a compact human-readable string describing the tool invocation.
+ * Used in the renderCall slot of the workflow tool registration.
+ */
+export function renderCall(args: WorkflowToolArgs): string {
+  const action = args.action ?? "run";
+  const name = args.workflow ?? args.runId ?? "(unnamed)";
+
+  switch (action) {
+    case "list":
+      return "workflow: list registered workflows";
+    case "status":
+      return "workflow: list in-flight runs";
+    case "inputs":
+      return `workflow: show inputs for "${name}"`;
+    case "run":
+      return `workflow: run "${name}"`;
+    case "interrupt":
+      return `workflow: interrupt run "${name}"`;
+    case "resume":
+      return `workflow: resume run "${name}"`;
+    case "get":
+      return `workflow: get "${name}"`;
+    default:
+      return `workflow: ${action} "${name}"`;
+  }
+}

package/dist/builtin/workflows/src/extension/render-result.ts

@@ -0,0 +1,214 @@
+/**
+ * Render the workflow tool result for chat / LLM-tool surfaces.
+ *
+ * Rich background-workflow surfaces (status list, per-run detail) delegate
+ * to the canonical Catppuccin renderers in `src/tui/`. Compact one-liners
+ * (list/run/interrupt/resume) stay inline here.
+ *
+ * cross-ref:
+ *  - src/tui/status-list.ts  band-header status list
+ *  - src/tui/run-detail.ts   per-run detail block
+ *  - pi-subagents src/extension/index.ts renderResult slot
+ */
+
+import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
+import type { WorkflowDetails } from "../shared/types.js";
+import type { RunDetail } from "../runs/background/status.js";
+import { renderInputsSchema } from "../shared/render-inputs-schema.js";
+import { renderStatusList } from "../tui/status-list.js";
+import { renderRunDetail } from "../tui/run-detail.js";
+import { renderWorkflowList } from "../tui/workflow-list.js";
+import { deriveGraphTheme } from "../tui/graph-theme.js";
+
+// ---------------------------------------------------------------------------
+// Result variants
+// ---------------------------------------------------------------------------
+
+/* WorkflowRunEntry — removed. The status surface now consumes the
+ * canonical `RunSnapshot` shape directly; the intermediate `runs` projection
+ * is gone. */
+
+export interface WorkflowInputEntry {
+  name: string;
+  type: string;
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+  /**
+   * Allowed values when `type` is `"select"` — surfaces in the picker as a
+   * radio row and in the pretty inputs listing as a `values:` line.
+   */
+  choices?: readonly string[];
+  /** Optional hint shown when the field is empty in the interactive picker. */
+  placeholder?: string;
+}
+
+/**
+ * One entry per registered workflow, sourced from the live registry.
+ * Carries the metadata the catalogue surface needs.
+ */
+export interface WorkflowListItem {
+  name: string;
+  description: string;
+  inputs: ReadonlyArray<{ name: string; required?: boolean }>;
+}
+type ListResult = {
+  action: "list";
+  items: WorkflowListItem[];
+};
+type StatusResult = {
+  action: "status";
+  /** Live snapshots from the in-process store. */
+  snapshots: RunSnapshot[];
+};
+type StatusDetailResult =
+  | {
+      action: "statusDetail";
+      runId: string;
+      detail: RunDetail;
+    }
+  | {
+      action: "statusDetail";
+      runId: string;
+      error: string;
+    };
+type InputsResult = { action: "inputs"; name: string; inputs: WorkflowInputEntry[]; error?: string };
+type GetResult = {
+  action: "get";
+  workflow: string;
+  details?: WorkflowDetails;
+  error?: string;
+};
+type RunResult = {
+  action: "run";
+  name?: string;
+  runId: string;
+  status: string;
+  result?: Record<string, unknown>;
+  details?: WorkflowDetails;
+  error?: string;
+  stages?: StageSnapshot[];
+  /**
+   * Free-form message carried by the result. Carries the "started in
+   * background" copy emitted by `runDetached()`; foreground-completion
+   * results don't set this since `error`/`stages` cover them.
+   */
+  message?: string;
+};
+type InterruptResult = { action: "interrupt"; runId: string; status: string; message: string };
+type ResumeResult = { action: "resume"; runId: string; status: string; message: string };
+
+export type WorkflowToolResult =
+  | ListResult
+  | StatusResult
+  | StatusDetailResult
+  | InputsResult
+  | GetResult
+  | RunResult
+  | InterruptResult
+  | ResumeResult;
+
+export interface RenderResultOpts {
+  isPartial?: boolean;
+  /**
+   * Suppress ANSI colour output (CLI flag paths / non-TTY consumers).
+   * When false/undefined the canonical Catppuccin chrome is rendered.
+   */
+  plain?: boolean;
+}
+
+/**
+ * Returns a human-readable string describing the tool result. Multi-line
+ * rich blocks for `status` / `statusDetail`; compact one-liners for the
+ * remaining variants.
+ *
+ * Note: type assertions inside each `case` arm are required because the
+ * fallback default below (`{ action: string }`) prevents TypeScript from
+ * narrowing the union via `switch (result.action)`.
+ */
+export function renderResult(result: WorkflowToolResult, opts?: RenderResultOpts): string {
+  const partial = opts?.isPartial === true;
+  const themed = opts?.plain !== true;
+
+  switch (result.action) {
+    case "list": {
+      const r = result as ListResult;
+      return renderWorkflowList(r.items, {
+        theme: themed ? deriveGraphTheme({}) : undefined,
+      });
+    }
+
+    case "status": {
+      const r = result as StatusResult;
+      return renderStatusList(r.snapshots, {
+        theme: themed ? deriveGraphTheme({}) : undefined,
+      });
+    }
+
+    case "statusDetail": {
+      if ("error" in result) {
+        const r = result as Extract<StatusDetailResult, { error: string }>;
+        return `workflow status id=${r.runId}: ${r.error}`;
+      }
+      const r = result as Extract<StatusDetailResult, { detail: RunDetail }>;
+      return renderRunDetail(r.detail, {
+        theme: themed ? deriveGraphTheme({}) : undefined,
+      });
+    }
+
+    case "inputs": {
+      const r = result as InputsResult;
+      return renderInputsSchema(r.name, r.inputs);
+    }
+
+    case "get": {
+      const r = result as GetResult;
+      if (r.error) return `workflow get (${r.workflow}): ${r.error}`;
+      const output = r.details?.output;
+      const description = typeof output?.["description"] === "string" ? ` — ${output["description"]}` : "";
+      return `workflow get (${r.workflow}): ${r.details?.status ?? "completed"}${description}`;
+    }
+
+    case "run": {
+      const r = result as RunResult;
+      if (partial) return `workflow run ${r.runId}: ${r.status} (in progress…)`;
+      if (r.status === "failed" && !r.runId) {
+        // Not-found path — render the error verbatim, no fake runId banner.
+        const label = r.name ? ` (${r.name})` : "";
+        return `workflow run${label}: ${r.error ?? "workflow not found"}`;
+      }
+      if (r.error) {
+        const label = r.name ? ` (${r.name})` : "";
+        return `workflow run ${r.runId}${label}: ${r.status} — ${r.error}`;
+      }
+      if (r.details) {
+        const label = r.name ? ` (${r.name})` : "";
+        return `workflow run ${r.runId}${label}: ${r.details.mode} ${r.details.status}`;
+      }
+      if (r.status === "completed" || r.status === "killed") {
+        const label = r.name ? ` (${r.name})` : "";
+        return `workflow run ${r.runId}${label}: ${r.status}`;
+      }
+      // Background dispatch — `runDetached()` returns status "running" and
+      // a message; the workflow surfaces progress via store / overlay.
+      const label = r.name ? ` (${r.name})` : "";
+      return `workflow run ${r.runId}${label}: started in background — ${r.message ?? r.status}`;
+    }
+
+    case "interrupt": {
+      const r = result as InterruptResult;
+      return `workflow interrupt ${r.runId}: ${r.message}`;
+    }
+
+    case "resume": {
+      const r = result as ResumeResult;
+      return `workflow resume ${r.runId}: ${r.message}`;
+    }
+
+    default: {
+      // Runtime guard — handles values coerced from external sources.
+      const fallback = result as { action: string; message?: string };
+      return `workflow: ${fallback.message ?? JSON.stringify(result)}`;
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Stub message renderers for workflow lifecycle events.
+ * Registered via pi.registerMessageRenderer for each event type.
+ *
+ * Renderers return compact strings suitable for inline chat display.
+ * Full TUI graph engine integration is a later phase (§5.4).
+ *
+ * cross-ref: spec §5.6 Persistence renderers (registration only)
+ */
+
+// ---------------------------------------------------------------------------
+// Entry payload shapes (matches pi.appendEntry call signatures from §5.6)
+// ---------------------------------------------------------------------------
+
+export interface RunStartPayload {
+  runId: string;
+  name: string;
+  inputs?: Record<string, unknown>;
+  ts?: number;
+}
+
+export interface StageStartPayload {
+  runId: string;
+  stageId: string;
+  name: string;
+  parentIds?: string[];
+  model?: string;
+  ts?: number;
+}
+
+export interface StageProgressPayload {
+  runId: string;
+  stageId: string;
+  kind: string;
+  payload?: unknown;
+}
+
+export interface StageEndPayload {
+  runId: string;
+  stageId: string;
+  status: "ok" | "error" | "killed" | string;
+  durationMs?: number;
+  summary?: string;
+}
+
+export interface RunEndPayload {
+  runId: string;
+  status: "ok" | "error" | "killed" | string;
+  result?: Record<string, unknown>;
+  ts?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Renderer functions (stub — full TUI graph engine is Phase C/D)
+// ---------------------------------------------------------------------------
+
+/** Render workflow.run.start entry. */
+export function renderRunBanner(payload: RunStartPayload): string {
+  const inputCount = payload.inputs ? Object.keys(payload.inputs).length : 0;
+  const inputNote = inputCount > 0 ? ` (${inputCount} input${inputCount !== 1 ? "s" : ""})` : "";
+  return `▶ workflow "${payload.name}" started [${payload.runId}]${inputNote}`;
+}
+
+/** Render workflow.stage.start entry. */
+export function renderStageChip(payload: StageStartPayload): string {
+  const model = payload.model ? ` via ${payload.model}` : "";
+  return `  ○ stage "${payload.name}"${model} started`;
+}
+
+/** Render workflow.stage.progress entry. */
+export function renderStageProgress(payload: StageProgressPayload): string {
+  return `  … stage progress [${payload.stageId}] ${payload.kind}`;
+}
+
+/** Render workflow.stage.end entry. */
+export function renderStageResult(payload: StageEndPayload): string {
+  const icon = payload.status === "ok" ? "✓" : "✗";
+  const dur = payload.durationMs !== undefined ? ` (${payload.durationMs}ms)` : "";
+  const summary = payload.summary ? `: ${payload.summary}` : "";
+  return `  ${icon} stage [${payload.stageId}] ${payload.status}${dur}${summary}`;
+}
+
+/** Render workflow.run.end entry. */
+export function renderRunSummary(payload: RunEndPayload): string {
+  const icon = payload.status === "ok" ? "✅" : "❌";
+  return `${icon} workflow [${payload.runId}] ${payload.status}`;
+}