pi-workflow-engine 0.8.0 → 0.9.0

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

@@ -302,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.`;
 }
 
@@ -487,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({

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

@@ -6,6 +6,7 @@ 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";
@@ -156,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.
  *
@@ -209,14 +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);
 
-          const { model } = resolveAgentModel(opts.model, rc.modelRegistry, rc.hostModel);
           const createSessionForRun = rc.createSession ?? defaultCreateSession;
 
           throwIfAborted(rc.signal);
@@ -230,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,
@@ -244,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 {

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/types.ts

@@ -79,6 +79,13 @@ export interface AgentOptions<S extends TSchema = TSchema> {
   thinkingLevel?: ThinkingLevel;
   /** Allowlist of built-in tool names the agent may use (e.g. ["read", "bash"]). */
   tools?: string[];
+  /**
+   * Skill names to expose to this subagent. Subagents receive no skills by default.
+   * When omitted, clear prompt text such as `/skill:name`, `include skill name`, or
+   * `use the name skill` is treated as a natural-language opt-in. Pass [] to suppress
+   * prompt inference for prompts that mention skills only as subject matter.
+   */
+  skills?: readonly string[];
   /** typebox schema. When set, the agent is forced to return matching structured data. */
   schema?: S;
 }

package/README.md

@@ -205,6 +205,7 @@ Inline workflows are passed to the `workflow` tool as a script string. They are
 - A single run-level semaphore caps concurrent agents, so nested `parallel`, `pipeline`, and `workflow()` calls stay bounded.
 - Built-in workflows stay statically imported so they share pi's bundled `typebox` identity.
 - Set `thinkingLevel` per fan-out agent. Otherwise many subagents can inherit an expensive global reasoning level.
+- Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; clear prompt text like `include skill name` also works when `skills` is omitted.
 - Set `model` per agent only when needed: bare ids are Anthropic shorthand, and `provider/id` targets other providers.
   Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
 

package/USAGE.md

@@ -146,6 +146,8 @@ Core primitives:
 
 Set `thinkingLevel` on fan-out agents. Otherwise many subagents can inherit an expensive global reasoning level.
 
+Subagents receive no skills by default. Opt in per agent with `skills: ["skill-name"]`; if `tools` is also restricted, the engine automatically keeps `read` available so the subagent can load the selected `SKILL.md`. When `skills` is omitted, clear prompt text such as `/skill:name`, `include skill name`, or `use the name skill` is also treated as an opt-in. Pass `skills: []` to suppress that inference.
+
 Set `model` only when a subagent should use a specific model. Bare ids keep the Anthropic shorthand; `provider/id` targets built-in, custom, or local providers. Omitted models inherit the host/session default; malformed or unknown explicit refs fail fast.
 
 ### Compose workflows
@@ -203,6 +205,7 @@ Inline rules:
 - default-export an async workflow function;
 - no imports or dynamic `import()`;
 - use the injected `Type` object for schemas;
+- add `skills: ["skill-name"]` per `agent()` call when a subagent should use a pi skill; no skills are exposed by default;
 - no extra exports or code after the default export.
 
 Inline workflows run in-process with extension permissions, so treat them as trusted task automation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-workflow-engine",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Zero-dependency Dynamax workflows for pi: live parallel subagents, typed handoffs, synthesized results.",
   "keywords": [