pi-extensible-workflows 3.0.0 → 3.2.0

package/dist/src/doctor.js

@@ -2,7 +2,9 @@ import { readFileSync, readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { InMemoryCredentialStore } from "@earendil-works/pi-ai";
 import { ModelRuntime, createAgentSessionFromServices, createAgentSessionServices, getAgentDir, hasTrustRequiringProjectResources, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_SETTINGS, loadSettings, resolveAgentResourcePolicy, resolveModelReference, parseRoleMarkdown, registeredWorkflowFunctions, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "./index.js";
+import { DEFAULT_SETTINGS, loadSettings, resolveAgentResourcePolicy, resolveWorkflowSettings, resolveModelReference, parseThinking, parseRoleMarkdown, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "./index.js";
+import { loadingRegistry } from "./registry.js";
+import { disabledResources, unmatchedResourcePatterns } from "./utils.js";
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
 function canonical(path) {
     const absolute = resolve(path);
@@ -13,6 +15,11 @@ function canonical(path) {
         return absolute;
     }
 }
+function isDynamicModelAlias(value, aliases) {
+    const match = /^([^/\s:]+)(?::([^\s]+))?$/.exec(value);
+    const name = match?.[1];
+    return Boolean(name && (match[2] === undefined || parseThinking(match[2]) !== undefined) && aliases.has(name));
+}
 async function readCredentials(agentDir) {
     const credentials = new InMemoryCredentialStore();
     try {
@@ -112,6 +119,30 @@ function roleFilesFrom(dirs) {
     const paths = dirs.flatMap((dir) => roleFiles(dir));
     return [...new Map(paths.map((path) => [basename(path, ".md"), path])).values()].sort();
 }
+function extensionLabel(extension) { return `Extension "${extension.headline}" (${extension.version})`; }
+function scanExtensionRoleFiles(registrations) {
+    const files = [];
+    const empty = [];
+    const errors = [];
+    for (const registration of registrations) {
+        try {
+            const entries = readdirSync(registration.path, { withFileTypes: true });
+            const roleFiles = entries.filter((entry) => entry.isFile() && extname(entry.name) === ".md");
+            if (!roleFiles.length)
+                empty.push(registration);
+            for (const entry of roleFiles)
+                files.push({ name: basename(entry.name, ".md"), path: join(registration.path, entry.name), directory: registration.path, extension: registration.extension });
+        }
+        catch (error) {
+            errors.push({ registration, error });
+        }
+    }
+    files.sort((left, right) => left.name.localeCompare(right.name) || left.path.localeCompare(right.path));
+    return { files, empty, errors };
+}
+function roleProvenance(source) {
+    return source ? `${extensionLabel(source.extension)} role directory "${source.directory}"` : "Role";
+}
 function diagnostic(severity, code, message, source, hint) {
     return { severity, code, message, ...(source ? { source } : {}), ...(hint ? { hint } : {}) };
 }
@@ -119,7 +150,9 @@ function emptyResourcePolicy(globalSettingsPath, cwd, projectTrusted) {
     const empty = { skills: [], extensions: [] };
     return { globalSettingsPath, projectSettingsPath: workflowProjectSettingsPath(cwd), projectTrusted, global: empty, project: empty, effective: empty, unmatchedSkills: [], unmatchedExtensions: [] };
 }
-function validateModel(value, known, available, source, diagnostics, aliases, settingsPath) {
+function validateModel(value, known, available, source, diagnostics, aliases, dynamicAliases, settingsPath) {
+    if (isDynamicModelAlias(value, dynamicAliases))
+        return;
     try {
         const parsed = resolveModelReference(value, aliases, known, settingsPath);
         const name = `${parsed.provider}/${parsed.model}`;
@@ -130,13 +163,14 @@ function validateModel(value, known, available, source, diagnostics, aliases, se
         diagnostics.push(diagnostic("error", "MODEL_INVALID", error.message, source, error.message.includes("thinking") ? THINKING_HINT : "Use provider/model or provider/model:thinking."));
     }
 }
-function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath) {
+function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, source) {
     let definition;
     try {
         definition = parseRoleMarkdown(readFileSync(path, "utf8"), true, path);
     }
     catch (error) {
-        diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", error.message, path, "Fix the role YAML frontmatter."));
+        const message = error instanceof Error ? error.message : String(error);
+        diagnostics.push(diagnostic("error", "ROLE_FRONTMATTER", source ? `${roleProvenance(source)} contains invalid role at "${path}": ${message}` : message, path, "Fix the role YAML frontmatter."));
         return undefined;
     }
     const body = definition.prompt ?? "";
@@ -147,20 +181,18 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
     if (/{{\s*[^{}]+\s*}}/.test(body))
         diagnostics.push(diagnostic("warning", "ROLE_PLACEHOLDER", "Role body contains an unsupported placeholder-looking token", path));
     if (definition.model)
-        validateModel(definition.model, knownModels, availableModels, path, diagnostics, aliases, settingsPath);
+        validateModel(definition.model, knownModels, availableModels, path, diagnostics, aliases, dynamicAliases, settingsPath);
     for (const tool of definition.tools ?? [])
         if (!activeTools.has(tool))
             diagnostics.push(diagnostic("error", "ROLE_TOOL_INACTIVE", `Tool is unknown or inactive: ${tool}`, path, "Use a tool listed under Active tools or enable its Pi extension."));
     return definition;
 }
 function matchResourcePolicy(policy, pi) {
-    const extensions = new Set((pi.extensions ?? []).map(canonical));
-    const skills = new Set(pi.skills ?? []);
-    return { ...policy, unmatchedSkills: policy.effective.skills.filter((name) => !skills.has(name)), unmatchedExtensions: policy.effective.extensions.filter((path) => !extensions.has(canonical(path))) };
-}
-function resourcePolicySource(policy, kind, selector) {
-    return policy.project[kind].includes(selector) && !policy.global[kind].includes(selector) ? policy.projectSettingsPath : policy.globalSettingsPath;
+    const extensions = [...new Set((pi.extensions ?? []).map(canonical))];
+    const skills = [...new Set(pi.skills ?? [])];
+    return { ...policy, excludedSkills: disabledResources(policy.effective.skills, skills), excludedExtensions: disabledResources(policy.effective.extensions, extensions), unmatchedSkills: unmatchedResourcePatterns(policy.effective.skills, skills), unmatchedExtensions: unmatchedResourcePatterns(policy.effective.extensions, extensions) };
 }
+function resourcePolicySource(settingsSource) { return settingsSource; }
 export async function doctor(options = {}) {
     const cwd = canonical(options.cwd ?? process.cwd());
     const agentDir = canonical(options.agentDir ?? getAgentDir());
@@ -173,6 +205,8 @@ export async function doctor(options = {}) {
     catch (error) {
         diagnostics.push(diagnostic("error", "SETTINGS_INVALID", error.message, settingsPath, "Fix or remove the invalid workflow settings file."));
     }
+    let settingsSources = { concurrency: settingsPath, modelAliases: settingsPath, disabledAgentResources: settingsPath };
+    const projectSettingsPath = workflowProjectSettingsPath(cwd);
     let pi;
     try {
         pi = await (options.discoverPi ?? discoverPi)(cwd, agentDir);
@@ -187,41 +221,98 @@ export async function doctor(options = {}) {
         diagnostics.push(diagnostic("warning", "PROJECT_UNTRUSTED", "Pi project resources are inactive because the project is not trusted", cwd, "Open this project in Pi, choose Trust, then rerun doctor."));
     for (const error of pi.extensionErrors)
         diagnostics.push(diagnostic("error", "EXTENSION_LOAD", error.message, error.path, "Fix or disable the failing Pi extension."));
+    try {
+        const resolved = resolveWorkflowSettings(cwd, pi.trust.trusted, settingsPath);
+        settings = resolved.effective;
+        settingsSources = resolved.sources;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const source = message.includes(projectSettingsPath) ? projectSettingsPath : settingsPath;
+        if (!diagnostics.some(({ code, source: itemSource }) => code === "SETTINGS_INVALID" && itemSource === source))
+            diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, source, "Fix or remove the invalid workflow settings file."));
+    }
     let resourcePolicy;
     try {
         resourcePolicy = matchResourcePolicy(resolveAgentResourcePolicy(cwd, pi.trust.trusted, settingsPath), pi);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        if (!diagnostics.some(({ code, source }) => code === "SETTINGS_INVALID" && source === settingsPath))
-            diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, message.includes(".json") ? message.match(/(?:settings: )?([^ )]+\.json)/)?.[1] : undefined, "Fix or remove the invalid workflow settings file."));
+        const source = message.includes(projectSettingsPath) ? projectSettingsPath : settingsPath;
+        if (!diagnostics.some(({ code, source: itemSource }) => code === "SETTINGS_INVALID" && itemSource === source))
+            diagnostics.push(diagnostic("error", "SETTINGS_INVALID", message, source, "Fix or remove the invalid workflow settings file."));
         resourcePolicy = emptyResourcePolicy(settingsPath, cwd, pi.trust.trusted);
     }
     for (const skill of resourcePolicy.unmatchedSkills)
-        diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled skill selector currently matches no discovered skill: ${skill}`, `${resourcePolicySource(resourcePolicy, "skills", skill)}.disabledAgentResources.skills`));
+        diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled skill selector currently matches no discovered skill: ${skill}`, `${resourcePolicySource(settingsSources.disabledAgentResources)}.disabledAgentResources.skills`));
     for (const extension of resourcePolicy.unmatchedExtensions)
-        diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled extension selector currently matches no discovered extension source: ${extension}`, `${resourcePolicySource(resourcePolicy, "extensions", extension)}.disabledAgentResources.extensions`));
+        diagnostics.push(diagnostic("warning", "AGENT_RESOURCE_UNMATCHED", `Disabled extension selector currently matches no discovered extension source: ${extension}`, `${resourcePolicySource(settingsSources.disabledAgentResources)}.disabledAgentResources.extensions`));
     const activeTools = new Set(pi.activeTools);
     const knownModels = new Set(pi.knownModels);
     const availableModels = new Set(pi.availableModels);
     const aliases = settings.modelAliases ?? {};
+    const registry = options.registry ?? loadingRegistry();
+    const registeredModelAliases = registry.modelAliases();
+    const dynamicAliases = new Set(registeredModelAliases.map(({ name }) => name).filter((name) => !Object.prototype.hasOwnProperty.call(aliases, name)));
+    const modelAliases = [
+        ...Object.keys(aliases).map((name) => ({ name, kind: "static", provenance: settingsSources.modelAliases })),
+        ...registeredModelAliases.map(({ name, version, headline, extensionDescription }) => ({ name, kind: "dynamic", provenance: `extension: ${headline}`, version, headline, extensionDescription })),
+    ].sort((left, right) => left.name.localeCompare(right.name) || left.kind.localeCompare(right.kind));
     const roles = [];
     const definitions = new Map();
+    const extensionScan = scanExtensionRoleFiles(registeredWorkflowRoleDirectoryRegistrations());
+    for (const { registration, error } of extensionScan.errors) {
+        const message = error instanceof Error ? error.message : String(error);
+        diagnostics.push(diagnostic("error", "ROLE_DIRECTORY", `${extensionLabel(registration.extension)} role directory "${registration.path}" could not be scanned: ${message}`, registration.path, "Fix or remove the registered role directory."));
+    }
+    for (const registration of extensionScan.empty)
+        diagnostics.push(diagnostic("warning", "ROLE_DIRECTORY_EMPTY", `${extensionLabel(registration.extension)} role directory "${registration.path}" contains no .md role files`, registration.path, "Add packaged role files or remove the directory registration."));
+    const extensionFilesByName = new Map();
+    for (const file of extensionScan.files)
+        extensionFilesByName.set(file.name, [...(extensionFilesByName.get(file.name) ?? []), file]);
+    const duplicateExtensionNames = new Set();
+    for (const [name, matches] of extensionFilesByName)
+        if (matches.length > 1) {
+            duplicateExtensionNames.add(name);
+            diagnostics.push(diagnostic("error", "ROLE_DUPLICATE", `Duplicate extension role "${name}": ${matches.map(({ path, directory, extension }) => `${extensionLabel(extension)} role directory "${directory}" (${path})`).join("; ")}`, matches[0]?.path, "Keep one extension role with this name; global and project roles may override packaged defaults."));
+        }
+    const extensionPaths = new Map();
+    for (const file of extensionScan.files) {
+        roles.push({ name: file.name, path: file.path, scope: "extension", active: true, extension: file.extension });
+        const definition = inspectRole(file.path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, { directory: file.directory, extension: file.extension });
+        if (duplicateExtensionNames.has(file.name))
+            continue;
+        extensionPaths.set(file.name, file.path);
+        if (definition)
+            definitions.set(file.name, definition);
+    }
     const globalPaths = new Map();
     const globalRoleDirs = workflowRoleDirectories(agentDir);
     for (const path of roleFilesFrom(globalRoleDirs)) {
         const name = basename(path, ".md");
-        roles.push({ name, path, scope: "global", active: true });
+        const extensionPath = extensionPaths.get(name);
+        roles.push({ name, path, scope: "global", active: true, ...(extensionPath ? { overrides: extensionPath } : {}) });
         globalPaths.set(name, path);
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
+        if (extensionPath) {
+            const extension = roles.find((role) => role.path === extensionPath);
+            if (extension) {
+                extension.active = false;
+                extension.overriddenBy = path;
+            }
+        }
+        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
         if (definition)
             definitions.set(name, definition);
+        else
+            definitions.delete(name);
     }
     for (const path of roleFilesFrom([join(cwd, ".pi", "pi-extensible-workflows", "roles")])) {
         const name = basename(path, ".md");
         const globalPath = globalPaths.get(name);
+        const extensionPath = extensionPaths.get(name);
+        const overriddenPath = globalPath ?? extensionPath;
         const active = pi.trust.trusted;
-        roles.push({ name, path, scope: "project", active, ...(active && globalPath ? { overrides: globalPath } : {}) });
+        roles.push({ name, path, scope: "project", active, ...(active && overriddenPath ? { overrides: overriddenPath } : {}) });
         if (!active)
             continue;
         if (globalPath) {
@@ -231,7 +322,14 @@ export async function doctor(options = {}) {
                 global.overriddenBy = path;
             }
         }
-        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, settingsPath);
+        else if (extensionPath) {
+            const extension = roles.find((role) => role.path === extensionPath);
+            if (extension) {
+                extension.active = false;
+                extension.overriddenBy = path;
+            }
+        }
+        const definition = inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath);
         if (definition)
             definitions.set(name, definition);
         else
@@ -244,7 +342,7 @@ export async function doctor(options = {}) {
     const severityOrder = { error: 0, warning: 1 };
     diagnostics.sort((left, right) => severityOrder[left.severity] - severityOrder[right.severity] || (left.source ?? "").localeCompare(right.source ?? "") || left.code.localeCompare(right.code) || left.message.localeCompare(right.message));
     roles.sort((left, right) => left.name.localeCompare(right.name) || left.scope.localeCompare(right.scope));
-    return { cwd, agentDir, settingsPath, settings, trust: pi.trust, activeTools: [...activeTools].sort(), roles, functions, resourcePolicy, diagnostics };
+    return { cwd, agentDir, settingsPath, settings, settingsSources, trust: pi.trust, activeTools: [...activeTools].sort(), roles, functions, modelAliases, resourcePolicy, diagnostics };
 }
 function count(report, severity) { return report.diagnostics.filter((item) => item.severity === severity).length; }
 export function doctorExitCode(report) { return count(report, "error") > 0 ? 1 : 0; }
@@ -255,7 +353,9 @@ export function formatDoctorReport(report) {
         "## Environment",
         `- CWD: \`${report.cwd}\``,
         `- Agent dir: \`${report.agentDir}\``,
-        `- Workflow settings: \`${report.settingsPath}\``,
+        `- Global workflow settings: \`${report.settingsPath}\``,
+        `- Project workflow settings: \`${report.resourcePolicy.projectSettingsPath}\` (${report.resourcePolicy.projectTrusted ? "trusted" : "ignored: project untrusted"})`,
+        `- Effective setting sources: concurrency=\`${report.settingsSources.concurrency}\`, modelAliases=\`${report.settingsSources.modelAliases}\`, disabledAgentResources=\`${report.settingsSources.disabledAgentResources}\``,
         `- Limits: concurrency=${String(report.settings.concurrency)}`,
         "",
         "## Trust/resources",
@@ -270,6 +370,8 @@ export function formatDoctorReport(report) {
         `- Project extensions: ${report.resourcePolicy.project.extensions.join(", ") || "(none)"}`,
         `- Effective skills: ${report.resourcePolicy.effective.skills.join(", ") || "(none)"}`,
         `- Effective extensions: ${report.resourcePolicy.effective.extensions.join(", ") || "(none)"}`,
+        `- Excluded skills: ${report.resourcePolicy.excludedSkills?.join(", ") || "(none)"}`,
+        `- Excluded extensions: ${report.resourcePolicy.excludedExtensions?.join(", ") || "(none)"}`,
         `- Unmatched skills: ${report.resourcePolicy.unmatchedSkills.join(", ") || "(none)"}`,
         `- Unmatched extensions: ${report.resourcePolicy.unmatchedExtensions.join(", ") || "(none)"}`,
         "",
@@ -277,7 +379,10 @@ export function formatDoctorReport(report) {
         ...(report.activeTools.length ? report.activeTools.map((tool) => `- \`${tool}\``) : ["- None resolved"]),
         "",
         "## Roles",
-        ...(report.roles.length ? report.roles.map((role) => `- \`${role.name}\` (${role.scope}, ${role.active ? "active" : role.overriddenBy ? `overridden by ${role.overriddenBy}` : "inactive: project untrusted"}) - \`${role.path}\`${role.overrides ? `; overrides \`${role.overrides}\`` : ""}`) : ["- None found"]),
+        ...(report.roles.length ? report.roles.map((role) => `- \`${role.name}\` (${role.scope}, ${role.active ? "active" : role.overriddenBy ? `overridden by ${role.overriddenBy}` : "inactive: project untrusted"}) - \`${role.path}\`${role.extension ? `; ${extensionLabel(role.extension)} role directory "${dirname(role.path)}"` : ""}${role.overrides ? `; overrides \`${role.overrides}\`` : ""}`) : ["- None found"]),
+        "",
+        "## Model aliases",
+        ...(report.modelAliases.length ? report.modelAliases.map((alias) => `- [${alias.kind}] \`${alias.name}\`${alias.kind === "static" ? ` -> ${report.settings.modelAliases?.[alias.name] ?? "(unresolved)"}` : ""} (${alias.provenance})`) : ["- None registered"]),
         "",
         "## Reusable functions",
         ...(report.functions.length ? report.functions.map((fn) => `- [${fn.valid ? "ok" : "error"}] \`${fn.name}\` - ${fn.description}`) : ["- None registered"]),

package/dist/src/execution.js

@@ -1,5 +1,5 @@
 import { fork, spawn } from "node:child_process";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
@@ -72,6 +72,7 @@ const named = (value, kind) => { if (typeof value !== "string" || !value.trim())
 const path = (...names) => names.map(encodeURIComponent).join("/");
 const inheritedAgentPath = new AsyncLocalStorage();
 const agentOccurrences = new Map();
+const agentInflight = new Set();
 const shellOccurrences = new Map();
 const worktreeOwners = new AsyncLocalStorage();
 const rejectAgent = () => { throw workError("INVALID_METADATA", "Workflow agent calls must use a direct agent(...) call; aliases and indirect calls are unsupported"); };
@@ -92,14 +93,22 @@ const internalAgent = (...values) => {
   const callSite = values.pop();
   if (typeof callSite !== "string") throw workError("INTERNAL_ERROR", "Missing workflow agent call-site identity");
   const inherited = inheritedAgentPath.getStore() || [];
-  // ponytail: same-callsite races outside parallel/pipeline lack a stable structural scope and are unsupported.
   const occurrenceKey = JSON.stringify([inherited, callSite]);
+  if (agentInflight.has(occurrenceKey)) throw workError("INVALID_METADATA", "Concurrent agent calls from the same source call site are unsupported; use parallel(...) or pipeline(...)");
+  agentInflight.add(occurrenceKey);
   const occurrence = (agentOccurrences.get(occurrenceKey) || 0) + 1;
   agentOccurrences.set(occurrenceKey, occurrence);
   const options = values.length < 2 || values[1] === undefined ? {} : values[1];
   const worktreeOwner = worktreeOwners.getStore();
   const identity = { structuralPath: [...inherited], callSite, occurrence, ...(worktreeOwner ? { worktreeOwner } : {}) };
-  const result = rpc("agent", [values[0], options, identity]).then(unwrap);
+  let result;
+  try {
+    result = rpc("agent", [values[0], options, identity]).then(unwrap);
+  } catch (error) {
+    agentInflight.delete(occurrenceKey);
+    throw error;
+  }
+  void result.then(() => agentInflight.delete(occurrenceKey), () => agentInflight.delete(occurrenceKey));
   Object.defineProperties(result, {
     toJSON: { value() { throw workError("INVALID_METADATA", "Workflow agent result is a Promise; await it before serialization"); } },
     toString: { value() { throw workError("INVALID_METADATA", "Workflow agent result is a Promise; await it before interpolation"); } },
@@ -421,7 +430,7 @@ function workflowErrorFromWorker(error) {
 export function runWorkflow(script, args = null, bridge = {}, signal) {
     encoded(args);
     const config = JSON.stringify({ script: instrumentWorkflow(script), args: structuredClone(args), functions: bridge.functions ?? {}, variables: bridge.variables ?? {} });
-    const childDir = mkdtempSync(join(tmpdir(), "pi-wf-"));
+    const childDir = realpathSync(mkdtempSync(join(tmpdir(), "pi-wf-")));
     const childFile = join(childDir, "child.cjs");
     writeFileSync(childFile, childSource);
     const child = fork(childFile, [String(RPC_LIMIT_BYTES), config], {

package/dist/src/host.d.ts

@@ -2,7 +2,7 @@ import { Type } from "@earendil-works/pi-ai";
 import { copyToClipboard, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type SessionFactory } from "./agent-execution.js";
 import type { AwaitingCheckpoint, PersistedRun, WorktreeReference } from "./persistence.js";
-import { type LaunchSnapshot, type RunState, type WorkflowFailureDiagnostics } from "./types.js";
+import { type AgentRecord, type LaunchSnapshot, type RunState, type WorkflowFailureDiagnostics } from "./types.js";
 export interface WorkflowProgressStyles {
     accent(text: string): string;
     success(text: string): string;
@@ -34,8 +34,8 @@ export declare function formatWorkflowPreview(args: {
     description?: unknown;
 }): string;
 export declare const WORKFLOW_TOOL_LABEL = "Workflow";
-export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow";
-export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow that orchestrates subagents. Inline launches require an explicit non-empty name; registered function launches reject name and use workflow as the run name. Runs in the background by default; completion arrives as a follow-up message. Foreground results include the completed run ID. Use workflow_retry with an explicit failed run ID to replay completed structural operations; parentRunId only reuses named worktrees.";
+export declare const WORKFLOW_TOOL_DESCRIPTION = "Run a deterministic JavaScript workflow with a named inline parallel-to-summary path by default";
+export declare const WORKFLOW_TOOL_PROMPT_SNIPPET = "Run a deterministic, resumable JavaScript workflow. Prefer a named inline script that fans out independent work with parallel(...), awaits the keyed results before interpolating them into one summarizing agent(...), and returns. Inline launches require an explicit non-empty name; registered function launches reject name and use workflow as the run name. Advanced controls include registered functions, outputSchema, budgets, checkpoints, worktrees, retry/resume, CLI export, and pipelines. Use workflow_retry with an explicit failed run ID; parentRunId only reuses named worktrees. Runs are in the background by default; completion arrives as a follow-up message. Set foreground: true when the caller must wait for the final value. Foreground results include the completed run ID. Recovery map: agent(..., { retries }) reruns one agent call in the same run for transient failures; workflow_retry({ runId }) replays a failed run into a child; workflow_resume({ runId, budget? }) continues a budget_exhausted run; parentRunId on a new launch only borrows named worktrees and never replays or resumes.";
 export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
     name: Type.TOptional<Type.TString>;
     description: Type.TOptional<Type.TString>;
@@ -50,13 +50,92 @@ export declare const WORKFLOW_TOOL_PARAMETERS: Type.TObject<{
 export declare const WORKFLOW_RETRY_PARAMETERS: Type.TObject<{
     runId: Type.TString;
 }>;
+export type WorkflowPhaseState = "not started" | "running" | "completed" | "failed" | "cancelled" | "interrupted" | "budget_exhausted";
+export interface WorkflowPhaseAgentCounts {
+    total: number;
+    completed: number;
+    running: number;
+    failed: number;
+    cancelled: number;
+    pending: number;
+}
+export interface WorkflowPhaseView {
+    id: string;
+    name: string;
+    occurrence: number;
+    state: WorkflowPhaseState;
+    observed: boolean;
+    afterAgent?: number;
+    agents: readonly AgentRecord[];
+    counts: WorkflowPhaseAgentCounts;
+}
+export interface WorkflowPhaseModel {
+    declaredPhases: readonly string[];
+    phases: readonly WorkflowPhaseView[];
+    currentPhaseIndex?: number;
+    currentPhaseId?: string;
+    counts: Readonly<Partial<Record<WorkflowPhaseState, number>>>;
+    unassignedAgents?: readonly AgentRecord[];
+}
+type WorkflowPhaseSource = readonly string[] | Pick<LaunchSnapshot, "phases"> | undefined;
+export declare function buildWorkflowPhaseModel(run: Pick<PersistedRun, "state" | "phase" | "phaseHistory" | "agents">, source?: WorkflowPhaseSource): WorkflowPhaseModel;
+export interface WorkflowPhaseSelection {
+    phaseId?: string | undefined;
+    agentId?: string | undefined;
+    nodeId?: string | undefined;
+    expandedNodeIds?: readonly string[] | undefined;
+    treeOnly?: boolean | undefined;
+    detailsOnly?: boolean | undefined;
+    actions?: {
+        title: string;
+        options: readonly string[];
+        index: number;
+    } | undefined;
+}
+export type WorkflowPhaseTreeNodeKind = "phase" | "operation" | "agent";
+export interface WorkflowPhaseTreeNode {
+    id: string;
+    kind: WorkflowPhaseTreeNodeKind;
+    label: string;
+    depth: number;
+    phaseId: string;
+    operationPath: readonly string[];
+    parentId?: string;
+    children: readonly string[];
+    state: WorkflowPhaseState | AgentRecord["state"];
+    agentId?: string;
+    agent?: AgentRecord;
+    phase?: WorkflowPhaseView;
+}
+export interface WorkflowPhaseTree {
+    roots: readonly string[];
+    nodes: readonly WorkflowPhaseTreeNode[];
+    byId: ReadonlyMap<string, WorkflowPhaseTreeNode>;
+}
+export interface WorkflowPhaseTreeSelection {
+    nodeId?: string | undefined;
+}
+export type WorkflowPhaseTreeDirection = "up" | "down" | "left" | "right";
+export declare function buildWorkflowPhaseTree(model: WorkflowPhaseModel): WorkflowPhaseTree;
+export declare function workflowPhaseTreeVisibleNodes(tree: WorkflowPhaseTree, expanded?: ReadonlySet<string>): readonly WorkflowPhaseTreeNode[];
+export declare function workflowPhaseTreeInitialExpanded(tree: WorkflowPhaseTree): ReadonlySet<string>;
+export declare function preserveWorkflowPhaseTreeSelection(tree: WorkflowPhaseTree, selection: WorkflowPhaseTreeSelection): WorkflowPhaseTreeSelection;
+export declare function navigateWorkflowPhaseTree(tree: WorkflowPhaseTree, selectedNodeId: string | undefined, expandedNodeIds: ReadonlySet<string>, direction: WorkflowPhaseTreeDirection): {
+    nodeId?: string;
+    expandedNodeIds: ReadonlySet<string>;
+};
+export declare function preserveWorkflowPhaseSelection(model: WorkflowPhaseModel, selection: WorkflowPhaseSelection): WorkflowPhaseSelection;
 export declare function formatWorkflowProgress(run: PersistedRun, spinner?: string, styles?: WorkflowProgressStyles): string;
 export declare function truncateWorkflowProgress(text: string, width: number): string[];
 export declare function formatBudgetStatus(run: Pick<PersistedRun, "budget" | "budgetVersion" | "usage" | "budgetEvents">): string[];
+export declare function agentBreadcrumbParts(agent: AgentRecord, byId: Map<string, AgentRecord>, includeStructuralPath?: boolean): string[];
+export declare function agentBreadcrumb(agent: AgentRecord, byId: Map<string, AgentRecord>, includeStructuralPath?: boolean): string;
 export declare function formatNavigatorDashboard(run: PersistedRun, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string;
 export declare function formatNavigatorRun(loaded: {
     run: PersistedRun;
     snapshot: Readonly<LaunchSnapshot>;
-}, checkpoints: readonly AwaitingCheckpoint[], _worktrees: readonly WorktreeReference[]): string;
+}, checkpoints: readonly AwaitingCheckpoint[], worktrees: readonly WorktreeReference[]): string;
+export declare function formatWorkflowPhaseDashboard(run: PersistedRun, snapshot: Readonly<LaunchSnapshot>, width: number, selection?: WorkflowPhaseSelection, styles?: WorkflowProgressStyles): string[];
 export declare function formatWorkflowFailureDiagnostics(diagnostic: WorkflowFailureDiagnostics): string;
 export default function workflowExtension(pi: ExtensionAPI, home?: string, clipboard?: typeof copyToClipboard, createSession?: SessionFactory, agentDir?: string): void;
+export {};