pi-workflow-engine 0.4.0 → 0.5.0

package/.pi/extensions/pi-workflow-engine/index.ts

@@ -4,6 +4,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 import { Text } from "@earendil-works/pi-tui";
 import type { WorkflowModule, WorkflowRunOptions } from "./src/types.ts";
 import type { PerfSink, PerfSnapshot } from "./src/perf.ts";
+import { registerDynamax } from "./src/dynamax.ts";
 import { isWorkflowResult, renderWorkflowResult, type WorkflowPerfDetails, type WorkflowResultEnvelope } from "./src/ui/workflow-result-renderer.ts";
 
 /** Extension root (this file lives in <repo>/.pi/extensions/pi-workflow-engine/index.ts). */
@@ -38,6 +39,7 @@ function formatPerfLine(perf: WorkflowPerfDetails | undefined): string | undefin
 
 type DiscoveryModule = typeof import("./src/discovery.ts");
 type EngineModule = typeof import("./src/engine.ts");
+type InlineWorkflowModule = typeof import("./src/inline-workflow.ts");
 
 async function loadDiscovery(): Promise<DiscoveryModule> {
   return await import("./src/discovery.ts");
@@ -47,6 +49,10 @@ async function loadEngine(): Promise<EngineModule> {
   return await import("./src/engine.ts");
 }
 
+async function loadInlineWorkflow(): Promise<InlineWorkflowModule> {
+  return await import("./src/inline-workflow.ts");
+}
+
 async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSink | undefined> {
   const enabled = options.perf ?? process.env.PI_WORKFLOW_PERF === "1";
   if (!enabled) return undefined;
@@ -54,11 +60,14 @@ async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSi
   return createPerfRecorder(true);
 }
 
+const AUTHOR_TEMP_WORKFLOW_CHOICE = "✍ Author temporary one-shot workflow…";
+
 export interface WorkflowInvocation {
   name: string;
   args: string;
   options: WorkflowRunOptions;
   refreshDiscovery?: boolean;
+  authorBrief?: string;
 }
 
 export function parseWorkflowInvocation(input: string): WorkflowInvocation {
@@ -120,14 +129,77 @@ function parseNumericOption(value: string | undefined): number | undefined {
   return Number.isFinite(parsed) ? parsed : undefined;
 }
 
+function compactInlinePreview(script: string | undefined): string {
+  if (!script) return "";
+  const compact = script.replace(/\s+/g, " ").trim();
+  return compact.length > 60 ? `${compact.slice(0, 57)}…` : compact;
+}
+
+export function buildTemporaryWorkflowAuthorPrompt(brief: string): string {
+  return `dynamax author and run a temporary one-shot inline workflow.
+
+User brief:
+${brief.trim()}
+
+Use the workflow tool with a script argument, not a saved workflow name.
+The script must start with export const meta = { ... } and default-export an async workflow function.
+Use the injected Type object for schemas. Do not import anything or use dynamic import().
+Set thinkingLevel explicitly on each agent() call.
+Do not edit files unless the user explicitly requested edits.`;
+}
+
+export interface WorkflowToolRequestParams {
+  readonly name?: string;
+  readonly script?: string;
+}
+
+export type WorkflowToolRequest =
+  | { readonly kind: "named"; readonly name: string }
+  | { readonly kind: "inline"; readonly script: string }
+  | { readonly kind: "error"; readonly error: "invalid_workflow_invocation"; readonly message: string };
+
+export interface WorkflowToolErrorResult {
+  readonly content: Array<{ readonly type: "text"; readonly text: string }>;
+  readonly details: { readonly error: "invalid_workflow_invocation" } | { readonly error: "inline_compile_error"; readonly message: string };
+}
+
+const INVALID_WORKFLOW_INVOCATION_MESSAGE = "Provide exactly one workflow name or inline workflow script.";
+
+export function normalizeWorkflowToolRequest(params: WorkflowToolRequestParams): WorkflowToolRequest {
+  const name = params.name?.trim() ?? "";
+  const script = params.script?.trim() ?? "";
+  const hasName = name.length > 0;
+  const hasScript = script.length > 0;
+  if (hasName === hasScript) return { kind: "error", error: "invalid_workflow_invocation", message: INVALID_WORKFLOW_INVOCATION_MESSAGE };
+  return hasName ? { kind: "named", name } : { kind: "inline", script };
+}
+
+export function invalidWorkflowInvocationResult(): WorkflowToolErrorResult {
+  return { content: [{ type: "text", text: INVALID_WORKFLOW_INVOCATION_MESSAGE }], details: { error: "invalid_workflow_invocation" } };
+}
+
+export function inlineCompileErrorResult(message: string): WorkflowToolErrorResult {
+  return { content: [{ type: "text", text: `Inline workflow did not compile: ${message}` }], details: { error: "inline_compile_error", message } };
+}
+
 async function pickWorkflow(
   workflows: ReadonlyMap<string, WorkflowModule>,
   ctx: ExtensionCommandContext,
 ): Promise<WorkflowInvocation | undefined> {
-  const choices = [...workflows.values()].map((mod) => `${mod.meta.name} — ${mod.meta.description}`);
+  const choices = [AUTHOR_TEMP_WORKFLOW_CHOICE, ...[...workflows.values()].map((mod) => `${mod.meta.name} — ${mod.meta.description}`)];
   const choice = await ctx.ui.select("Run workflow", choices);
   if (!choice) return undefined;
 
+  if (choice === AUTHOR_TEMP_WORKFLOW_CHOICE) {
+    const brief = await ctx.ui.editor(
+      "Describe temporary workflow",
+      "Goal:\n\nAgents to run:\n- \n\nFinal output should include:\n- summary\n- findings\n- next steps\n",
+    );
+    const trimmed = brief?.trim();
+    if (!trimmed) return undefined;
+    return { name: "", args: "", options: {}, authorBrief: trimmed };
+  }
+
   const separator = choice.indexOf(" — ");
   const name = separator === -1 ? choice : choice.slice(0, separator);
   const args = name === "code-review" ? (await ctx.ui.input("Code-review target/instructions", "Blank = auto-detect diff"))?.trim() ?? "" : "";
@@ -163,6 +235,8 @@ async function sendWorkflowResult(
 }
 
 export default function workflowEngine(pi: ExtensionAPI): void {
+  registerDynamax(pi);
+
   pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) => {
     const details = message.details;
     if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
@@ -185,6 +259,11 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         return;
       }
 
+      if (invocation.authorBrief) {
+        pi.sendUserMessage(buildTemporaryWorkflowAuthorPrompt(invocation.authorBrief));
+        return;
+      }
+
       const mod = workflows.get(invocation.name);
       if (!mod) {
         ctx.ui.notify(`Unknown workflow "${invocation.name}". Available: ${available}`, "error");
@@ -200,9 +279,18 @@ export default function workflowEngine(pi: ExtensionAPI): void {
     name: "workflow",
     label: "Workflow",
     description:
-      "Run a named multi-agent workflow (fan-out → verify → synthesize) and return its structured result. Use for thorough reviews or audits.",
+      "ONLY call workflow when the user opted into multi-agent orchestration via the literal token `dynamax`, sticky `/dynamax on`, an explicit request to run or author a workflow, or a command/skill instruction. Runs either a registered named workflow or an inline one-off workflow script (fan-out → verify → synthesize) and returns its structured result.",
+    promptSnippet: "Run an existing named workflow or an inline one-off workflow script",
+    promptGuidelines: [
+      "Use workflow only when the user opted into workflow orchestration via `dynamax`, `/dynamax on`, an explicit request to run/author a workflow, or a command/skill instruction.",
+      "Use workflow with `name` for existing registered workflows such as code-review, diagnose, refactor-scout, or perf-review.",
+      "Use workflow with `script` for a new one-off inline workflow; the script must start with `export const meta = { ... }` and default-export an async workflow function.",
+      "Inline workflow scripts must use the injected `Type` object for schemas and must not contain imports or dynamic import().",
+      "Every workflow tool call must provide exactly one of `name` or `script`, never both.",
+    ],
     parameters: Type.Object({
-      name: Type.String({ description: "Workflow name, e.g. code-review" }),
+      name: Type.Optional(Type.String({ description: "Workflow name, e.g. code-review. Provide exactly one of name or script." })),
+      script: Type.Optional(Type.String({ description: "Inline workflow script. Provide exactly one of script or name." })),
       args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
       concurrency: Type.Optional(Type.Number({ description: "Optional per-run agent concurrency cap" })),
       parallelSubmissionLimit: Type.Optional(Type.Number({ description: "Optional limit for eagerly submitted parallel thunks" })),
@@ -210,7 +298,12 @@ export default function workflowEngine(pi: ExtensionAPI): void {
     }),
     renderCall(args, theme) {
       const suffix = args.args ? ` ${theme.fg("dim", args.args)}` : "";
-      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name)}${suffix}`, 0, 0);
+      if (args.name?.trim()) {
+        return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name.trim())}${suffix}`, 0, 0);
+      }
+      const preview = compactInlinePreview(args.script);
+      const previewSuffix = preview ? ` ${theme.fg("dim", preview)}` : "";
+      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", "inline")}${suffix}${previewSuffix}`, 0, 0);
     },
     renderResult(result, { expanded, isPartial }, theme) {
       if (isPartial) return new Text(theme.fg("accent", "Running workflow…"), 0, 0);
@@ -221,6 +314,9 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       return new Text(theme.fg("muted", text), 0, 0);
     },
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const request = normalizeWorkflowToolRequest(params);
+      if (request.kind === "error") return invalidWorkflowInvocationResult();
+
       const runOptions: WorkflowRunOptions = {
         concurrency: params.concurrency,
         parallelSubmissionLimit: params.parallelSubmissionLimit,
@@ -228,16 +324,33 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         signal,
       };
       const perfRecorder = await createInvocationPerf(runOptions);
-      const { discoverWorkflows } = await loadDiscovery();
-      const workflows = await discoverWorkflows(EXTENSION_DIR, { perf: perfRecorder });
-      const mod = workflows.get(params.name);
-      if (!mod) {
-        const available = [...workflows.keys()].join(", ") || "(none)";
-        return {
-          content: [{ type: "text", text: `Unknown workflow "${params.name}". Available: ${available}` }],
-          details: { error: "unknown_workflow", available },
-        };
+      let mod: WorkflowModule;
+      let resultName: string;
+
+      if (request.kind === "named") {
+        const { discoverWorkflows } = await loadDiscovery();
+        const workflows = await discoverWorkflows(EXTENSION_DIR, { perf: perfRecorder });
+        const named = workflows.get(request.name);
+        if (!named) {
+          const available = [...workflows.keys()].join(", ") || "(none)";
+          return {
+            content: [{ type: "text", text: `Unknown workflow "${request.name}". Available: ${available}` }],
+            details: { error: "unknown_workflow", available },
+          };
+        }
+        mod = named;
+        resultName = request.name;
+      } else {
+        const inline = await loadInlineWorkflow();
+        try {
+          mod = inline.compileInlineWorkflow(request.script);
+        } catch (error) {
+          if (error instanceof inline.InlineWorkflowCompileError) return inlineCompileErrorResult(error.message);
+          throw error;
+        }
+        resultName = mod.meta.name;
       }
+
       const { runWorkflow } = await loadEngine();
       let perfSnapshot: PerfSnapshot | undefined;
       const result = await runWorkflow(ctx, mod, params.args ?? "", {
@@ -250,7 +363,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       });
       const perf = compactPerfSnapshot(perfSnapshot);
       const perfLine = formatPerfLine(perf);
-      return { content: [{ type: "text", text: `${summarize(result)}${perfLine ? `\n\n${perfLine}` : ""}` }], details: workflowEnvelope(params.name, result, perf) };
+      return { content: [{ type: "text", text: `${summarize(result)}${perfLine ? `\n\n${perfLine}` : ""}` }], details: workflowEnvelope(resultName, result, perf) };
     },
   });
 }

package/.pi/extensions/pi-workflow-engine/src/discovery.ts

@@ -2,15 +2,11 @@ import { readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
-import type { WorkflowMeta, WorkflowModule } from "./types.ts";
+import type { WorkflowModule } from "./types.ts";
 import type { PerfSink } from "./perf.ts";
+import { parseWorkflowModule } from "./workflow-module.ts";
 import { BUILTIN_WORKFLOW_FILES, BUILTIN_WORKFLOWS } from "./workflows.ts";
 
-type WorkflowModuleCandidate = {
-  meta?: { name?: unknown; description?: unknown; phases?: unknown };
-  default?: unknown;
-};
-
 export interface DiscoverWorkflowsOptions {
   readonly refresh?: boolean;
   readonly perf?: PerfSink;
@@ -19,33 +15,6 @@ export interface DiscoverWorkflowsOptions {
 
 const discoveryCache = new Map<string, Map<string, WorkflowModule>>();
 
-function parseWorkflowModule(value: unknown): { module: WorkflowModule } | { reason: string } {
-  if (!value || typeof value !== "object") return { reason: "module export is not an object" };
-  const candidate = value as WorkflowModuleCandidate;
-  const meta = candidate.meta;
-  if (!meta || typeof meta !== "object") return { reason: "missing meta export" };
-  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
-
-  const description = meta.description;
-  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
-
-  const phases = meta.phases;
-  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
-  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
-
-  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
-  if (phases !== undefined) workflowMeta.phases = phases;
-  return { module: { meta: workflowMeta, default: candidate.default } };
-}
-
-function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
-  return typeof value === "function";
-}
-
-function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
-  return Array.isArray(value) && value.every((phase) => typeof phase === "object" && phase !== null && typeof (phase as { title?: unknown }).title === "string");
-}
-
 /** Best-effort dynamic load of every `*.ts` workflow in a directory. */
 async function loadDir(dir: string, excludeFiles: ReadonlySet<string> = new Set()): Promise<WorkflowModule[]> {
   let entries: string[];

package/.pi/extensions/pi-workflow-engine/src/dynamax.ts

@@ -0,0 +1,123 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export interface DynamaxState {
+  sticky: boolean;
+  oneShotPending: boolean;
+}
+
+export const DYNAMAX_TOKEN_PATTERN = /(^|[^A-Za-z0-9_])dynamax([^A-Za-z0-9_]|$)/i;
+
+export const DYNAMAX_REMINDER = `
+## dynamax workflow opt-in
+
+The user has opted into dynamax multi-agent orchestration. The workflow tool is permitted for this task. You may either run an existing named workflow or author a new inline workflow script when that best serves the user's request.
+
+Inline workflow rules:
+- Use the injected Type object for schemas, for example Type.Object({ ok: Type.Boolean() }); do not import typebox.
+- Do not use import statements or dynamic import() in inline workflow scripts.
+- Set thinkingLevel explicitly on each agent() call so fan-out remains bounded.
+- Provide exactly one of workflow.name or workflow.script.
+`;
+
+const DYNAMAX_CONTEXT_CUSTOM_TYPE = "workflow-dynamax-reminder";
+
+export function createDynamaxState(): DynamaxState {
+  return { sticky: false, oneShotPending: false };
+}
+
+export function hasDynamaxToken(text: string): boolean {
+  return DYNAMAX_TOKEN_PATTERN.test(text);
+}
+
+export function markDynamaxOneShot(state: DynamaxState): void {
+  state.oneShotPending = true;
+}
+
+export function setDynamaxSticky(state: DynamaxState, sticky: boolean): void {
+  state.sticky = sticky;
+  if (!sticky) state.oneShotPending = false;
+}
+
+export function clearDynamax(state: DynamaxState): void {
+  state.sticky = false;
+  state.oneShotPending = false;
+}
+
+export function consumeDynamaxOneShot(state: DynamaxState): boolean {
+  const pending = state.oneShotPending;
+  state.oneShotPending = false;
+  return pending;
+}
+
+export function isDynamaxActive(state: DynamaxState): boolean {
+  return state.sticky || state.oneShotPending;
+}
+
+export function appendDynamaxSystemReminder(systemPrompt: string, state: DynamaxState): string {
+  if (!isDynamaxActive(state)) return systemPrompt;
+  state.oneShotPending = false;
+  return `${systemPrompt}\n\n${DYNAMAX_REMINDER.trim()}`;
+}
+
+export function appendDynamaxContextReminder(messages: AgentMessage[], state: DynamaxState): AgentMessage[] {
+  if (!state.sticky) return messages;
+  return [...messages, createDynamaxContextMessage()];
+}
+
+export function registerDynamax(pi: ExtensionAPI): void {
+  const state = createDynamaxState();
+
+  pi.on("input", (event) => {
+    if (event.source === "extension") return { action: "continue" };
+    if (hasDynamaxToken(event.text)) markDynamaxOneShot(state);
+    return { action: "continue" };
+  });
+
+  pi.on("before_agent_start", (event) => {
+    const systemPrompt = appendDynamaxSystemReminder(event.systemPrompt, state);
+    if (systemPrompt === event.systemPrompt) return undefined;
+    return { systemPrompt };
+  });
+
+  pi.on("context", (event) => {
+    const messages = appendDynamaxContextReminder(event.messages, state);
+    if (messages === event.messages) return undefined;
+    return { messages };
+  });
+
+  pi.registerCommand("dynamax", {
+    description: "Toggle dynamax workflow orchestration opt-in: /dynamax on|off|status",
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase();
+      if (action === "on") {
+        setDynamaxSticky(state, true);
+        ctx.ui.notify("dynamax workflow orchestration is on for this session", "info");
+        return;
+      }
+      if (action === "off") {
+        clearDynamax(state);
+        ctx.ui.notify("dynamax workflow orchestration is off", "info");
+        return;
+      }
+      if (action === "status") {
+        const sticky = state.sticky ? "on" : "off";
+        const oneShot = state.oneShotPending ? "; one-shot opt-in pending" : "";
+        ctx.ui.notify(`dynamax sticky mode is ${sticky}${oneShot}`, "info");
+        return;
+      }
+      ctx.ui.notify("Usage: /dynamax on|off|status", "warning");
+    },
+  });
+}
+
+function createDynamaxContextMessage(): AgentMessage {
+  return {
+    role: "custom",
+    customType: DYNAMAX_CONTEXT_CUSTOM_TYPE,
+    content: DYNAMAX_REMINDER.trim(),
+    display: false,
+    details: { dynamax: true, sticky: true },
+    timestamp: Date.now(),
+  };
+}

package/.pi/extensions/pi-workflow-engine/src/inline-workflow.ts

@@ -0,0 +1,396 @@
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta, WorkflowModule } from "./types.ts";
+import { parseWorkflowMeta } from "./workflow-module.ts";
+
+/**
+ * v1 inline workflow source contract:
+ * - The script starts with `export const meta = { ... };` where the object is a pure literal.
+ * - The script contains exactly one `export default async ...` workflow function.
+ * - Inline scripts must not use `import` or any exports other than `meta` and the default function.
+ * - `Type` is injected lexically by the host; scripts must use that `Type`, not import typebox.
+ */
+
+export class InlineWorkflowCompileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InlineWorkflowCompileError";
+  }
+}
+
+export interface InlineMetaLiteral {
+  readonly literal: string;
+  readonly value: unknown;
+  readonly endOffset: number;
+}
+
+type InlineWorkflowExecutor = (api: WorkflowApi, typebox: typeof Type) => Promise<unknown>;
+type AsyncFunctionConstructor = new (...args: string[]) => InlineWorkflowExecutor;
+
+const AsyncFunction = Object.getPrototypeOf(async function inlineWorkflowCompilerSentinel() {}).constructor as AsyncFunctionConstructor;
+
+export function compileInlineWorkflow(source: string): WorkflowModule {
+  rejectForbiddenModuleSyntax(source);
+  const metaLiteral = extractMetaLiteral(source);
+  const parsedMeta = parseWorkflowMeta(metaLiteral.value);
+  if ("reason" in parsedMeta) throw new InlineWorkflowCompileError(parsedMeta.reason);
+
+  const defaultExpression = extractDefaultWorkflowExpression(source, metaLiteral.endOffset);
+  const executor = compileExecutor(defaultExpression);
+  return { meta: parsedMeta.meta, default: (api) => executor(api, Type) };
+}
+
+export function extractMetaLiteral(source: string): InlineMetaLiteral {
+  const start = skipWhitespace(source, 0);
+  const prefix = /export\s+const\s+meta\s*=/y;
+  prefix.lastIndex = start;
+  const match = prefix.exec(source);
+  if (!match || match.index !== start) {
+    throw new InlineWorkflowCompileError("inline workflow must start with `export const meta = { ... }`;");
+  }
+
+  const objectStart = skipWhitespace(source, prefix.lastIndex);
+  if (source[objectStart] !== "{") {
+    throw new InlineWorkflowCompileError("inline workflow meta must be an object literal");
+  }
+
+  const parser = new LiteralParser(source, objectStart);
+  const value = parser.parseValue();
+  const literalEnd = parser.offset;
+  let endOffset = skipWhitespace(source, literalEnd);
+  if (source[endOffset] === ";") endOffset++;
+
+  return { literal: source.slice(objectStart, literalEnd), value, endOffset };
+}
+
+function rejectForbiddenModuleSyntax(source: string): void {
+  if (/^\s*import\s/m.test(source)) {
+    throw new InlineWorkflowCompileError("inline workflows must not contain import statements; use injected Type instead");
+  }
+  if (/\bimport\s*\(/.test(source)) {
+    throw new InlineWorkflowCompileError("inline workflows must not use dynamic import()");
+  }
+}
+
+function extractDefaultWorkflowExpression(source: string, startOffset: number): string {
+  const moduleSource = source.slice(startOffset).trim();
+  if (!moduleSource) throw new InlineWorkflowCompileError("inline workflow must export a default async function");
+  if (!moduleSource.startsWith("export default")) {
+    throw new InlineWorkflowCompileError("inline workflow default export must directly follow the meta declaration");
+  }
+
+  const defaultPrefix = /^export\s+default\s+/;
+  const match = defaultPrefix.exec(moduleSource);
+  if (!match) throw new InlineWorkflowCompileError("inline workflow must export a default async function");
+
+  const expressionSource = moduleSource.slice(match[0].length).trimStart();
+  const bodyOpen = findDefaultBodyOpen(expressionSource);
+  const bodyClose = findMatchingDelimiter(expressionSource, bodyOpen, "{", "}");
+  const expression = expressionSource.slice(0, bodyClose + 1);
+  const remainder = expressionSource.slice(bodyClose + 1).trim();
+  if (remainder !== "" && remainder !== ";") {
+    throw new InlineWorkflowCompileError("inline workflow must not contain code after the default export");
+  }
+  return expression;
+}
+
+function findDefaultBodyOpen(expressionSource: string): number {
+  const functionMatch = /^async\s+function(?:\s+[A-Za-z_$][\w$]*)?\s*/.exec(expressionSource);
+  if (functionMatch) {
+    const paramsOpen = skipWhitespace(expressionSource, functionMatch[0].length);
+    if (expressionSource[paramsOpen] !== "(") {
+      throw new InlineWorkflowCompileError("default async function must declare parameters with parentheses");
+    }
+    const paramsClose = findMatchingDelimiter(expressionSource, paramsOpen, "(", ")");
+    const bodyOpen = skipWhitespace(expressionSource, paramsClose + 1);
+    if (expressionSource[bodyOpen] !== "{") {
+      throw new InlineWorkflowCompileError("default async function must use a block body");
+    }
+    return bodyOpen;
+  }
+
+  const arrowMatch = /^async\s*/.exec(expressionSource);
+  if (arrowMatch) {
+    const paramsOpen = skipWhitespace(expressionSource, arrowMatch[0].length);
+    if (expressionSource[paramsOpen] !== "(") {
+      throw new InlineWorkflowCompileError("default async arrow workflow must declare parameters with parentheses");
+    }
+    const paramsClose = findMatchingDelimiter(expressionSource, paramsOpen, "(", ")");
+    let cursor = skipWhitespace(expressionSource, paramsClose + 1);
+    if (!expressionSource.startsWith("=>", cursor)) {
+      throw new InlineWorkflowCompileError("default async arrow workflow must use =>");
+    }
+    cursor = skipWhitespace(expressionSource, cursor + 2);
+    if (expressionSource[cursor] !== "{") {
+      throw new InlineWorkflowCompileError("default async arrow workflow must use a block body");
+    }
+    return cursor;
+  }
+
+  throw new InlineWorkflowCompileError("inline workflow default export must be an async function or async arrow function");
+}
+
+function compileExecutor(defaultExpression: string): InlineWorkflowExecutor {
+  try {
+    return new AsyncFunction("api", "Type", `"use strict";\nconst workflow = ${defaultExpression};\nreturn await workflow(api);`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new InlineWorkflowCompileError(`inline workflow default export did not compile: ${message}`);
+  }
+}
+
+class LiteralParser {
+  private index: number;
+
+  constructor(private readonly source: string, offset: number) {
+    this.index = offset;
+  }
+
+  get offset(): number {
+    return this.index;
+  }
+
+  parseValue(): unknown {
+    this.skipWhitespace();
+    const char = this.source[this.index];
+    if (char === "{") return this.parseObject();
+    if (char === "[") return this.parseArray();
+    if (char === '"' || char === "'") return this.parseString(char);
+    if (char === "-" || isDigit(char)) return this.parseNumber();
+    if (this.source.startsWith("true", this.index)) return this.consumeKeyword("true", true);
+    if (this.source.startsWith("false", this.index)) return this.consumeKeyword("false", false);
+    if (this.source.startsWith("null", this.index)) return this.consumeKeyword("null", null);
+    if (char === "`") this.fail("template literals are not allowed in inline workflow meta");
+    this.fail(`unexpected token in inline workflow meta: ${char ?? "end of input"}`);
+  }
+
+  private parseObject(): Record<string, unknown> {
+    const object: Record<string, unknown> = {};
+    this.expect("{");
+    this.skipWhitespace();
+    if (this.peek() === "}") {
+      this.index++;
+      return object;
+    }
+
+    while (true) {
+      this.skipWhitespace();
+      if (this.source.startsWith("...", this.index)) this.fail("spread properties are not allowed in inline workflow meta");
+      if (this.peek() === "[") this.fail("computed properties are not allowed in inline workflow meta");
+      const key = this.parsePropertyKey();
+      this.skipWhitespace();
+      if (this.peek() !== ":") this.fail("inline workflow meta properties must use explicit key: value syntax");
+      this.index++;
+      object[key] = this.parseValue();
+      this.skipWhitespace();
+      const next = this.peek();
+      if (next === ",") {
+        this.index++;
+        this.skipWhitespace();
+        if (this.peek() === "}") {
+          this.index++;
+          return object;
+        }
+        continue;
+      }
+      if (next === "}") {
+        this.index++;
+        return object;
+      }
+      this.fail("expected `,` or `}` in inline workflow meta object");
+    }
+  }
+
+  private parseArray(): unknown[] {
+    const array: unknown[] = [];
+    this.expect("[");
+    this.skipWhitespace();
+    if (this.peek() === "]") {
+      this.index++;
+      return array;
+    }
+
+    while (true) {
+      array.push(this.parseValue());
+      this.skipWhitespace();
+      const next = this.peek();
+      if (next === ",") {
+        this.index++;
+        this.skipWhitespace();
+        if (this.peek() === "]") {
+          this.index++;
+          return array;
+        }
+        continue;
+      }
+      if (next === "]") {
+        this.index++;
+        return array;
+      }
+      this.fail("expected `,` or `]` in inline workflow meta array");
+    }
+  }
+
+  private parsePropertyKey(): string {
+    const char = this.peek();
+    if (char === '"' || char === "'") return this.parseString(char);
+    if (!isIdentifierStart(char)) this.fail("inline workflow meta property keys must be strings or identifiers");
+    const start = this.index;
+    this.index++;
+    while (isIdentifierPart(this.peek())) this.index++;
+    return this.source.slice(start, this.index);
+  }
+
+  private parseString(quote: string): string {
+    this.expect(quote);
+    let value = "";
+    while (this.index < this.source.length) {
+      const char = this.source[this.index];
+      if (char === quote) {
+        this.index++;
+        return value;
+      }
+      if (char === "\\") {
+        value += this.parseEscapeSequence();
+        continue;
+      }
+      if (char === "\n" || char === "\r") this.fail("inline workflow meta strings must not contain raw newlines");
+      value += char;
+      this.index++;
+    }
+    this.fail("unterminated string in inline workflow meta");
+  }
+
+  private parseEscapeSequence(): string {
+    this.expect("\\");
+    const escaped = this.source[this.index];
+    if (escaped === undefined) this.fail("unterminated escape sequence in inline workflow meta");
+    this.index++;
+    switch (escaped) {
+      case '"':
+      case "'":
+      case "\\":
+      case "/":
+        return escaped;
+      case "b":
+        return "\b";
+      case "f":
+        return "\f";
+      case "n":
+        return "\n";
+      case "r":
+        return "\r";
+      case "t":
+        return "\t";
+      case "u": {
+        const hex = this.source.slice(this.index, this.index + 4);
+        if (!/^[0-9A-Fa-f]{4}$/.test(hex)) this.fail("invalid unicode escape in inline workflow meta");
+        this.index += 4;
+        return String.fromCharCode(Number.parseInt(hex, 16));
+      }
+      default:
+        this.fail(`unsupported escape sequence \\${escaped} in inline workflow meta`);
+    }
+  }
+
+  private parseNumber(): number {
+    const match = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+    match.lastIndex = this.index;
+    const parsed = match.exec(this.source);
+    if (!parsed) this.fail("invalid number in inline workflow meta");
+    this.index = match.lastIndex;
+    return Number(parsed[0]);
+  }
+
+  private consumeKeyword<T>(keyword: string, value: T): T {
+    this.index += keyword.length;
+    if (isIdentifierPart(this.peek())) this.fail(`unexpected identifier after ${keyword} in inline workflow meta`);
+    return value;
+  }
+
+  private skipWhitespace(): void {
+    this.index = skipWhitespace(this.source, this.index);
+  }
+
+  private peek(): string | undefined {
+    return this.source[this.index];
+  }
+
+  private expect(char: string): void {
+    if (this.source[this.index] !== char) this.fail(`expected ${char} in inline workflow meta`);
+    this.index++;
+  }
+
+  private fail(message: string): never {
+    throw new InlineWorkflowCompileError(`${message} at offset ${this.index}`);
+  }
+}
+
+function findMatchingDelimiter(source: string, openIndex: number, open: string, close: string): number {
+  let depth = 1;
+  let index = openIndex + 1;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === '"' || char === "'" || char === "`") {
+      index = skipQuotedSource(source, index, char);
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "/") {
+      index = skipLineComment(source, index);
+      continue;
+    }
+    if (char === "/" && source[index + 1] === "*") {
+      index = skipBlockComment(source, index);
+      continue;
+    }
+    if (char === open) depth++;
+    if (char === close) {
+      depth--;
+      if (depth === 0) return index;
+    }
+    index++;
+  }
+  throw new InlineWorkflowCompileError(`unterminated ${open}${close} block in inline workflow default export`);
+}
+
+function skipQuotedSource(source: string, start: number, quote: string): number {
+  let index = start + 1;
+  while (index < source.length) {
+    const char = source[index];
+    if (char === "\\") {
+      index += 2;
+      continue;
+    }
+    if (char === quote) return index + 1;
+    index++;
+  }
+  throw new InlineWorkflowCompileError("unterminated string in inline workflow default export");
+}
+
+function skipLineComment(source: string, start: number): number {
+  const newline = source.indexOf("\n", start + 2);
+  return newline === -1 ? source.length : newline + 1;
+}
+
+function skipBlockComment(source: string, start: number): number {
+  const end = source.indexOf("*/", start + 2);
+  if (end === -1) throw new InlineWorkflowCompileError("unterminated block comment in inline workflow default export");
+  return end + 2;
+}
+
+function skipWhitespace(source: string, start: number): number {
+  let index = start;
+  while (index < source.length && /\s/.test(source[index] ?? "")) index++;
+  return index;
+}
+
+function isDigit(value: string | undefined): boolean {
+  return value !== undefined && value >= "0" && value <= "9";
+}
+
+function isIdentifierStart(value: string | undefined): boolean {
+  return value !== undefined && /[A-Za-z_$]/.test(value);
+}
+
+function isIdentifierPart(value: string | undefined): boolean {
+  return value !== undefined && /[A-Za-z0-9_$]/.test(value);
+}

package/.pi/extensions/pi-workflow-engine/src/workflow-module.ts

@@ -0,0 +1,57 @@
+import type { WorkflowMeta, WorkflowModule } from "./types.ts";
+
+type WorkflowMetaCandidate = {
+  readonly name?: unknown;
+  readonly description?: unknown;
+  readonly phases?: unknown;
+};
+
+type WorkflowModuleCandidate = {
+  readonly meta?: unknown;
+  readonly default?: unknown;
+};
+
+/** Validate and normalize workflow metadata without executing workflow code. */
+export function parseWorkflowMeta(value: unknown): { meta: WorkflowMeta } | { reason: string } {
+  if (!isRecord(value)) return { reason: "meta export must be an object" };
+  return parseWorkflowMetaObject(value);
+}
+
+export function parseWorkflowModule(value: unknown): { module: WorkflowModule } | { reason: string } {
+  if (!isRecord(value)) return { reason: "module export is not an object" };
+  const candidate = value as WorkflowModuleCandidate;
+  const meta = candidate.meta;
+  if (!isRecord(meta)) return { reason: "missing meta export" };
+
+  const parsedMeta = parseWorkflowMetaObject(meta);
+  if ("reason" in parsedMeta) return parsedMeta;
+  if (!isWorkflowRun(candidate.default)) return { reason: "default export must be a function" };
+
+  return { module: { meta: parsedMeta.meta, default: candidate.default } };
+}
+
+function parseWorkflowMetaObject(meta: WorkflowMetaCandidate): { meta: WorkflowMeta } | { reason: string } {
+  if (typeof meta.name !== "string") return { reason: "meta.name must be a string" };
+
+  const description = meta.description;
+  if (description !== undefined && typeof description !== "string") return { reason: "meta.description must be a string when provided" };
+
+  const phases = meta.phases;
+  if (phases !== undefined && !isWorkflowPhases(phases)) return { reason: "meta.phases must be an array of { title: string }" };
+
+  const workflowMeta: WorkflowMeta = { name: meta.name, description: description ?? "" };
+  if (phases !== undefined) workflowMeta.phases = phases;
+  return { meta: workflowMeta };
+}
+
+function isWorkflowRun(value: unknown): value is WorkflowModule["default"] {
+  return typeof value === "function";
+}
+
+function isWorkflowPhases(value: unknown): value is Array<{ title: string }> {
+  return Array.isArray(value) && value.every((phase) => isRecord(phase) && typeof phase.title === "string");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/.pi/extensions/pi-workflow-engine/src/workflows.ts

@@ -1,6 +1,5 @@
 import type { WorkflowModule } from "./types.ts";
 import * as codeReview from "../workflows/code-review.ts";
-import * as ping from "../workflows/ping.ts";
 import * as refactorScout from "../workflows/refactor-scout.ts";
 import * as diagnose from "../workflows/diagnose.ts";
 import * as perfReview from "../workflows/perf-review.ts";
@@ -19,6 +18,6 @@ import * as perfReview from "../workflows/perf-review.ts";
  * dynamically imported built-ins. Startup optimizations should happen at the extension
  * entrypoint/discovery boundary first.
  */
-export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, ping, refactorScout, diagnose, perfReview];
-export const BUILTIN_WORKFLOW_FILES = new Set(["code-review.ts", "ping.ts", "refactor-scout.ts", "diagnose.ts", "perf-review.ts"]);
+export const BUILTIN_WORKFLOWS: WorkflowModule[] = [codeReview, refactorScout, diagnose, perfReview];
+export const BUILTIN_WORKFLOW_FILES = new Set(["code-review.ts", "refactor-scout.ts", "diagnose.ts", "perf-review.ts"]);
 export const BUILTIN_WORKFLOW_NAMES = BUILTIN_WORKFLOWS.map((mod) => mod.meta.name);

package/README.md

@@ -55,6 +55,8 @@ pi remove git:github.com/timbrinded/pi-workflow-engine
 
 ## Usage
 
+For the complete installation, invocation, authoring, tuning, and troubleshooting guide, see [USAGE.md](USAGE.md).
+
 In a pi session, from inside a git repo with changes:
 
 ```text
@@ -64,15 +66,25 @@ In a pi session, from inside a git repo with changes:
 /workflow diagnose "typecheck fails after the schema change"
 /workflow perf-review "workflow startup latency"
 /workflow code-review --inspect  # open the live workflow inspector
-/workflow ping                   # quick engine smoke test
 ```
 
-The host agent can also invoke the `workflow` tool mid-conversation:
+The host agent can also invoke the `workflow` tool mid-conversation. It accepts either a registered workflow `name` or a one-off inline workflow `script`:
 
 ```text
 Run the code-review workflow on this PR and use the result before deciding what to fix.
 ```
 
+Opt into dynamic multi-agent orchestration with the literal `dynamax` token, or keep it sticky for the session:
+
+```text
+dynamax inspect this bug with multiple focused agents
+/dynamax on
+/dynamax status
+/dynamax off
+```
+
+`dynamax` is a permission signal for the host agent: once opted in, it may run an existing named workflow or author an inline workflow script through the `workflow` tool. In interactive mode, `/workflow` with no arguments also offers `✍ Author temporary one-shot workflow…`; choose it, type a brief, and pi will ask the host agent to author/run a temporary inline workflow.
+
 The advisory workflows inspect and report only; they do not edit files. They return the same shape: summary, ranked findings, evidence, impact, recommendations, and next steps.
 
 ## Built-in workflows
@@ -81,7 +93,6 @@ The advisory workflows inspect and report only; they do not edit files. They ret
 - `refactor-scout`: Looks for small, safe refactor opportunities: duplication, complexity, weak types, boundary leaks, dead code, and convention drift.
 - `diagnose`: Investigates a symptom, failing command, or regression. It generates competing root-cause hypotheses, verifies them, and returns the most likely causes with next validation steps.
 - `perf-review`: Reviews a slow path or workload for bottleneck hypotheses, measurement gaps, and safe optimization directions. It avoids claiming certainty when measurement evidence is missing.
-- `ping`: Minimal smoke workflow for checking that the engine can run one structured agent call.
 
 ## The code-review workflow
 
@@ -135,12 +146,33 @@ export default async function run({ agent, parallel, phase }: WorkflowApi) {
 }
 ```
 
+Inline workflow scripts use the same primitives, but are passed as a string to the `workflow` tool instead of being saved as files. A minimal inline workflow starts with `export const meta` and uses the injected Type object for schemas:
+
+```ts
+export const meta = {
+  name: "inline-review",
+  description: "One-off focused review workflow.",
+};
+
+export default async function run({ agent, parallel, phase, args }) {
+  phase("Find");
+  const Finding = Type.Object({ summary: Type.String() });
+  const findings = await parallel([
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+  ]);
+  return { summary: JSON.stringify(findings) };
+}
+```
+
+Inline v1 rules: no imports, no dynamic `import()`, pure-literal `meta`, schemas must use the injected Type value, and scripts run in-process with the extension's permissions. This v1 path is permissive rather than sandboxed.
+
 Under the hood:
 
 - **Each `agent()` is an in-process pi `AgentSession`** using `createAgentSession` and `SessionManager.inMemory()`.
 - **Structured output is a terminating tool**. The engine registers one tool whose `parameters` is your schema; pi validates the call and the engine captures the args. There is no JSON scraping.
 - **A single global semaphore caps concurrent agents**, so `parallel` and `pipeline` can nest freely while every `agent()` call still respects the run cap.
-- **Two surfaces are registered**: `/workflow <name> [args]` for direct use, and a `workflow` tool for host-agent delegation.
+- **Three surfaces are registered**: `/workflow <name> [args]` for direct use, `/dynamax on|off|status` for sticky orchestration opt-in, and a `workflow` tool for host-agent delegation by `name` or inline `script`.
 
 ## Local development
 
@@ -177,11 +209,7 @@ bun run bench:startup -- --json
 bun run bench:ui -- --agents 1000 --lane-items 1000 --json
 ```
 
-Add `--out` to write machine-local JSON under `.artifacts/benchmarks/`. These timings are advisory, not portable thresholds. Optional LLM smoke timing is separate from the required gates:
-
-```bash
-pi -e . -p "/workflow ping"
-```
+Add `--out` to write machine-local JSON under `.artifacts/benchmarks/`. These timings are advisory, not portable thresholds.
 
 Guardrails:
 
@@ -192,7 +220,7 @@ Guardrails:
 Load your working copy through the package manifest without installing it. This is ephemeral and exercises the same `.pi/extensions/pi-workflow-engine/index.ts` entrypoint that installed packages use:
 
 ```bash
-pi -e . -p "/workflow ping"
+pi -e .
 ```
 
 This repo also includes `.pi/settings.json` for project-local auto-discovery. If you also have the global package installed, pi may report duplicate `/workflow` or `workflow` tool diagnostics; remove one source or force pi to ignore discovered extensions and load this working copy instead:
@@ -227,7 +255,6 @@ Tune the built-in review workflow by editing the `ANGLES` array in `.pi/extensio
       refactor-scout.ts                 advisory refactor opportunities
       diagnose.ts                       advisory bug diagnosis
       perf-review.ts                    advisory performance investigation
-      ping.ts                           minimal smoke workflow
 ```
 
 ## License

package/USAGE.md

@@ -0,0 +1,183 @@
+# Usage
+
+`pi-workflow-engine` adds multi-agent workflows to pi. Most users only need two surfaces:
+
+- `/workflow <name> [args]` to run a saved workflow directly.
+- `dynamax` when you want the host agent to author a one-off inline workflow for investigation/review.
+
+## Run a workflow
+
+From inside a repo:
+
+```text
+/workflow code-review
+/workflow code-review HEAD~3
+/workflow refactor-scout src/
+/workflow diagnose "typecheck fails after the schema change"
+/workflow perf-review "workflow startup latency"
+```
+
+The built-in workflows are advisory. They inspect, verify, and report; they do **not** edit files.
+
+Useful flags:
+
+```text
+/workflow code-review --inspect          # show live inspector
+/workflow code-review --concurrency=4    # cap concurrent subagents
+/workflow code-review --refresh          # rediscover newly added workflow files
+```
+
+## Built-in workflows
+
+| Name | Purpose |
+| --- | --- |
+| `code-review` | Reviews a PR, branch diff, ref range, or focus area. |
+| `refactor-scout` | Finds small, safe refactor opportunities. |
+| `diagnose` | Investigates a bug, failing command, or regression. |
+| `perf-review` | Reviews a slow path or performance concern. |
+
+`code-review` auto-detects a diff when you do not pass args. If there is an open GitHub PR for the current branch, it uses that PR diff; otherwise it falls back to branch-vs-main/master or `HEAD~1`.
+
+## Use `dynamax` for inline workflows
+
+Use `dynamax` when the built-in workflows are not specific enough and you want the main pi agent to author a temporary workflow for the current question.
+
+Interactive shortcut: run `/workflow` with no arguments, choose `✍ Author temporary one-shot workflow…`, and type a brief. pi will send that brief back to the host agent as a `dynamax` request so it can author and run an inline workflow with the `workflow` tool's `script` argument.
+
+That inline workflow should investigate, fan out, verify, and summarize. It is **not** where code edits happen. If you want changes made, use the workflow result as evidence and then ask pi to edit separately.
+
+One-off examples:
+
+```text
+dynamax author an inline workflow to investigate why typecheck is failing
+dynamax create a one-off workflow to compare the parser and tests before we change code
+dynamax use parallel agents to review this design and report the risks
+```
+
+Sticky for the session:
+
+```text
+/dynamax on
+/dynamax off
+/dynamax status
+```
+
+With dynamax enabled, the host agent usually calls the `workflow` tool with `script`: a one-off inline workflow. It can still call a saved workflow by `name` when one already fits.
+
+## Workflow results
+
+Workflow results are rendered in pi with:
+
+- summary;
+- ranked findings;
+- locations and evidence;
+- recommendations;
+- next steps;
+- run stats when available.
+
+During a run, pi shows live phases and subagent status. Use `--inspect` if you want a larger live view.
+
+## Author a saved workflow
+
+Saved workflows are TypeScript modules with `meta` plus a default async function:
+
+```ts
+import { Type } from "typebox";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "my-workflow",
+  description: "Find and summarize something important.",
+};
+
+const Finding = Type.Object({
+  summary: Type.String(),
+});
+
+export default async function run({ agent, parallel, phase, args }: WorkflowApi) {
+  phase("Find");
+  const findings = await parallel([
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, tools: ["read", "bash"], thinkingLevel: "low" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, tools: ["read", "bash"], thinkingLevel: "low" }),
+  ]);
+
+  phase("Synthesize");
+  return agent(`Summarize: ${JSON.stringify(findings)}`, { thinkingLevel: "medium" });
+}
+```
+
+Core primitives:
+
+| Primitive | What it does |
+| --- | --- |
+| `agent(prompt, opts)` | Runs one isolated subagent. With `schema`, returns validated structured data. |
+| `parallel(thunks)` | Runs thunks concurrently and waits for all. |
+| `pipeline(items, ...stages)` | Runs each item through stages independently. |
+| `phase(title)` / `log(message)` | Updates workflow progress UI. |
+| `progress(event)` | Emits counters, summaries, and lane items. |
+
+Set `thinkingLevel` on fan-out agents. Otherwise many subagents can inherit an expensive global reasoning level.
+
+### Where workflows live
+
+Guaranteed built-ins are statically registered:
+
+1. Add `.pi/extensions/pi-workflow-engine/workflows/<name>.ts`.
+2. Import it in `.pi/extensions/pi-workflow-engine/src/workflows.ts`.
+3. Add it to `BUILTIN_WORKFLOWS`.
+
+Drop-in workflows are also discovered best-effort from:
+
+- `.pi/extensions/pi-workflow-engine/workflows/*.ts`
+- `~/.pi/agent/workflows/*.ts`
+
+Use `/workflow <name> --refresh` after adding a drop-in file.
+
+## Author an inline workflow
+
+Inline workflows are passed to the `workflow` tool as a script string. They are useful for one-off dynamax orchestration.
+
+```ts
+export const meta = {
+  name: "inline-review",
+  description: "One-off focused review.",
+};
+
+export default async function run({ agent, parallel, phase, args }) {
+  phase("Find");
+  const Finding = Type.Object({ summary: Type.String() });
+  const findings = await parallel([
+    () => agent(`Find correctness issues: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+    () => agent(`Find edge cases: ${args}`, { schema: Finding, thinkingLevel: "low" }),
+  ]);
+  return { summary: JSON.stringify(findings) };
+}
+```
+
+Inline rules:
+
+- start with `export const meta = { ... }`;
+- default-export an async workflow function;
+- no imports or dynamic `import()`;
+- use the injected `Type` object for schemas;
+- no extra exports or code after the default export.
+
+Inline workflows run in-process with extension permissions, so treat them as trusted task automation.
+
+## Runtime knobs
+
+Only tune these when a workflow is too slow, too expensive, or too noisy:
+
+| Knob | Meaning |
+| --- | --- |
+| `--concurrency=N` / `PI_WORKFLOW_CONCURRENCY=N` | Cap concurrent subagents. Default is `min(8, max(2, CPU count))`. |
+| `--parallel-limit=N` / `PI_WORKFLOW_PARALLEL_SUBMISSION_LIMIT=N` | Limit eager `parallel()` submission. |
+| `--perf` / `PI_WORKFLOW_PERF=1` | Include internal timing aggregates. |
+| `PI_WORKFLOW_LANE_ITEM_LIMIT=N` | Cap retained progress lane items. |
+
+## Common fixes
+
+- **Unknown workflow**: confirm the extension is loaded with `pi list`; use `--refresh` for new drop-ins.
+- **Inline compile error**: check the inline rules above.
+- **Slow run**: lower fan-out, set `thinkingLevel`, or reduce `--concurrency`.
+- **Duplicate command/tool warnings while developing**: avoid loading both the global package and the working copy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "A customisable multi-agent workflow-orchestration engine for the pi coding agent.",
   "keywords": [
@@ -25,6 +25,7 @@
     ".pi/settings.json",
     "assets",
     "README.md",
+    "USAGE.md",
     "LICENSE"
   ],
   "pi": {

package/.pi/extensions/pi-workflow-engine/workflows/ping.ts

@@ -1,29 +0,0 @@
-import { Type } from "typebox";
-import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
-
-/** Minimal engine smoke test: a single structured-output agent call. Fast + cheap. */
-export const meta: WorkflowMeta = {
-  name: "ping",
-  description: "Engine smoke test — one structured agent call, no tools.",
-  phases: [{ title: "Ping" }],
-};
-
-export default async function run(api: WorkflowApi): Promise<unknown> {
-  const { agent, phase, log } = api;
-  phase("Ping");
-  log("calling one structured agent");
-  const result = await agent(
-    "You are a code-review workflow engine. Return a one-word headline and a one-sentence summary of what you do.",
-    {
-      phase: "Ping",
-      label: "ping",
-      tools: [],
-      thinkingLevel: "low",
-      schema: Type.Object({
-        headline: Type.String({ description: "One word" }),
-        summary: Type.String({ description: "One sentence" }),
-      }),
-    },
-  );
-  return result ?? { headline: "none", summary: "no structured answer returned" };
-}