@wichayutdew/pi-workflows 2.7.0 → 3.0.0

package/README.md

@@ -33,8 +33,7 @@ dictating your language, framework, or delivery process.
 - Keep worktree-bound iterations safe, including follow-up enhancements.
 - Enforce declared resources and stop unsafe loops before they run away.
 - Assign a workflow-owned role prompt with `agent: planner`, `worker`,
-  `reviewer`, or `scout`; customize profiles under your user workflow
-  directory's `agents/` folder.
+  `reviewer`, or `scout`; customize profiles under `~/.agents/agents`.
 
 ## Herdr workflow status
 

package/dist/index.js

@@ -1505,17 +1505,19 @@ var directWorkerCommand = (request) => [
   "--print",
   request.task
 ];
-function directWorkerResponse(request, code, signal, stderr) {
+function directWorkerResponse(request, code, signal, stderr, diagnostic) {
   const status = code === 0 ? "completed" : signal ? "cancelled" : "failed";
   return {
     requestId: request.requestId,
     agent: request.agent,
     status,
     ...code === null ? {} : { exitCode: code },
-    ...status !== "completed" && stderr.trim() ? { error: stderr.trim().slice(-4000) } : {}
+    ...status !== "completed" && stderr.trim() ? { error: stderr.trim().slice(-4000) } : {},
+    ...diagnostic ? { diagnostic } : {}
   };
 }
 var MAX_PROGRESS_DETAIL_CHARS = 480;
+var MAX_DIAGNOSTIC_CALLS = 64;
 var SECRET_KEY = /authorization|cookie|password|secret|token|api[-_]?key/i;
 function redactProgressValue(value, key = "") {
   if (SECRET_KEY.test(key))
@@ -1537,6 +1539,52 @@ function formatToolCall(toolName, args) {
   const rendered = JSON.stringify(redactProgressValue(args));
   return `call ${toolName} ${rendered}`.slice(0, MAX_PROGRESS_DETAIL_CHARS);
 }
+var createDiagnostic2 = () => ({
+  settled: false,
+  truncated: false,
+  calls: new Map
+});
+var diagnosticSnapshot = (diagnostic) => ({
+  settled: diagnostic.settled,
+  truncated: diagnostic.truncated,
+  calls: [...diagnostic.calls.values()]
+});
+var recordWorkerDiagnostic = (line, diagnostic) => {
+  let event;
+  try {
+    const parsed = JSON.parse(line);
+    if (typeof parsed !== "object" || parsed === null)
+      return;
+    event = parsed;
+  } catch {
+    return;
+  }
+  if (event.type === "agent_settled") {
+    diagnostic.settled = true;
+    return;
+  }
+  if (event.type !== "tool_execution_start" && event.type !== "tool_execution_end" || typeof event.toolName !== "string" || typeof event.toolCallId !== "string") {
+    return;
+  }
+  if (!diagnostic.calls.has(event.toolCallId)) {
+    if (diagnostic.calls.size >= MAX_DIAGNOSTIC_CALLS) {
+      diagnostic.truncated = true;
+      return;
+    }
+    diagnostic.calls.set(event.toolCallId, {
+      id: event.toolCallId,
+      name: event.toolName,
+      state: "started"
+    });
+  }
+  if (event.type === "tool_execution_end") {
+    diagnostic.calls.set(event.toolCallId, {
+      id: event.toolCallId,
+      name: event.toolName,
+      state: event.isError === false ? "completed" : "failed"
+    });
+  }
+};
 function workerProgressFromJsonLine(line, requestId, toolCount, responseText = "") {
   let event;
   try {
@@ -1609,6 +1657,7 @@ function createSubagentDelegationClient(spawnWorker = spawn) {
       let stdoutBuffer = "";
       let toolCount = 0;
       let responseText = "";
+      const diagnostic = createDiagnostic2();
       const stdoutDecoder = new StringDecoder("utf8");
       const consumeWorkerLines = () => {
         while (true) {
@@ -1618,6 +1667,7 @@ function createSubagentDelegationClient(spawnWorker = spawn) {
             return;
           const line = stdoutBuffer.slice(0, newline);
           stdoutBuffer = stdoutBuffer.slice(newline + 1);
+          recordWorkerDiagnostic(line, diagnostic);
           const progress = workerProgressFromJsonLine(line, request.requestId, toolCount, responseText);
           toolCount = progress.toolCount;
           responseText = progress.responseText;
@@ -1648,7 +1698,7 @@ function createSubagentDelegationClient(spawnWorker = spawn) {
         if (active?.process === child)
           active = undefined;
         options.signal?.removeEventListener("abort", abort);
-        resolve3(directWorkerResponse(request, code, signal, stderr));
+        resolve3(directWorkerResponse(request, code, signal, stderr, diagnosticSnapshot(diagnostic)));
       });
     });
   };
@@ -5461,6 +5511,7 @@ function buildMainWorkflowNotice(workflow, run, statusShortcutLabel = "Ctrl+Alt+
 }
 // src/agents/profile.ts
 import { existsSync as existsSync2, readFileSync } from "node:fs";
+import { homedir as homedir3 } from "node:os";
 import { join as join5 } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse } from "yaml";
@@ -5509,8 +5560,9 @@ function parseAgentProfile(source, name) {
     ...typeof thinking === "string" ? { thinking } : {}
   };
 }
-function loadAgentProfile(name, userDirectory = defaultUserWorkflowDirectory2()) {
-  const userPath = join5(userDirectory, "agents", `${name}.md`);
+var DEFAULT_AGENT_PROFILE_DIRECTORY = join5(homedir3(), ".agents", "agents");
+function loadAgentProfile(name, agentProfileDirectory = DEFAULT_AGENT_PROFILE_DIRECTORY) {
+  const userPath = join5(agentProfileDirectory, `${name}.md`);
   const bundledUrl = new URL(`../../examples/starter-kit/agents/${name}.md`, import.meta.url);
   const path = existsSync2(userPath) ? userPath : fileURLToPath(bundledUrl);
   try {
@@ -6563,6 +6615,26 @@ function createStepExecutionActions() {
   };
 }
 
+// src/integrations/subagents/diagnostics.ts
+var READ_ONLY_TOOLS = new Set([
+  "read",
+  "ls",
+  "grep",
+  "structured_output"
+]);
+var classifyRecoverySafety = (diagnostic) => {
+  if (!diagnostic || !diagnostic.settled || diagnostic.truncated) {
+    return "incomplete";
+  }
+  if (diagnostic.calls.some((call) => call.state !== "completed" || !READ_ONLY_TOOLS.has(call.name))) {
+    return "unsafe";
+  }
+  return "read-only";
+};
+
+// src/harness/delegation-recovery.ts
+var shouldRetryMissingCompletion = (diagnostic, subagentAttemptCount) => subagentAttemptCount === 1 && classifyRecoverySafety(diagnostic) === "read-only";
+
 // src/harness/delegation-response-actions.ts
 function hasErrorCode(error, code) {
   return error instanceof Error && "code" in error && error.code === code;
@@ -6638,7 +6710,15 @@ async function finishDelegation(active, response) {
       serializedResult = await this.dependencies.readDelegatedResult(active);
     } catch (error) {
       if (hasErrorCode(error, "ENOENT")) {
-        throw new Error(`Subagent "${active.agent}" completed without producing the required correlated structured_output result`, { cause: error });
+        const subagentAttemptCount = this.run.currentStepAttempts?.filter((attempt) => attempt.kind === "subagent").length ?? 0;
+        if (shouldRetryMissingCompletion(response.diagnostic, subagentAttemptCount)) {
+          cleanupAttempted = true;
+          await this.cleanupDelegation(active);
+          this.launchCurrentStep(workflow);
+          return;
+        }
+        const diagnosticState = response.diagnostic ? `settled=${response.diagnostic.settled}, truncated=${response.diagnostic.truncated}, calls=${response.diagnostic.calls.length}` : "unavailable";
+        throw new Error(`Subagent "${active.agent}" completed without producing the required correlated structured_output result (request ${active.requestId}; diagnostic ${diagnosticState})`, { cause: error });
       }
       throw error;
     }
@@ -7521,6 +7601,24 @@ var DEFAULT_CHILD_RUNTIME_DEPENDENCIES = {
   tokensAreEqual
 };
 
+// src/integrations/subagents/child-runtime-repair.ts
+var COMPLETION_REPAIR_PROMPT = [
+  "The delegated step settled without its required correlated result.",
+  "Do not repeat completed work and do not execute work tools.",
+  "Call `structured_output` exactly once, alone, with one configured outcome and the required summary, artifact, and workspace fields."
+].join(`
+`);
+var needsCompletionRepair = ({
+  policy,
+  dependencies
+}) => {
+  try {
+    return !dependencies.fileSystem.exists(policy.resultPath);
+  } catch {
+    return false;
+  }
+};
+
 // src/integrations/subagents/child-runtime-files.ts
 var verifyChildWorkingDirectory = (policy, dependencies) => {
   let expected;
@@ -7618,7 +7716,8 @@ var INITIAL_STATE = {
   activePolicy: undefined,
   policyError: undefined,
   invalidCompletionCalls: new Set,
-  effectiveTools: new Set
+  effectiveTools: new Set,
+  repairRequested: false
 };
 var errorMessage2 = (error) => error instanceof Error ? error.message : String(error);
 var invalidPolicyInput = (pi, policyError, images) => {
@@ -7684,7 +7783,8 @@ var registerSubagentChildRuntime = (pi, options = {}) => {
         ...state,
         activePolicy: extracted.policy,
         policyError: undefined,
-        effectiveTools
+        effectiveTools,
+        repairRequested: false
       };
     } catch (error) {
       const policyError = errorMessage2(error);
@@ -7717,6 +7817,19 @@ ${childSystemPrompt(state.activePolicy)}`
   pi.on("turn_start", () => {
     state = { ...state, invalidCompletionCalls: new Set };
   });
+  pi.on("agent_settled", () => {
+    const policy = state.activePolicy;
+    if (!policy || state.repairRequested || !needsCompletionRepair({ policy, dependencies })) {
+      return;
+    }
+    state = {
+      ...state,
+      repairRequested: true,
+      effectiveTools: new Set([CHILD_COMPLETION_TOOL])
+    };
+    pi.setActiveTools([CHILD_COMPLETION_TOOL]);
+    pi.sendUserMessage(COMPLETION_REPAIR_PROMPT, { deliverAs: "followUp" });
+  });
   pi.on("message_end", (event) => {
     if (!state.activePolicy)
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wichayutdew/pi-workflows",
-  "version": "2.7.0",
+  "version": "3.0.0",
   "description": "A declarative, pauseable workflow harness for Pi",
   "license": "MIT",
   "repository": {

package/src/agents/profile.ts

@@ -1,8 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'yaml';
-import { defaultUserWorkflowDirectory } from '../config/load.ts';
 
 export const THINKING_LEVELS = [
   'off',
@@ -74,12 +74,14 @@ export function parseAgentProfile(source: string, name: string): AgentProfile {
   };
 }
 
+const DEFAULT_AGENT_PROFILE_DIRECTORY = join(homedir(), '.agents', 'agents');
+
 /** Loads a user-owned agent profile, with a bundled prompt-only fallback. */
 export function loadAgentProfile(
   name: string,
-  userDirectory = defaultUserWorkflowDirectory(),
+  agentProfileDirectory = DEFAULT_AGENT_PROFILE_DIRECTORY,
 ): AgentProfile {
-  const userPath = join(userDirectory, 'agents', `${name}.md`);
+  const userPath = join(agentProfileDirectory, `${name}.md`);
   const bundledUrl = new URL(
     `../../examples/starter-kit/agents/${name}.md`,
     import.meta.url,

package/src/harness/delegation-recovery.ts

@@ -0,0 +1,15 @@
+import {
+  classifyRecoverySafety,
+  type DelegationDiagnostic,
+} from '../integrations/subagents/diagnostics.ts';
+
+/**
+ * Allows one fresh retry only after the same-child repair settled with complete
+ * read-only evidence. The caller owns preserving run identity and cleanup.
+ */
+export const shouldRetryMissingCompletion = (
+  diagnostic: DelegationDiagnostic | undefined,
+  subagentAttemptCount: number,
+): boolean =>
+  subagentAttemptCount === 1 &&
+  classifyRecoverySafety(diagnostic) === 'read-only';

package/src/harness/delegation-response-actions.ts

@@ -9,6 +9,7 @@ import type { WorkflowStepResult } from '../runtime/step-result.ts';
 import type { HarnessActionContext as FullHarnessActionContext } from './action-context.ts';
 import type { ActiveDelegation } from './types.ts';
 import { resolveStepEffects } from './step-effects.ts';
+import { shouldRetryMissingCompletion } from './delegation-recovery.ts';
 
 type HarnessActionContext = Pick<
   FullHarnessActionContext,
@@ -19,6 +20,7 @@ type HarnessActionContext = Pick<
   | 'finishDelegation'
   | 'isSessionActive'
   | 'latestContext'
+  | 'launchCurrentStep'
   | 'mutationQueue'
   | 'pauseForDelegationFailure'
   | 'releaseMainAfterCancellation'
@@ -174,8 +176,26 @@ async function finishDelegation(
       serializedResult = await this.dependencies.readDelegatedResult(active);
     } catch (error) {
       if (hasErrorCode(error, 'ENOENT')) {
+        const subagentAttemptCount =
+          this.run.currentStepAttempts?.filter(
+            (attempt) => attempt.kind === 'subagent',
+          ).length ?? 0;
+        if (
+          shouldRetryMissingCompletion(
+            response.diagnostic,
+            subagentAttemptCount,
+          )
+        ) {
+          cleanupAttempted = true;
+          await this.cleanupDelegation(active);
+          this.launchCurrentStep(workflow);
+          return;
+        }
+        const diagnosticState = response.diagnostic
+          ? `settled=${response.diagnostic.settled}, truncated=${response.diagnostic.truncated}, calls=${response.diagnostic.calls.length}`
+          : 'unavailable';
         throw new Error(
-          `Subagent "${active.agent}" completed without producing the required correlated structured_output result`,
+          `Subagent "${active.agent}" completed without producing the required correlated structured_output result (request ${active.requestId}; diagnostic ${diagnosticState})`,
           { cause: error },
         );
       }

package/src/integrations/subagents/child-runtime-repair.ts

@@ -0,0 +1,23 @@
+import type { ChildStepPolicy } from './child-policy-types.ts';
+import type { SubagentChildRuntimeDependencies } from './child-runtime-types.ts';
+
+export const COMPLETION_REPAIR_PROMPT = [
+  'The delegated step settled without its required correlated result.',
+  'Do not repeat completed work and do not execute work tools.',
+  'Call `structured_output` exactly once, alone, with one configured outcome and the required summary, artifact, and workspace fields.',
+].join('\n');
+
+/** Returns whether a same-child completion repair may be requested safely. */
+export const needsCompletionRepair = ({
+  policy,
+  dependencies,
+}: {
+  readonly policy: ChildStepPolicy;
+  readonly dependencies: SubagentChildRuntimeDependencies;
+}): boolean => {
+  try {
+    return !dependencies.fileSystem.exists(policy.resultPath);
+  } catch {
+    return false;
+  }
+};

package/src/integrations/subagents/child-runtime.ts

@@ -13,6 +13,10 @@ import {
   parseChildStructuredResult,
 } from './child-runtime-completion.ts';
 import { DEFAULT_CHILD_RUNTIME_DEPENDENCIES } from './child-runtime-dependencies.ts';
+import {
+  COMPLETION_REPAIR_PROMPT,
+  needsCompletionRepair,
+} from './child-runtime-repair.ts';
 import {
   verifyChildCapability,
   verifyChildWorkingDirectory,
@@ -39,6 +43,7 @@ type ChildRuntimeState = {
   readonly policyError: string | undefined;
   readonly invalidCompletionCalls: ReadonlySet<string>;
   readonly effectiveTools: ReadonlySet<string>;
+  readonly repairRequested: boolean;
 };
 
 const INITIAL_STATE: ChildRuntimeState = {
@@ -46,6 +51,7 @@ const INITIAL_STATE: ChildRuntimeState = {
   policyError: undefined,
   invalidCompletionCalls: new Set(),
   effectiveTools: new Set(),
+  repairRequested: false,
 };
 
 const errorMessage = (error: unknown): string =>
@@ -142,6 +148,7 @@ export const registerSubagentChildRuntime = (
         activePolicy: extracted.policy,
         policyError: undefined,
         effectiveTools,
+        repairRequested: false,
       };
     } catch (error) {
       const policyError = errorMessage(error);
@@ -175,6 +182,24 @@ export const registerSubagentChildRuntime = (
     state = { ...state, invalidCompletionCalls: new Set() };
   });
 
+  pi.on('agent_settled', () => {
+    const policy = state.activePolicy;
+    if (
+      !policy ||
+      state.repairRequested ||
+      !needsCompletionRepair({ policy, dependencies })
+    ) {
+      return;
+    }
+    state = {
+      ...state,
+      repairRequested: true,
+      effectiveTools: new Set([CHILD_COMPLETION_TOOL]),
+    };
+    pi.setActiveTools([CHILD_COMPLETION_TOOL]);
+    pi.sendUserMessage(COMPLETION_REPAIR_PROMPT, { deliverAs: 'followUp' });
+  });
+
   pi.on('message_end', (event) => {
     if (!state.activePolicy) return;
     const invalid = invalidCompletionCallIds(

package/src/integrations/subagents/client.ts

@@ -5,6 +5,10 @@ import type {
   SubagentDelegationResponse,
   SubagentDelegationUpdate,
 } from './protocol-events.ts';
+import type {
+  DelegationDiagnostic,
+  DelegationDiagnosticCall,
+} from './diagnostics.ts';
 
 export type DelegateOptions = {
   readonly signal?: AbortSignal;
@@ -52,6 +56,7 @@ export function directWorkerResponse(
   code: number | null,
   signal: NodeJS.Signals | null,
   stderr: string,
+  diagnostic?: DelegationDiagnostic,
 ): SubagentDelegationResponse {
   const status = code === 0 ? 'completed' : signal ? 'cancelled' : 'failed';
   return {
@@ -62,12 +67,15 @@ export function directWorkerResponse(
     ...(status !== 'completed' && stderr.trim()
       ? { error: stderr.trim().slice(-4_000) }
       : {}),
+    ...(diagnostic ? { diagnostic } : {}),
   };
 }
 
 type WorkerJsonEvent = {
   readonly type?: unknown;
+  readonly toolCallId?: unknown;
   readonly toolName?: unknown;
+  readonly isError?: unknown;
   readonly args?: unknown;
   readonly message?: { readonly role?: unknown };
   readonly assistantMessageEvent?: {
@@ -83,6 +91,7 @@ type WorkerProgress = {
 };
 
 const MAX_PROGRESS_DETAIL_CHARS = 480;
+const MAX_DIAGNOSTIC_CALLS = 64;
 const SECRET_KEY = /authorization|cookie|password|secret|token|api[-_]?key/i;
 
 function redactProgressValue(value: unknown, key = ''): unknown {
@@ -110,6 +119,70 @@ function formatToolCall(toolName: string, args: unknown): string {
   return `call ${toolName} ${rendered}`.slice(0, MAX_PROGRESS_DETAIL_CHARS);
 }
 
+type MutableDiagnostic = {
+  settled: boolean;
+  truncated: boolean;
+  calls: Map<string, DelegationDiagnosticCall>;
+};
+
+const createDiagnostic = (): MutableDiagnostic => ({
+  settled: false,
+  truncated: false,
+  calls: new Map(),
+});
+
+const diagnosticSnapshot = (
+  diagnostic: MutableDiagnostic,
+): DelegationDiagnostic => ({
+  settled: diagnostic.settled,
+  truncated: diagnostic.truncated,
+  calls: [...diagnostic.calls.values()],
+});
+
+const recordWorkerDiagnostic = (
+  line: string,
+  diagnostic: MutableDiagnostic,
+): void => {
+  let event: WorkerJsonEvent;
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (typeof parsed !== 'object' || parsed === null) return;
+    event = parsed;
+  } catch {
+    return;
+  }
+  if (event.type === 'agent_settled') {
+    diagnostic.settled = true;
+    return;
+  }
+  if (
+    (event.type !== 'tool_execution_start' &&
+      event.type !== 'tool_execution_end') ||
+    typeof event.toolName !== 'string' ||
+    typeof event.toolCallId !== 'string'
+  ) {
+    return;
+  }
+  if (!diagnostic.calls.has(event.toolCallId)) {
+    if (diagnostic.calls.size >= MAX_DIAGNOSTIC_CALLS) {
+      diagnostic.truncated = true;
+      return;
+    }
+    diagnostic.calls.set(event.toolCallId, {
+      id: event.toolCallId,
+      name: event.toolName,
+      state: 'started',
+    });
+  }
+  if (event.type === 'tool_execution_end') {
+    diagnostic.calls.set(event.toolCallId, {
+      id: event.toolCallId,
+      name: event.toolName,
+      state: event.isError === false ? 'completed' : 'failed',
+    });
+  }
+};
+
 /** Converts one Pi JSONL event into safe, operator-visible worker progress. */
 export function workerProgressFromJsonLine(
   line: string,
@@ -211,6 +284,7 @@ export function createSubagentDelegationClient(
       let stdoutBuffer = '';
       let toolCount = 0;
       let responseText = '';
+      const diagnostic = createDiagnostic();
       const stdoutDecoder = new StringDecoder('utf8');
       const consumeWorkerLines = (): void => {
         while (true) {
@@ -218,6 +292,7 @@ export function createSubagentDelegationClient(
           if (newline === -1) return;
           const line = stdoutBuffer.slice(0, newline);
           stdoutBuffer = stdoutBuffer.slice(newline + 1);
+          recordWorkerDiagnostic(line, diagnostic);
           const progress = workerProgressFromJsonLine(
             line,
             request.requestId,
@@ -250,7 +325,15 @@ export function createSubagentDelegationClient(
         consumeWorkerLines();
         if (active?.process === child) active = undefined;
         options.signal?.removeEventListener('abort', abort);
-        resolve(directWorkerResponse(request, code, signal, stderr));
+        resolve(
+          directWorkerResponse(
+            request,
+            code,
+            signal,
+            stderr,
+            diagnosticSnapshot(diagnostic),
+          ),
+        );
       });
     });
   };

package/src/integrations/subagents/diagnostics.ts

@@ -0,0 +1,43 @@
+export type DiagnosticCallState = 'completed' | 'failed' | 'started';
+
+export type DelegationDiagnosticCall = {
+  readonly id: string;
+  readonly name: string;
+  readonly state: DiagnosticCallState;
+};
+
+export type DelegationDiagnostic = {
+  readonly settled: boolean;
+  readonly truncated: boolean;
+  readonly calls: ReadonlyArray<DelegationDiagnosticCall>;
+};
+
+export type RecoverySafety = 'read-only' | 'unsafe' | 'incomplete';
+
+const READ_ONLY_TOOLS: ReadonlySet<string> = new Set([
+  'read',
+  'ls',
+  'grep',
+  'structured_output',
+]);
+
+/**
+ * Decides whether a fresh child may safely repeat a step after same-child
+ * completion repair failed. Unknown, partial, and mutation-capable evidence
+ * always fails closed.
+ */
+export const classifyRecoverySafety = (
+  diagnostic: DelegationDiagnostic | undefined,
+): RecoverySafety => {
+  if (!diagnostic || !diagnostic.settled || diagnostic.truncated) {
+    return 'incomplete';
+  }
+  if (
+    diagnostic.calls.some(
+      (call) => call.state !== 'completed' || !READ_ONLY_TOOLS.has(call.name),
+    )
+  ) {
+    return 'unsafe';
+  }
+  return 'read-only';
+};

package/src/integrations/subagents/protocol-events.ts

@@ -1,3 +1,5 @@
+import type { DelegationDiagnostic } from './diagnostics.ts';
+
 export const SUBAGENT_DELEGATION_PROTOCOL_VERSION = 1 as const;
 export const SUBAGENT_DELEGATION_REQUEST_EVENT =
   'prompt-template:subagent:request';
@@ -41,4 +43,5 @@ export type SubagentDelegationResponse = {
   readonly error?: string;
   readonly exitCode?: number;
   readonly warnings?: ReadonlyArray<string>;
+  readonly diagnostic?: DelegationDiagnostic;
 };