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

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

@@ -0,0 +1,213 @@
+import { inspectRun } from "../runs/background/status.js";
+import { renderInputsSchema } from "../shared/render-inputs-schema.js";
+import { schemaIsRequired } from "../shared/schema-introspection.js";
+import { store } from "../shared/store.js";
+import type { WorkflowExecutionPolicy } from "../shared/types.js";
+import { emitChatSurface } from "../tui/chat-surface-message.js";
+import { openInlineInputsForm } from "../tui/inline-form-overlay.js";
+import { openInputsPicker } from "../tui/inputs-overlay.js";
+import { deriveGraphTheme } from "../tui/graph-theme.js";
+import { selectRunsForPicker } from "../tui/session-picker.js";
+import type { GraphOverlayPort } from "../tui/overlay-adapter.js";
+import type { ExtensionRuntime } from "./runtime.js";
+import type { WorkflowInputEntry, WorkflowToolResult } from "./render-result.js";
+import type { ExtensionAPI, PiCommandContext, PiArgumentCompletionResult } from "./public-types.js";
+import { workflowArgumentCompletions } from "./workflow-command-completions.js";
+import {
+  createWorkflowCommandReporter,
+  emitWorkflowCommandOutput,
+  formatAvailableWorkflowNames,
+  parseWorkflowArgs,
+  registerWorkflowCommand,
+  tokenizeWorkflowArgs,
+  type WorkflowCommandHandler,
+  type WorkflowCommandOutputDetails,
+} from "./workflow-command-utils.js";
+import { emitTerminalRunDetailSurface } from "./workflow-command-surfaces.js";
+import { handleRunControlCommand, type WorkflowRunControlDeps } from "./workflow-run-control-command.js";
+import { workflowPolicyFromContext } from "./workflow-policy.js";
+import {
+  inFlightRunCount,
+  reloadBlockedMessage,
+  reloadFailureMessage,
+  resolveRunIdPrefix,
+  overlaySurfaceFromContext,
+} from "./workflow-targets.js";
+
+export interface WorkflowSlashCommandDeps {
+  runtimeProxy: ExtensionRuntime;
+  runtimeForContext: (ctx?: PiCommandContext) => ExtensionRuntime;
+  overlay: GraphOverlayPort;
+  reloadWorkflowResources: () => Promise<void> | void;
+  runWithLifecycleSuppressedForPolicy: <T>(
+    policy: WorkflowExecutionPolicy,
+    fn: () => Promise<T>,
+  ) => Promise<T>;
+  runControl: WorkflowRunControlDeps;
+}
+
+export function registerWorkflowSlashCommand(
+  pi: ExtensionAPI,
+  workflowCommands: Map<string, WorkflowCommandHandler>,
+  deps: WorkflowSlashCommandDeps,
+): void {
+  registerWorkflowCommand(
+    pi,
+    "workflow",
+    {
+      description: "Run or inspect Atomic workflows. Usage: /workflow <name> [key=value…] | /workflow [list|status|connect|attach|interrupt|kill|pause|resume|inputs|reload] [args]",
+      handler: (args, ctx) => workflowSlashHandler(args, ctx, pi, deps),
+      getArgumentCompletions: (partial: string): PiArgumentCompletionResult =>
+        workflowArgumentCompletions(partial, deps.runtimeProxy),
+    },
+    workflowCommands,
+  );
+}
+
+async function workflowSlashHandler(
+  args: string,
+  ctx: PiCommandContext,
+  pi: ExtensionAPI,
+  deps: WorkflowSlashCommandDeps,
+): Promise<void> {
+  const policy = workflowPolicyFromContext(ctx);
+  const reporter = createWorkflowCommandReporter(ctx, policy, pi);
+  const print = (msg: string): void => reporter.info(msg);
+  const fail = (msg: string): void => reporter.error(msg);
+  const withImplicitYesFlag = (tokens: string[]): string[] =>
+    tokens.some((t) => t === "--yes" || t === "-y") ? tokens : [...tokens, "-y"];
+  const showWorkflowInputs = async (
+    workflowName: string,
+    command: WorkflowCommandOutputDetails["command"] = "inputs",
+  ): Promise<void> => {
+    const result = await deps.runtimeForContext(ctx).dispatch({ workflow: workflowName, inputs: {}, action: "inputs" }, { policy });
+    if (result.action !== "inputs" || !("inputs" in result)) return;
+    const inputResult = result as Extract<WorkflowToolResult, { action: "inputs" }>;
+    if (inputResult.error) {
+      fail(`${inputResult.error}\nAvailable: ${formatAvailableWorkflowNames(deps.runtimeProxy.registry.names())}`);
+      return;
+    }
+    const schemaText = renderInputsSchema(workflowName, inputResult.inputs, { theme: deriveGraphTheme({}) });
+    if (policy.mode === "non_interactive") emitWorkflowCommandOutput(pi, schemaText, { command, workflowName });
+    else print(schemaText);
+  };
+
+  const parts = tokenizeWorkflowArgs(args);
+  const subcommand = parts[0] ?? "";
+  if (["connect", "attach", "pause", "resume"].includes(subcommand)) {
+    await handleRunControlCommand(subcommand as "connect" | "attach" | "pause" | "resume", parts.slice(1), ctx, reporter, deps.runControl);
+    return;
+  }
+  if (!subcommand || subcommand === "list") {
+    const items = deps.runtimeProxy.registry.all().map((def) => ({
+      name: def.normalizedName,
+      description: def.description,
+      inputs: Object.entries(def.inputs).map(([iname, schema]) => ({
+        name: iname,
+        required: schemaIsRequired(schema),
+      })),
+    }));
+    emitChatSurface(pi, { kind: "list", entries: items });
+    return;
+  }
+  if (subcommand === "status") {
+    const target = parts[1];
+    if (target && !target.startsWith("--")) {
+      const resolved = resolveRunIdPrefix(target);
+      if (resolved.kind === "not_found") return fail(`Run not found: ${target}`);
+      if (resolved.kind === "ambiguous") {
+        return fail(`Ambiguous run prefix "${target}" matches: ${resolved.matches.map((id) => id.slice(0, 12)).join(", ")}`);
+      }
+      const inspected = inspectRun(resolved.runId);
+      if (!inspected.ok) return fail(`Run not found: ${target}`);
+      emitChatSurface(pi, { kind: "detail", detail: inspected.detail });
+      return;
+    }
+    const rows = selectRunsForPicker(store.runs(), "", true, Date.now());
+    emitChatSurface(pi, { kind: "status", runs: rows.map((r) => r.run) });
+    return;
+  }
+  if (subcommand === "reload") {
+    const activeRuns = inFlightRunCount();
+    if (activeRuns > 0) return fail(reloadBlockedMessage(activeRuns));
+    try {
+      await deps.reloadWorkflowResources();
+      print("Reloaded workflow resources.");
+    } catch (error) {
+      fail(reloadFailureMessage(error));
+    }
+    return;
+  }
+  if (subcommand === "interrupt" || subcommand === "kill") {
+    await handleRunControlCommand(subcommand, withImplicitYesFlag(parts.slice(1)), ctx, reporter, deps.runControl);
+    return;
+  }
+  if (subcommand === "inputs") {
+    const workflowName = parts[1] ?? "";
+    if (!workflowName) return fail("Usage: /workflow inputs <name>");
+    await showWorkflowInputs(workflowName);
+    return;
+  }
+
+  const workflowName = subcommand;
+  const inputTokens = parts.slice(1);
+  if (inputTokens.includes("--help")) {
+    await showWorkflowInputs(workflowName, "help");
+    return;
+  }
+  const inputs = parseWorkflowArgs(inputTokens);
+  const wantsPickerSkip = inputTokens.includes("--no-picker");
+  let mergedInputs = inputs;
+  let pickerWasShown = false;
+  const canOpenPicker = policy.allowInputPicker && !wantsPickerSkip && (
+    typeof ctx.ui?.setEditorComponent === "function" || typeof ctx.ui?.custom === "function"
+  );
+  if (canOpenPicker) {
+    const schemaResult = await deps.runtimeForContext(ctx).dispatch({ workflow: workflowName, inputs: {}, action: "inputs" }, { policy });
+    const schema = schemaResult.action === "inputs" && "inputs" in schemaResult
+      ? (schemaResult as Extract<WorkflowToolResult, { action: "inputs" }>)
+      : undefined;
+    const fields = schema?.inputs ?? [];
+    const missingRequired = fields.some((f: WorkflowInputEntry) =>
+      f.required === true && (inputs[f.name] === undefined || (typeof inputs[f.name] === "string" && (inputs[f.name] as string).trim() === "")),
+    );
+    if (fields.length > 0 && (inputTokens.length === 0 || missingRequired)) {
+      pickerWasShown = true;
+      const pickerTheme = deriveGraphTheme({});
+      let pickerResult = typeof ctx.ui?.setEditorComponent === "function"
+        ? await openInlineInputsForm(pi, ctx, { workflowName, fields, prefilled: inputs, theme: pickerTheme })
+        : { kind: "unsupported" as const };
+      if (pickerResult.kind === "unsupported" && typeof ctx.ui?.custom === "function") {
+        pickerResult = await openInputsPicker(ctx.ui, { workflowName, fields, prefilled: inputs, theme: pickerTheme });
+      }
+      if (pickerResult.kind === "cancel") return;
+      if (pickerResult.kind === "run") mergedInputs = pickerResult.values;
+    }
+  }
+
+  const result = await deps.runWithLifecycleSuppressedForPolicy(policy, () =>
+    deps.runtimeForContext(ctx).dispatch({ workflow: workflowName, inputs: mergedInputs, action: "run" }, { policy }),
+  );
+  if (result.action !== "run" || !("runId" in result)) return;
+  const runResult = result as Extract<WorkflowToolResult, { action: "run"; runId: string }>;
+  if (runResult.status === "failed" && runResult.runId === "") {
+    if (runResult.error?.toLowerCase().includes("not found")) {
+      fail(`Workflow not found: ${workflowName}\nAvailable: ${formatAvailableWorkflowNames(deps.runtimeProxy.registry.names())}`);
+    } else {
+      fail(`Workflow "${workflowName}" failed: ${runResult.error ?? "unknown error"}`);
+    }
+    return;
+  }
+  if (runResult.status === "failed") {
+    fail(`Workflow "${workflowName}" failed: ${runResult.error ?? "unknown error"}`);
+    return;
+  }
+  if (policy.mode === "non_interactive") {
+    emitTerminalRunDetailSurface(pi, workflowName, mergedInputs, runResult);
+    return;
+  }
+  emitChatSurface(pi, { kind: "dispatch", workflowName, runId: runResult.runId, inputs: mergedInputs });
+  if (pickerWasShown && typeof ctx.ui?.custom === "function") {
+    deps.overlay.open(runResult.runId, overlaySurfaceFromContext(ctx));
+  }
+}

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

@@ -0,0 +1,81 @@
+import { inspectRun, type RunDetail } from "../runs/background/status.js";
+import type { WorkflowInputValues } from "../shared/types.js";
+import { emitChatSurface } from "../tui/chat-surface-message.js";
+import { renderRunDetail } from "../tui/run-detail.js";
+import type { ConfigLoadResult } from "./config-loader.js";
+import type { DiscoveryResult } from "./discovery.js";
+import type { WorkflowToolResult } from "./render-result.js";
+import type { ExtensionAPI } from "./public-types.js";
+import { isRunStatus } from "./workflow-targets.js";
+
+function fallbackRunDetailFromResult(
+  workflowName: string,
+  inputs: Readonly<WorkflowInputValues>,
+  result: Extract<WorkflowToolResult, { action: "run"; runId: string }>,
+): RunDetail {
+  const now = Date.now();
+  const stages = result.stages?.map((stage) => structuredClone(stage)) ?? [];
+  return {
+    runId: result.runId,
+    name: result.name ?? workflowName,
+    status: isRunStatus(result.status) ? result.status : "failed",
+    mode: stages.length > 1 ? "chain" : "single",
+    startedAt: now,
+    endedAt: now,
+    durationMs: 0,
+    inputs,
+    stages,
+    result: result.result,
+    error: result.error,
+    exited: result.exited,
+    exitReason: result.exitReason,
+  };
+}
+
+export function emitTerminalRunDetailSurface(
+  pi: ExtensionAPI,
+  workflowName: string,
+  inputs: Readonly<WorkflowInputValues>,
+  result: Extract<WorkflowToolResult, { action: "run"; runId: string }>,
+): void {
+  const inspected = inspectRun(result.runId);
+  const detail = inspected.ok
+    ? inspected.detail
+    : fallbackRunDetailFromResult(workflowName, inputs, result);
+  emitChatSurface(pi, { kind: "detail", detail }, { content: renderRunDetail(detail, { width: 100 }) });
+}
+
+export function formatStartupDiagnostics(
+  configResult: ConfigLoadResult | null,
+  discoveryResult: DiscoveryResult | null,
+): string | null {
+  const lines: string[] = [];
+  for (const diagnostic of configResult?.diagnostics ?? []) {
+    lines.push(`- [${diagnostic.level} ${diagnostic.code}] ${diagnostic.source ?? "workflow config"}: ${diagnostic.message}`);
+  }
+  for (const diagnostic of discoveryResult?.errors ?? []) {
+    lines.push(`- [${diagnostic.level} ${diagnostic.code}] ${diagnostic.source ?? "workflow discovery"}: ${diagnostic.message}`);
+  }
+  if (lines.length === 0) return null;
+  const maxVisible = 8;
+  const visible = lines.slice(0, maxVisible);
+  const remaining = lines.length - visible.length;
+  return [
+    `Workflow discovery diagnostics (${lines.length}): some workflow resources were skipped or need attention.`,
+    ...visible,
+    ...(remaining > 0 ? [`- … ${remaining} more`] : []),
+  ].join("\n");
+}
+
+const ASK_USER_QUESTION_TOOL_NAME = "ask_user_question";
+
+export function deAdvertiseAskUserQuestionWhenHeadless(
+  pi: ExtensionAPI,
+  hasUI: boolean | undefined,
+): void {
+  if (hasUI !== false) return;
+  if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
+  const activeTools = pi.getActiveTools();
+  if (!activeTools.includes(ASK_USER_QUESTION_TOOL_NAME)) return;
+  pi.setActiveTools(activeTools.filter((toolName) => toolName !== ASK_USER_QUESTION_TOOL_NAME));
+}

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

@@ -0,0 +1,181 @@
+import type { WorkflowExecutionPolicy, WorkflowInputValues, WorkflowSerializableValue } from "../shared/types.js";
+import type { ExtensionAPI, PiCommandContext, PiCommandOptions } from "./public-types.js";
+import { workflowPolicyFromContext } from "./workflow-policy.js";
+
+export const WORKFLOW_COMMAND_OUTPUT_CUSTOM_TYPE = "workflows:command-output";
+
+export interface WorkflowCommandOutputDetails {
+  readonly command: string;
+  readonly workflowName?: string;
+}
+
+export function emitWorkflowCommandOutput(
+  pi: ExtensionAPI,
+  content: string,
+  details: WorkflowCommandOutputDetails,
+): void {
+  if (typeof pi.sendMessage !== "function") return;
+  void pi.sendMessage<WorkflowCommandOutputDetails>({
+    customType: WORKFLOW_COMMAND_OUTPUT_CUSTOM_TYPE,
+    content,
+    display: true,
+    details,
+  });
+}
+
+export interface WorkflowCommandReporter {
+  info(message: string): void;
+  error(message: string): void;
+}
+
+export function formatAvailableWorkflowNames(names: readonly string[]): string {
+  return names.length > 0 ? names.join(", ") : "(none)";
+}
+
+export class WorkflowHeadlessCommandError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "WorkflowHeadlessCommandError";
+  }
+}
+
+export function createWorkflowCommandReporter(
+  ctx: PiCommandContext,
+  policy: WorkflowExecutionPolicy = workflowPolicyFromContext(ctx),
+  pi?: ExtensionAPI,
+): WorkflowCommandReporter {
+  return {
+    info(message: string): void {
+      if (policy.mode === "non_interactive") {
+        if (pi) emitWorkflowCommandOutput(pi, message, { command: "message" });
+        return;
+      }
+      ctx.ui.notify(message, "info");
+    },
+    error(message: string): void {
+      if (policy.mode === "non_interactive") throw new WorkflowHeadlessCommandError(message);
+      ctx.ui.notify(message, "error");
+    },
+  };
+}
+
+export type WorkflowCommandHandler = PiCommandOptions["handler"];
+
+interface ParsedWorkflowSlashCommand {
+  name: string;
+  args: string;
+}
+
+function parseWorkflowSlashCommand(text: string): ParsedWorkflowSlashCommand | undefined {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("/")) return undefined;
+  const firstSpace = trimmed.indexOf(" ");
+  const name = firstSpace === -1 ? trimmed.slice(1) : trimmed.slice(1, firstSpace);
+  const args = firstSpace === -1 ? "" : trimmed.slice(firstSpace + 1);
+  return { name, args };
+}
+
+export function registerWorkflowCommand(
+  pi: ExtensionAPI,
+  name: string,
+  options: PiCommandOptions,
+  registry: Map<string, WorkflowCommandHandler>,
+): void {
+  pi.registerCommand?.(name, options);
+  registry.set(name, options.handler);
+}
+
+export function installInputInterceptor(
+  pi: ExtensionAPI,
+  commands: Map<string, WorkflowCommandHandler>,
+): void {
+  if (typeof pi.on !== "function") return;
+  pi.on("input", async (event, ctx) => {
+    const text = (event as { text?: unknown } | undefined)?.text;
+    if (typeof text !== "string") return undefined;
+    const parsedCommand = parseWorkflowSlashCommand(text);
+    if (!parsedCommand) return undefined;
+    const { name, args } = parsedCommand;
+    const handler = commands.get(name);
+    if (!handler) return undefined;
+    const commandCtx = ctx as PiCommandContext;
+    try {
+      await handler(args, commandCtx);
+    } catch (err) {
+      if (commandCtx.hasUI === false) throw err;
+      const message = err instanceof Error ? err.message : String(err);
+      commandCtx.ui.notify(`/${name} failed: ${message}`, "error");
+    }
+    return { action: "handled" };
+  });
+}
+
+export function stripYesFlag(tokens: string[]): {
+  tokens: string[];
+  yes: boolean;
+} {
+  const yes = tokens.some((t) => t === "--yes" || t === "-y");
+  return { tokens: tokens.filter((t) => t !== "--yes" && t !== "-y"), yes };
+}
+
+export function tokenizeWorkflowArgs(args: string): string[] {
+  const tokens: string[] = [];
+  let buf = "";
+  let quote: '"' | "'" | undefined;
+  let hasBuf = false;
+  for (let i = 0; i < args.length; i++) {
+    const ch = args[i]!;
+    if (quote !== undefined) {
+      buf += ch;
+      if (ch === quote) quote = undefined;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      buf += ch;
+      hasBuf = true;
+      quote = ch;
+      continue;
+    }
+    if (ch === " " || ch === "\t" || ch === "\n" || ch === "\r") {
+      if (hasBuf) {
+        tokens.push(buf);
+        buf = "";
+        hasBuf = false;
+      }
+      continue;
+    }
+    buf += ch;
+    hasBuf = true;
+  }
+  if (hasBuf) tokens.push(buf);
+  return tokens;
+}
+
+export function parseWorkflowArgs(tokens: string[]): WorkflowInputValues {
+  const result: Record<string, WorkflowSerializableValue> = {};
+  for (const token of tokens) {
+    if (
+      (token.startsWith("{") && token.endsWith("}")) ||
+      (token.startsWith("[") && token.endsWith("]"))
+    ) {
+      try {
+        const parsed = JSON.parse(token) as unknown;
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+          Object.assign(result, parsed as WorkflowInputValues);
+        }
+        continue;
+      } catch {}
+    }
+    const eqIdx = token.indexOf("=");
+    if (eqIdx > 0) {
+      const key = token.slice(0, eqIdx);
+      const raw = token.slice(eqIdx + 1);
+      let value: WorkflowSerializableValue = raw;
+      try {
+        value = JSON.parse(raw) as WorkflowSerializableValue;
+      } catch {}
+      result[key] = value;
+    }
+  }
+  return result;
+}

package/dist/builtin/workflows/src/extension/workflow-module-loader.ts

@@ -7,8 +7,9 @@
  */
 
 import { createJiti } from "jiti/static";
+import * as typeboxModule from "typebox";
 import * as workflowsSdkSurface from "../sdk-surface.js";
-import { isBrandedWorkflowDefinition } from "../workflows/define-workflow.js";
+import { isBrandedWorkflowDefinition } from "../authoring/workflow.js";
 import deepResearchCodebase from "../../builtin/deep-research-codebase.js";
 import goal from "../../builtin/goal.js";
 import openClaudeDesign from "../../builtin/open-claude-design.js";
@@ -16,6 +17,7 @@ import ralph from "../../builtin/ralph.js";
 
 const WORKFLOWS_MODULE_SPECIFIER = "@bastani/workflows";
 const WORKFLOWS_BUILTIN_MODULE_SPECIFIER = `${WORKFLOWS_MODULE_SPECIFIER}/builtin`;
+const TYPEBOX_MODULE_SPECIFIER = "typebox";
 // Keep this in sync with index.ts through sdk-surface.ts.
 const WORKFLOWS_SDK_MODULE: Record<string, unknown> = {
   ...workflowsSdkSurface,
@@ -26,9 +28,13 @@ const WORKFLOWS_BUILTIN_MODULE: Record<string, unknown> = {
   openClaudeDesign,
   ralph,
 };
+const TYPEBOX_MODULE: Record<string, unknown> = {
+  ...typeboxModule,
+};
 const WORKFLOWS_VIRTUAL_MODULES: Record<string, unknown> = {
   [WORKFLOWS_MODULE_SPECIFIER]: WORKFLOWS_SDK_MODULE,
   [WORKFLOWS_BUILTIN_MODULE_SPECIFIER]: WORKFLOWS_BUILTIN_MODULE,
+  [TYPEBOX_MODULE_SPECIFIER]: TYPEBOX_MODULE,
   [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/deep-research-codebase`]: { default: deepResearchCodebase },
   [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/goal`]: { default: goal },
   [`${WORKFLOWS_BUILTIN_MODULE_SPECIFIER}/open-claude-design`]: { default: openClaudeDesign },
@@ -95,10 +101,10 @@ export function validateWorkflowDefinitionShape(value: unknown): string | null {
   const d = value as Record<string, unknown>;
 
   if (d["__piWorkflow"] !== true) {
-    return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from defineWorkflow(...).compile()";
+    return "missing or incorrect __piWorkflow sentinel (expected true); export a workflow from workflow({...})";
   }
   if (!isBrandedWorkflowDefinition(value)) {
-    return "workflow definition is not produced by defineWorkflow(...).compile(); hand-rolled __piWorkflow objects are not supported";
+    return "workflow definition is not produced by workflow({...}); hand-rolled __piWorkflow objects are not supported";
   }
   if (typeof d["name"] !== "string" || (d["name"] as string).trim().length === 0) {
     return "name must be a non-empty string";

package/dist/builtin/workflows/src/extension/workflow-policy.ts

@@ -0,0 +1,15 @@
+import {
+  INTERACTIVE_WORKFLOW_POLICY,
+  NON_INTERACTIVE_WORKFLOW_POLICY,
+  type WorkflowExecutionPolicy,
+} from "../shared/types.js";
+
+export const WORKFLOW_NON_INTERACTIVE_MESSAGE =
+  "Workflows are policy-gated in non-interactive (-p) mode; deterministic workflows can run headlessly while runtime human input remains unavailable.";
+
+export function workflowPolicyFromContext(ctx?: {
+  readonly hasUI?: boolean;
+}): WorkflowExecutionPolicy {
+  if (ctx?.hasUI === false) return NON_INTERACTIVE_WORKFLOW_POLICY;
+  return INTERACTIVE_WORKFLOW_POLICY;
+}

package/dist/builtin/workflows/src/extension/workflow-ports.ts

@@ -0,0 +1,41 @@
+import type { WorkflowMcpPort, WorkflowPersistencePort } from "../shared/types.js";
+import { clearMcpScope, setMcpScope, type PiEventBus, type PiMcpExtensionAPI } from "./mcp.js";
+import type { ExtensionAPI } from "./public-types.js";
+
+export function makePersistencePort(
+  pi: ExtensionAPI,
+  persistRuns: boolean,
+): WorkflowPersistencePort | undefined {
+  if (!persistRuns) return undefined;
+  if (typeof pi.appendEntry !== "function") return undefined;
+  const port: WorkflowPersistencePort = {
+    appendEntry: (type, payload) => pi.appendEntry!(type, payload),
+  };
+  if (typeof pi.setLabel === "function") {
+    port.setLabel = (entryId, label) => pi.setLabel!(entryId, label);
+  }
+  if (typeof pi.appendCustomMessageEntry === "function") {
+    port.appendCustomMessageEntry = (content, meta) =>
+      pi.appendCustomMessageEntry!(content, meta);
+  }
+  return port;
+}
+
+export function makeMcpPort(pi: ExtensionAPI): WorkflowMcpPort | undefined {
+  if (typeof pi.events?.emit !== "function") return undefined;
+  const piForMcp: PiMcpExtensionAPI = {
+    events: { emit: pi.events.emit as PiEventBus["emit"] },
+  };
+  return {
+    setScope(stageId: string, allow: string[] | null, deny: string[] | null) {
+      setMcpScope(piForMcp, {
+        stageId,
+        allow: allow ?? undefined,
+        deny: deny ?? undefined,
+      });
+    },
+    clearScope(stageId: string) {
+      clearMcpScope(piForMcp, stageId);
+    },
+  };
+}

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -0,0 +1,23 @@
+export const WORKFLOW_TOOL_DESCRIPTION =
+  "Run named workflows or direct one-off task/tasks/chain workflows; " +
+  "discover with list/get/inputs, inspect status/stages/stage details, " +
+  "send prompt answers or steering, pause/resume/interrupt/kill runs, and reload workflow resources. " +
+  "For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
+  "For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
+  "quote the exact path without rewriting separators (Windows backslashes are valid), " +
+  "then search it with rg/grep and read small ranges; transcript is path-only by default when sessionFile/transcriptPath exists, explicit tail/limit returns bounded previews, and missing transcript paths fall back to a small preview.";
+
+export const DEFAULT_PROMPT_GUIDANCE: string[] = [
+  `**Workflows**: Use the \`workflow\` tool for existing named workflows and for repeatable, inspectable, resumable, or multi-stage processes; use direct \`task\`, \`tasks\`, or \`chain\` workflow calls for one-off tracked work when that is useful.
+  - For unfamiliar named workflows, discover with \`action: "list"\`, inspect with \`action: "get"\` or \`action: "inputs"\`, and run with \`action: "run"\`, \`workflow\`, and validated \`inputs\`; do not invent workflow names or input keys.
+  - When designing or editing workflows, read docs/workflows.md and reference its Workflow Starter Patterns: Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, and Loop until done. Choose or combine these patterns before inventing a custom stage graph, and reflect the selected pattern in the spec and Mermaid diagram when using the create-spec skill.
+  - Once you run a workflow with the workflow tool, end your current turn and wait for the next user input or lifecycle notice.
+    - You will automatically be alerted of key lifecycle events like start, finish, failure; do not micro-manage the run with sleep/status polling loops or read its logs/stages unless the user asks you to or you need information for the next step.
+    - If the user needs information from the workflow run, use targeted \`status\`/\`stages\`/\`stage\` checks instead of trying to read everything.
+    - Offer to help the user on another task instead of anxiously polling or help the user run another workflow if they need.
+    - Use run-control and messaging actions (\`send\`, \`pause\`, \`resume\`, \`interrupt\`, \`kill\`) only when needed to answer prompts, steer a stage, resume or interrupt paused work, or respond to user requests/control signals.
+  - For transcripts, avoid reading whole session transcripts at once. Use \`stages\` or \`stage\` to get \`sessionFile\`/\`transcriptPath\`, quote the exact path without rewriting separators (preserve Windows backslashes), search it with \`rg\`/\`grep\`, and read small relevant ranges; use \`transcript\` with explicit \`tail\` or \`limit\` only for quick recent-context checks.
+  - If a user asks to create or edit a workflow, use the create-spec skill when available and ask detailed clarifying questions until you understand its purpose, inputs, stages, handoffs, validation, success criteria, and selected starter pattern. Then read the workflow docs/examples and implement the workflow from the created spec directly as a TypeScript definition. After you implement the workflow, reload it to access it and run it with test inputs to validate it works as intended before presenting it to the user.
+    - Tip: when designing workflows, implement it in a way that you pass information from stage to stage by writing it to a file or artifact (either deterministic or model-driven), pass the path with \`reads\`, and explicitly prompt the downstream agent with wording like \`Read the file at <path>...\`; do not inject large \`previous\` payloads or session history into the next prompt unless explicitly requested to.
+  - If you run \`ralph\` or \`goal\` workflow, define an objective that includes tight scope, concrete and verifiable done criteria, and validation steps; then monitor progress as above instead of doing parallel implementation yourself.`,
+];