pi-workflow-engine 0.7.0 → 0.9.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, ExtensionContext } 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, 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 {
@@ -78,7 +81,81 @@ export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Pro
   return mod;
 }
 
-const AUTHOR_TEMP_WORKFLOW_CHOICE = "✍ Author temporary one-shot workflow…";
+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;
@@ -225,6 +302,7 @@ Use the workflow tool with a script argument, not a saved workflow name.
 The script must start with export const meta = { ... } and default-export an async workflow function.
 Use the injected Type object for schemas. Do not import anything or use dynamic import().
 Set thinkingLevel explicitly on each agent() call.
+Subagents receive no skills by default. When the brief asks for a skill or a stage clearly benefits from one, pass \`skills: ["skill-name"]\` on that agent call only.
 Do not edit files unless the user explicitly requested edits.`;
 }
 
@@ -266,11 +344,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",
@@ -297,6 +374,7 @@ 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,
@@ -317,6 +395,10 @@ export async function sendWorkflowResult(
       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);
@@ -336,7 +418,7 @@ 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 },
   );
 }
@@ -346,7 +428,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
 
   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);
   });
 
@@ -406,6 +488,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
       "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.",
+      "Subagents receive no skills by default. In inline workflows, pass `skills: [\"skill-name\"]` per `agent()` call when the user asks for a skill or a stage should use one; grant only the needed skills.",
       "Every workflow tool call must provide exactly one of `name` or `script`, never both.",
     ],
     parameters: Type.Object({
@@ -428,7 +511,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);
@@ -474,6 +557,7 @@ export default function workflowEngine(pi: ExtensionAPI): void {
 
       const { runWorkflow } = await loadEngine();
       let perfSnapshot: PerfSnapshot | undefined;
+      let usageSnapshot: WorkflowUsageSnapshot | undefined;
       let liveInspection: ActiveWorkflowInspection | undefined;
       const resultArgs = params.args ?? "";
       const result = await runWorkflow(ctx, mod, resultArgs, {
@@ -493,6 +577,9 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         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.
@@ -500,8 +587,10 @@ export default function workflowEngine(pi: ExtensionAPI): void {
         },
       });
       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,7 +4,9 @@ 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";
+import { appendSkillReminder, createAgentSkillResourceLoader, extractSkillSelectorsFromText } from "./agent-skills.ts";
 
 /** Name of the synthetic terminating tool that carries structured output. */
 const FINAL_TOOL = "final_answer";
@@ -42,9 +44,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;
@@ -95,6 +157,20 @@ function linkSessionAbort(signal: AbortSignal | undefined, session: AgentRunnerS
   return () => signal.removeEventListener("abort", onAbort);
 }
 
+function buildToolAllowlist(opts: AgentOptions, skillsEnabled: boolean): string[] | undefined {
+  if (!opts.tools) return undefined;
+  const allow = [...opts.tools];
+  if (skillsEnabled && !allow.includes("read")) allow.push("read");
+  if (opts.schema && !allow.includes(FINAL_TOOL)) allow.push(FINAL_TOOL);
+  return allow;
+}
+
+function shouldCreateSkillResourceLoader(rc: RunContext, prompt: string, opts: AgentOptions): boolean {
+  if (!rc.createSession) return true;
+  if (opts.skills !== undefined) return true;
+  return extractSkillSelectorsFromText(prompt).length > 0;
+}
+
 /**
  * Run one subagent to completion in an isolated in-memory session.
  *
@@ -124,7 +200,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({
@@ -142,15 +224,25 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
           : [];
 
         try {
-          // When the workflow restricts built-in tools, keep the terminating tool visible.
-          const allow = opts.tools
-            ? opts.schema
-              ? [...opts.tools, FINAL_TOOL]
-              : opts.tools
+          const { model } = resolveAgentModel(opts.model, rc.modelRegistry, rc.hostModel);
+          const skillSetup = shouldCreateSkillResourceLoader(rc, prompt, opts)
+            ? await rc.perf.time(
+                "agent.skills_ms",
+                () =>
+                  createAgentSkillResourceLoader({
+                    cwd: rc.cwd,
+                    prompt,
+                    skills: opts.skills,
+                    log: (message) => rc.progress.log(`${label}: ${message}`),
+                  }),
+                tags,
+              )
             : undefined;
+          const selectedSkills = skillSetup?.selectedSkills ?? [];
+          // When the workflow restricts built-in tools, keep the terminating tool visible.
+          // Skill opt-ins also need read so the subagent can load SKILL.md on demand.
+          const allow = buildToolAllowlist(opts, selectedSkills.length > 0);
 
-          // 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 createSessionForRun = rc.createSession ?? defaultCreateSession;
 
           throwIfAborted(rc.signal);
@@ -164,6 +256,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
                 thinkingLevel: opts.thinkingLevel,
                 tools: allow,
                 customTools,
+                resourceLoader: skillSetup?.resourceLoader,
                 sessionManager: SessionManager.inMemory(rc.cwd),
               }),
             tags,
@@ -178,9 +271,10 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
             }
           });
 
+          const promptedWithSkills = appendSkillReminder(prompt, selectedSkills);
           const finalPrompt = opts.schema
-            ? `${prompt}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
-            : prompt;
+            ? `${promptedWithSkills}\n\nWhen finished, return your result by calling the ${FINAL_TOOL} tool.`
+            : promptedWithSkills;
           throwIfAborted(rc.signal);
           const unlinkPromptAbort = linkSessionAbort(rc.signal, activeSession);
           try {
@@ -188,6 +282,7 @@ export async function runAgent(rc: RunContext, prompt: string, opts: AgentOption
           } finally {
             unlinkPromptAbort();
           }
+          recordUsage(activeSession);
           throwIfAborted(rc.signal);
 
           return rc.perf.timeSync(
@@ -213,6 +308,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/agent-skills.ts

@@ -0,0 +1,222 @@
+import { DefaultResourceLoader, getAgentDir, type ResourceDiagnostic, type Skill } from "@earendil-works/pi-coding-agent";
+
+export type AgentSkillOption = readonly string[] | undefined;
+export type AgentSkillRequestSource = "explicit" | "prompt";
+
+export interface AgentSkillRequest {
+  readonly selectors: readonly string[];
+  readonly source: AgentSkillRequestSource;
+  readonly strict: boolean;
+}
+
+export interface AgentSkillResolution {
+  readonly selected: readonly Skill[];
+  readonly unmatched: readonly string[];
+}
+
+export interface AgentSkillResourceSetup {
+  readonly resourceLoader: DefaultResourceLoader;
+  readonly selectedSkills: readonly Skill[];
+  readonly unmatchedSelectors: readonly string[];
+  readonly diagnostics: readonly ResourceDiagnostic[];
+}
+
+const SLASH_SKILL_PATTERN = /\/skill:([a-z0-9][a-z0-9-]{0,63})/gi;
+const SKILLS_FIELD_PATTERN = /(?<!\/)\bskills?\s*[:=]\s*([^\n.;]+)/gi;
+const VERB_SKILL_LIST_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?skills?\s+([^\n.;]+)/gi;
+const VERB_NAMED_SKILL_PATTERN = /\b(?:include|use|enable|load|provide|allow|grant|with)\s+(?:the\s+|this\s+|these\s+)?(["'`]?)([a-z0-9][a-z0-9 _-]{0,80}?)\1\s+skills?\b/gi;
+const PURPOSE_BOUNDARY_PATTERN = /\s+\b(?:for|to|when|while|so|because|in\s+order\s+to)\b.*$/i;
+
+/**
+ * Resolve which subagent skills were requested.
+ *
+ * Subagents are skillless by default. Explicit `opts.skills` wins and suppresses prompt inference;
+ * when it is omitted we only infer from clear natural-language opt-ins such as `/skill:name`,
+ * `include skill diagnose`, `include this Skill diagnose`, or `use the diagnose skill`.
+ */
+export function resolveAgentSkillRequest(prompt: string, explicitSkills: unknown): AgentSkillRequest {
+  if (explicitSkills !== undefined) {
+    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), source: "explicit", strict: true };
+  }
+  return { selectors: extractSkillSelectorsFromText(prompt), source: "prompt", strict: false };
+}
+
+export function extractSkillSelectorsFromText(text: string): string[] {
+  const selectors: string[] = [];
+  collectPatternMatches(text, SLASH_SKILL_PATTERN, selectors, 1);
+  collectListPatternMatches(text, SKILLS_FIELD_PATTERN, selectors);
+  collectListPatternMatches(text, VERB_SKILL_LIST_PATTERN, selectors);
+  collectPatternMatches(text, VERB_NAMED_SKILL_PATTERN, selectors, 2);
+  return uniqueSelectors(selectors);
+}
+
+export function normalizeSkillSelector(value: string): string {
+  return value
+    .trim()
+    .replace(/^\/skill:/i, "")
+    .replace(/^skills?\s*[:=]?\s*/i, "")
+    .replace(/^(?:named|called)\s+/i, "")
+    .replace(/^(?:the|this|these)\s+/i, "")
+    .replace(/\s+skills?$/i, "")
+    .replace(/^[`"']+|[`"']+$/g, "")
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^a-z0-9-]/g, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+export function selectAgentSkills(skills: readonly Skill[], selectors: readonly string[]): AgentSkillResolution {
+  const selected = new Map<string, Skill>();
+  const unmatched: string[] = [];
+
+  for (const selector of selectors) {
+    const match = matchSkillSelector(skills, selector);
+    if (!match) {
+      unmatched.push(selector);
+      continue;
+    }
+    selected.set(match.name, makeSkillModelInvocable(match));
+  }
+
+  return { selected: [...selected.values()], unmatched };
+}
+
+export async function createAgentSkillResourceLoader(options: {
+  readonly cwd: string;
+  readonly prompt: string;
+  readonly skills: unknown;
+  readonly log?: (message: string) => void;
+}): Promise<AgentSkillResourceSetup> {
+  const request = resolveAgentSkillRequest(options.prompt, options.skills);
+  let resolution: AgentSkillResolution = { selected: [], unmatched: [] };
+  let availableSkillNames: readonly string[] = [];
+
+  const loader = new DefaultResourceLoader({
+    cwd: options.cwd,
+    agentDir: getAgentDir(),
+    noSkills: request.selectors.length === 0,
+    skillsOverride:
+      request.selectors.length === 0
+        ? undefined
+        : (current) => {
+            availableSkillNames = current.skills.map((skill) => skill.name).sort();
+            resolution = selectAgentSkills(current.skills, request.selectors);
+            return { skills: [...resolution.selected], diagnostics: current.diagnostics };
+          },
+  });
+  await loader.reload();
+  const { diagnostics } = loader.getSkills();
+  logSkillDiagnostics(options.log, diagnostics, request.selectors.length > 0);
+
+  if (request.strict && resolution.unmatched.length > 0) {
+    throw new Error(
+      `Unknown subagent skill${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}. Available: ${
+        availableSkillNames.join(", ") || "(none)"
+      }.`,
+    );
+  }
+
+  if (!request.strict && resolution.unmatched.length > 0) {
+    options.log?.(`Ignoring unrecognized subagent skill mention${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}`);
+  }
+
+  return { resourceLoader: loader, selectedSkills: resolution.selected, unmatchedSelectors: resolution.unmatched, diagnostics };
+}
+
+export function appendSkillReminder(prompt: string, skills: readonly Pick<Skill, "name" | "filePath">[]): string {
+  if (skills.length === 0) return prompt;
+  const skillList = skills.map((skill) => `${skill.name} (${skill.filePath})`).join(", ");
+  return `${prompt}\n\nWorkflow subagent skills enabled: ${skillList}. If you rely on an enabled skill, first read its SKILL.md with the read tool and follow its instructions. No other skills are available in this subagent.`;
+}
+
+function collectPatternMatches(text: string, pattern: RegExp, selectors: string[], captureIndex: number): void {
+  pattern.lastIndex = 0;
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const value = match[captureIndex];
+    if (value !== undefined) selectors.push(value);
+  }
+}
+
+function collectListPatternMatches(text: string, pattern: RegExp, selectors: string[]): void {
+  pattern.lastIndex = 0;
+  for (let match = pattern.exec(text); match !== null; match = pattern.exec(text)) {
+    const value = match[1];
+    if (value === undefined) continue;
+    selectors.push(...parseSkillList(value));
+  }
+}
+
+function parseSkillList(fragment: string): string[] {
+  const scoped = fragment.replace(PURPOSE_BOUNDARY_PATTERN, "");
+  return scoped
+    .split(/\s*(?:,|\s+\band\b\s+|&|\+)\s*/i)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+}
+
+function normalizeExplicitSkillSelectors(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Invalid subagent skills option: expected an array of skill names.");
+  }
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string") {
+      throw new Error("Invalid subagent skills option: every skill name must be a string.");
+    }
+    const normalized = normalizeSkillSelector(item);
+    if (!normalized || isGenericSkillWord(normalized)) {
+      throw new Error(`Invalid subagent skills option: \"${item}\" is not a valid skill name.`);
+    }
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function logSkillDiagnostics(log: ((message: string) => void) | undefined, diagnostics: readonly ResourceDiagnostic[], requested: boolean): void {
+  if (!requested || !log) return;
+  for (const diagnostic of diagnostics) {
+    const where = diagnostic.path ? ` (${diagnostic.path})` : "";
+    log(`skill ${diagnostic.type}: ${diagnostic.message}${where}`);
+  }
+}
+
+function uniqueSelectors(values: Iterable<string>): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values) {
+    const normalized = normalizeSkillSelector(value);
+    if (!normalized || isGenericSkillWord(normalized) || seen.has(normalized)) continue;
+    seen.add(normalized);
+    result.push(normalized);
+  }
+  return result;
+}
+
+function isGenericSkillWord(value: string): boolean {
+  return value === "skill" || value === "skills" || value === "the" || value === "this" || value === "these" || value === "that";
+}
+
+function matchSkillSelector(skills: readonly Skill[], selector: string): Skill | undefined {
+  const normalized = normalizeSkillSelector(selector);
+  if (!normalized) return undefined;
+
+  const exact = skills.find((skill) => skill.name.toLowerCase() === normalized);
+  if (exact) return exact;
+
+  const selectorWords = normalized.replace(/-/g, " ");
+  const fuzzy = skills.filter((skill) => {
+    const name = skill.name.toLowerCase();
+    const words = name.replace(/-/g, " ");
+    return name.includes(normalized) || words.includes(selectorWords);
+  });
+  return fuzzy.length === 1 ? fuzzy[0] : undefined;
+}
+
+function makeSkillModelInvocable(skill: Skill): Skill {
+  return skill.disableModelInvocation ? { ...skill, disableModelInvocation: false } : skill;
+}

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

@@ -32,6 +32,7 @@ Inline workflow rules:
 - Use the injected Type object for schemas, for example Type.Object({ ok: Type.Boolean() }); do not import typebox.
 - Do not use import statements or dynamic import() in inline workflow scripts.
 - Set thinkingLevel explicitly on each agent() call so fan-out remains bounded.
+- Subagents receive no skills by default. Add \`skills: ["skill-name"]\` per agent only when that stage should load that skill; grant the smallest useful set.
 - Provide exactly one of workflow.name or workflow.script.
 `;
 

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

@@ -4,6 +4,7 @@ import { linkAbortSignal } from "./cancellation.ts";
 import { runAgent, type RunContext } from "./agent-runner.ts";
 import { ProgressTracker } from "./progress.ts";
 import { createPerfRecorder, type PerfSnapshot } from "./perf.ts";
+import { createWorkflowUsageRecorder } from "./usage.ts";
 import { defaultConcurrency, resolveWorkflowRunOptions } from "./options.ts";
 import type { AgentOptions, WorkflowApi, WorkflowModule, WorkflowProgressEvent, WorkflowRef, WorkflowRunOptions } from "./types.ts";
 import { WorkflowInspector } from "./ui/workflow-inspector.ts";
@@ -58,6 +59,7 @@ export async function runWorkflow(
   }
 
   const perf = resolvedOptions.perfRecorder ?? createPerfRecorder(resolvedOptions.perf);
+  const usage = createWorkflowUsageRecorder();
   const runAbortController = new AbortController();
   const unlinkContextAbortSignal = linkAbortSignal(ctx.signal, runAbortController);
   const unlinkOptionAbortSignal = linkAbortSignal(resolvedOptions.signal, runAbortController);
@@ -69,6 +71,7 @@ export async function runWorkflow(
     progress,
     signal: runAbortController.signal,
     perf,
+    usage,
   };
 
   try {
@@ -84,6 +87,7 @@ export async function runWorkflow(
     );
   } finally {
     try {
+      resolvedOptions.onUsageSnapshot?.(usage.snapshot());
       const snapshot = perf.snapshot();
       if (resolvedOptions.perf) {
         resolvedOptions.onPerfSnapshot?.(snapshot);