pi-workflow-engine 0.6.1 → 0.8.0

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

@@ -1,11 +1,12 @@
 import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
-import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
+import { SelectList, Text, truncateToWidth, type Component, type SelectItem, type SelectListTheme, type TUI } from "@earendil-works/pi-tui";
 import type { WorkflowProgressSnapshot } from "./src/progress.ts";
-import type { WorkflowModule, WorkflowRunOptions } from "./src/types.ts";
+import type { WorkflowModule, WorkflowProgressSource, WorkflowRef, WorkflowRunOptions } from "./src/types.ts";
 import { WorkflowInspector } from "./src/ui/workflow-inspector.ts";
 import type { PerfSink, PerfSnapshot } from "./src/perf.ts";
+import { formatWorkflowUsageLine, type WorkflowUsageSnapshot } from "./src/usage.ts";
 import { registerDynamax } from "./src/dynamax.ts";
 import { handleReviewViewerAction } from "./src/review/review-actions.ts";
 import { decideReviewResultsPresentation, extensionContextMode, maybeShowReviewResultsViewer } from "./src/review/review-results-flow.ts";
@@ -21,13 +22,15 @@ function summarize(result: unknown): string {
   return typeof result === "string" ? result : "Workflow finished.";
 }
 
-function formatMessageContent(name: string, result: unknown, perf?: WorkflowPerfDetails): string {
+function formatMessageContent(name: string, result: unknown, usage?: WorkflowUsageSnapshot, perf?: WorkflowPerfDetails): string {
+  const usageLine = formatWorkflowUsageLine(usage);
   const perfLine = formatPerfLine(perf);
-  return `## Workflow: ${name}\n\n${summarize(result)}${perfLine ? `\n\n${perfLine}` : ""}`;
+  const details = [usageLine, perfLine].filter((line): line is string => line !== undefined);
+  return `## Workflow: ${name}\n\n${summarize(result)}${details.length > 0 ? `\n\n${details.join("\n")}` : ""}`;
 }
 
-function workflowEnvelope(name: string, result: unknown, perf?: WorkflowPerfDetails): WorkflowResultEnvelope {
-  return { name, result, completedAt: Date.now(), perf };
+function workflowEnvelope(name: string, result: unknown, usage?: WorkflowUsageSnapshot, perf?: WorkflowPerfDetails): WorkflowResultEnvelope {
+  return { name, result, completedAt: Date.now(), usage, perf };
 }
 
 function compactPerfSnapshot(snapshot: PerfSnapshot | undefined): WorkflowPerfDetails | undefined {
@@ -64,7 +67,95 @@ async function createInvocationPerf(options: WorkflowRunOptions): Promise<PerfSi
   return createPerfRecorder(true);
 }
 
-const AUTHOR_TEMP_WORKFLOW_CHOICE = "✍ Author temporary one-shot workflow…";
+/**
+ * Resolve an `api.workflow()` reference to a registered workflow module. Throws on an unknown name.
+ */
+export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Promise<WorkflowModule> {
+  const { discoverWorkflows } = await loadDiscovery();
+  const workflows = await discoverWorkflows(EXTENSION_DIR, { perf });
+  const mod = workflows.get(ref);
+  if (!mod) {
+    const available = [...workflows.keys()].join(", ") || "(none)";
+    throw new Error(`Unknown workflow "${ref}". Available: ${available}`);
+  }
+  return mod;
+}
+
+const AUTHOR_TEMP_WORKFLOW_VALUE = "__author-temporary-workflow__";
+const AUTHOR_TEMP_WORKFLOW_LABEL = "Author temporary one-shot workflow";
+const AUTHOR_TEMP_WORKFLOW_DESCRIPTION = "Ask the host agent to author and run an inline workflow.";
+const WORKFLOW_PICKER_MAX_VISIBLE = 8;
+const WORKFLOW_PICKER_LAYOUT = { minPrimaryColumnWidth: 18, maxPrimaryColumnWidth: 22 };
+
+class WorkflowPickerComponent implements Component {
+  private readonly list: SelectList;
+
+  constructor(
+    items: SelectItem[],
+    private readonly tui: TUI,
+    private readonly theme: Theme,
+    done: (value: string | undefined) => void,
+  ) {
+    this.list = new SelectList(items, Math.min(WORKFLOW_PICKER_MAX_VISIBLE, items.length), selectListTheme(theme), WORKFLOW_PICKER_LAYOUT);
+    this.list.onSelect = (item) => done(item.value);
+    this.list.onCancel = () => done(undefined);
+    this.list.onSelectionChange = () => this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    const safeWidth = Math.max(20, width);
+    const rule = this.theme.fg("borderMuted", "-".repeat(safeWidth));
+    const lines = [
+      rule,
+      this.theme.fg("accent", this.theme.bold("Run workflow")),
+      "",
+      ...this.list.render(safeWidth),
+      "",
+      this.theme.fg("muted", "up/down navigate  enter select  escape cancel"),
+      rule,
+    ];
+    return lines.map((line) => truncateToWidth(line, safeWidth));
+  }
+
+  handleInput(data: string): void {
+    this.list.handleInput(data);
+    this.tui.requestRender();
+  }
+
+  invalidate(): void {
+    this.list.invalidate();
+  }
+}
+
+function selectListTheme(theme: Theme): SelectListTheme {
+  return {
+    selectedPrefix: (text) => theme.fg("accent", text),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("muted", text),
+    scrollInfo: (text) => theme.fg("muted", text),
+    noMatch: (text) => theme.fg("muted", text),
+  };
+}
+
+function workflowPickerItems(workflows: ReadonlyMap<string, WorkflowModule>): SelectItem[] {
+  return [
+    { value: AUTHOR_TEMP_WORKFLOW_VALUE, label: AUTHOR_TEMP_WORKFLOW_LABEL, description: AUTHOR_TEMP_WORKFLOW_DESCRIPTION },
+    ...[...workflows.values()].map((mod) => ({ value: mod.meta.name, label: mod.meta.name, description: mod.meta.description })),
+  ];
+}
+
+async function selectWorkflowValue(workflows: ReadonlyMap<string, WorkflowModule>, ctx: ExtensionCommandContext): Promise<string | undefined> {
+  const items = workflowPickerItems(workflows);
+  if (typeof ctx.ui.custom === "function") {
+    return await ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => new WorkflowPickerComponent(items, tui, theme, done));
+  }
+
+  const choice = await ctx.ui.select(
+    "Run workflow",
+    items.map((item) => item.label),
+  );
+  return items.find((item) => item.label === choice)?.value ?? choice;
+}
 
 export interface LastWorkflowInspection {
   readonly name: string;
@@ -73,19 +164,53 @@ export interface LastWorkflowInspection {
   readonly snapshot: WorkflowProgressSnapshot;
 }
 
+export interface ActiveWorkflowInspection {
+  readonly name: string;
+  readonly args: string;
+  readonly startedAt: number;
+  readonly snapshot: () => WorkflowProgressSnapshot;
+}
+
 let lastWorkflowInspection: LastWorkflowInspection | undefined;
+let activeWorkflowInspection: ActiveWorkflowInspection | undefined;
 
 export function getLastWorkflowInspection(): LastWorkflowInspection | undefined {
   return lastWorkflowInspection;
 }
 
-export async function openWorkflowInspector(ctx: ExtensionCommandContext, inspection: LastWorkflowInspection): Promise<void> {
+export function getActiveWorkflowInspection(): ActiveWorkflowInspection | undefined {
+  return activeWorkflowInspection;
+}
+
+export async function openWorkflowInspector(ctx: ExtensionContext, inspection: LastWorkflowInspection | ActiveWorkflowInspection): Promise<void> {
   await ctx.ui.custom<void>(
-    (tui, theme, _keybindings, done) => new WorkflowInspector(() => inspection.snapshot, tui, theme, () => done(undefined)),
+    (tui, theme, _keybindings, done) => new WorkflowInspector(snapshotGetter(inspection), tui, theme, () => done(undefined)),
     { overlay: true, overlayOptions: { anchor: "right-center", width: "60%", maxHeight: "80%", margin: 1 } },
   );
 }
 
+async function openAvailableWorkflowInspector(ctx: ExtensionContext): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("Workflow inspector requires the TUI", "warning");
+    return;
+  }
+  const inspection = activeWorkflowInspection ?? lastWorkflowInspection;
+  if (!inspection) {
+    ctx.ui.notify("No workflow inspector is available yet", "warning");
+    return;
+  }
+  await openWorkflowInspector(ctx, inspection);
+}
+
+function snapshotGetter(inspection: LastWorkflowInspection | ActiveWorkflowInspection): () => WorkflowProgressSnapshot {
+  const snapshot = inspection.snapshot;
+  return typeof snapshot === "function" ? snapshot : () => snapshot;
+}
+
+function bindActiveWorkflowInspection(name: string, args: string, source: WorkflowProgressSource): ActiveWorkflowInspection {
+  return { name, args, startedAt: Date.now(), snapshot: () => source.snapshot() };
+}
+
 export interface WorkflowInvocation {
   name: string;
   args: string;
@@ -218,11 +343,10 @@ export async function pickWorkflow(
   workflows: ReadonlyMap<string, WorkflowModule>,
   ctx: ExtensionCommandContext,
 ): Promise<WorkflowInvocation | undefined> {
-  const choices = [AUTHOR_TEMP_WORKFLOW_CHOICE, ...[...workflows.values()].map((mod) => `${mod.meta.name} — ${mod.meta.description}`)];
-  const choice = await ctx.ui.select("Run workflow", choices);
+  const choice = await selectWorkflowValue(workflows, ctx);
   if (!choice) return undefined;
 
-  if (choice === AUTHOR_TEMP_WORKFLOW_CHOICE) {
+  if (choice === AUTHOR_TEMP_WORKFLOW_VALUE || choice === AUTHOR_TEMP_WORKFLOW_LABEL) {
     const brief = await ctx.ui.editor(
       "Describe temporary workflow",
       "Goal:\n\nAgents to run:\n- \n\nFinal output should include:\n- summary\n- findings\n- next steps\n",
@@ -249,14 +373,31 @@ export async function sendWorkflowResult(
 ): Promise<void> {
   const { runWorkflow } = await loadEngine();
   let perfSnapshot: PerfSnapshot | undefined;
+  let usageSnapshot: WorkflowUsageSnapshot | undefined;
+  let liveInspection: ActiveWorkflowInspection | undefined;
   const result = await runWorkflow(ctx, mod, args, {
     ...options,
     perf: options.perf ?? perfRecorder !== undefined,
     perfRecorder,
+    resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
+    onProgressSource(source) {
+      if (source) {
+        liveInspection = bindActiveWorkflowInspection(name, args, source);
+        activeWorkflowInspection = liveInspection;
+      } else if (activeWorkflowInspection === liveInspection) {
+        activeWorkflowInspection = undefined;
+        liveInspection = undefined;
+      }
+      options.onProgressSource?.(source);
+    },
     onPerfSnapshot(snapshot) {
       perfSnapshot = snapshot;
       options.onPerfSnapshot?.(snapshot);
     },
+    onUsageSnapshot(snapshot) {
+      usageSnapshot = snapshot;
+      options.onUsageSnapshot?.(snapshot);
+    },
     onProgressSnapshot(snapshot) {
       lastWorkflowInspection = { name, args, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
       options.onProgressSnapshot?.(snapshot);
@@ -276,38 +417,29 @@ export async function sendWorkflowResult(
     await handleReviewViewerAction(pi, ctx, reviewAction, reviewDecision.issues, reviewDecision.report.reviewContext);
   }
   pi.sendMessage(
-    { customType: "workflow-result", content: formatMessageContent(name, result, perf), display: true, details: workflowEnvelope(name, result, perf) },
+    { customType: "workflow-result", content: formatMessageContent(name, result, usageSnapshot, perf), display: true, details: workflowEnvelope(name, result, usageSnapshot, perf) },
     { triggerTurn: false },
   );
 }
 
 export default function workflowEngine(pi: ExtensionAPI): void {
-  registerDynamax(pi);
+  registerDynamax(pi, undefined, { openInspector: openAvailableWorkflowInspector });
 
   pi.registerMessageRenderer("workflow-result", (message, { expanded }, theme) => {
     const details = message.details;
-    if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
+    if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme, details.usage);
     return renderWorkflowResult("workflow", details ?? message.content, expanded, theme);
   });
 
   pi.registerCommand("workflow:inspector", {
-    description: "Open the last completed workflow inspector",
+    description: "Open the current or last workflow inspector",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       const trimmed = args.trim();
       if (trimmed && trimmed !== "last") {
         ctx.ui.notify("Usage: /workflow:inspector [last]", "warning");
         return;
       }
-      if (!ctx.hasUI) {
-        ctx.ui.notify("Workflow inspector requires the TUI", "warning");
-        return;
-      }
-      const inspection = lastWorkflowInspection;
-      if (!inspection) {
-        ctx.ui.notify("No completed workflow inspector is available yet", "warning");
-        return;
-      }
-      await openWorkflowInspector(ctx, inspection);
+      await openAvailableWorkflowInspector(ctx);
     },
   });
 
@@ -354,6 +486,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       "Use workflow with `name` for existing registered workflows such as code-review, diagnose, refactor-scout, or perf-review.",
       "Use workflow with `script` for a new one-off inline workflow; the script must start with `export const meta = { ... }` and default-export an async workflow function.",
       "Inline workflow scripts must use the injected `Type` object for schemas and must not contain imports or dynamic import().",
+      "Inline scripts may compose registered workflows in-process via `api.workflow(\"<name>\", args)` (e.g. `await api.workflow(\"code-review\", \"HEAD~3\")`); it returns the sub-workflow's result and nests one level only.",
       "Every workflow tool call must provide exactly one of `name` or `script`, never both.",
     ],
     parameters: Type.Object({
@@ -376,7 +509,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
     renderResult(result, { expanded, isPartial }, theme) {
       if (isPartial) return new Text(theme.fg("accent", "Running workflow…"), 0, 0);
       const details = result.details;
-      if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme);
+      if (isWorkflowResult(details)) return renderWorkflowResult(details.name, details.result, expanded, theme, details.usage);
       const first = result.content[0];
       const text = first?.type === "text" ? first.text : "Workflow finished.";
       return new Text(theme.fg("muted", text), 0, 0);
@@ -386,6 +519,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       if (request.kind === "error") return invalidWorkflowInvocationResult();
 
       const runOptions: WorkflowRunOptions = {
+        inspect: ctx.hasUI,
         concurrency: params.concurrency,
         parallelSubmissionLimit: params.parallelSubmissionLimit,
         perf: params.perf,
@@ -421,17 +555,40 @@ export default function workflowEngine(pi: ExtensionAPI): void {
 
       const { runWorkflow } = await loadEngine();
       let perfSnapshot: PerfSnapshot | undefined;
-      const result = await runWorkflow(ctx, mod, params.args ?? "", {
+      let usageSnapshot: WorkflowUsageSnapshot | undefined;
+      let liveInspection: ActiveWorkflowInspection | undefined;
+      const resultArgs = params.args ?? "";
+      const result = await runWorkflow(ctx, mod, resultArgs, {
         ...runOptions,
         perf: runOptions.perf ?? perfRecorder !== undefined,
         perfRecorder,
+        resolveWorkflow: (ref) => resolveWorkflowRef(ref, perfRecorder),
+        onProgressSource(source) {
+          if (source) {
+            liveInspection = bindActiveWorkflowInspection(resultName, resultArgs, source);
+            activeWorkflowInspection = liveInspection;
+          } else if (activeWorkflowInspection === liveInspection) {
+            activeWorkflowInspection = undefined;
+            liveInspection = undefined;
+          }
+        },
         onPerfSnapshot: (snapshot) => {
           perfSnapshot = snapshot;
         },
+        onUsageSnapshot: (snapshot) => {
+          usageSnapshot = snapshot;
+        },
+        onProgressSnapshot: (snapshot) => {
+          // Record the run so /workflow:inspector can reopen it — tool-invoked (dynamax) runs were
+          // previously uninspectable, unlike the /workflow command path.
+          lastWorkflowInspection = { name: resultName, args: resultArgs, completedAt: snapshot.doneAt ?? Date.now(), snapshot };
+        },
       });
       const perf = compactPerfSnapshot(perfSnapshot);
+      const usageLine = formatWorkflowUsageLine(usageSnapshot);
       const perfLine = formatPerfLine(perf);
-      return { content: [{ type: "text", text: `${summarize(result)}${perfLine ? `\n\n${perfLine}` : ""}` }], details: workflowEnvelope(resultName, result, perf) };
+      const detailLines = [usageLine, perfLine].filter((line): line is string => line !== undefined);
+      return { content: [{ type: "text", text: `${summarize(result)}${detailLines.length > 0 ? `\n\n${detailLines.join("\n")}` : ""}` }], details: workflowEnvelope(resultName, result, usageSnapshot, perf) };
     },
   });
 }

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

@@ -4,6 +4,7 @@ import type { Api, Model } from "@earendil-works/pi-ai";
 import type { AgentOptions } from "./types.ts";
 import type { Semaphore } from "./concurrency.ts";
 import type { PerfSink } from "./perf.ts";
+import type { WorkflowUsageSink } from "./usage.ts";
 import { throwIfAborted } from "./cancellation.ts";
 
 /** Name of the synthetic terminating tool that carries structured output. */
@@ -42,9 +43,69 @@ export interface RunContext {
   progress: AgentProgress;
   signal: AbortSignal | undefined;
   perf: PerfSink;
+  usage: WorkflowUsageSink;
   createSession?: CreateAgentSession;
 }
 
+export interface ResolvedAgentModelRequest {
+  readonly ref: string;
+  readonly provider: string;
+  readonly id: string;
+}
+
+export interface ResolvedAgentModel {
+  readonly model: Model<Api> | undefined;
+  readonly requested: ResolvedAgentModelRequest | undefined;
+}
+
+function parseAgentModelRef(modelRef: string): ResolvedAgentModelRequest {
+  const normalized = modelRef.trim();
+  if (normalized.length === 0) {
+    throw new Error('Invalid agent model ref: expected a bare model id or "provider/id".');
+  }
+  if (normalized !== modelRef) {
+    throw new Error(`Invalid agent model ref "${modelRef}": remove leading or trailing whitespace.`);
+  }
+
+  const slash = modelRef.indexOf("/");
+  if (slash === -1) {
+    return { ref: modelRef, provider: "anthropic", id: modelRef };
+  }
+
+  const provider = modelRef.slice(0, slash);
+  const id = modelRef.slice(slash + 1);
+  if (provider.length === 0 || id.length === 0 || id.startsWith("/")) {
+    throw new Error(`Invalid agent model ref "${modelRef}": expected "provider/id".`);
+  }
+  return { ref: modelRef, provider, id };
+}
+
+/**
+ * Resolve a workflow agent model reference.
+ *
+ * Omitted refs inherit the host/session default model. Explicit refs are strict:
+ * bare model ids keep the original Anthropic shorthand for compatibility, and
+ * provider-qualified refs split only on the first slash so provider routers such
+ * as OpenRouter can use ids that contain additional slashes.
+ */
+export function resolveAgentModel(
+  modelRef: string | undefined,
+  modelRegistry: Pick<ModelRegistry, "find">,
+  hostModel: Model<Api> | undefined,
+): ResolvedAgentModel {
+  if (modelRef === undefined) {
+    return { model: hostModel, requested: undefined };
+  }
+
+  const parsed = parseAgentModelRef(modelRef);
+  const found = modelRegistry.find(parsed.provider, parsed.id);
+  if (!found) {
+    throw new Error(`Agent model "${modelRef}" not found (resolved as ${parsed.provider}/${parsed.id}).`);
+  }
+
+  return { model: found, requested: parsed };
+}
+
 /** Pull the last assistant message's plain text out of a finished session. */
 function lastAssistantText(state: { readonly messages: readonly unknown[] }): string {
   const messages = state.messages;
@@ -124,7 +185,13 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
         let captured: unknown = null;
         let failed = false;
         let session: AgentRunnerSession | undefined;
+        let usageRecorded = false;
         let unsubscribe: (() => void) | undefined;
+        const recordUsage = (activeSession: AgentRunnerSession): void => {
+          if (usageRecorded) return;
+          usageRecorded = true;
+          rc.usage.recordAgentSession({ label, phase, messages: activeSession.state.messages });
+        };
         const customTools: ToolDefinition[] = opts.schema
           ? [
               defineTool({
@@ -149,8 +216,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
               : opts.tools
             : undefined;
 
-          // Resolve the model by runtime id lookup (no compile-time model-id union); fall back to the host's model.
-          const model = opts.model ? rc.modelRegistry.find("anthropic", opts.model) ?? rc.hostModel : rc.hostModel;
+          const { model } = resolveAgentModel(opts.model, rc.modelRegistry, rc.hostModel);
           const createSessionForRun = rc.createSession ?? defaultCreateSession;
 
           throwIfAborted(rc.signal);
@@ -188,6 +254,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
           } finally {
             unlinkPromptAbort();
           }
+          recordUsage(activeSession);
           throwIfAborted(rc.signal);
 
           return rc.perf.timeSync(
@@ -213,6 +280,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
         } finally {
           const disposable = session;
           if (disposable) {
+            recordUsage(disposable);
             rc.perf.timeSync(
               "agent.dispose_ms",
               () => {

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

@@ -0,0 +1,75 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
+
+export const DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT = "ctrl+shift+m" satisfies KeyId;
+
+const CONFIG_FILE_NAME = "pi-workflow-engine.json";
+
+export interface DynamaxShortcuts {
+  inspector: KeyId | null;
+}
+
+interface DynamaxShortcutConfig {
+  inspector?: unknown;
+}
+
+export function dynamaxShortcutsConfigPath(agentDir: string = getAgentDir()): string {
+  return join(agentDir, "extensions", CONFIG_FILE_NAME);
+}
+
+export function resolveDynamaxShortcuts(configPath: string = dynamaxShortcutsConfigPath()): DynamaxShortcuts {
+  if (!existsSync(configPath)) return defaultDynamaxShortcuts();
+
+  const config = readShortcutConfig(configPath);
+  if (!config) return defaultDynamaxShortcuts();
+
+  return {
+    inspector: shortcutFromConfig(config.inspector, DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT),
+  };
+}
+
+function readShortcutConfig(configPath: string): DynamaxShortcutConfig | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    warnUsingDefaults("Could not read", configPath);
+    return null;
+  }
+
+  const shortcuts = isRecord(parsed) ? parsed.shortcuts : undefined;
+  if (shortcuts === undefined) return {};
+  if (!isRecord(shortcuts) || !hasValidShortcutValues(shortcuts)) {
+    warnUsingDefaults("Invalid", configPath);
+    return null;
+  }
+
+  return shortcuts;
+}
+
+function hasValidShortcutValues(shortcuts: Record<string, unknown>): boolean {
+  return isValidShortcutConfigValue(shortcuts.inspector);
+}
+
+function isValidShortcutConfigValue(value: unknown): value is string | null | undefined {
+  return value === undefined || value === null || (typeof value === "string" && value.trim().length > 0);
+}
+
+function shortcutFromConfig(configured: unknown, fallback: KeyId): KeyId | null {
+  if (configured === null) return null;
+  return typeof configured === "string" ? (configured.trim() as KeyId) : fallback;
+}
+
+function defaultDynamaxShortcuts(): DynamaxShortcuts {
+  return { inspector: DEFAULT_DYNAMAX_INSPECTOR_SHORTCUT };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function warnUsingDefaults(reason: "Could not read" | "Invalid", configPath: string): void {
+  console.warn(`${reason} pi-workflow-engine config at ${configPath}; using default Dynamax shortcuts.`);
+}