@piewf/cli 5.0.0 → 5.2.0

package/dist/src/bundles.js

@@ -2,13 +2,50 @@ import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, re
 import { basename, dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJsonObject(path) {
+    try {
+        const value = JSON.parse(readFileSync(path, "utf8"));
+        return isJsonObject(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readPackageMetadata(path) {
+    const value = readJsonObject(path);
+    if (!value)
+        return undefined;
+    const metadata = {};
+    if (typeof value.name === "string")
+        metadata.name = value.name;
+    if (typeof value.version === "string")
+        metadata.version = value.version;
+    if (typeof value.bin === "string")
+        metadata.bin = value.bin;
+    else if (isJsonObject(value.bin)) {
+        const bin = {};
+        let valid = true;
+        for (const [name, entry] of Object.entries(value.bin)) {
+            if (typeof entry !== "string") {
+                valid = false;
+                break;
+            }
+            bin[name] = entry;
+        }
+        if (valid)
+            metadata.bin = bin;
+    }
+    return metadata;
+}
 function packageJson() {
     const directory = dirname(fileURLToPath(import.meta.url));
     for (const path of [join(directory, "../package.json"), join(directory, "../../package.json")]) {
-        try {
-            return JSON.parse(readFileSync(path, "utf8"));
-        }
-        catch { /* Try the source and built layouts. */ }
+        const metadata = readPackageMetadata(path);
+        if (metadata)
+            return metadata;
     }
     return {};
 }
@@ -300,7 +337,6 @@ function workflowModule(workflow, functionSource, withRoles, aliasTargets, exten
         "  registerWorkflowExtension({",
         `    version: ${JSON.stringify("1.0.0")},`,
         `    headline: ${JSON.stringify("Portable workflow bundle")},`,
-        `    description: ${JSON.stringify(workflow.description)},`,
         ...(withRoles ? [`    roleDirectories: [new URL("./roles", import.meta.url)],`] : []),
         ...(aliases.length ? [`    modelAliases: { ${aliases.map(([name, target]) => `${JSON.stringify(name)}: { resolve: () => ${JSON.stringify(target)} }`).join(", ")} },`] : []),
         "    functions: {",
@@ -328,6 +364,8 @@ function roleMarkdown(role) {
         metadata.push(`tools: ${JSON.stringify(role.tools)}`);
     if (role.overrideSystemPrompt !== undefined)
         metadata.push(`overrideSystemPrompt: ${String(role.overrideSystemPrompt)}`);
+    if (role.contextFiles !== undefined)
+        metadata.push(`contextFiles: ${JSON.stringify(role.contextFiles)}`);
     if (role.disabledAgentResources !== undefined)
         metadata.push(`disabledAgentResources: ${JSON.stringify(role.disabledAgentResources)}`);
     metadata.push("---");
@@ -352,12 +390,9 @@ function copyResources(root, resources) {
                 throw new Error(`Bundle resource may contain credentials and cannot be selected: ${source}`);
             let name = basename(source);
             if (kind === "dependencies") {
-                try {
-                    const packageName = JSON.parse(readFileSync(join(source, "package.json"), "utf8")).name;
-                    if (typeof packageName === "string" && packageName.trim())
-                        name = packageName;
-                }
-                catch { /* Files can be dependency entry points. */ }
+                const packageName = readPackageMetadata(join(source, "package.json"))?.name;
+                if (typeof packageName === "string" && packageName.trim())
+                    name = packageName;
             }
             if (!name || name === "." || name === ".." || name.includes("\\") || name.startsWith("/"))
                 throw new Error(`Invalid bundle resource name: ${name}`);

package/dist/src/cli.d.ts

@@ -15,5 +15,9 @@ export interface CliOptions extends DoctorOptions {
 }
 export declare function formatWorkflowCliHelp(fn: WorkflowCatalogFunction, command?: string): string;
 export declare function parseWorkflowCliArgs(schema: JsonSchema, rawArgs: readonly string[]): Record<string, JsonValue>;
+export declare function parseDoctorArgs(rawArgs: readonly string[]): {
+    role?: string;
+    prompt?: string;
+};
 export declare function parseDoctorCleanupArgs(rawArgs: readonly string[]): Required<Pick<DoctorCleanupOptions, "olderThanDays" | "yes">>;
 export declare function runCli(args: readonly string[], options?: CliOptions, write?: (text: string) => void): Promise<number>;

package/dist/src/cli.js

@@ -8,17 +8,27 @@ import { ProjectTrustStore, SessionManager, SettingsManager, createAgentSessionF
 import { Value } from "typebox/value";
 import { doctor, doctorExitCode, formatDoctorReport } from "./doctor.js";
 import { doctorCleanup, doctorCleanupExitCode, formatDoctorCleanupReport } from "./doctor-cleanup.js";
-import workflowExtension, { formatWorkflowProgress, loadAgentDefinitions, registeredWorkflowFunctions, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "pi-extensible-workflows";
+import workflowExtension, { formatWorkflowProgress, isNodeError, jsonValue, loadAgentDefinitions, registeredWorkflowFunctions, truncateWorkflowProgress, workflowCatalog, workflowSettingsPath } from "pi-extensible-workflows";
 import { portableEngineVersion, portablePiVersion, writePortableWorkflowBundle } from "./bundles.js";
 import { runSessionInspector, transcriptFileLines } from "./session-inspector.js";
+import { isPersistedRun } from "pi-extensible-workflows/persistence";
 function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
 function has(value, key) { return Object.prototype.hasOwnProperty.call(value, key); }
-function clone(value) { return structuredClone(value); }
+function requiredArg(args, index) {
+    const value = args[index];
+    if (value === undefined)
+        throw new Error("Missing argument");
+    return value;
+}
+function typedOptionKey(options, key) { return Object.prototype.hasOwnProperty.call(options, key); }
+function clone(value) { const cloned = structuredClone(value); if (!jsonValue(cloned))
+    throw new Error("Invalid JSON passed to --input"); return cloned; }
 function kebabCase(value) { return value.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase(); }
+function isCliScalar(value) { return value === "string" || value === "integer" || value === "number" || value === "boolean"; }
 function scalarType(schema) {
     if (!object(schema) || typeof schema.type !== "string")
         return undefined;
-    return ["string", "integer", "number", "boolean"].includes(schema.type) ? schema.type : undefined;
+    return isCliScalar(schema.type) ? schema.type : undefined;
 }
 function schemaPlan(schema) {
     if (!object(schema) || schema.type !== "object")
@@ -40,8 +50,14 @@ function schemaPlan(schema) {
     return { fields, ...(requiredScalars.length === 1 ? { positional: requiredScalars[0] } : {}) };
 }
 function scalarLabel(type) { return type === "integer" ? "integer" : type; }
-function scalarFieldType(field) { return field.type === "array" ? field.itemType : field.type; }
-function fieldLabel(field) { return field.type === "array" ? `${field.option} <${scalarLabel(field.itemType)}>` : `${field.option}${field.type === "boolean" ? "" : ` <${scalarLabel(field.type)}>`}`; }
+function scalarFieldType(field) {
+    if (field.type !== "array")
+        return field.type;
+    if (!isCliScalar(field.itemType))
+        throw new Error("Invalid array field");
+    return field.itemType;
+}
+function fieldLabel(field) { return field.type === "array" ? `${field.option} <${scalarLabel(scalarFieldType(field))}>` : `${field.option}${field.type === "boolean" ? "" : ` <${scalarLabel(field.type)}>`}`; }
 function fieldDescription(field) {
     const description = typeof field.schema.description === "string" ? field.schema.description.trim() : "";
     const required = field.required ? "required" : "optional";
@@ -109,15 +125,19 @@ export function parseWorkflowCliArgs(schema, rawArgs) {
     let endOptions = false;
     const assign = (field, raw) => {
         if (field.type === "array") {
-            const values = Array.isArray(result[field.name]) ? result[field.name] : [];
-            values.push(coerce(raw, field.itemType, field.schema.items));
+            const current = result[field.name];
+            const values = Array.isArray(current) ? current : [];
+            const itemSchema = field.schema.items;
+            if (!object(itemSchema))
+                throw new Error("Invalid array field");
+            values.push(coerce(raw, scalarFieldType(field), itemSchema));
             result[field.name] = values;
         }
         else
             result[field.name] = coerce(raw, field.type, field.schema);
     };
     for (let index = 0; index < rawArgs.length; index += 1) {
-        const token = rawArgs[index];
+        const token = requiredArg(rawArgs, index);
         if (token === "--") {
             endOptions = true;
             continue;
@@ -147,7 +167,7 @@ export function parseWorkflowCliArgs(schema, rawArgs) {
                 if (equals >= 0)
                     assign(field, token.slice(equals + 1));
                 else if (rawArgs[index + 1] === "true" || rawArgs[index + 1] === "false")
-                    assign(field, rawArgs[++index]);
+                    assign(field, requiredArg(rawArgs, ++index));
                 else
                     result[field.name] = true;
             }
@@ -218,12 +238,47 @@ function parseInspectArgs(rawArgs) {
     }
     return { ...(sessionId ? { sessionId } : {}), mode: failedOnly && mode === "tui" ? "summary" : mode, failedOnly };
 }
+export function parseDoctorArgs(rawArgs) {
+    let role;
+    let prompt;
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const token = requiredArg(rawArgs, index);
+        const equals = token.indexOf("=");
+        const option = equals >= 0 ? token.slice(0, equals) : token;
+        if (option === "--role" || option === "--prompt") {
+            const value = equals >= 0 ? token.slice(equals + 1) : rawArgs[++index];
+            if (!value)
+                throw new Error(`Missing value for ${option}`);
+            if (option === "--role") {
+                if (role !== undefined)
+                    throw new Error("--role may only be provided once");
+                role = value;
+            }
+            else {
+                if (prompt !== undefined)
+                    throw new Error("--prompt may only be provided once");
+                prompt = value;
+            }
+            continue;
+        }
+        if (token === "--help" || token === "-h")
+            throw new Error("help");
+        if (token.startsWith("--"))
+            throw new Error(`Unknown doctor option: ${token}`);
+        if (role !== undefined)
+            throw new Error(`Unexpected argument: ${token}`);
+        role = token;
+    }
+    if (prompt !== undefined && role === undefined)
+        throw new Error("--prompt requires --role");
+    return { ...(role === undefined ? {} : { role }), ...(prompt === undefined ? {} : { prompt }) };
+}
 export function parseDoctorCleanupArgs(rawArgs) {
     let olderThanDays = 90;
     let yes = false;
     let seenDays = false;
     for (let index = 0; index < rawArgs.length; index += 1) {
-        const token = rawArgs[index];
+        const token = requiredArg(rawArgs, index);
         if (token === "--yes") {
             yes = true;
             continue;
@@ -267,6 +322,8 @@ function stripTrustOptions(rawArgs) {
     }
     return { args, ...(trustOverride !== undefined ? { trustOverride } : {}) };
 }
+function isHeadlessWorkflowResult(value) { return object(value) && Array.isArray(value.content) && value.content.every((entry) => object(entry) && typeof entry.type === "string" && typeof entry.text === "string"); }
+function isHeadlessWorkflowTool(value) { return object(value) && value.name === "workflow" && typeof value.execute === "function"; }
 async function createWorkflowRuntime(options, shutdownHandlers = []) {
     const cwd = options.cwd ?? process.cwd();
     const agentDir = options.agentDir ?? getAgentDir();
@@ -289,6 +346,8 @@ async function createWorkflowRuntime(options, shutdownHandlers = []) {
             for (const handler of extension.handlers.get("project_trust") ?? []) {
                 try {
                     const result = await handler({ type: "project_trust", cwd }, projectTrustContext);
+                    if (!object(result))
+                        continue;
                     if (result.trusted === "undecided")
                         continue;
                     if (result.trusted !== "yes" && result.trusted !== "no")
@@ -328,7 +387,7 @@ async function createWorkflowRuntime(options, shutdownHandlers = []) {
         events: { emit() { } },
     };
     workflowExtension(headlessPi, homedir(), undefined, undefined, agentDir, options.skillPaths);
-    const workflowTool = tools.find((tool) => object(tool) && tool.name === "workflow");
+    const workflowTool = tools.find(isHeadlessWorkflowTool);
     if (!workflowTool)
         throw new Error("The workflow runtime could not be initialized");
     return { catalog: workflowCatalog({ cwd, projectTrusted: settingsManager.isProjectTrusted(), globalSettingsPath: workflowSettingsPath(agentDir) }), services, workflowTool, shutdownHandlers };
@@ -360,8 +419,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 let cli;
-try { cli = await import(import.meta.resolve("@piewf/cli")); } catch {}
-if (!cli) try { cli = await import(pathToFileURL(join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "npm", "node_modules", "@piewf/cli", "dist", "src", "cli.js")).href); } catch {}
+try { cli = await import(pathToFileURL(join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "npm", "node_modules", "@piewf/cli", "dist", "src", "cli.js")).href); } catch {}
+if (!cli) try { cli = await import(import.meta.resolve("@piewf/cli")); } catch {}
 if (cli) process.exitCode = await cli.runCli(["run", ${JSON.stringify(workflowName)}, ...process.argv.slice(2)]);
 else { const result = spawnSync("piewf", ["run", ${JSON.stringify(workflowName)}, ...process.argv.slice(2)], { stdio: "inherit" }); if (result.error) { console.error("Could not resolve @piewf/cli; install it or put piewf on PATH."); process.exitCode = 1; } else process.exitCode = result.status ?? 1; }
 `;
@@ -374,7 +433,7 @@ else { const result = spawnSync("piewf", ["run", ${JSON.stringify(workflowName)}
                 linkSync(tempPath, destination);
             }
             catch (error) {
-                if (error.code === "EEXIST")
+                if (isNodeError(error, "EEXIST"))
                     throw new Error(`Destination already exists: ${destination}; use --force to replace it`, { cause: error });
                 throw error;
             }
@@ -467,13 +526,15 @@ async function invokeWorkflow(fn, args, runtime, options, context) {
         return; announcedRunId = runId; options.stderr(`Run ID: ${runId}\n`); };
     const progress = new CliProgress(options.stderr, options.isTTY ?? process.stderr.isTTY, announceRunId);
     try {
-        const result = await runtime.workflowTool.execute(randomUUID(), { name: fn.name, script: `return await ${fn.name}(args);`, args, foreground: true }, options.signal, (update) => { if (object(update) && object(update.details) && object(update.details.run))
+        const result = await runtime.workflowTool.execute(randomUUID(), { name: fn.name, script: `return await ${fn.name}(args);`, args, foreground: true }, options.signal, (update) => { if (object(update) && object(update.details) && isPersistedRun(update.details.run))
             progress.update(update.details.run); }, context);
+        if (!isHeadlessWorkflowResult(result))
+            throw new Error("Workflow returned an invalid result");
         const details = object(result.details) ? result.details : {};
         const runId = typeof details.runId === "string" ? details.runId : undefined;
         if (runId)
             announceRunId(runId);
-        if (has(details, "value"))
+        if (has(details, "value") && jsonValue(details.value))
             return { value: details.value, ...(runId ? { runId } : {}) };
         const first = result.content[0];
         if (!first || first.type !== "text")
@@ -522,7 +583,7 @@ async function runWorkflowCli(rawArgs, options) {
         options.write(workflowUsage());
         return args.length ? 0 : 1;
     }
-    const name = args[0];
+    const name = requiredArg(args, 0);
     return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime, context) => {
         const help = args.slice(1).some((arg) => arg === "--help" || arg === "-h");
         const fn = runtime.catalog.functions.find((candidate) => candidate.name === name);
@@ -547,13 +608,13 @@ async function exportWorkflowCli(rawArgs, options) {
         options.write(exportUsage());
         return args.length ? 0 : 1;
     }
-    const workflowName = args[0];
+    const workflowName = requiredArg(args, 0);
     return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime) => {
         let name;
         let output;
         let force = false;
         for (let index = 1; index < args.length; index += 1) {
-            const arg = args[index];
+            const arg = requiredArg(args, index);
             if (arg === "--force") {
                 force = true;
                 continue;
@@ -605,7 +666,7 @@ async function bundleWorkflowCli(rawArgs, options) {
         options.write(bundleUsage());
         return args.length ? 0 : 1;
     }
-    const workflowName = args[0];
+    const workflowName = requiredArg(args, 0);
     return withWorkflowRuntime({ ...options, ...(parsed.trustOverride !== undefined ? { trustOverride: parsed.trustOverride } : {}) }, async (runtime) => {
         let name;
         let output;
@@ -613,7 +674,7 @@ async function bundleWorkflowCli(rawArgs, options) {
         const requirements = { roles: [], aliases: [], tools: [], commands: [], environment: [] };
         const resources = { extensions: [], skills: [], static: [], dependencies: [] };
         for (let index = 1; index < args.length; index += 1) {
-            const arg = args[index];
+            const arg = requiredArg(args, index);
             if (arg === "--force") {
                 force = true;
                 continue;
@@ -622,7 +683,7 @@ async function bundleWorkflowCli(rawArgs, options) {
             const option = equals >= 0 ? arg.slice(0, equals) : arg;
             const requirementOptions = { "--role": "roles", "--alias": "aliases", "--tool": "tools", "--command": "commands", "--environment": "environment" };
             const resourceOptions = { "--extension": "extensions", "--skill": "skills", "--resource": "static", "--dependency": "dependencies" };
-            if (option === "--name" || option === "--output" || Object.prototype.hasOwnProperty.call(requirementOptions, option) || Object.prototype.hasOwnProperty.call(resourceOptions, option)) {
+            if (option === "--name" || option === "--output" || typedOptionKey(requirementOptions, option) || typedOptionKey(resourceOptions, option)) {
                 const value = equals >= 0 ? arg.slice(equals + 1) : args[++index];
                 if (!value)
                     throw new Error(`Missing value for ${option}`);
@@ -630,9 +691,9 @@ async function bundleWorkflowCli(rawArgs, options) {
                     name = value;
                 else if (option === "--output")
                     output = value;
-                else if (Object.prototype.hasOwnProperty.call(requirementOptions, option))
+                else if (typedOptionKey(requirementOptions, option))
                     requirements[requirementOptions[option]].push(value);
-                else
+                else if (typedOptionKey(resourceOptions, option))
                     resources[resourceOptions[option]].push(value);
                 continue;
             }
@@ -674,10 +735,21 @@ async function bundleWorkflowCli(rawArgs, options) {
 }
 export async function runCli(args, options = {}, write = (text) => { process.stdout.write(text); }) {
     const stderr = options.stderr ?? ((text) => { process.stderr.write(text); });
-    if (args[0] === "doctor" && args.length === 1) {
-        const report = await doctor(options);
-        write(formatDoctorReport(report));
-        return doctorExitCode(report);
+    if (args[0] === "doctor" && args[1] !== "cleanup") {
+        if (args.slice(1).some((arg) => arg === "--help" || arg === "-h")) {
+            write("Usage: piewf doctor [role] [--role <role>] [--prompt <text>]\n");
+            return 0;
+        }
+        try {
+            const parsed = parseDoctorArgs(args.slice(1));
+            const report = await doctor({ ...options, ...parsed });
+            write(formatDoctorReport(report));
+            return doctorExitCode(report);
+        }
+        catch (error) {
+            stderr(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+            return 1;
+        }
     }
     if (args[0] === "doctor" && args[1] === "cleanup") {
         if (args.slice(2).some((arg) => arg === "--help" || arg === "-h")) {
@@ -712,10 +784,11 @@ export async function runCli(args, options = {}, write = (text) => { process.std
     }
     if (args[0] === "transcript" && args.length === 2) {
         try {
+            const transcript = requiredArg(args, 1);
             if (options.transcript)
-                await options.transcript(args[1]);
+                await options.transcript(transcript);
             else
-                write(`${transcriptFileLines(args[1]).join("\n")}\n`);
+                write(`${transcriptFileLines(transcript).join("\n")}\n`);
             return 0;
         }
         catch (error) {
@@ -735,7 +808,7 @@ export async function runCli(args, options = {}, write = (text) => { process.std
             return 1;
         }
     }
-    write("Usage: piewf doctor | inspect [session-id] [--json|--summary] [--failed] | transcript <session-file> | bundle <workflow-name> [--name <command>] [--output <path>] [--force] | run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]\n");
+    write("Usage: piewf doctor [role] [--role <role>] [--prompt <text>] | inspect [session-id] [--json|--summary] [--failed] | transcript <session-file> | bundle <workflow-name> [--name <command>] [--output <path>] [--force] | run <workflow-name> [workflow arguments] | export <workflow-name> [--name <command>] [--output <path>] [--force] [--bundle]\n");
     return 1;
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {

package/dist/src/doctor-cleanup.js

@@ -4,7 +4,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { validateBudget } from "pi-extensible-workflows";
 import { RUN_STATES } from "pi-extensible-workflows";
-import { jsonValue, validateModelAliases } from "pi-extensible-workflows";
+import { isNodeError, jsonValue, validateModelAliases } from "pi-extensible-workflows";
 import { validateSchema } from "pi-extensible-workflows";
 import { acquireSessionLease, hasLiveSessionLease, projectSessionsDirectory, RunStore } from "pi-extensible-workflows/persistence";
 const TERMINAL_STATES = new Set(["completed", "failed", "stopped"]);
@@ -18,6 +18,13 @@ const SCHEDULER_STATES = new Set(["queued", "running", "waiting_for_child", "pau
 const BUDGET_DIMENSIONS = new Set(["tokens", "costUsd", "durationMs", "agentLaunches"]);
 const BUDGET_EVENT_TYPES = new Set(["soft_crossed", "hard_overrun", "hard_exhausted", "adjustment_requested", "adjustment_approved", "adjustment_rejected"]);
 function object(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function isList(value) { return Array.isArray(value); }
+function isThinking(value) { return ["off", "minimal", "low", "medium", "high", "xhigh", "max"].some((candidate) => candidate === value); }
+function isRunState(value) { return RUN_STATES.some((candidate) => candidate === value); }
+function isAgentState(value) { return typeof value === "string" && AGENT_STATES.has(value); }
+function isSchedulerState(value) { return typeof value === "string" && SCHEDULER_STATES.has(value); }
+function isToolCallState(value) { return ["running", "completed", "failed"].some((candidate) => candidate === value); }
+function isActivityKind(value) { return ["reasoning", "tool", "text"].some((candidate) => candidate === value); }
 function textError(error) { return error instanceof Error ? error.message : String(error); }
 function positiveDays(value) { if (!Number.isSafeInteger(value) || value < 1 || !Number.isFinite(value * DAY_MS))
     throw new Error("older-than-days must be a positive integer"); return value; }
@@ -26,17 +33,17 @@ function sameNames(left, right) { return left.length === right.length && left.ev
 async function jsonFile(path) { return JSON.parse(await readFile(path, "utf8")); }
 async function requiredFile(path) { const info = await lstat(path); if (!info.isFile())
     throw new Error(`Required artifact is not a regular file: ${path}`); }
-function stringList(value, label, nonEmpty = false) { if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || (nonEmpty && !item)))
+function stringList(value, label, nonEmpty = false) { if (!isList(value) || value.some((item) => typeof item !== "string" || (nonEmpty && !item)))
     throw new Error(`${label} is invalid`); }
 function optionalString(value, label) { if (value !== undefined && typeof value !== "string")
     throw new Error(`${label} is invalid`); }
-function nonNegativeInteger(value, label) { if (!Number.isSafeInteger(value) || value < 0)
+function nonNegativeInteger(value, label) { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
     throw new Error(`${label} is invalid`); }
-function positiveInteger(value, label) { if (!Number.isSafeInteger(value) || value < 1)
+function positiveInteger(value, label) { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
     throw new Error(`${label} is invalid`); }
 function finiteNumber(value, label) { if (typeof value !== "number" || !Number.isFinite(value) || value < 0)
     throw new Error(`${label} is invalid`); }
-function model(value, label) { if (!object(value) || typeof value.provider !== "string" || !value.provider || typeof value.model !== "string" || !value.model || (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking)))
+function model(value, label) { if (!object(value) || typeof value.provider !== "string" || !value.provider || typeof value.model !== "string" || !value.model || (value.thinking !== undefined && !isThinking(value.thinking)))
     throw new Error(`${label} is invalid`); }
 function accounting(value, label) { if (!object(value))
     throw new Error(`${label} is invalid`); for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost"])
@@ -47,26 +54,48 @@ function resourceExclusions(value, label) { if (value === undefined)
     stringList(value.skills, `${label}.skills`); if (value.extensions !== undefined)
     stringList(value.extensions, `${label}.extensions`); }
 function agentDefinition(value, label) { if (!object(value))
-    throw new Error(`${label} is invalid`); optionalString(value.prompt, `${label}.prompt`); optionalString(value.description, `${label}.description`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking))
+    throw new Error(`${label} is invalid`); optionalString(value.prompt, `${label}.prompt`); optionalString(value.description, `${label}.description`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !isThinking(value.thinking))
     throw new Error(`${label}.thinking is invalid`); if (value.tools !== undefined)
     stringList(value.tools, `${label}.tools`); resourceExclusions(value.disabledAgentResources, `${label}.disabledAgentResources`); }
+function optionalRole(value, label) {
+    if (value === undefined)
+        return;
+    if (typeof value === "string") {
+        if (!value.trim())
+            throw new Error(`${label} is invalid`);
+        return;
+    }
+    if (!object(value) || typeof value.name !== "string" || !value.name.trim())
+        throw new Error(`${label} is invalid`);
+    for (const key of ["model", "description"])
+        if (value[key] !== undefined && value[key] !== null && typeof value[key] !== "string")
+            throw new Error(`${label}.${key} is invalid`);
+    if (value.thinking !== undefined && value.thinking !== null && !isThinking(value.thinking))
+        throw new Error(`${label}.thinking is invalid`);
+    if (value.tools !== undefined && value.tools !== null)
+        stringList(value.tools, `${label}.tools`);
+    if (value.overrideSystemPrompt !== undefined && value.overrideSystemPrompt !== null && typeof value.overrideSystemPrompt !== "boolean")
+        throw new Error(`${label}.overrideSystemPrompt is invalid`);
+    if (value.contextFiles !== undefined && value.contextFiles !== null)
+        stringList(value.contextFiles, `${label}.contextFiles`);
+    if (value.disabledAgentResources !== undefined && value.disabledAgentResources !== null)
+        resourceExclusions(value.disabledAgentResources, `${label}.disabledAgentResources`);
+}
 function validateScheduledOptions(value, label) { if (!object(value) || typeof value.label !== "string" || !value.label || typeof value.cwd !== "string" || !value.cwd)
-    throw new Error(`${label} is invalid`); optionalString(value.requestedLabel, `${label}.requestedLabel`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); stringList(value.tools, `${label}.tools`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value.thinking))
-    throw new Error(`${label}.thinking is invalid`); optionalString(value.role, `${label}.role`); if (value.schema !== undefined)
+    throw new Error(`${label} is invalid`); optionalString(value.requestedLabel, `${label}.requestedLabel`); optionalString(value.parentBreadcrumb, `${label}.parentBreadcrumb`); stringList(value.tools, `${label}.tools`); optionalString(value.worktreeOwner, `${label}.worktreeOwner`); optionalString(value.model, `${label}.model`); if (value.thinking !== undefined && !isThinking(value.thinking))
+    throw new Error(`${label}.thinking is invalid`); optionalRole(value.role, `${label}.role`); if (value.schema !== undefined)
     validateSchema(value.schema, `${label}.schema`); if (value.retries !== undefined)
     nonNegativeInteger(value.retries, `${label}.retries`); if (value.timeoutMs !== undefined && value.timeoutMs !== null)
     positiveInteger(value.timeoutMs, `${label}.timeoutMs`); if (value.agentOptions !== undefined && (!object(value.agentOptions) || !jsonValue(value.agentOptions)))
     throw new Error(`${label}.agentOptions is invalid`); if (value.agentIdentity !== undefined) {
-    if (!object(value.agentIdentity) || !Array.isArray(value.agentIdentity.structuralPath) || value.agentIdentity.structuralPath.some((part) => typeof part !== "string") || typeof value.agentIdentity.callSite !== "string")
+    if (!object(value.agentIdentity) || !isList(value.agentIdentity.structuralPath) || value.agentIdentity.structuralPath.some((part) => typeof part !== "string") || typeof value.agentIdentity.callSite !== "string")
         throw new Error(`${label}.agentIdentity is invalid`);
     positiveInteger(value.agentIdentity.occurrence, `${label}.agentIdentity.occurrence`);
     optionalString(value.agentIdentity.parentBreadcrumb, `${label}.agentIdentity.parentBreadcrumb`);
     optionalString(value.agentIdentity.worktreeOwner, `${label}.agentIdentity.worktreeOwner`);
 } }
-function validateSessionReference(value, label) {
-    if (!object(value) || typeof value.transport !== "string" || !value.transport || typeof value.sessionId !== "string" || !value.sessionId || (value.locator !== undefined && !jsonValue(value.locator)))
-        throw new Error(`${label} is invalid`);
-}
+function validateSessionReference(value, label) { if (!object(value) || typeof value.transport !== "string" || !value.transport || typeof value.sessionId !== "string" || !value.sessionId || (value.locator !== undefined && !jsonValue(value.locator)))
+    throw new Error(`${label} is invalid`); }
 function validateAgentSetup(value, label) {
     if (!object(value))
         throw new Error(`${label} is invalid`);
@@ -78,7 +107,7 @@ function validateAgentSetup(value, label) {
     resourceExclusions(value.disabledAgentResources, `${label}.disabledAgentResources`);
 }
 function validateAgent(value, label) {
-    if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.name !== "string" || !value.name || typeof value.path !== "string" || !value.path || typeof value.state !== "string" || !AGENT_STATES.has(value.state))
+    if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.name !== "string" || !value.name || typeof value.path !== "string" || !value.path || !isAgentState(value.state))
         throw new Error(`${label} is invalid`);
     optionalString(value.systemPrompt, `${label}.systemPrompt`);
     optionalString(value.prompt, `${label}.prompt`);
@@ -94,7 +123,7 @@ function validateAgent(value, label) {
     stringList(value.tools, `${label}.tools`);
     nonNegativeInteger(value.attempts, `${label}.attempts`);
     if (value.attemptDetails !== undefined) {
-        if (!Array.isArray(value.attemptDetails))
+        if (!isList(value.attemptDetails))
             throw new Error(`${label}.attemptDetails is invalid`);
         for (const [index, attempt] of value.attemptDetails.entries()) {
             const at = `${label}.attemptDetails[${String(index)}]`;
@@ -102,8 +131,9 @@ function validateAgent(value, label) {
                 throw new Error(`${at} is invalid`);
             validateAgentSetup(attempt.setup, `${at}.setup`);
             if (attempt.session !== undefined) {
-                validateSessionReference(attempt.session, `${at}.session`);
-                if (attempt.session.transport !== attempt.transport)
+                const session = attempt.session;
+                validateSessionReference(session, `${at}.session`);
+                if (session.transport !== attempt.transport)
                     throw new Error(`${at}.session transport does not match attempt transport`);
             }
             accounting(attempt.accounting, `${at}.accounting`);
@@ -114,14 +144,14 @@ function validateAgent(value, label) {
     if (value.accounting !== undefined)
         accounting(value.accounting, `${label}.accounting`);
     if (value.toolCalls !== undefined) {
-        if (!Array.isArray(value.toolCalls))
+        if (!isList(value.toolCalls))
             throw new Error(`${label}.toolCalls is invalid`);
         for (const [index, call] of value.toolCalls.entries())
-            if (!object(call) || typeof call.id !== "string" || !call.id || typeof call.name !== "string" || !call.name || !["running", "completed", "failed"].includes(call.state))
+            if (!object(call) || typeof call.id !== "string" || !call.id || typeof call.name !== "string" || !call.name || !isToolCallState(call.state))
                 throw new Error(`${label}.toolCalls[${String(index)}] is invalid`);
     }
     if (value.activity !== undefined) {
-        if (!object(value.activity) || !["reasoning", "tool", "text"].includes(value.activity.kind) || typeof value.activity.text !== "string")
+        if (!object(value.activity) || !isActivityKind(value.activity.kind) || typeof value.activity.text !== "string")
             throw new Error(`${label}.activity is invalid`);
     }
     if (value.lastEventAt !== undefined)
@@ -131,20 +161,18 @@ function validateUsage(value, label) { if (!object(value))
     throw new Error(`${label} is invalid`); for (const key of ["tokens", "costUsd", "durationMs", "agentLaunches"])
     finiteNumber(value[key], `${label}.${key}`); }
 function validateBudgetEvents(value) { if (value === undefined)
-    return; if (!Array.isArray(value))
+    return; if (!isList(value))
     throw new Error("Persisted budget events are invalid"); for (const [index, event] of value.entries()) {
     const label = `budgetEvents[${String(index)}]`;
-    if (!object(event) || typeof event.type !== "string" || !BUDGET_EVENT_TYPES.has(event.type) || !Number.isSafeInteger(event.budgetVersion) || Number(event.budgetVersion) < 1 || !Array.isArray(event.dimensions) || event.dimensions.some((dimension) => typeof dimension !== "string" || !BUDGET_DIMENSIONS.has(dimension)) || typeof event.at !== "number" || !Number.isFinite(event.at) || event.limits === undefined)
+    if (!object(event) || typeof event.type !== "string" || !BUDGET_EVENT_TYPES.has(event.type) || !Number.isSafeInteger(event.budgetVersion) || Number(event.budgetVersion) < 1 || !isList(event.dimensions) || event.dimensions.some((dimension) => typeof dimension !== "string" || !BUDGET_DIMENSIONS.has(dimension)) || typeof event.at !== "number" || !Number.isFinite(event.at) || event.limits === undefined)
         throw new Error(`${label} is invalid`);
     validateUsage(event.usage, `${label}.usage`);
     validateBudget(event.limits);
 } }
-function validateRunRecord(run) {
-    const value = run;
-    if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.workflowName !== "string" || !value.workflowName || typeof value.cwd !== "string" || !value.cwd || typeof value.sessionId !== "string" || !value.sessionId || !RUN_STATES.includes(value.state) || !Array.isArray(value.agents) || !Array.isArray(value.agentSessions) || Object.hasOwn(value, "nativeSessions"))
+function validateRunRecord(value) {
+    if (!object(value) || typeof value.id !== "string" || !value.id || typeof value.workflowName !== "string" || !value.workflowName || typeof value.cwd !== "string" || !value.cwd || typeof value.sessionId !== "string" || !value.sessionId || !isRunState(value.state) || !isList(value.agents) || !isList(value.agentSessions) || Object.hasOwn(value, "nativeSessions"))
         throw new Error("Persisted run state is invalid");
-    const agents = value.agents;
-    agents.forEach((agent, index) => { validateAgent(agent, `agents[${String(index)}]`); });
+    const agents = value.agents.map((agent, index) => { validateAgent(agent, `agents[${String(index)}]`); return agent; });
     const agentIds = new Set();
     for (const agent of agents) {
         const id = agent.id;
@@ -154,36 +182,36 @@ function validateRunRecord(run) {
     }
     for (const agent of agents) {
         const parentId = agent.parentId;
-        if (parentId !== undefined && (typeof parentId !== "string" || !agentIds.has(parentId)))
+        if (parentId !== undefined && !agentIds.has(parentId))
             throw new Error("Persisted agent has a missing parent");
         const seen = new Set();
-        let parent = typeof parentId === "string" ? parentId : undefined;
+        let parent = parentId;
         while (parent) {
             if (seen.has(parent))
                 throw new Error("Persisted agent parent cycle");
             seen.add(parent);
             const parentAgent = agents.find((candidate) => candidate.id === parent);
-            parent = typeof parentAgent?.parentId === "string" ? parentAgent.parentId : undefined;
+            parent = parentAgent?.parentId;
         }
     }
-    const sessions = value.agentSessions;
-    for (const [index, session] of sessions.entries())
+    for (const [index, session] of value.agentSessions.entries())
         validateSessionReference(session, `agentSessions[${String(index)}]`);
     optionalString(value.parentRunId, "Persisted parent run");
     optionalString(value.failedAt, "Persisted failed path");
-    if (value.retry !== undefined) {
-        if (!object(value.retry) || typeof value.retry.sourceRunId !== "string" || !value.retry.sourceRunId || typeof value.retry.lineageRootRunId !== "string" || !value.retry.lineageRootRunId)
+    const retry = value.retry;
+    if (retry !== undefined) {
+        if (!object(retry) || typeof retry.sourceRunId !== "string" || !retry.sourceRunId || typeof retry.lineageRootRunId !== "string" || !retry.lineageRootRunId)
             throw new Error("Persisted retry provenance is invalid");
-        const sourceRunId = value.retry.sourceRunId;
-        stringList(value.retry.completedPaths, "Persisted retry completed paths");
-        stringList(value.retry.incompletePaths, "Persisted retry incomplete paths");
-        stringList(value.retry.namedWorktrees, "Persisted retry named worktrees");
+        const sourceRunId = retry.sourceRunId;
+        stringList(retry.completedPaths, "Persisted retry completed paths");
+        stringList(retry.incompletePaths, "Persisted retry incomplete paths");
+        stringList(retry.namedWorktrees, "Persisted retry named worktrees");
         if (value.parentRunId !== sourceRunId)
             throw new Error("Persisted retry parent does not match its source");
     }
     optionalString(value.phase, "Persisted phase");
     if (value.phaseHistory !== undefined) {
-        if (!Array.isArray(value.phaseHistory))
+        if (!isList(value.phaseHistory))
             throw new Error("Persisted phase history is invalid");
         for (const phase of value.phaseHistory) {
             if (!object(phase) || typeof phase.phase !== "string" || !phase.phase)
@@ -191,6 +219,18 @@ function validateRunRecord(run) {
             nonNegativeInteger(phase.afterAgent, "Persisted phase history afterAgent");
         }
     }
+    if (value.phaseHistoryIndex !== undefined)
+        nonNegativeInteger(value.phaseHistoryIndex, "Persisted phase history index");
+    if (value.activeShellsByPhase !== undefined) {
+        if (!isList(value.activeShellsByPhase))
+            throw new Error("Persisted phase shell activity is invalid");
+        for (const activity of value.activeShellsByPhase) {
+            if (!object(activity) || !Number.isSafeInteger(activity.phaseIndex) || Number(activity.phaseIndex) < -1)
+                throw new Error("Persisted phase shell activity is invalid");
+            positiveInteger(activity.active, "Persisted phase shell activity count");
+            finiteNumber(activity.startedAt, "Persisted phase shell activity start");
+        }
+    }
     if (value.error !== undefined && (!object(value.error) || typeof value.error.code !== "string" || typeof value.error.message !== "string"))
         throw new Error("Persisted run error is invalid");
     validateBudget(value.budget);
@@ -200,7 +240,7 @@ function validateRunRecord(run) {
         validateUsage(value.usage, "Persisted usage");
     validateBudgetEvents(value.budgetEvents);
     if (value.events !== undefined) {
-        if (!Array.isArray(value.events))
+        if (!isList(value.events))
             throw new Error("Persisted run events are invalid");
         for (const event of value.events)
             if (!object(event) || typeof event.type !== "string" || typeof event.message !== "string")
@@ -208,7 +248,7 @@ function validateRunRecord(run) {
     }
 }
 function validateSnapshot(snapshot) {
-    if (!object(snapshot) || typeof snapshot.script !== "string" || !snapshot.script || !jsonValue(snapshot.args) || !object(snapshot.metadata) || typeof snapshot.metadata.name !== "string" || !snapshot.metadata.name || (snapshot.metadata.description !== undefined && typeof snapshot.metadata.description !== "string") || !object(snapshot.settings) || !Number.isSafeInteger(snapshot.settings.concurrency) || Number(snapshot.settings.concurrency) < 1 || Number(snapshot.settings.concurrency) > 16 || !Array.isArray(snapshot.models) || snapshot.models.some((modelName) => typeof modelName !== "string") || !Array.isArray(snapshot.tools) || snapshot.tools.some((tool) => typeof tool !== "string") || !Array.isArray(snapshot.agentTypes) || snapshot.agentTypes.some((agentType) => typeof agentType !== "string") || !Array.isArray(snapshot.schemas))
+    if (!object(snapshot) || typeof snapshot.script !== "string" || !snapshot.script || !jsonValue(snapshot.args) || !object(snapshot.metadata) || typeof snapshot.metadata.name !== "string" || !snapshot.metadata.name || (snapshot.metadata.description !== undefined && typeof snapshot.metadata.description !== "string") || !object(snapshot.settings) || !Number.isSafeInteger(snapshot.settings.concurrency) || Number(snapshot.settings.concurrency) < 1 || Number(snapshot.settings.concurrency) > 16 || !isList(snapshot.models) || snapshot.models.some((modelName) => typeof modelName !== "string") || !isList(snapshot.tools) || snapshot.tools.some((tool) => typeof tool !== "string") || !isList(snapshot.agentTypes) || snapshot.agentTypes.some((agentType) => typeof agentType !== "string") || !isList(snapshot.schemas))
         throw new Error("Persisted launch snapshot is invalid");
     if (snapshot.identityVersion !== undefined)
         positiveInteger(snapshot.identityVersion, "Persisted snapshot identity version");
@@ -254,7 +294,7 @@ async function validateSystemPrompts(store) {
         await store.systemPrompts();
         return;
     }
-    if (!object(value) || value.version !== 1 || !Array.isArray(value.entries))
+    if (!object(value) || value.version !== 1 || !isList(value.entries))
         throw new Error("Persisted system prompts are invalid");
     for (const [index, entry] of value.entries.entries()) {
         const label = `system-prompts.entries[${String(index)}]`;
@@ -276,6 +316,13 @@ async function validateRunDirectory(store) {
             throw new Error(`Run artifact is not a regular file: ${join(store.directory, entry.name)}`);
     }
 }
+function validateOwnershipRecord(value, label, ownershipIds) {
+    if (!object(value) || typeof value.id !== "string" || !value.id || ownershipIds.has(value.id) || typeof value.label !== "string" || !value.label || !isSchedulerState(value.state))
+        throw new Error(`${label} is invalid`);
+    optionalString(value.parentId, `${label}.parentId`);
+    optionalString(value.prompt, `${label}.prompt`);
+    validateScheduledOptions(value.options, `${label}.options`);
+}
 async function validateRunArtifacts(store, workflowScript, state) {
     await validateRunDirectory(store);
     for (const name of REQUIRED_RUN_FILES)
@@ -283,7 +330,7 @@ async function validateRunArtifacts(store, workflowScript, state) {
     if (await readFile(join(store.directory, "workflow.js"), "utf8") !== workflowScript)
         throw new Error("Persisted workflow source does not match its launch snapshot");
     await validateSystemPrompts(store);
-    const result = await jsonFile(join(store.directory, "result.json")).catch((error) => { if (error.code === "ENOENT")
+    const result = await jsonFile(join(store.directory, "result.json")).catch((error) => { if (isNodeError(error, "ENOENT"))
         return undefined; throw error; });
     if (result === undefined && state === "completed")
         throw new Error("Completed run result is missing");
@@ -291,21 +338,17 @@ async function validateRunArtifacts(store, workflowScript, state) {
         throw new Error("Persisted workflow result is invalid");
     validateJournal(await jsonFile(join(store.directory, "journal.json")));
     const rawOwnership = await jsonFile(join(store.directory, "ownership.json"));
-    if (!Array.isArray(rawOwnership))
+    if (!isList(rawOwnership))
         throw new Error("Persisted ownership records are invalid");
-    const ownership = rawOwnership;
     const ownershipIds = new Set();
-    for (const [index, record] of ownership.entries()) {
+    const ownership = rawOwnership.map((record, index) => {
         const label = `ownership[${String(index)}]`;
-        if (!object(record) || typeof record.id !== "string" || !record.id || ownershipIds.has(record.id) || typeof record.label !== "string" || !record.label || typeof record.state !== "string" || !SCHEDULER_STATES.has(record.state))
-            throw new Error(`${label} is invalid`);
+        validateOwnershipRecord(record, label, ownershipIds);
         ownershipIds.add(record.id);
-        optionalString(record.parentId, `${label}.parentId`);
-        optionalString(record.prompt, `${label}.prompt`);
-        validateScheduledOptions(record.options, `${label}.options`);
-    }
+        return record;
+    });
     for (const record of ownership)
-        if (object(record) && record.parentId !== undefined && (typeof record.parentId !== "string" || !ownershipIds.has(record.parentId)))
+        if (record.parentId !== undefined && !ownershipIds.has(record.parentId))
             throw new Error("Persisted ownership parent is missing");
     await store.validateDeletionWorktrees();
     const borrowed = await store.borrowedWorktrees();
@@ -443,7 +486,7 @@ function planSession(scan, cutoffMs) {
     }
     return { candidates: scan.runs.filter(({ runId }) => oldTerminal.has(runId) && !protectedRuns.has(runId)), skipped };
 }
-function deletionOrder(scan, candidates) {
+function deletionOrder(_scan, candidates) {
     const candidateIds = new Set(candidates.map(({ runId }) => runId));
     const remaining = new Set(candidateIds);
     const ordered = [];
@@ -463,7 +506,7 @@ async function storedSessionIds(cwd, home) {
         entries = await sessionEntries(path);
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (isNodeError(error, "ENOENT"))
             return [];
         throw error;
     }

package/dist/src/doctor.d.ts

@@ -27,8 +27,42 @@ export interface DoctorTrust {
     trusted: boolean;
     source: string;
 }
+export interface DoctorRoleInspection {
+    role: string;
+    path: string;
+    model: {
+        provider: string;
+        model: string;
+        thinking?: string;
+        inherited?: boolean;
+    };
+    tools: readonly string[];
+    resources: {
+        skills: readonly string[];
+        extensions: readonly string[];
+        excludedSkills: readonly string[];
+        excludedExtensions: readonly string[];
+        unmatchedSkills: readonly string[];
+        unmatchedExtensions: readonly string[];
+    };
+    systemPrompt: {
+        probe: string;
+        expandedProbe: string;
+        text: string;
+        source?: string;
+    };
+    setup: {
+        hooks: readonly string[];
+        diagnostics: readonly DoctorDiagnostic[];
+    };
+}
 export interface DoctorPiState {
     trust: DoctorTrust;
+    model?: {
+        provider: string;
+        model: string;
+        thinking?: string;
+    };
     activeTools: readonly string[];
     knownModels: readonly string[];
     availableModels: readonly string[];
@@ -48,16 +82,22 @@ export interface DoctorReport {
     settingsSources: WorkflowSettingsSources;
     trust: DoctorTrust;
     activeTools: readonly string[];
+    piExtensions: readonly string[];
+    piSkills: readonly string[];
     roles: readonly DoctorRole[];
     functions: readonly DoctorFunction[];
     resourcePolicy: AgentResourcePolicy;
     modelAliases: readonly WorkflowCatalogModelAlias[];
+    roleTarget?: string;
+    roleInspection?: DoctorRoleInspection;
     diagnostics: readonly DoctorDiagnostic[];
 }
 export interface DoctorOptions {
     cwd?: string;
     agentDir?: string;
     settingsPath?: string;
+    role?: string;
+    prompt?: string;
     discoverPi?: (cwd: string, agentDir: string) => Promise<DoctorPiState>;
     activeTools?: readonly string[];
     registry?: WorkflowRegistryApi;

package/dist/src/doctor.js

@@ -1,8 +1,8 @@
-import { readFileSync, readdirSync, realpathSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync, statSync } 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, resolveWorkflowSettings, resolveModelReference, parseThinking, parseRoleMarkdown, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "pi-extensible-workflows";
+import { DEFAULT_SETTINGS, createLocalPiSession, errorText, isNodeError, isObject, loadSettings, prepareAgentSetupForInspection, resolveAgentResourcePolicy, resolveWorkflowSettings, resolveModelReference, parseThinking, parseRoleMarkdown, registeredWorkflowFunctions, registeredWorkflowRoleDirectoryRegistrations, workflowRoleDirectories, workflowProjectSettingsPath, workflowSettingsPath, } from "pi-extensible-workflows";
 import { loadingRegistry } from "pi-extensible-workflows";
 import { disabledResources, unmatchedResourcePatterns } from "pi-extensible-workflows";
 const THINKING_HINT = "Use off, minimal, low, medium, high, xhigh, or max.";
@@ -20,16 +20,23 @@ function isDynamicModelAlias(value, aliases) {
     const name = match?.[1];
     return Boolean(name && (match[2] === undefined || parseThinking(match[2]) !== undefined) && aliases.has(name));
 }
+function isCredential(value) {
+    if (!isObject(value))
+        return false;
+    if (value.type === "api_key")
+        return (value.key === undefined || typeof value.key === "string") && (value.env === undefined || isObject(value.env) && Object.values(value.env).every((entry) => typeof entry === "string"));
+    return value.type === "oauth" && typeof value.refresh === "string" && typeof value.access === "string" && typeof value.expires === "number";
+}
 async function readCredentials(agentDir) {
     const credentials = new InMemoryCredentialStore();
     try {
         const parsed = JSON.parse(readFileSync(join(agentDir, "auth.json"), "utf8"));
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        if (!isObject(parsed))
             throw new Error("Pi auth.json must be an object");
-        await Promise.all(Object.entries(parsed).map(([provider, credential]) => credentials.modify(provider, async () => credential)));
+        await Promise.all(Object.entries(parsed).flatMap(([provider, credential]) => isCredential(credential) ? [credentials.modify(provider, async () => credential)] : []));
     }
     catch (error) {
-        if (error.code !== "ENOENT")
+        if (!isNodeError(error, "ENOENT"))
             throw error;
     }
     return credentials;
@@ -40,11 +47,11 @@ function savedTrust(cwd, agentDir) {
         parsed = JSON.parse(readFileSync(join(agentDir, "trust.json"), "utf8"));
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (isNodeError(error, "ENOENT"))
             return undefined;
         throw error;
     }
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+    if (!isObject(parsed))
         throw new Error("Pi trust.json must be an object");
     let current = canonical(cwd);
     while (current !== dirname(current)) {
@@ -86,6 +93,7 @@ async function discoverPi(cwd, agentDir) {
         const skills = services.resourceLoader.getSkills().skills;
         return {
             trust: { required, trusted, source },
+            model: { provider: model.provider, model: model.id, thinking: session.thinkingLevel },
             activeTools,
             knownModels: allModels.map(({ provider, id }) => `${provider}/${id}`),
             availableModels: availableModels.map(({ provider, id }) => `${provider}/${id}`),
@@ -105,12 +113,28 @@ async function discoverPi(cwd, agentDir) {
             process.env.PI_OFFLINE = previousOffline;
     }
 }
+function isRoleFile(dir, entry) {
+    if (extname(entry.name) !== ".md")
+        return false;
+    if (entry.isFile())
+        return true;
+    if (!entry.isSymbolicLink())
+        return false;
+    try {
+        return statSync(join(dir, entry.name)).isFile();
+    }
+    catch (error) {
+        if (isNodeError(error, "ENOENT"))
+            return false;
+        throw error;
+    }
+}
 function roleFiles(dir) {
     try {
-        return readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && extname(entry.name) === ".md").map((entry) => join(dir, entry.name)).sort();
+        return readdirSync(dir, { withFileTypes: true }).filter((entry) => isRoleFile(dir, entry)).map((entry) => join(dir, entry.name)).sort();
     }
     catch (error) {
-        if (error.code === "ENOENT")
+        if (isNodeError(error, "ENOENT"))
             return [];
         throw error;
     }
@@ -127,7 +151,7 @@ function scanExtensionRoleFiles(registrations) {
     for (const registration of registrations) {
         try {
             const entries = readdirSync(registration.path, { withFileTypes: true });
-            const roleFiles = entries.filter((entry) => entry.isFile() && extname(entry.name) === ".md");
+            const roleFiles = entries.filter((entry) => isRoleFile(registration.path, entry));
             if (!roleFiles.length)
                 empty.push(registration);
             for (const entry of roleFiles)
@@ -160,7 +184,8 @@ function validateModel(value, known, available, source, diagnostics, aliases, dy
             diagnostics.push(diagnostic("warning", "MODEL_UNAVAILABLE", `Model is valid-shaped but unavailable: ${name}`, source));
     }
     catch (error) {
-        diagnostics.push(diagnostic("error", "MODEL_INVALID", error.message, source, error.message.includes("thinking") ? THINKING_HINT : "Use provider/model or provider/model:thinking."));
+        const message = errorText(error);
+        diagnostics.push(diagnostic("error", "MODEL_INVALID", message, source, message.includes("thinking") ? THINKING_HINT : "Use provider/model or provider/model:thinking."));
     }
 }
 function inspectRole(path, activeTools, knownModels, availableModels, diagnostics, aliases, dynamicAliases, settingsPath, source) {
@@ -184,7 +209,7 @@ function inspectRole(path, activeTools, knownModels, availableModels, diagnostic
         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."));
+            diagnostics.push(diagnostic("error", "ROLE_TOOL_INACTIVE", `Tool is unknown or inactive: ${tool}`, path, "Use a tool listed under Pi active tools or enable its Pi extension."));
     return definition;
 }
 function matchResourcePolicy(policy, pi) {
@@ -192,6 +217,60 @@ function matchResourcePolicy(policy, pi) {
     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) };
 }
+async function inspectRoleSession(cwd, agentDir, roleName, definition, rolePath, basePolicy, rootModel, activeTools, aliases, knownModels, availableModels, settingsPath, prompt, hooks, diagnostics) {
+    const setupDiagnostics = [];
+    const signal = new AbortController().signal;
+    const transport = { id: "doctor-local", createSession: async () => { throw new Error("Doctor inspection does not create transport sessions"); } };
+    const run = { cwd, sessionId: "doctor", runId: "doctor", workflow: { name: "doctor" }, args: null, signal };
+    const root = { cwd, model: { ...rootModel }, tools: new Set(activeTools), agentDefinitions: { [roleName]: definition }, agentDir, modelAliases: aliases, knownModels, availableModels, settingsPath, agentSetupHooks: hooks, agentResourcePolicy: () => structuredClone(basePolicy), runContext: run };
+    const options = { label: roleName, workflowName: "doctor", role: roleName };
+    let prepared;
+    try {
+        prepared = await prepareAgentSetupForInspection(root, prompt, options, transport);
+    }
+    catch (error) {
+        setupDiagnostics.push(diagnostic("error", "ROLE_INSPECTION", error instanceof Error ? error.message : String(error), rolePath));
+        diagnostics.push(...setupDiagnostics);
+        return undefined;
+    }
+    if (prepared.failure) {
+        const error = prepared.failure.error;
+        const code = prepared.failure.hook ? "ROLE_SETUP_HOOK" : "ROLE_INSPECTION";
+        setupDiagnostics.push(diagnostic("error", code, `${prepared.failure.hook ? `Role setup hook ${prepared.failure.hook} failed: ` : ""}${error instanceof Error ? error.message : String(error)}`, prepared.failure.hook ?? rolePath));
+        diagnostics.push(...setupDiagnostics);
+        return undefined;
+    }
+    const session = await (async () => { try {
+        return await createLocalPiSession({ ...prepared.setup.sessionInput, sessionManager: SessionManager.inMemory() });
+    }
+    catch (error) {
+        setupDiagnostics.push(diagnostic("error", "ROLE_INSPECTION", error instanceof Error ? error.message : String(error), rolePath));
+        return undefined;
+    } })();
+    if (!session) {
+        diagnostics.push(...setupDiagnostics);
+        return undefined;
+    }
+    try {
+        const promptResult = await session.preparePrompt(prompt);
+        const resources = session.getResourceInspection();
+        const state = session.agent?.state;
+        const inherited = prepared.setup.sessionInput.model.provider === rootModel.provider && prepared.setup.sessionInput.model.model === rootModel.model && prepared.setup.sessionInput.model.thinking === rootModel.thinking;
+        const actualModel = session.model?.provider && (session.model.model ?? session.model.id) ? { provider: session.model.provider, model: session.model.model ?? session.model.id ?? prepared.setup.sessionInput.model.model, ...(session.thinkingLevel ? { thinking: session.thinkingLevel } : {}), ...(inherited ? { inherited: true } : {}) } : { ...prepared.setup.sessionInput.model, ...(inherited ? { inherited: true } : {}) };
+        const policy = prepared.setup.sessionInput.resourcePolicy ?? basePolicy;
+        for (const item of [...resources.diagnostics, ...promptResult.diagnostics])
+            setupDiagnostics.push(diagnostic(item.type === "error" ? "error" : "warning", "ROLE_INSPECTION", item.message, item.source));
+        return { role: roleName, path: rolePath, model: actualModel, tools: state?.tools.map(({ name }) => name) ?? [...prepared.setup.sessionInput.tools], resources: { skills: resources.skills, extensions: resources.extensions, excludedSkills: policy.excludedSkills ?? [], excludedExtensions: policy.excludedExtensions ?? [], unmatchedSkills: policy.unmatchedSkills, unmatchedExtensions: policy.unmatchedExtensions }, systemPrompt: { probe: prompt, expandedProbe: promptResult.expandedPrompt, text: promptResult.systemPrompt, ...(resources.systemPromptSource ? { source: resources.systemPromptSource } : {}) }, setup: { hooks: prepared.summary.hookNames, diagnostics: setupDiagnostics } };
+    }
+    catch (error) {
+        setupDiagnostics.push(diagnostic("error", "ROLE_INSPECTION", error instanceof Error ? error.message : String(error), rolePath));
+        diagnostics.push(...setupDiagnostics);
+        return undefined;
+    }
+    finally {
+        await session.dispose();
+    }
+}
 function resourcePolicySource(settingsSource) { return settingsSource; }
 export async function doctor(options = {}) {
     const cwd = canonical(options.cwd ?? process.cwd());
@@ -203,7 +282,7 @@ export async function doctor(options = {}) {
         settings = loadSettings(settingsPath);
     }
     catch (error) {
-        diagnostics.push(diagnostic("error", "SETTINGS_INVALID", error.message, settingsPath, "Fix or remove the invalid workflow settings file."));
+        diagnostics.push(diagnostic("error", "SETTINGS_INVALID", errorText(error), settingsPath, "Fix or remove the invalid workflow settings file."));
     }
     let settingsSources = { concurrency: settingsPath, modelAliases: settingsPath, disabledAgentResources: settingsPath };
     const projectSettingsPath = workflowProjectSettingsPath(cwd);
@@ -212,7 +291,7 @@ export async function doctor(options = {}) {
         pi = await (options.discoverPi ?? discoverPi)(cwd, agentDir);
     }
     catch (error) {
-        diagnostics.push(diagnostic("error", "PI_DISCOVERY", `Pi headless discovery failed: ${error.message}`, undefined, "Open and trust the project in Pi, fix extension errors, then rerun doctor."));
+        diagnostics.push(diagnostic("error", "PI_DISCOVERY", `Pi headless discovery failed: ${errorText(error)}`, undefined, "Open and trust the project in Pi, fix extension errors, then rerun doctor."));
         pi = { trust: { required: false, trusted: false, source: "discovery failed" }, activeTools: [], knownModels: [], availableModels: [], extensionErrors: [], functions: {} };
     }
     if (options.activeTools)
@@ -256,7 +335,7 @@ export async function doctor(options = {}) {
     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 })),
+        ...registeredModelAliases.map(({ name, version, headline }) => ({ name, kind: "dynamic", provenance: `extension: ${headline}`, version, headline })),
     ].sort((left, right) => left.name.localeCompare(right.name) || left.kind.localeCompare(right.kind));
     const roles = [];
     const definitions = new Map();
@@ -335,6 +414,40 @@ export async function doctor(options = {}) {
         else
             definitions.delete(name);
     }
+    let roleInspection;
+    if (options.role !== undefined) {
+        const activeRole = roles.find(({ name, active }) => name === options.role && active);
+        const definition = activeRole ? definitions.get(options.role) : undefined;
+        if (!activeRole || !definition)
+            diagnostics.push(diagnostic("error", "ROLE_NOT_FOUND", `Active role not found: ${options.role}`, options.role));
+        else {
+            const rootReference = pi.model ? `${pi.model.provider}/${pi.model.model}` : pi.availableModels[0] ?? pi.knownModels[0];
+            if (!rootReference)
+                diagnostics.push(diagnostic("error", "ROLE_INSPECTION_MODEL", "Cannot inspect a role because Pi has no registered model"));
+            else {
+                let rootModel;
+                try {
+                    if (pi.model) {
+                        const thinking = parseThinking(pi.model.thinking);
+                        rootModel = { provider: pi.model.provider, model: pi.model.model, ...(thinking ? { thinking } : {}) };
+                    }
+                    else
+                        rootModel = resolveModelReference(rootReference, aliases, knownModels, settingsPath);
+                    let roleAliases = aliases;
+                    if (definition.model && isDynamicModelAlias(definition.model, dynamicAliases)) {
+                        const dynamic = await registry.resolveModelAliases({ cwd, projectTrusted: pi.trust.trusted, rootModel, knownModels, availableModels, signal: new AbortController().signal });
+                        roleAliases = { ...aliases, ...dynamic };
+                    }
+                    roleInspection = await inspectRoleSession(cwd, agentDir, options.role, definition, activeRole.path, resourcePolicy, rootModel, [...activeTools], roleAliases, knownModels, availableModels, settingsPath, options.prompt ?? "", registry.agentSetupHooks(), diagnostics);
+                    if (roleInspection)
+                        diagnostics.push(...roleInspection.setup.diagnostics);
+                }
+                catch (error) {
+                    diagnostics.push(diagnostic("error", "ROLE_INSPECTION_MODEL", error instanceof Error ? error.message : String(error), activeRole.path));
+                }
+            }
+        }
+    }
     const functions = [];
     for (const [name, fn] of Object.entries(pi.functions).sort(([left], [right]) => left.localeCompare(right))) {
         functions.push({ name, description: fn.description, valid: true });
@@ -342,11 +455,55 @@ 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, settingsSources, trust: pi.trust, activeTools: [...activeTools].sort(), roles, functions, modelAliases, resourcePolicy, diagnostics };
+    return { cwd, agentDir, settingsPath, settings, settingsSources, trust: pi.trust, activeTools: [...activeTools].sort(), piExtensions: [...new Set((pi.extensions ?? []).map(canonical))].sort(), piSkills: [...new Set(pi.skills ?? [])].sort(), roles, functions, modelAliases, resourcePolicy, ...(options.role !== undefined ? { roleTarget: options.role } : {}), ...(roleInspection ? { roleInspection } : {}), 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; }
+function exposedValues(values, excluded) {
+    const disabled = new Set(excluded);
+    return values.filter((value) => !disabled.has(value));
+}
+function nestedValues(label, values) {
+    return [`- ${label}:`, ...(values.length ? values.map((value) => `  - \`${value}\``) : ["  - (none)"])];
+}
+function roleInspectionLines(inspection) {
+    return [
+        `- Role: \`${inspection.role}\` - \`${inspection.path}\``,
+        `- Model: \`${inspection.model.provider}/${inspection.model.model}\` (${inspection.model.inherited ? "inherited, " : ""}${inspection.model.thinking ?? "off"})`,
+        ...nestedValues("Tools", inspection.tools),
+        ...nestedValues("Effective skills", inspection.resources.skills),
+        ...nestedValues("Effective extensions", inspection.resources.extensions),
+        ...nestedValues("Excluded skills", inspection.resources.excludedSkills),
+        ...nestedValues("Excluded extensions", inspection.resources.excludedExtensions),
+        ...nestedValues("Unmatched skills", inspection.resources.unmatchedSkills),
+        ...nestedValues("Unmatched extensions", inspection.resources.unmatchedExtensions),
+        `- Prompt probe: ${inspection.systemPrompt.probe ? JSON.stringify(inspection.systemPrompt.probe) : "empty"}`,
+        `- Expanded probe: ${JSON.stringify(inspection.systemPrompt.expandedProbe)}`,
+        `- System prompt source: ${inspection.systemPrompt.source ?? "(none)"}`,
+        "### Final system prompt",
+        "```",
+        inspection.systemPrompt.text,
+        "```",
+        ...nestedValues("Applied setup hooks", inspection.setup.hooks),
+        `- Setup diagnostics: ${String(inspection.setup.diagnostics.length)}`,
+    ];
+}
 export function formatDoctorReport(report) {
+    if (report.roleInspection || report.roleTarget !== undefined) {
+        const lines = [
+            "# pi-extensible-workflows doctor",
+            "",
+            "## Role inspection",
+            ...(report.roleInspection ? roleInspectionLines(report.roleInspection) : [`- Role: \`${report.roleTarget ?? "(unknown)"}\``, "- Inspection unavailable"]),
+            "",
+            "## Diagnostics",
+            ...(report.diagnostics.length ? report.diagnostics.map((item) => `- [${item.severity}] ${item.code}${item.source ? ` \`${item.source}\`` : ""}: ${item.message}${item.hint ? ` Fix: ${item.hint}` : ""}`) : ["- [ok] No diagnostics"]),
+            "",
+            "## Summary",
+            `- ${String(count(report, "error"))} error(s), ${String(count(report, "warning"))} warning(s)`,
+        ];
+        return `${lines.join("\n")}\n`;
+    }
     const lines = [
         "# pi-extensible-workflows doctor",
         "",
@@ -361,7 +518,16 @@ export function formatDoctorReport(report) {
         "## Trust/resources",
         `- [${report.trust.trusted ? "ok" : "warning"}] ${report.trust.source}`,
         "",
-        "## Agent resource exclusions",
+        "## Pi active tools",
+        ...(report.activeTools.length ? report.activeTools.map((tool) => `- \`${tool}\``) : ["- None resolved"]),
+        "",
+        "## Pi active extensions",
+        ...(report.piExtensions.length ? report.piExtensions.map((extension) => `- \`${extension}\``) : ["- None resolved"]),
+        "",
+        "## Pi active skills",
+        ...(report.piSkills.length ? report.piSkills.map((skill) => `- \`${skill}\``) : ["- None resolved"]),
+        "",
+        "## Workflow agent resources (after disabledAgentResources)",
         `- Global settings: \`${report.resourcePolicy.globalSettingsPath}\``,
         `- Global skills: ${report.resourcePolicy.global.skills.join(", ") || "(none)"}`,
         `- Global extensions: ${report.resourcePolicy.global.extensions.join(", ") || "(none)"}`,
@@ -370,14 +536,13 @@ 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)"}`,
+        ...nestedValues("Exposed skills", exposedValues(report.piSkills, report.resourcePolicy.excludedSkills ?? [])),
+        ...nestedValues("Exposed extensions", exposedValues(report.piExtensions, report.resourcePolicy.excludedExtensions ?? [])),
+        ...nestedValues("Disabled skills", report.resourcePolicy.excludedSkills ?? []),
+        ...nestedValues("Disabled extensions", report.resourcePolicy.excludedExtensions ?? []),
         `- Unmatched skills: ${report.resourcePolicy.unmatchedSkills.join(", ") || "(none)"}`,
         `- Unmatched extensions: ${report.resourcePolicy.unmatchedExtensions.join(", ") || "(none)"}`,
         "",
-        "## Active tools",
-        ...(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.extension ? `; ${extensionLabel(role.extension)} role directory "${dirname(role.path)}"` : ""}${role.overrides ? `; overrides \`${role.overrides}\`` : ""}`) : ["- None found"]),
         "",

package/dist/src/session-inspector.js

@@ -14,27 +14,39 @@ function text(content) {
     const parts = content;
     return parts.flatMap((part) => typeof part === "object" && part !== null && "type" in part && part.type === "text" && "text" in part && typeof part.text === "string" ? [part.text] : []).join("");
 }
+function isTranscriptPart(value) {
+    if (typeof value !== "object" || value === null || !("type" in value))
+        return false;
+    if (value.type === "text")
+        return "text" in value && typeof value.text === "string";
+    if (value.type === "thinking")
+        return "thinking" in value && typeof value.thinking === "string";
+    if (value.type === "toolCall")
+        return "name" in value && typeof value.name === "string";
+    return value.type === "image";
+}
+function isTranscriptMessage(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return (!(("role" in value) && value.role !== undefined) || typeof value.role === "string") && (!(("toolName" in value) && value.toolName !== undefined) || typeof value.toolName === "string") && (!(("customType" in value) && value.customType !== undefined) || typeof value.customType === "string");
+}
 function transcriptPartLines(part) {
-    if (typeof part !== "object" || part === null || !("type" in part))
+    if (!isTranscriptPart(part))
         return [];
-    const value = part;
-    if (value.type === "text" && typeof value.text === "string")
-        return value.text.split("\n");
-    if (value.type === "thinking" && typeof value.thinking === "string")
-        return ["Thinking:", ...value.thinking.split("\n")];
-    if (value.type === "toolCall" && typeof value.name === "string")
-        return [`Tool call: ${value.name}`, JSON.stringify(value.arguments, null, 2)];
-    if (value.type === "image")
-        return ["[image]"];
-    return [];
+    if (part.type === "text")
+        return part.text.split("\n");
+    if (part.type === "thinking")
+        return ["Thinking:", ...part.thinking.split("\n")];
+    if (part.type === "toolCall")
+        return [`Tool call: ${part.name}`, JSON.stringify(part.arguments, null, 2)];
+    return ["[image]"];
 }
 function transcriptMessageLines(message) {
-    if (typeof message !== "object" || message === null)
+    if (!isTranscriptMessage(message))
         return ["(invalid message)"];
-    const value = message;
-    const role = typeof value.role === "string" ? value.role : "message";
-    const label = role === "toolResult" && typeof value.toolName === "string" ? `${role}: ${value.toolName}` : role === "custom" && typeof value.customType === "string" ? `${role}: ${value.customType}` : role;
-    const content = Array.isArray(value.content) ? value.content.flatMap(transcriptPartLines) : typeof value.content === "string" ? value.content.split("\n") : [];
+    const role = message.role ?? "message";
+    const label = role === "toolResult" && message.toolName !== undefined ? `${role}: ${message.toolName}` : role === "custom" && message.customType !== undefined ? `${role}: ${message.customType}` : role;
+    const content = Array.isArray(message.content) ? message.content.flatMap(transcriptPartLines) : typeof message.content === "string" ? message.content.split("\n") : [];
     return [`[${label}]`, ...(content.length ? content : ["(empty)"])];
 }
 export function transcriptLines(entries) {
@@ -58,8 +70,11 @@ function mergedModels(groups) {
     return [...totals].map(([model, cost]) => ({ model, cost })).sort((a, b) => b.cost - a.cost || a.model.localeCompare(b.model));
 }
 const thinkingLevels = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+function isThinkingLevel(value) {
+    return typeof value === "string" && thinkingLevels.some((level) => level === value);
+}
 function parsedThinking(value) {
-    return typeof value === "string" && thinkingLevels.includes(value) ? value : undefined;
+    return isThinkingLevel(value) ? value : undefined;
 }
 function modelName(provider, model) {
     return typeof provider === "string" && provider && typeof model === "string" && model ? `${provider}/${model}` : undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piewf/cli",
-  "version": "5.0.0",
+  "version": "5.2.0",
   "description": "CLI for pi-extensible-workflows",
   "homepage": "https://vekexasia.github.io/pi-extensible-workflows/",
   "repository": {
@@ -45,7 +45,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "pi-extensible-workflows": "5.0.0"
+    "pi-extensible-workflows": "5.2.0"
   },
   "publishConfig": {
     "access": "public"