pi-workflow-engine 1.1.0 → 1.2.0

package/.pi/extensions/pi-workflow-engine/src/agent-session.ts

@@ -12,6 +12,7 @@ import {
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { prepareAgentSkillResources } from "./agent-skills.ts";
+import { createCodemodeSlotExtension, runToolCallsSequentially } from "./codemode-slots.ts";
 import type {
   AgentExecutionOptions,
   AgentProgress,
@@ -35,6 +36,16 @@ export const FINAL_TOOL = "final_answer";
 /** pi's codemode tool; SDK sessions only have it when their resource loader registers the extension. */
 export const CODEMODE_TOOL = "codemode";
 
+/** pi's stock prompt frames a chat with a person; a subagent's last message is program data instead. */
+const RETURN_VALUE_FRAMING =
+  "Your final message is returned verbatim to the workflow program that started you, as data. " +
+  "It is not shown to a person as a chat reply. Make it exactly the output your task asks for, in the format it asks for, " +
+  "with no greeting, preamble, narration of your process, or offer of further help.";
+/** A schema agent returns its final_answer arguments, not its last message. */
+const STRUCTURED_RETURN_VALUE_FRAMING =
+  `Your ${FINAL_TOOL} arguments are returned to the workflow program that started you, as data. ` +
+  "They are not shown to a person as a chat reply. Fill each field with exactly the content it asks for, " +
+  "with no greeting, preamble, narration of your process, or offer of further help.";
 const SCHEMA_REPROMPT =
   `You ended your turn without calling the ${FINAL_TOOL} tool, so no result was recorded. ` +
   `Call ${FINAL_TOOL} now with your final answer as its arguments. Do not reply with plain text.`;
@@ -234,6 +245,7 @@ async function prepareAgentSessionResources(input: {
     sessionManager: SessionManager.inMemory(cwd),
   });
   const createSession = rc.createSession;
+  // Injected test sessions build no resource loader, so they get neither skills nor the return-value framing.
   if (createSession) {
     return {
       selectedSkills: [],
@@ -251,9 +263,15 @@ async function prepareAgentSessionResources(input: {
     log: (message: string) => rc.progress.log(`${label}: ${message}`),
   };
   const preparedSkills = prepareAgentSkillResources(skillOptions);
+  const codemode = opts.tools?.includes(CODEMODE_TOOL) ?? false;
   const services = await createAgentSessionServices({
     cwd,
-    resourceLoaderOptions: { ...preparedSkills.resourceLoaderOptions, ...codemodeExtension(opts) },
+    resourceLoaderOptions: {
+      ...preparedSkills.resourceLoaderOptions,
+      ...(codemode ? codemodeExtensions() : {}),
+      // An override, not `appendSystemPrompt`: passing that replaces pi's discovery of the user's APPEND_SYSTEM.md.
+      appendSystemPromptOverride: (base) => [...base, opts.schema ? STRUCTURED_RETURN_VALUE_FRAMING : RETURN_VALUE_FRAMING],
+    },
   });
   await synchronizeWorkflowModelRuntime({
     host: rc.modelRegistry,
@@ -272,11 +290,14 @@ async function prepareAgentSessionResources(input: {
   const selectedSkills = preparedSkills.resolve(services.resourceLoader);
   return {
     selectedSkills,
-    createSession: (sessionOptions) =>
-      createAgentSessionFromServices({
+    createSession: async (sessionOptions) => {
+      const created = await createAgentSessionFromServices({
         services,
         ...commonSessionOptions(sessionOptions),
-      }),
+      });
+      if (codemode) runToolCallsSequentially(created.session);
+      return created;
+    },
   };
 }
 
@@ -284,10 +305,16 @@ async function prepareAgentSessionResources(input: {
  * SDK sessions load none of pi's built-in extensions, so codemode is registered only for agents whose
  * allowlist names it. Scripts can call just the agent's other allowed tools. Mode "on" keeps those
  * tools declared whatever the user's `codemode.mode`, so the author's allowlist stays what the model sees.
+ * Its calls queue for the process-wide codemode slots instead of failing at pi's worker limit, so the
+ * session runs its tool calls one at a time.
  */
-function codemodeExtension(opts: AgentExecutionOptions): Pick<SessionResourceLoaderOptions, "extensionFactories"> {
-  if (!opts.tools?.includes(CODEMODE_TOOL)) return {};
-  return { extensionFactories: [{ name: CODEMODE_TOOL, factory: createCodemodeExtension({ mode: "on" }), replaceable: true }] };
+function codemodeExtensions(): Pick<SessionResourceLoaderOptions, "extensionFactories"> {
+  return {
+    extensionFactories: [
+      { name: CODEMODE_TOOL, factory: createCodemodeExtension({ mode: "on" }), replaceable: true },
+      { name: "workflow-codemode-slots", factory: createCodemodeSlotExtension(CODEMODE_TOOL), hidden: true },
+    ],
+  };
 }
 
 type SessionResourceLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;

package/.pi/extensions/pi-workflow-engine/src/background-workflow-tool.ts

@@ -1,8 +1,10 @@
+import { join } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { BackgroundWorkflowCoordinator, backgroundOrigin } from "./background-workflows.ts";
-import { createWorkflowRunId } from "./journal.ts";
+import { createWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { ResolvedWorkflowRunOptions } from "./options.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
+import { workflowRunScriptFile } from "./workflow-run-record.ts";
 
 export interface BackgroundWorkflowToolResult {
   readonly content: Array<{ readonly type: "text"; readonly text: string }>;
@@ -15,6 +17,8 @@ export interface BackgroundWorkflowToolStartInput {
   readonly ctx: ExtensionContext;
   readonly name: string;
   readonly options: ResolvedWorkflowRunOptions;
+  /** Deliver the completion with a new agent turn instead of silently. */
+  readonly wakeOnComplete?: boolean;
   readonly execute: (ctx: ExtensionContext, options: ResolvedWorkflowRunOptions) => Promise<void>;
 }
 
@@ -39,8 +43,9 @@ export async function startBackgroundWorkflowTool(
     inspect: false,
     resultViewer: "skip",
     runId,
-    background: backgroundOrigin(input.ctx),
+    background: backgroundOrigin(input.ctx, Date.now(), input.wakeOnComplete),
   };
+  let scriptPersisted = false;
   try {
     await input.coordinator.start({
       ctx: input.ctx,
@@ -53,6 +58,7 @@ export async function startBackgroundWorkflowTool(
             ...backgroundOptions,
             signal,
             onRunMetadata(metadata) {
+              scriptPersisted = metadata.scriptPath !== undefined;
               onStarted();
               return backgroundOptions.onRunMetadata?.(metadata);
             },
@@ -71,7 +77,7 @@ export async function startBackgroundWorkflowTool(
   return {
     content: [{
       type: "text",
-      text: `Background workflow "${input.name}" started.\nRun ID: ${runId}\nDurable record: .pi/.workflow-runs/${runId}.run.json`,
+      text: `Background workflow "${input.name}" started.\nRun ID: ${runId}\nDurable record: .pi/.workflow-runs/${runId}.run.json${scriptPersisted ? `\nScript: ${join(WORKFLOW_RUNS_DIR, workflowRunScriptFile(runId))}` : ""}`,
     }],
     details: { background: true, state: "running", name: input.name, runId },
   };

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

@@ -1,6 +1,8 @@
+import { join } from "node:path";
 import { SessionManager, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { WorkflowAbortError, WorkflowPauseError } from "./cancellation.ts";
 import { isRecord } from "./guards.ts";
+import { WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { WorkflowBackgroundOrigin } from "./types.ts";
 import {
   stopWorkflowRunRecord,
@@ -9,9 +11,11 @@ import {
   type WorkflowRunState,
 } from "./workflow-run-record.ts";
 import { updateWorkflowRunDelivery, type WorkflowRunDelivery } from "./workflow-run-background.ts";
-import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { ProjectWorkflowRunStore, WORKFLOW_RUN_RECORD_SUFFIX, type WorkflowRunStore } from "./workflow-run-store.ts";
 import { truncateText } from "./text.ts";
+import { formatWorkflowUsageLine } from "./usage.ts";
 import { workflowResultSummary } from "./workflow-execution.ts";
+import { formatResultForContext, formatWorkflowRunFileLines } from "./workflow-result-context.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 
 const BACKGROUND_DELIVERY_CUSTOM_TYPE = "workflow-result";
@@ -294,11 +298,12 @@ export class BackgroundWorkflowCoordinator {
       this.pi.sendMessage(
         {
           customType: BACKGROUND_DELIVERY_CUSTOM_TYPE,
-          content: formatBackgroundDelivery(details),
+          content: formatBackgroundDelivery(record, details),
           display: true,
           details,
         },
-        { triggerTurn: false },
+        // Delivery waits for an idle session, and pi steers a message sent while a run starts into that run.
+        { triggerTurn: wakesAgent(record) },
       );
     }
     await markDelivery(store, runId, { state: "delivered", deliveredAt: Date.now() });
@@ -306,8 +311,13 @@ export class BackgroundWorkflowCoordinator {
   }
 }
 
-export function backgroundOrigin(ctx: Pick<ExtensionContext, "sessionManager">, requestedAt = Date.now()): WorkflowBackgroundOrigin {
-  return { sessionId: ctx.sessionManager.getSessionId(), requestedAt };
+export function backgroundOrigin(
+  ctx: Pick<ExtensionContext, "sessionManager">,
+  requestedAt = Date.now(),
+  wakeOnComplete = false,
+): WorkflowBackgroundOrigin {
+  const origin = { sessionId: ctx.sessionManager.getSessionId(), requestedAt };
+  return wakeOnComplete ? { ...origin, wakeOnComplete } : origin;
 }
 
 export function backgroundResultDetails(record: WorkflowRunRecord): BackgroundWorkflowResultDetails {
@@ -336,17 +346,41 @@ function backgroundSummary(record: WorkflowRunRecord): string {
   return summary === undefined ? "Workflow completed. Open run history for the retained result." : truncateText(summary, SUMMARY_LIMIT);
 }
 
-function formatBackgroundDelivery(details: BackgroundWorkflowResultDetails): string {
+/**
+ * The host model only sees this text, never `details`. A woken agent acts on it at once, so it gets the
+ * result as the synchronous tool path renders it; a silent delivery keeps the summary. Both name the run's
+ * files so a later turn can read the retained result.
+ */
+function formatBackgroundDelivery(record: WorkflowRunRecord, details: BackgroundWorkflowResultDetails): string {
+  const woken = record.background?.origin.wakeOnComplete === true;
+  const usage = woken && record.state === "completed" ? formatWorkflowUsageLine(record.usage) : undefined;
   return [
     `## Background workflow: ${details.name}`,
     "",
-    `Run ID: ${details.runId}`,
+    // A resume, including an automatic one, has a new run id; name the run the agent started.
+    details.resumedFromRunId ? `Run ID: ${details.runId} (resumed from ${details.resumedFromRunId})` : `Run ID: ${details.runId}`,
     `State: ${details.status}`,
     "",
-    details.summary,
+    woken ? wokenDeliveryBody(record, details.summary) : details.summary,
+    "",
+    ...backgroundRunFileLines(record),
+    ...(usage === undefined ? [] : [usage]),
   ].join("\n");
 }
 
+function wokenDeliveryBody(record: WorkflowRunRecord, summary: string): string {
+  if (record.state !== "completed") return `Workflow ${record.state}: ${record.message}`;
+  return record.result.kind === "value" ? formatResultForContext(record.result.value) : summary;
+}
+
+/** The retained record, script and journal, relative to the workflow cwd like the synchronous result's lines. */
+function backgroundRunFileLines(record: WorkflowRunRecord): string[] {
+  return [
+    `Record: ${join(WORKFLOW_RUNS_DIR, `${record.runId}${WORKFLOW_RUN_RECORD_SUFFIX}`)}`,
+    ...formatWorkflowRunFileLines(record.runId, record.scriptFile !== undefined),
+  ];
+}
+
 function sessionHasBackgroundDelivery(ctx: ExtensionContext, runId: string): boolean {
   for (const entry of ctx.sessionManager.getEntries()) {
     if (entry.type !== "message" || entry.message.role !== "custom") continue;
@@ -361,6 +395,15 @@ function isPendingBackgroundOutcome(record: WorkflowRunRecord): record is Workfl
   return record.background?.delivery.state === "pending" && isDeliverableState(record.state);
 }
 
+/**
+ * A run started under Dynamax wakes the agent to act on its result; others arrive silently. So does a run
+ * the user stopped, or one paused with a resume already scheduled, whose successor wakes it instead.
+ */
+function wakesAgent(record: WorkflowRunRecord): boolean {
+  if (record.background?.origin.wakeOnComplete !== true || record.state === "stopped") return false;
+  return !(record.state === "paused" && record.pause?.autoResume === true);
+}
+
 function isDeliverableState(state: WorkflowRunState): state is "completed" | "failed" | "stopped" | "paused" {
   return state === "completed" || state === "failed" || state === "stopped" || state === "paused";
 }

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

@@ -13,6 +13,20 @@ export class WorkflowPauseError extends WorkflowAbortError {
   }
 }
 
+/**
+ * Abort reason for one agent the user skipped from the inspector. It deliberately does not extend
+ * WorkflowAbortError: the run carries on, so `parallel()`/`pipeline()` turn the skipped branch into a
+ * `null` slot while a direct `await agent()` sees this error.
+ */
+export class WorkflowAgentSkippedError extends Error {
+  override readonly name = "WorkflowAgentSkippedError";
+  readonly code = "WORKFLOW_AGENT_SKIPPED";
+
+  constructor(readonly label: string) {
+    super(`Workflow agent "${label}" was skipped by the user.`);
+  }
+}
+
 export function abortReason(signal: AbortSignal | undefined): Error {
   const reason = signal?.reason;
   if (safeInstanceOf(reason, Error)) return reason;

package/.pi/extensions/pi-workflow-engine/src/codemode-slots.ts

@@ -0,0 +1,73 @@
+import type { AgentSession, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import { Semaphore } from "./concurrency.ts";
+
+/**
+ * pi runs at most this many codemode scripts per process, and rejects one more with "Codemode worker
+ * limit reached" instead of waiting (pi 1.3 `extensions/codemode/execute.js`). Every subagent shares
+ * that limit with the others and with the host, so a fan-out of codemode agents would fail calls.
+ */
+export const CODEMODE_WORKER_SLOTS = 2;
+
+const processSlots = new Semaphore(CODEMODE_WORKER_SLOTS);
+
+/**
+ * Queue a subagent's top-level calls to `toolName` for one of the process-wide codemode slots, so a
+ * call waits for a running script instead of failing. pi frees its own slot only once the worker has
+ * exited, which can lag the result on Bun, so a call can still meet pi's limit now and then. The host's
+ * own codemode calls are not queued. A session using it must run its tool calls one at a time
+ * ({@link runToolCallsSequentially}).
+ */
+export function createCodemodeSlotExtension(toolName: string, slots: Semaphore = processSlots): ExtensionFactory {
+  return (pi) => {
+    const held = new Map<string, () => void>();
+    const release = (toolCallId: string): void => {
+      held.get(toolCallId)?.();
+      held.delete(toolCallId);
+    };
+    // A call another handler blocks after this one took a slot never runs, so the turn's end frees it.
+    const releaseAll = (): void => {
+      for (const toolCallId of [...held.keys()]) release(toolCallId);
+    };
+
+    pi.on("tool_call", async (event, ctx) => {
+      // A script's nested calls run inside the slot its own call holds.
+      if (event.toolName !== toolName || event.parentToolCallId !== undefined) return undefined;
+      // Rejects while queued once the agent is aborted; pi then blocks the call.
+      await new Promise<void>((acquired, failed) => {
+        slots
+          .run(
+            () =>
+              new Promise<void>((done) => {
+                held.set(event.toolCallId, done);
+                acquired();
+              }),
+            { signal: ctx.signal },
+          )
+          .catch(failed);
+      });
+      return undefined;
+    });
+    pi.on("tool_execution_end", (event) => release(event.toolCallId));
+    pi.on("tool_result", (event) => {
+      release(event.toolCallId);
+      return undefined;
+    });
+    pi.on("turn_end", () => {
+      releaseAll();
+      return undefined;
+    });
+    pi.on("session_shutdown", releaseAll);
+  };
+}
+
+/**
+ * Run a codemode session's tool calls one at a time. pi's default "parallel" execution runs every call's
+ * `tool_call` hook before it executes any (pi-agent-core `executeToolCallsParallel`), so a message with
+ * more codemode calls than free slots would leave the calls holding slots waiting on the one queued
+ * behind them until the agent timed out, and starve every other codemode agent. In order, each call
+ * has freed its slot before the next call asks for one. pi then also runs the calls a script makes one
+ * at a time (`NestedToolCallRunner`).
+ */
+export function runToolCallsSequentially(session: Pick<AgentSession, "agent">): void {
+  session.agent.toolExecution = "sequential";
+}

package/.pi/extensions/pi-workflow-engine/src/config-file.ts

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isMissingPathError } from "./filesystem-error.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/** A JSON config that lives once per user and once per project, the project file overriding the user one. */
+export interface ConfigFilePaths {
+  readonly user: string;
+  readonly project: string;
+}
+
+export function configFilePaths(fileName: string, cwd: string, agentDir: string = getAgentDir()): ConfigFilePaths {
+  return {
+    user: join(agentDir, fileName),
+    project: join(cwd, ".pi", fileName),
+  };
+}
+
+/** The parsed JSON at `configPath`, or undefined when there is no file. `label` names the config in errors. */
+export function readJsonConfigFile(configPath: string, label: string): unknown {
+  let contents: string;
+  try {
+    contents = readFileSync(configPath, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    throw new Error(`Could not read ${label} at ${configPath}: ${unknownErrorMessage(error)}. Fix the file permissions or remove the file.`);
+  }
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${label} at ${configPath}: ${unknownErrorMessage(error)}. Fix or remove the file.`);
+  }
+}
+
+/** Replace `configPath` atomically, so a concurrent reader sees the old file or the new one. */
+export function writeJsonConfigFile(configPath: string, value: unknown, label: string): void {
+  const temporaryPath = `${configPath}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    mkdirSync(dirname(configPath), { recursive: true });
+    writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+    renameSync(temporaryPath, configPath);
+  } catch (error) {
+    try {
+      unlinkSync(temporaryPath);
+    } catch {
+      // Best effort: preserve the original write error.
+    }
+    throw new Error(`Could not write ${label} at ${configPath}: ${unknownErrorMessage(error)}.`);
+  }
+}

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

@@ -4,18 +4,75 @@ import { pathToFileURL } from "node:url";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { LoadedWorkflow, WorkflowSourceIdentity } from "./types.ts";
 import type { PerfSink } from "./perf.ts";
+import { compileInlineWorkflow, inlineScriptFingerprint } from "./inline-workflow.ts";
 import { loadWorkflow, parseWorkflowModule } from "./workflow-module.ts";
 import { BUILTIN_SOURCE_ROOT, BUILTIN_WORKFLOW_DEFINITIONS, BUILTIN_WORKFLOW_FILES } from "./workflows.ts";
 import { captureSourceTreeFingerprint, type FingerprintCapture } from "./tree-fingerprint.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
+import { readBoundedScriptFile } from "./workflow-script-file.ts";
 
 export interface DiscoverWorkflowsOptions {
   readonly refresh?: boolean;
   readonly perf?: PerfSink;
   readonly userWorkflowDir?: string;
+  /**
+   * Project root whose `.pi/workflows/*.js` saved scripts load right after the built-ins. Callers omit
+   * it for an untrusted project, which then contributes no workflows.
+   */
+  readonly projectDir?: string;
+}
+
+/**
+ * Built-ins and `.ts` drop-ins hash source trees and import modules, so they load once per directory pair
+ * until a refresh. Saved scripts are not cached: see `discoverWorkflows`.
+ */
+interface CachedModules {
+  readonly builtins: readonly LoadedWorkflow[];
+  readonly repoDynamic: readonly LoadedWorkflow[];
+  readonly userDynamic: readonly LoadedWorkflow[];
+}
+
+const moduleCache = new Map<string, CachedModules>();
+
+/** Saved scripts are re-read on every discovery, so each distinct skip is reported once, not on every lookup. */
+const reportedScriptSkips = new Set<string>();
+
+function isWorkflowFileCandidate(name: string, extension: string): boolean {
+  return name.endsWith(extension) && !name.startsWith("_") && !name.startsWith(".");
+}
+
+/**
+ * Load every `*.js` saved workflow in the inline script format from a directory. Unlike `.ts` drop-ins
+ * they are compiled with the injected `Type`, so they share pi's typebox, and a content fingerprint is
+ * their whole identity, so they replay on resume.
+ */
+async function loadScriptDir(dir: string): Promise<LoadedWorkflow[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const workflows: LoadedWorkflow[] = [];
+  for (const name of entries.filter((entry) => isWorkflowFileCandidate(entry, ".js")).sort()) {
+    const path = join(dir, name);
+    try {
+      // Discovery runs on every lookup, so a linked FIFO or huge file must not stall it.
+      const source = await readBoundedScriptFile(path, path);
+      const compiled = compileInlineWorkflow(source);
+      workflows.push(loadWorkflow(compiled, { kind: "file", path, root: dir, fingerprint: inlineScriptFingerprint(source), selfContained: true }));
+    } catch (error) {
+      const note = `[workflow-engine] skipped ${name}: ${unknownErrorMessage(error)}`;
+      const key = `${path}\0${note}`;
+      if (!reportedScriptSkips.has(key)) {
+        reportedScriptSkips.add(key);
+        console.error(note);
+      }
+    }
+  }
+  return workflows;
 }
 
-const discoveryCache = new Map<string, Map<string, LoadedWorkflow>>();
 /** Best-effort dynamic load of every `*.ts` workflow in a directory. */
 async function loadDir(
   dir: string,
@@ -29,9 +86,7 @@ async function loadDir(
   } catch {
     return [];
   }
-  const candidates = entries.filter(
-    (name) => !excludeFiles.has(name) && name.endsWith(".ts") && !name.startsWith("_") && !name.startsWith("."),
-  );
+  const candidates = entries.filter((name) => !excludeFiles.has(name) && isWorkflowFileCandidate(name, ".ts"));
   // The shipped workflows/ dir holds only excluded built-ins; skip the tree hash when nothing will be imported.
   if (candidates.length === 0) return [];
 
@@ -56,72 +111,86 @@ async function loadDir(
 }
 
 /**
- * All available workflows by name. Static registry wins on name collisions, so the
- * bundled example is always the verified one even if a same-named file is dropped in.
+ * All available workflows by name. The first source to define a name wins: the static registry, so
+ * the bundled example is always the verified one even if a same-named file is dropped in, then the
+ * project's saved scripts, the extension's `.ts` drop-ins, the user's saved scripts, and the user's
+ * `.ts` drop-ins.
+ *
+ * Saved scripts are read and compiled on every call (small files, no import), so one written or edited
+ * mid-session resolves by name with its current content; built-ins and `.ts` drop-ins come from the cache
+ * unless `refresh` is set.
  */
 export async function discoverWorkflows(repoDir: string, options: DiscoverWorkflowsOptions = {}): Promise<Map<string, LoadedWorkflow>> {
   const userWorkflowDir = options.userWorkflowDir ?? join(getAgentDir(), "workflows");
+  const projectWorkflowDir = options.projectDir === undefined ? undefined : join(options.projectDir, ".pi", "workflows");
+  return await timed(options.perf, "discovery.total_ms", async () => {
+    const [modules, projectScripts, userScripts] = await Promise.all([
+      cachedModules(repoDir, userWorkflowDir, options),
+      projectWorkflowDir === undefined
+        ? []
+        : timed(options.perf, "discovery.project_scripts_ms", () => loadScriptDir(projectWorkflowDir)),
+      timed(options.perf, "discovery.user_scripts_ms", () => loadScriptDir(userWorkflowDir)),
+    ]);
+    const byName = new Map<string, LoadedWorkflow>();
+    for (const mod of [...modules.builtins, ...projectScripts, ...modules.repoDynamic, ...userScripts, ...modules.userDynamic]) {
+      if (!byName.has(mod.meta.name)) byName.set(mod.meta.name, mod);
+    }
+    return byName;
+  });
+}
+
+async function cachedModules(repoDir: string, userWorkflowDir: string, options: DiscoverWorkflowsOptions): Promise<CachedModules> {
   const cacheKey = `${repoDir}\0${userWorkflowDir}`;
-  const cached = discoveryCache.get(cacheKey);
+  const cached = moduleCache.get(cacheKey);
   if (cached && !options.refresh) {
     options.perf?.counter("discovery.cache_hit");
-    return new Map(cached);
+    return cached;
   }
 
-  const byName = await timed(options.perf, "discovery.total_ms", async () => {
-    const next = new Map<string, LoadedWorkflow>();
-    const builtinSource = await captureSourceTreeFingerprint(BUILTIN_SOURCE_ROOT);
-    for (const definition of BUILTIN_WORKFLOW_DEFINITIONS) {
-      const source: WorkflowSourceIdentity =
-        builtinSource.kind === "verified"
-          ? {
-              kind: "file",
-              path: definition.path,
-              root: BUILTIN_SOURCE_ROOT,
-              fingerprint: builtinSource.fingerprint,
-            }
-          : {
-              kind: "unverifiable",
-              reason: `built-in workflow source capture failed: ${builtinSource.reason}`,
-            };
-      next.set(definition.module.meta.name, loadWorkflow(definition.module, source));
-    }
-
-    const repoWorkflowDir = join(repoDir, "workflows");
-    // The shipped extension dir is both the built-in root and the drop-in root; hash that tree once.
-    const repoProvenance =
-      resolve(repoDir) === resolve(BUILTIN_SOURCE_ROOT) ? async () => builtinSource : () => captureSourceTreeFingerprint(repoDir);
-    const [repoDynamic, userDynamic] = await Promise.all([
-      timed(options.perf, "discovery.repo_dir_ms", () =>
-        loadDir(
-          repoWorkflowDir,
-          () => ({
+  const builtinSource = await captureSourceTreeFingerprint(BUILTIN_SOURCE_ROOT);
+  const builtins = BUILTIN_WORKFLOW_DEFINITIONS.map((definition) => {
+    const source: WorkflowSourceIdentity =
+      builtinSource.kind === "verified"
+        ? {
+            kind: "file",
+            path: definition.path,
+            root: BUILTIN_SOURCE_ROOT,
+            fingerprint: builtinSource.fingerprint,
+          }
+        : {
             kind: "unverifiable",
-            reason: "dynamic workflow module graphs are not loaded from an immutable source snapshot",
-          }),
-          BUILTIN_WORKFLOW_FILES,
-          repoProvenance,
-        ),
-      ),
-      timed(options.perf, "discovery.user_dir_ms", () =>
-        loadDir(userWorkflowDir, () => ({
+            reason: `built-in workflow source capture failed: ${builtinSource.reason}`,
+          };
+    return loadWorkflow(definition.module, source);
+  });
+
+  const repoWorkflowDir = join(repoDir, "workflows");
+  // The shipped extension dir is both the built-in root and the drop-in root; hash that tree once.
+  const repoProvenance =
+    resolve(repoDir) === resolve(BUILTIN_SOURCE_ROOT) ? async () => builtinSource : () => captureSourceTreeFingerprint(repoDir);
+  const [repoDynamic, userDynamic] = await Promise.all([
+    timed(options.perf, "discovery.repo_dir_ms", () =>
+      loadDir(
+        repoWorkflowDir,
+        () => ({
           kind: "unverifiable",
-          reason: "dynamic user workflow dependencies do not have a declared trusted source root",
-        })),
+          reason: "dynamic workflow module graphs are not loaded from an immutable source snapshot",
+        }),
+        BUILTIN_WORKFLOW_FILES,
+        repoProvenance,
       ),
-    ]);
-
-    for (const mod of repoDynamic) {
-      if (!next.has(mod.meta.name)) next.set(mod.meta.name, mod);
-    }
-    for (const mod of userDynamic) {
-      if (!next.has(mod.meta.name)) next.set(mod.meta.name, mod);
-    }
-    return next;
-  });
+    ),
+    timed(options.perf, "discovery.user_dir_ms", () =>
+      loadDir(userWorkflowDir, () => ({
+        kind: "unverifiable",
+        reason: "dynamic user workflow dependencies do not have a declared trusted source root",
+      })),
+    ),
+  ]);
 
-  discoveryCache.set(cacheKey, byName);
-  return new Map(byName);
+  const modules: CachedModules = { builtins, repoDynamic, userDynamic };
+  moduleCache.set(cacheKey, modules);
+  return modules;
 }
 
 async function timed<T>(perf: PerfSink | undefined, name: string, fn: () => Promise<T>): Promise<T> {