pi-workflow-engine 0.10.3 → 0.12.0

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

@@ -1,11 +1,16 @@
-import { DefaultResourceLoader, getAgentDir, type ResourceDiagnostic, type Skill } from "@earendil-works/pi-coding-agent";
+import type {
+  CreateAgentSessionServicesOptions,
+  ResourceDiagnostic,
+  ResourceLoader,
+  Skill,
+} from "@earendil-works/pi-coding-agent";
+import { dirname, resolve } from "node:path";
+import { logicalWorkspacePath, type ReplayWorkspaceRoots } from "./replay-path-identity.ts";
+import { captureTreeFingerprint } from "./tree-fingerprint.ts";
+import type { ResolvedSkillIdentity } from "./resume-context.ts";
 
-export type AgentSkillOption = readonly string[] | undefined;
-export type AgentSkillRequestSource = "explicit" | "prompt";
-
-export interface AgentSkillRequest {
+interface AgentSkillRequest {
   readonly selectors: readonly string[];
-  readonly source: AgentSkillRequestSource;
   readonly strict: boolean;
 }
 
@@ -14,13 +19,28 @@ export interface AgentSkillResolution {
   readonly unmatched: readonly string[];
 }
 
-export interface AgentSkillResourceSetup {
-  readonly resourceLoader: DefaultResourceLoader;
-  readonly selectedSkills: readonly Skill[];
-  readonly unmatchedSelectors: readonly string[];
-  readonly diagnostics: readonly ResourceDiagnostic[];
+type AgentSkillResourceLoaderOptions = Pick<
+  NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>,
+  "noSkills" | "skillsOverride"
+>;
+
+interface PreparedAgentSkillResources {
+  readonly resourceLoaderOptions: AgentSkillResourceLoaderOptions;
+  resolve(resourceLoader: Pick<ResourceLoader, "getSkills">): readonly Skill[];
+}
+
+export type AgentSkillIdentityCapture =
+  | { readonly kind: "verified"; readonly skills: readonly ResolvedSkillIdentity[] }
+  | { readonly kind: "unverifiable"; readonly reason: string };
+
+export interface AgentSkillIdentityOptions extends ReplayWorkspaceRoots {
+  readonly signal?: AbortSignal;
 }
 
+const SKILL_FINGERPRINT_EXCLUSIONS = new Set([".git", "node_modules"]);
+const SKILL_FINGERPRINT_MAX_BYTES = 8 << 20;
+const SKILL_FINGERPRINT_MAX_FILES = 1024;
+
 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;
@@ -36,9 +56,9 @@ const PURPOSE_BOUNDARY_PATTERN = /\s+\b(?:for|to|when|while|so|because|in\s+orde
  */
 export function resolveAgentSkillRequest(prompt: string, explicitSkills: unknown): AgentSkillRequest {
   if (explicitSkills !== undefined) {
-    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), source: "explicit", strict: true };
+    return { selectors: normalizeExplicitSkillSelectors(explicitSkills), strict: true };
   }
-  return { selectors: extractSkillSelectorsFromText(prompt), source: "prompt", strict: false };
+  return { selectors: extractSkillSelectorsFromText(prompt), strict: false };
 }
 
 export function extractSkillSelectorsFromText(text: string): string[] {
@@ -83,19 +103,21 @@ export function selectAgentSkills(skills: readonly Skill[], selectors: readonly
   return { selected: [...selected.values()], unmatched };
 }
 
-export async function createAgentSkillResourceLoader(options: {
-  readonly cwd: string;
+/**
+ * Prepare the skill-selection hooks consumed by pi's session-service factory.
+ * The returned resolver is scoped to one resource loader and must not be reused
+ * across concurrently-created session services.
+ */
+export function prepareAgentSkillResources(options: {
   readonly prompt: string;
   readonly skills: unknown;
   readonly log?: (message: string) => void;
-}): Promise<AgentSkillResourceSetup> {
+}): PreparedAgentSkillResources {
   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(),
+  const resourceLoaderOptions: AgentSkillResourceLoaderOptions = {
     noSkills: request.selectors.length === 0,
     skillsOverride:
       request.selectors.length === 0
@@ -105,30 +127,56 @@ export async function createAgentSkillResourceLoader(options: {
             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 {
+    resourceLoaderOptions,
+    resolve(resourceLoader) {
+      const { diagnostics } = resourceLoader.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)"
+          }.`,
+        );
+      }
 
-  return { resourceLoader: loader, selectedSkills: resolution.selected, unmatchedSelectors: resolution.unmatched, diagnostics };
+      if (!request.strict && resolution.unmatched.length > 0) {
+        options.log?.(`Ignoring unrecognized subagent skill mention${resolution.unmatched.length === 1 ? "" : "s"}: ${resolution.unmatched.join(", ")}`);
+      }
+
+      return resolution.selected;
+    },
+  };
 }
 
-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.`;
+/** Capture the exact selected skill directories before journal lookup. */
+export async function captureAgentSkillIdentities(
+  skills: readonly Skill[],
+  options: AgentSkillIdentityOptions,
+): Promise<AgentSkillIdentityCapture> {
+  const identities: ResolvedSkillIdentity[] = [];
+  for (const skill of skills) {
+    const root = resolve(dirname(skill.filePath));
+    const capture = await captureTreeFingerprint({
+      root,
+      excludedRelativePaths: SKILL_FINGERPRINT_EXCLUSIONS,
+      maxBytes: SKILL_FINGERPRINT_MAX_BYTES,
+      maxFiles: SKILL_FINGERPRINT_MAX_FILES,
+      signal: options.signal,
+    });
+    if (capture.kind === "unverifiable") {
+      return { kind: "unverifiable", reason: `skill ${skill.name} could not be fingerprinted: ${capture.reason}` };
+    }
+    identities.push({
+      name: skill.name,
+      path: logicalWorkspacePath(root, options) ?? `external:${skill.name}`,
+      fingerprint: capture.fingerprint,
+    });
+  }
+  return { kind: "verified", skills: identities };
 }
 
 function collectPatternMatches(text: string, pattern: RegExp, selectors: string[], captureIndex: number): void {

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

@@ -0,0 +1,89 @@
+import type { AgentExecutionOptions, AgentProgress } from "./agent-runner-types.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+import type { WorktreeRegistry } from "./worktree.ts";
+
+interface AgentWorkspaceBase {
+  readonly cwd: string;
+  wrapResult(result: unknown): Promise<unknown>;
+  dispose(): Promise<void>;
+}
+
+export interface SharedAgentWorkspace extends AgentWorkspaceBase {
+  readonly kind: "shared";
+}
+
+export interface IsolatedAgentWorkspace extends AgentWorkspaceBase {
+  readonly kind: "isolated";
+  readonly baselineOid: string;
+}
+
+export type AgentWorkspace = SharedAgentWorkspace | IsolatedAgentWorkspace;
+
+export interface AgentWorkspaceContext {
+  readonly cwd: string;
+  readonly worktrees: Pick<WorktreeRegistry, "probe" | "add" | "capturePatch" | "remove">;
+  readonly signal: AbortSignal | undefined;
+  readonly progress: Pick<AgentProgress, "log">;
+}
+
+export async function createAgentWorkspace(
+  rc: AgentWorkspaceContext,
+  opts: AgentExecutionOptions,
+  label: string,
+): Promise<AgentWorkspace> {
+  if (opts.isolation !== "worktree") {
+    return {
+      kind: "shared",
+      cwd: rc.cwd,
+      async wrapResult(result) {
+        return result;
+      },
+      async dispose() {},
+    };
+  }
+
+  const probe = await rc.worktrees.probe(rc.signal);
+  if (!probe.ok) {
+    throw new Error(`Failed to check git worktree availability for isolated agent: ${probe.error ?? "unknown git error"}`);
+  }
+  if (!probe.inside) {
+    throw new Error("Agent requested worktree isolation, but the workflow cwd is not inside a git work tree.");
+  }
+
+  const added = await rc.worktrees.add(rc.signal, opts.worktreeBaseline);
+  if ("error" in added) throw new Error(`Failed to create isolated worktree: ${added.error}`);
+  const worktreePath = added.path;
+  rc.progress.log(`${label}: using isolated worktree ${worktreePath}`);
+
+  return {
+    kind: "isolated",
+    cwd: worktreePath,
+    baselineOid: added.baselineOid,
+    async wrapResult(result) {
+      const patch = await rc.worktrees.capturePatch(worktreePath, added.baselineOid, rc.signal);
+      if ("error" in patch) throw new Error(`Failed to capture isolated worktree patch: ${patch.error}`);
+      return { result, patch: patch.patch, changed: patch.changed };
+    },
+    async dispose() {
+      const removed = await rc.worktrees.remove(worktreePath);
+      if (!removed.ok) {
+        rc.progress.log(
+          `${label}: failed to remove isolated worktree (${removed.error ?? (removed.stderr.trim() || "unknown error")})`,
+        );
+      }
+    },
+  };
+}
+
+export async function disposeAgentWorkspace(
+  rc: Pick<AgentWorkspaceContext, "progress">,
+  label: string,
+  workspace: AgentWorkspace | undefined,
+): Promise<void> {
+  if (!workspace) return;
+  try {
+    await workspace.dispose();
+  } catch (error) {
+    rc.progress.log(`${label}: failed to dispose isolated workspace (${unknownErrorMessage(error)})`);
+  }
+}

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

@@ -0,0 +1,75 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BackgroundWorkflowCoordinator, backgroundOrigin } from "./background-workflows.ts";
+import { createWorkflowRunId } from "./journal.ts";
+import type { ResolvedWorkflowRunOptions } from "./options.ts";
+import { unknownErrorMessage } from "./unknown-error.ts";
+
+export interface BackgroundWorkflowToolResult {
+  readonly content: Array<{ readonly type: "text"; readonly text: string }>;
+  readonly details: Readonly<Record<string, unknown>>;
+}
+
+export interface BackgroundWorkflowToolStartInput {
+  readonly coordinator: BackgroundWorkflowCoordinator;
+  readonly ctx: ExtensionContext;
+  readonly name: string;
+  readonly options: ResolvedWorkflowRunOptions;
+  readonly execute: (ctx: ExtensionContext, options: ResolvedWorkflowRunOptions) => Promise<void>;
+}
+
+export function backgroundUnavailableResult(mode: ExtensionContext["mode"]): BackgroundWorkflowToolResult | undefined {
+  if (mode !== "print" && mode !== "json") return undefined;
+  return {
+    content: [{
+      type: "text",
+      text: `Background workflows are unavailable in ${mode} mode because pi exits after the prompt. Run synchronously or use TUI/RPC mode.`,
+    }],
+    details: { error: "background_unavailable", mode },
+  };
+}
+
+export async function startBackgroundWorkflowTool(
+  input: BackgroundWorkflowToolStartInput,
+): Promise<BackgroundWorkflowToolResult> {
+  const runId = createWorkflowRunId();
+  const backgroundOptions: ResolvedWorkflowRunOptions = {
+    ...input.options,
+    inspect: false,
+    resultViewer: "skip",
+    runId,
+    background: backgroundOrigin(input.ctx),
+  };
+  try {
+    await input.coordinator.start({
+      ctx: input.ctx,
+      runId,
+      name: input.name,
+      run: async (signal, onStarted) => {
+        await input.execute(
+          { ...input.ctx, signal },
+          {
+            ...backgroundOptions,
+            signal,
+            onRunMetadata(metadata) {
+              onStarted();
+              return backgroundOptions.onRunMetadata?.(metadata);
+            },
+          },
+        );
+      },
+    });
+  } catch (error) {
+    const message = unknownErrorMessage(error);
+    return {
+      content: [{ type: "text", text: `Background workflow did not start: ${message}` }],
+      details: { error: "background_start_failed", message, runId },
+    };
+  }
+  return {
+    content: [{
+      type: "text",
+      text: `Background workflow "${input.name}" started.\nRun ID: ${runId}\nDurable record: .pi/.workflow-runs/${runId}.run.json`,
+    }],
+    details: { background: true, state: "running", name: input.name, runId },
+  };
+}