pi-workflow-engine 1.0.0 → 1.2.0

package/.pi/extensions/pi-workflow-engine/src/workflow-run-controller.ts

@@ -6,7 +6,7 @@ import type {
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
 import { BackgroundWorkflowCoordinator } from "./background-workflows.ts";
 import { backgroundUnavailableResult, startBackgroundWorkflowTool } from "./background-workflow-tool.ts";
-import { validateWorkflowRunId } from "./journal.ts";
+import { validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
 import { resolveWorkflowRunOptions, type ResolvedWorkflowRunOptions } from "./options.ts";
 import type { LoadedWorkflow } from "./types.ts";
 import {
@@ -17,15 +17,19 @@ import {
   formatWorkflowRunSummary,
   isWorkflowRunLifecycleAction,
   parseWorkflowRunsCommand,
+  isInlineWorkflowRun,
   retainedWorkflowRunOutcome,
   supersedingRuns,
   WORKFLOW_RUN_ACTIONS,
   WORKFLOW_RUN_HISTORY_LIMIT,
+  workflowRunDisplayName,
   type WorkflowRunActionContext,
   type WorkflowRunLifecycleAction,
 } from "./workflow-run-history.ts";
-import { stopWorkflowRunRecord, type WorkflowRunRecord } from "./workflow-run-record.ts";
-import { ProjectWorkflowRunStore, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { stopWorkflowRunRecord, workflowRunScriptFile, type WorkflowRunRecord } from "./workflow-run-record.ts";
+import { verifyWorkflowRunScriptSeal } from "./workflow-run-seal.ts";
+import { ProjectWorkflowRunStore, readWorkflowRunScript, type WorkflowRunStore } from "./workflow-run-store.ts";
+import { compileInlineWorkflow, inlineScriptFingerprint } from "./inline-workflow.ts";
 import { unknownErrorMessage } from "./unknown-error.ts";
 import {
   WorkflowUsageLimitScheduler,
@@ -39,7 +43,8 @@ import { completeCurrentArgument, splitArgumentPrefix } from "./command-completi
 type WorkflowRunCompletionContext = Pick<ExtensionContext, "cwd" | "sessionManager">;
 
 interface WorkflowRunControllerDependencies {
-  readonly resolveWorkflow: (name: string) => Promise<LoadedWorkflow | undefined>;
+  /** The registered workflow a relaunch runs; `ctx` decides which project's saved workflows are visible. */
+  readonly resolveWorkflow: (name: string, ctx: ExtensionContext) => Promise<LoadedWorkflow | undefined>;
   readonly execute: (
     ctx: ExtensionContext,
     name: string,
@@ -160,7 +165,7 @@ export class WorkflowRunController {
       }
       const actions = availableWorkflowRunActions(record, runs);
       const selectedAction = await ctx.ui.select(
-        `${record.workflow.name} · ${record.runId}`,
+        `${workflowRunDisplayName(record)} · ${record.runId}`,
         [...actions],
       );
       const action = actions.find((candidate) => candidate === selectedAction);
@@ -232,14 +237,10 @@ export class WorkflowRunController {
   ): Promise<string> {
     const unavailable = backgroundUnavailableResult(ctx.mode);
     if (unavailable) throw new Error(unavailable.content[0].text);
-    const workflow = await this.dependencies.resolveWorkflow(record.workflow.name);
-    if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
-    if (workflow.source.kind !== "file") {
-      throw new Error(`registered workflow ${record.workflow.name} no longer has verifiable file provenance`);
-    }
+    const { workflow, fingerprint } = await this.relaunchWorkflow(ctx, record);
     if (
       action === "resume"
-      && workflow.source.fingerprint !== record.workflow.sourceFingerprint
+      && fingerprint !== record.workflow.sourceFingerprint
     ) {
       throw new Error("workflow source changed, so journal replay cannot resume safely");
     }
@@ -264,6 +265,8 @@ export class WorkflowRunController {
       ctx,
       name: workflow.meta.name,
       options,
+      // A relaunch continues the original run, so it delivers the way that run would have.
+      wakeOnComplete: record.background?.origin.wakeOnComplete === true,
       execute: (backgroundCtx, backgroundOptions) =>
         this.dependencies.execute(backgroundCtx, workflow.meta.name, workflow, backgroundOptions),
     });
@@ -272,6 +275,35 @@ export class WorkflowRunController {
     return message;
   }
 
+  /** The module a relaunch runs: an inline run's persisted script, else the registered workflow of the same name. */
+  private async relaunchWorkflow(
+    ctx: ExtensionContext,
+    record: WorkflowRunRecord,
+  ): Promise<{ readonly workflow: LoadedWorkflow; readonly fingerprint: string }> {
+    if (record.workflow.sourceKind === "fingerprint") {
+      if (record.scriptFile === undefined) throw new Error(`inline workflow ${record.workflow.name} did not retain its script`);
+      const fingerprint = await sealedFingerprint(record);
+      let source: string;
+      try {
+        source = await readWorkflowRunScript(ctx.cwd, record.runId);
+      } catch (error) {
+        throw new Error(`inline workflow script ${record.scriptFile} is unavailable: ${unknownErrorMessage(error)}`);
+      }
+      if (inlineScriptFingerprint(source) !== fingerprint) throw new Error(unsealedRunMessage(record));
+      return { workflow: compileInlineWorkflow(source), fingerprint };
+    }
+    const workflow = await this.dependencies.resolveWorkflow(record.workflow.name, ctx);
+    if (!workflow) throw new Error(`registered workflow ${record.workflow.name} is unavailable`);
+    if (workflow.source.kind !== "file") {
+      throw new Error(`registered workflow ${record.workflow.name} no longer has verifiable file provenance`);
+    }
+    // A repository can also ship a saved script under the name a forged record claims.
+    if (workflow.source.selfContained === true && (await sealedFingerprint(record)) !== workflow.source.fingerprint) {
+      throw new Error(unsealedRunMessage(record));
+    }
+    return { workflow, fingerprint: workflow.source.fingerprint };
+  }
+
   private async autoResume(ctx: ExtensionContext, runId: string, attempt: number): Promise<void> {
     const record = await this.loadRecord(ctx.cwd, runId);
     if (
@@ -326,7 +358,7 @@ export class WorkflowRunController {
         .filter((record) => availableWorkflowRunActions(record, runs).includes(action))
         .map((record) => ({
           value: record.runId,
-          description: `${record.state} · ${record.workflow.name}`,
+          description: `${record.state} · ${workflowRunDisplayName(record)}`,
         })),
     );
   }
@@ -340,12 +372,36 @@ export class WorkflowRunController {
       { value: "last", description: "Inspect the current or most recent in-session workflow" },
       ...records.map((record) => ({
         value: record.runId,
-        description: `${record.state} · ${record.workflow.name}`,
+        description: `${record.state} · ${workflowRunDisplayName(record)}`,
       })),
     ]);
   }
 }
 
+/**
+ * The fingerprint a script-sourced record's seal covers. A repository can ship a record of its own, so
+ * the seal is checked before any script is read; it is this install's, over the script as recorded.
+ */
+async function sealedFingerprint(record: WorkflowRunRecord): Promise<string> {
+  const fingerprint = record.workflow.sourceFingerprint;
+  if (
+    fingerprint === undefined
+    || record.scriptSeal === undefined
+    || !(await verifyWorkflowRunScriptSeal(record.runId, fingerprint, record.scriptSeal))
+  ) {
+    throw new Error(unsealedRunMessage(record));
+  }
+  return fingerprint;
+}
+
+/** Why a script-sourced record will not run, and how to run the script anyway. */
+function unsealedRunMessage(record: WorkflowRunRecord): string {
+  const rerun = isInlineWorkflowRun(record)
+    ? `rerun it with the workflow tool's scriptPath (${WORKFLOW_RUNS_DIR}/${workflowRunScriptFile(record.runId)})`
+    : `run ${record.workflow.name} again by name`;
+  return `${isInlineWorkflowRun(record) ? "inline run" : "run"} ${record.runId} was not recorded by this pi install, or its script changed since; ${rerun}`;
+}
+
 /**
  * Runs that any stored run resumed, whatever that resume's outcome. A resumed run keeps its paused
  * record and pause attempt, so automatic resume treats the pause as spent: re-arming it after a

package/.pi/extensions/pi-workflow-engine/src/workflow-run-history.ts

@@ -86,9 +86,28 @@ export function availableWorkflowRunActions(
 }
 
 export function canRelaunchWorkflowRun(record: WorkflowRunRecord): boolean {
+  return hasRelaunchableWorkflowSource(record) && record.options.argumentsPresent === false;
+}
+
+/**
+ * A registered workflow resolves again by name; an inline one relaunches from the script persisted beside
+ * its record, and only when the record carries a seal. This check is only the seal's presence: relaunch
+ * verifies it, and the script's fingerprint, before running anything.
+ */
+export function hasRelaunchableWorkflowSource(record: WorkflowRunRecord): boolean {
+  if (typeof record.workflow.sourceFingerprint !== "string") return false;
   return record.workflow.sourceKind === "file"
-    && typeof record.workflow.sourceFingerprint === "string"
-    && record.options.argumentsPresent === false;
+    || (isInlineWorkflowRun(record) && record.scriptFile !== undefined && record.scriptSeal !== undefined);
+}
+
+/** A run of an inline script (a tool `script` or `scriptPath`), not of a registered workflow. */
+export function isInlineWorkflowRun(record: WorkflowRunRecord): boolean {
+  return record.workflow.sourceKind === "fingerprint";
+}
+
+/** The run's workflow name, marked when it ran an inline script, so such a record cannot pose as a registered workflow's run. */
+export function workflowRunDisplayName(record: WorkflowRunRecord): string {
+  return isInlineWorkflowRun(record) ? `${record.workflow.name} (inline)` : record.workflow.name;
 }
 
 export function formatWorkflowRunHistory(
@@ -112,7 +131,7 @@ export function formatWorkflowRunSummary(
   const usage = formatWorkflowUsageLine(record.usage);
   const resumedAs = runs.resumedAs.get(record.runId);
   const actions = availableWorkflowRunActions(record, runs).filter((action) => action !== "inspect");
-  return `${record.state.toUpperCase()} ${record.workflow.name} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${resumedAs ? ` · resumed as ${resumedAs}` : ""}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
+  return `${record.state.toUpperCase()} ${workflowRunDisplayName(record)} · age ${formatDuration(Math.max(0, now - record.createdAt))} · duration ${formatWorkflowRunDuration(record, now)}${usage ? ` · ${usage}` : ""} · ${record.runId}${resumedAs ? ` · resumed as ${resumedAs}` : ""}${actions.length > 0 ? ` · actions ${actions.join(", ")}` : ""}`;
 }
 
 export function formatWorkflowRunDetails(
@@ -127,7 +146,7 @@ export function formatWorkflowRunDetails(
   const usage = formatWorkflowUsageLine(record.usage);
   const lines = [
     `Workflow run ${record.runId}`,
-    `Workflow: ${record.workflow.name}`,
+    `Workflow: ${workflowRunDisplayName(record)}`,
     `State: ${record.state.toUpperCase()}`,
     `Age: ${formatDuration(Math.max(0, now - record.createdAt))}`,
     `Duration: ${formatWorkflowRunDuration(record, now)}`,

package/.pi/extensions/pi-workflow-engine/src/workflow-run-record.ts

@@ -17,8 +17,10 @@ import {
   isPersistedWorkflowBackground,
   type PersistedWorkflowBackground,
 } from "./workflow-run-background.ts";
+import { isWorkflowRunScriptSeal } from "./workflow-run-seal.ts";
 
 export const WORKFLOW_RUN_RECORD_VERSION = 1;
+export const WORKFLOW_RUN_SCRIPT_SUFFIX = ".script.js";
 
 const MAX_RESULT_BYTES = 1 << 20;
 const MAX_RESULT_DEPTH = 64;
@@ -97,6 +99,14 @@ interface WorkflowRunRecordBase {
   readonly runId: string;
   readonly workflow: PersistedWorkflowIdentity;
   readonly journalFile: string;
+  /** An inline run's script, persisted beside the record; prompts in it never enter the record itself. */
+  readonly scriptFile?: string;
+  /**
+   * This install's HMAC over the run id and source fingerprint, proving the engine recorded the script
+   * rather than a repository shipping it. A run of an inline or saved script relaunches from
+   * `/workflow:runs` only with one.
+   */
+  readonly scriptSeal?: string;
   readonly options: PersistedWorkflowRunOptions;
   readonly createdAt: number;
   readonly updatedAt: number;
@@ -125,6 +135,10 @@ export function createWorkflowRunRecord(input: {
   readonly options: ResolvedWorkflowRunOptions;
   readonly progress: WorkflowProgressSnapshot;
   readonly argumentsPresent?: boolean;
+  /** Whether the run's inline script was persisted beside the record. */
+  readonly scriptPersisted?: boolean;
+  /** The run's script seal; see {@link WorkflowRunRecordBase.scriptSeal}. */
+  readonly scriptSeal?: string;
 }): WorkflowRunRecord {
   const runId = validateWorkflowRunId(input.runId);
   assertMatchingRun(runId, input.progress.runId);
@@ -134,6 +148,8 @@ export function createWorkflowRunRecord(input: {
     state: "queued",
     workflow: persistedWorkflowIdentity(input.workflow),
     journalFile: `${runId}.jsonl`,
+    scriptFile: input.scriptPersisted ? workflowRunScriptFile(runId) : undefined,
+    scriptSeal: input.scriptSeal,
     options: persistedWorkflowRunOptions(input.options, input.argumentsPresent ?? false),
     createdAt: input.progress.startedAt,
     updatedAt: input.progress.startedAt,
@@ -142,6 +158,11 @@ export function createWorkflowRunRecord(input: {
   };
 }
 
+/** The persisted script's file name in the runs directory. */
+export function workflowRunScriptFile(runId: string): string {
+  return `${runId}${WORKFLOW_RUN_SCRIPT_SUFFIX}`;
+}
+
 export function updateWorkflowRunProgress(
   record: WorkflowRunRecord,
   progress: WorkflowProgressSnapshot,
@@ -169,6 +190,8 @@ export function transitionWorkflowRun(record: WorkflowRunRecord, transition: Wor
     runId: record.runId,
     workflow: record.workflow,
     journalFile: record.journalFile,
+    scriptFile: record.scriptFile,
+    scriptSeal: record.scriptSeal,
     options: record.options,
     createdAt: record.createdAt,
     updatedAt: at,
@@ -475,6 +498,9 @@ export function isWorkflowRunRecord(value: unknown): value is WorkflowRunRecord
   if (!isValidRunId(value.runId) || !isWorkflowRunState(value.state)) return false;
   if (!isPersistedWorkflowIdentity(value.workflow) || !isPersistedWorkflowRunOptions(value.options)) return false;
   if (value.journalFile !== `${value.runId}.jsonl`) return false;
+  if (value.scriptFile !== undefined && value.scriptFile !== workflowRunScriptFile(value.runId)) return false;
+  // A seal covers an inline run's persisted script or a saved script, which resolves again by name.
+  if (value.scriptSeal !== undefined && (!isWorkflowRunScriptSeal(value.scriptSeal) || (value.scriptFile === undefined && value.workflow.sourceKind !== "file"))) return false;
   if (!isFiniteNumber(value.createdAt) || !isFiniteNumber(value.updatedAt)) return false;
   if (value.startedAt !== undefined && !isFiniteNumber(value.startedAt)) return false;
   if (value.endedAt !== undefined && !isFiniteNumber(value.endedAt)) return false;
@@ -568,7 +594,7 @@ function isPhaseSnapshot(value: unknown): boolean {
 
 function isAgentSnapshot(value: unknown): boolean {
   if (!isRecord(value) || !isFiniteNumber(value.id) || typeof value.label !== "string") return false;
-  if (value.status !== "queued" && value.status !== "running" && value.status !== "done" && value.status !== "failed") return false;
+  if (value.status !== "queued" && value.status !== "running" && value.status !== "done" && value.status !== "failed" && value.status !== "skipped") return false;
   if (!isFiniteNumber(value.toolUses)) return false;
   if (value.startedAt !== undefined && !isFiniteNumber(value.startedAt)) return false;
   if (value.doneAt !== undefined && !isFiniteNumber(value.doneAt)) return false;

package/.pi/extensions/pi-workflow-engine/src/workflow-run-seal.ts

@@ -0,0 +1,83 @@
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { link, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isExistingPathError, isMissingPathError } from "./filesystem-error.ts";
+
+/**
+ * The per-install key that seals inline run scripts, in pi's agent directory. It lives outside every
+ * project, so a repository can ship run records and scripts but never a seal this install accepts.
+ */
+export const WORKFLOW_RUN_SEAL_KEY_FILE = "workflow-run-seal.key";
+
+const KEY_BYTES = 32;
+const HEX_256 = /^[0-9a-f]{64}$/;
+
+/** Whether `value` has a seal's shape; only {@link verifyWorkflowRunScriptSeal} says whether it is genuine. */
+export function isWorkflowRunScriptSeal(value: unknown): value is string {
+  return typeof value === "string" && HEX_256.test(value);
+}
+
+/** The seal a run record carries for its persisted inline script, creating this install's key on first use. */
+export async function sealWorkflowRunScript(
+  runId: string,
+  sourceFingerprint: string,
+  agentDir: string = getAgentDir(),
+): Promise<string> {
+  const path = join(agentDir, WORKFLOW_RUN_SEAL_KEY_FILE);
+  return runSeal((await readSealKey(path)) ?? (await createSealKey(agentDir, path)), runId, sourceFingerprint);
+}
+
+/** Whether this install sealed `sourceFingerprint` for `runId`. Never creates a key: without one, nothing was sealed here. */
+export async function verifyWorkflowRunScriptSeal(
+  runId: string,
+  sourceFingerprint: string,
+  seal: string,
+  agentDir: string = getAgentDir(),
+): Promise<boolean> {
+  if (!isWorkflowRunScriptSeal(seal)) return false;
+  const key = await readSealKey(join(agentDir, WORKFLOW_RUN_SEAL_KEY_FILE));
+  if (key === undefined) return false;
+  return timingSafeEqual(Buffer.from(runSeal(key, runId, sourceFingerprint), "hex"), Buffer.from(seal, "hex"));
+}
+
+function runSeal(key: Buffer, runId: string, sourceFingerprint: string): string {
+  return createHmac("sha256", key).update(`${runId}\0${sourceFingerprint}`).digest("hex");
+}
+
+async function readSealKey(path: string): Promise<Buffer | undefined> {
+  let content: string;
+  try {
+    content = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissingPathError(error)) return undefined;
+    throw error;
+  }
+  const hex = content.trim();
+  if (!HEX_256.test(hex)) {
+    throw new Error(`workflow run seal key ${path} is malformed; delete it to create a new one, which retires every existing seal`);
+  }
+  return Buffer.from(hex, "hex");
+}
+
+/**
+ * Publish a new key with an exclusive hard link from a complete temporary file, so a concurrent reader
+ * never sees a partial key. When another process published one first, its key wins and is read back.
+ */
+async function createSealKey(agentDir: string, path: string): Promise<Buffer> {
+  await mkdir(agentDir, { recursive: true });
+  const key = randomBytes(KEY_BYTES);
+  const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporaryPath, `${key.toString("hex")}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await link(temporaryPath, path);
+    return key;
+  } catch (error) {
+    if (!isExistingPathError(error)) throw error;
+    const existing = await readSealKey(path);
+    if (existing === undefined) throw error;
+    return existing;
+  } finally {
+    await rm(temporaryPath, { force: true }).catch(() => undefined);
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/workflow-run-store.ts

@@ -1,12 +1,14 @@
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
+import { ensureWorkflowRunsDir, validateWorkflowRunId, WORKFLOW_RUNS_DIR } from "./journal.ts";
 import type { WorkflowProgressSnapshot } from "./progress-types.ts";
 import {
   isWorkflowRunRecord,
   transitionWorkflowRun,
   updateWorkflowRunProgress,
+  WORKFLOW_RUN_SCRIPT_SUFFIX,
+  workflowRunScriptFile,
   type WorkflowRunRecord,
   type WorkflowRunState,
   type WorkflowRunTransition,
@@ -34,7 +36,7 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
     if (Buffer.byteLength(content) > MAX_RECORD_BYTES) {
       throw new Error(`Workflow run record exceeded ${MAX_RECORD_BYTES} bytes.`);
     }
-    await mkdir(dirname(path), { recursive: true });
+    await ensureWorkflowRunsDir(dirname(path));
     try {
       await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
       await rename(temporaryPath, path);
@@ -70,7 +72,12 @@ export class ProjectWorkflowRunStore implements WorkflowRunStore {
       .filter((entry): entry is { readonly path: string; readonly mtimeMs: number } => entry !== undefined)
       .sort((left, right) => right.mtimeMs - left.mtimeMs)
       .slice(Math.max(0, keep));
-    await Promise.all(stale.map((entry) => rm(entry.path, { force: true }).catch(() => undefined)));
+    // A pruned record takes its persisted script with it: scripts are only ever reached through their record.
+    const paths = stale.flatMap((entry) => [
+      entry.path,
+      `${entry.path.slice(0, -WORKFLOW_RUN_RECORD_SUFFIX.length)}${WORKFLOW_RUN_SCRIPT_SUFFIX}`,
+    ]);
+    await Promise.all(paths.map((path) => rm(path, { force: true }).catch(() => undefined)));
   }
 
   /** Record file paths in the runs directory; empty when the directory cannot be read. */
@@ -153,6 +160,25 @@ export function workflowRunRecordPath(cwd: string, runId: string): string {
   return join(cwd, WORKFLOW_RUNS_DIR, `${validateWorkflowRunId(runId)}${WORKFLOW_RUN_RECORD_SUFFIX}`);
 }
 
+export function workflowRunScriptPath(cwd: string, runId: string): string {
+  return join(cwd, WORKFLOW_RUNS_DIR, workflowRunScriptFile(validateWorkflowRunId(runId)));
+}
+
+/**
+ * Persist an inline run's script beside its record, which redacts prompts and so cannot hold it. This
+ * adds no new exposure: pi's session transcript already holds the script as the tool call's arguments.
+ */
+export async function persistWorkflowRunScript(cwd: string, runId: string, source: string): Promise<string> {
+  const path = workflowRunScriptPath(cwd, runId);
+  await ensureWorkflowRunsDir(dirname(path));
+  await writeFile(path, source, { encoding: "utf8", mode: 0o600 });
+  return path;
+}
+
+export async function readWorkflowRunScript(cwd: string, runId: string): Promise<string> {
+  return await readFile(workflowRunScriptPath(cwd, runId), "utf8");
+}
+
 async function loadWorkflowRunRecord(path: string): Promise<WorkflowRunRecord | undefined> {
   try {
     const content = await readFile(path, "utf8");

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

@@ -0,0 +1,50 @@
+import type { Stats } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+import { compileInlineWorkflow } from "./inline-workflow.ts";
+import type { LoadedWorkflow } from "./types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/** The largest script file a `scriptPath` may name; real workflow scripts are a few kilobytes. */
+export const MAX_WORKFLOW_SCRIPT_FILE_BYTES = 1 << 20;
+
+/** A `scriptPath` that cannot be read. */
+export class WorkflowScriptPathError extends Error {
+  override readonly name = "WorkflowScriptPathError";
+}
+
+/**
+ * Read an inline-format script named relative to `cwd`. No containment: the script runs with the
+ * extension's access either way, as an inline `script` does.
+ */
+export async function readWorkflowScriptFile(cwd: string, scriptPath: string): Promise<string> {
+  return await readBoundedScriptFile(resolve(cwd, scriptPath), `scriptPath ${scriptPath}`);
+}
+
+/**
+ * Read a workflow script only if it is a regular file within the size limit: a FIFO or device would
+ * block the read or never end. `label` names the file in errors.
+ */
+export async function readBoundedScriptFile(file: string, label: string): Promise<string> {
+  const unreadable = (error: unknown) => new WorkflowScriptPathError(`${label} could not be read: ${unknownErrorMessage(error)}`);
+  let info: Stats;
+  try {
+    info = await stat(file);
+  } catch (error) {
+    throw unreadable(error);
+  }
+  if (!info.isFile()) throw new WorkflowScriptPathError(`${label} is not a regular file`);
+  if (info.size > MAX_WORKFLOW_SCRIPT_FILE_BYTES) {
+    throw new WorkflowScriptPathError(`${label} is ${info.size} bytes, over the ${MAX_WORKFLOW_SCRIPT_FILE_BYTES}-byte limit`);
+  }
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    throw unreadable(error);
+  }
+}
+
+/** Compile a script file exactly like an inline `script`: same contract, injected `Type`, content fingerprint. */
+export async function compileWorkflowScriptFile(cwd: string, scriptPath: string): Promise<LoadedWorkflow> {
+  return compileInlineWorkflow(await readWorkflowScriptFile(cwd, scriptPath));
+}

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

@@ -0,0 +1,147 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { completeCurrentArgument, splitArgumentPrefix } from "./command-completions.ts";
+import { configFilePaths, readJsonConfigFile, writeJsonConfigFile, type ConfigFilePaths } from "./config-file.ts";
+import { isRecord } from "./guards.ts";
+import { DEFAULT_WORKFLOW_MAX_AGENTS } from "./options.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+/**
+ * How large the host should make each workflow it authors. A prompt guideline only: the run's
+ * `maxAgents` limit stays the separate hard cap.
+ */
+export const WORKFLOW_SIZE_GUIDELINES = ["small", "medium", "large", "off"] as const;
+export type WorkflowSizeGuideline = (typeof WORKFLOW_SIZE_GUIDELINES)[number];
+export const DEFAULT_WORKFLOW_SIZE_GUIDELINE: WorkflowSizeGuideline = "medium";
+
+const SIZE_AGENT_LIMITS: Readonly<Record<Exclude<WorkflowSizeGuideline, "off">, number>> = { small: 5, medium: 10, large: 25 };
+const SETTINGS_FILE_NAME = "workflow-settings.json";
+const SETTINGS_LABEL = "workflow settings";
+
+export interface WorkflowSettingsFile {
+  readonly size?: WorkflowSizeGuideline;
+}
+
+export type ResolvedWorkflowSize =
+  | { readonly size: WorkflowSizeGuideline; readonly source: "default" }
+  | { readonly size: WorkflowSizeGuideline; readonly source: "user" | "project"; readonly configPath: string };
+
+export function workflowSettingsPaths(cwd: string, agentDir?: string): ConfigFilePaths {
+  return configFilePaths(SETTINGS_FILE_NAME, cwd, agentDir);
+}
+
+export function isWorkflowSizeGuideline(value: string): value is WorkflowSizeGuideline {
+  return WORKFLOW_SIZE_GUIDELINES.includes(value as WorkflowSizeGuideline);
+}
+
+export function readWorkflowSettingsFile(configPath: string): WorkflowSettingsFile {
+  const parsed = readJsonConfigFile(configPath, SETTINGS_LABEL);
+  if (parsed === undefined) return {};
+  if (!isRecord(parsed)) throw invalidSettings(configPath, "the root must be an object");
+  const unexpected = Object.keys(parsed).find((key) => key !== "size");
+  if (unexpected) throw invalidSettings(configPath, `unexpected key "${unexpected}"`);
+  const { size } = parsed;
+  if (size === undefined) return {};
+  if (typeof size !== "string" || !isWorkflowSizeGuideline(size)) {
+    throw invalidSettings(configPath, '"size" must be small, medium, large, or off');
+  }
+  return { size };
+}
+
+/** The project file wins over the user file, which wins over the default. */
+export function resolveWorkflowSize(paths: ConfigFilePaths): ResolvedWorkflowSize {
+  for (const source of ["project", "user"] as const) {
+    const { size } = readWorkflowSettingsFile(paths[source]);
+    if (size !== undefined) return { size, source, configPath: paths[source] };
+  }
+  return { size: DEFAULT_WORKFLOW_SIZE_GUIDELINE, source: "default" };
+}
+
+export function setWorkflowSize(configPath: string, size: WorkflowSizeGuideline): void {
+  const current = readWorkflowSettingsFile(configPath);
+  writeJsonConfigFile(configPath, { ...current, size }, SETTINGS_LABEL);
+}
+
+/** The catalog line for a size, or undefined when the guideline is off. */
+export function workflowSizeGuidelineLine(size: WorkflowSizeGuideline): string | undefined {
+  if (size === "off") return undefined;
+  return `Workflow size guideline: ${size} — keep each workflow under ${SIZE_AGENT_LIMITS[size]} agents unless the user asks for more; the user changes this with /workflow:size.`;
+}
+
+type WorkflowSizeCommand =
+  | { readonly kind: "status" }
+  | { readonly kind: "set"; readonly size: WorkflowSizeGuideline; readonly scope: keyof ConfigFilePaths }
+  | { readonly kind: "error"; readonly message: string };
+
+const USAGE = "Usage: /workflow:size [small|medium|large|off] [--user|--project]";
+const SIZE_COMPLETIONS = WORKFLOW_SIZE_GUIDELINES.map((value) => ({
+  value,
+  description: value === "off" ? "No size guideline in the prompt" : `Keep each workflow under ${SIZE_AGENT_LIMITS[value]} agents`,
+}));
+const SCOPE_COMPLETIONS = [
+  { value: "--user", description: "Write the user-level workflow settings" },
+  { value: "--project", description: "Write the project-level workflow settings" },
+] as const;
+
+export function parseWorkflowSizeCommand(args: string): WorkflowSizeCommand {
+  const tokens = args.trim().toLowerCase().split(/\s+/).filter(Boolean);
+  const userScope = tokens.includes("--user");
+  const projectScope = tokens.includes("--project");
+  if (userScope && projectScope) return { kind: "error", message: "Choose either --user or --project, not both." };
+  const positional = tokens.filter((token) => token !== "--user" && token !== "--project");
+  if (positional.length === 0) {
+    return userScope || projectScope ? { kind: "error", message: "Name a size to write." } : { kind: "status" };
+  }
+  const [size, ...extra] = positional;
+  if (extra.length > 0 || !size || !isWorkflowSizeGuideline(size)) {
+    return { kind: "error", message: "Size must be small, medium, large, or off." };
+  }
+  return { kind: "set", size, scope: projectScope ? "project" : "user" };
+}
+
+export function workflowSizeArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
+  const { completed } = splitArgumentPrefix(argumentPrefix);
+  if (completed.length === 0) return completeCurrentArgument(argumentPrefix, SIZE_COMPLETIONS);
+  if (completed.length === 1 && isWorkflowSizeGuideline(completed[0] ?? "")) return completeCurrentArgument(argumentPrefix, SCOPE_COMPLETIONS);
+  return null;
+}
+
+export function formatWorkflowSize(resolved: ResolvedWorkflowSize): string {
+  const source = resolved.source === "default" ? "default" : `${resolved.source} config ${resolved.configPath}`;
+  const rule = resolved.size === "off"
+    ? "no size guideline is added to the prompt"
+    : `keep each workflow under ${SIZE_AGENT_LIMITS[resolved.size]} agents unless the user asks for more`;
+  return [
+    `Workflow size guideline: ${resolved.size} (${source}) — ${rule}.`,
+    `The maxAgents run limit (default ${DEFAULT_WORKFLOW_MAX_AGENTS}) stays the hard cap on live agents per run.`,
+  ].join("\n");
+}
+
+/** Register `/workflow:size`; `onChange` lets the session's prompt pick the new guideline up. */
+export function registerWorkflowSizeCommand(pi: Pick<ExtensionAPI, "registerCommand">, onChange: (ctx: ExtensionCommandContext) => void): void {
+  pi.registerCommand("workflow:size", {
+    description: "Show or set the workflow size guideline: /workflow:size [small|medium|large|off] [--user|--project]",
+    getArgumentCompletions: workflowSizeArgumentCompletions,
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const command = parseWorkflowSizeCommand(args);
+      if (command.kind === "error") {
+        ctx.ui.notify(`${command.message}\n${USAGE}`, "warning");
+        return;
+      }
+      try {
+        const paths = workflowSettingsPaths(ctx.cwd);
+        if (command.kind === "set") {
+          setWorkflowSize(paths[command.scope], command.size);
+          onChange(ctx);
+        }
+        ctx.ui.notify(formatWorkflowSize(resolveWorkflowSize(paths)), "info");
+      } catch (error) {
+        ctx.ui.notify(unknownErrorMessage(error), "error");
+      }
+    },
+  });
+}
+
+function invalidSettings(configPath: string, reason: string): Error {
+  return new Error(`Invalid workflow settings at ${configPath}: ${reason}. Fix or remove the file.`);
+}