@wichayutdew/pi-workflows 2.6.0 → 2.7.1

package/src/config/validation/step.ts

@@ -2,6 +2,7 @@ import { isAbsolute, win32 } from 'node:path';
 import {
   MAX_WORKSPACE_ALLOWED_ROOTS,
   MAX_WORKSPACE_PATH_CHARS,
+  type ArtifactContract,
   type PromptSpec,
   type StepWorkspaceBinding,
   type WorkflowGate,
@@ -68,6 +69,106 @@ function parseTransitions(
   return transitions;
 }
 
+function parseArtifactContract(
+  value: unknown,
+  path: string,
+  errors: ValidationErrors,
+): ArtifactContract | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return undefined;
+  }
+  rejectUnknownKeys(
+    value,
+    [
+      'maxChars',
+      'requiredSubstrings',
+      'forbiddenSubstrings',
+      'equalOccurrenceGroups',
+      'onValidationFailure',
+    ],
+    path,
+    errors,
+  );
+  if (value.maxChars === undefined) {
+    errors.push(`${path}.maxChars: expected an integer from 1 to 200000`);
+  }
+  const maxChars = readInteger(
+    value.maxChars,
+    200_000,
+    `${path}.maxChars`,
+    errors,
+    { min: 1, max: 200_000 },
+  );
+  const parseSubstrings = (field: string): Array<string> => {
+    const values = readStringList(
+      value[field],
+      `${path}.${field}`,
+      errors,
+      /.+/,
+    );
+    if (values.length > 32) {
+      errors.push(`${path}.${field}: at most 32 values are allowed`);
+    }
+    values.forEach((substring, index) => {
+      if (substring.length > 1_024) {
+        errors.push(`${path}.${field}[${index}]: exceeds 1024 characters`);
+      }
+    });
+    return values;
+  };
+  const equalOccurrenceGroups = (() => {
+    if (value.equalOccurrenceGroups === undefined) return [];
+    if (!Array.isArray(value.equalOccurrenceGroups)) {
+      errors.push(`${path}.equalOccurrenceGroups: expected an array`);
+      return [];
+    }
+    if (value.equalOccurrenceGroups.length > 32) {
+      errors.push(
+        `${path}.equalOccurrenceGroups: at most 32 groups are allowed`,
+      );
+    }
+    return value.equalOccurrenceGroups.reduce<Array<Array<string>>>(
+      (groups, group, index) => {
+        const groupPath = `${path}.equalOccurrenceGroups[${index}]`;
+        const values = readStringList(group, groupPath, errors, /.+/);
+        if (values.length < 2) {
+          errors.push(`${groupPath}: at least two values are required`);
+        }
+        if (values.length > 32) {
+          errors.push(`${groupPath}: at most 32 values are allowed`);
+        }
+        values.forEach((substring, valueIndex) => {
+          if (substring.length > 1_024) {
+            errors.push(`${groupPath}[${valueIndex}]: exceeds 1024 characters`);
+          }
+        });
+        return [...groups, values];
+      },
+      [],
+    );
+  })();
+  const onValidationFailure =
+    value.onValidationFailure === undefined
+      ? undefined
+      : readString(
+          value.onValidationFailure,
+          `${path}.onValidationFailure`,
+          errors,
+        );
+  if (onValidationFailure !== undefined && onValidationFailure !== 'retry') {
+    errors.push(`${path}.onValidationFailure: expected retry`);
+  }
+  return {
+    maxChars,
+    requiredSubstrings: parseSubstrings('requiredSubstrings'),
+    forbiddenSubstrings: parseSubstrings('forbiddenSubstrings'),
+    equalOccurrenceGroups,
+    ...(onValidationFailure === 'retry' ? { onValidationFailure } : {}),
+  };
+}
+
 function parseGate(
   value: unknown,
   path: string,
@@ -86,6 +187,7 @@ function parseGate(
       'approvedOutcome',
       'rejectedOutcome',
       'timeoutMs',
+      'artifactContract',
     ],
     path,
     errors,
@@ -120,6 +222,11 @@ function parseGate(
     errors,
     { pattern: OUTCOME_PATTERN },
   );
+  const artifactContract = parseArtifactContract(
+    value.artifactContract,
+    `${path}.artifactContract`,
+    errors,
+  );
   if (provider === 'prompt' && value.timeoutMs !== undefined) {
     errors.push(`${path}.timeoutMs: only valid with provider "plannotator"`);
   }
@@ -136,12 +243,14 @@ function parseGate(
         submitOutcome,
         approvedOutcome,
         rejectedOutcome,
+        ...(artifactContract ? { artifactContract } : {}),
       }
     : {
         provider,
         submitOutcome,
         approvedOutcome,
         rejectedOutcome,
+        ...(artifactContract ? { artifactContract } : {}),
         timeoutMs: readInteger(
           value.timeoutMs,
           30_000,
@@ -312,6 +421,14 @@ export function parseWorkflowStep(
         `${path}.transitions: submitOutcome is handled by the gate and must not be a transition`,
       );
     }
+    if (
+      gate.artifactContract?.onValidationFailure === 'retry' &&
+      !Object.hasOwn(transitions, 'retry')
+    ) {
+      errors.push(
+        `${path}.transitions: artifact-contract retry requires a "retry" transition`,
+      );
+    }
   }
   if (workspace) {
     workspace.bindOn.forEach((outcome) => {

package/src/harness/artifact-contract.ts

@@ -0,0 +1,46 @@
+import type { ArtifactContract } from '../config/types.ts';
+
+function countOccurrences(value: string, substring: string): number {
+  let count = 0;
+  let offset = 0;
+  while (true) {
+    const match = value.indexOf(substring, offset);
+    if (match === -1) return count;
+    count += 1;
+    offset = match + substring.length;
+  }
+}
+
+export function validateArtifactContract(
+  artifact: string,
+  contract: ArtifactContract | undefined,
+): string | undefined {
+  if (!contract) return undefined;
+  if (artifact.length > contract.maxChars) {
+    return `gate artifact exceeds ${contract.maxChars} characters`;
+  }
+  const required = contract.requiredSubstrings.find(
+    (substring) => !artifact.includes(substring),
+  );
+  if (required) {
+    return `gate artifact is missing required text: ${JSON.stringify(required)}`;
+  }
+  const forbidden = contract.forbiddenSubstrings.find((substring) =>
+    artifact.includes(substring),
+  );
+  if (forbidden) {
+    return `gate artifact contains forbidden text: ${JSON.stringify(forbidden)}`;
+  }
+  for (const group of contract.equalOccurrenceGroups) {
+    const counts = group.map((substring) =>
+      countOccurrences(artifact, substring),
+    );
+    if (counts.some((count) => count === 0)) {
+      return `gate artifact is missing required repeated text: ${JSON.stringify(group)}`;
+    }
+    if (!counts.every((count) => count === counts[0])) {
+      return `gate artifact has unequal repeated text counts: ${JSON.stringify(group)}`;
+    }
+  }
+  return undefined;
+}

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/harness/gate-submission-action.ts

@@ -1,7 +1,9 @@
 import type { LoadedWorkflow } from '../config/types.ts';
 import type { WorkflowRun } from '../engine/state.ts';
+import { validateArtifactContract } from './artifact-contract.ts';
 import {
   attachGateReviewId,
+  advanceRun,
   beginGate,
   failGate,
   failRun,
@@ -19,6 +21,7 @@ type HarnessActionContext = Pick<
   | 'pi'
   | 'restoreBaselineTools'
   | 'run'
+  | 'settleAfterTransition'
   | 'sessionEpoch'
   | 'updateStatus'
 >;
@@ -63,6 +66,31 @@ async function submitGate(
     this.dependencies.createRequestId();
   const step = workflow.definition.steps[originalRun.currentStepId];
   if (!step?.gate) throw new Error('Current step has no gate');
+  const contractError = validateArtifactContract(
+    artifact,
+    step.gate.artifactContract,
+  );
+  if (contractError) {
+    if (step.gate.artifactContract?.onValidationFailure !== 'retry') {
+      throw new Error(contractError);
+    }
+    const retrySummary = `Artifact contract failed: ${contractError}`;
+    this.run = advanceRun(
+      workflow,
+      originalRun,
+      'retry',
+      retrySummary,
+      this.dependencies.now(),
+    );
+    this.persist();
+    this.updateStatus();
+    this.settleAfterTransition(workflow, {
+      stepId: originalRun.currentStepId,
+      outcome: 'retry',
+      summary: retrySummary,
+    });
+    return;
+  }
 
   this.run = beginGate(
     workflow,

package/src/harness/status-actions.ts

@@ -78,6 +78,25 @@ function workflowStatusSnapshot(
 
 function updateStatus(this: StatusContext): void {
   refreshStatusWhileRunning.call(this);
+  const run = this.run;
+  this.pi.events.emit('pi-workflows:state', {
+    state:
+      run?.status === 'running'
+        ? 'working'
+        : run?.status === 'awaiting-gate' || run?.status === 'paused'
+          ? 'blocked'
+          : run?.status === 'completed'
+            ? 'completed'
+            : 'interrupted',
+    workflowId: run?.workflowId,
+    stepId: run?.currentStepId,
+    message:
+      run?.status === 'completed'
+        ? `Workflow "${run.workflowId}" completed`
+        : run?.status === 'paused'
+          ? run.pauseReason
+          : undefined,
+  });
   if (!this.latestContext) return;
   if (this.legacyProgressWidgetContext !== this.latestContext) {
     this.latestContext.ui.setWidget(LEGACY_PROGRESS_WIDGET_KEY, undefined);

package/src/herdr-workflow-state.ts

@@ -0,0 +1,65 @@
+import net from 'node:net';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+const source = 'herdr:pi-workflows';
+
+type WorkflowState = {
+  state: 'working' | 'blocked' | 'completed' | 'interrupted';
+  workflowId?: string;
+  stepId?: string;
+  message?: string;
+};
+
+export default function herdrWorkflowState(pi: ExtensionAPI): void {
+  const socketPath = process.env.HERDR_SOCKET_PATH;
+  const paneId = process.env.HERDR_PANE_ID;
+  if (process.env.HERDR_ENV !== '1' || !socketPath || !paneId) return;
+
+  let seq = Date.now() * 1000;
+  let last = '';
+  pi.events.on('pi-workflows:state', (data: unknown) => {
+    if (!data || typeof data !== 'object') return;
+    const event = data as WorkflowState;
+    if (
+      !['working', 'blocked', 'completed', 'interrupted'].includes(event.state)
+    )
+      return;
+    const state =
+      event.state === 'working'
+        ? 'working'
+        : event.state === 'blocked'
+          ? 'blocked'
+          : 'idle';
+    const message =
+      event.message ??
+      (event.workflowId
+        ? `Workflow "${event.workflowId}" ${event.state}`
+        : undefined);
+    const fingerprint = `${state}:${message ?? ''}`;
+    if (fingerprint === last) return;
+    last = fingerprint;
+    const request = {
+      id: `${source}:${Date.now()}:${++seq}`,
+      method: 'pane.report_agent',
+      params: {
+        pane_id: paneId,
+        source,
+        agent: 'pi-workflows',
+        state,
+        message,
+        seq,
+      },
+    };
+    const socket = net.createConnection(socketPath);
+    const timeout = setTimeout(() => socket.destroy(), 1500);
+    timeout.unref();
+    socket.on('connect', () => socket.write(`${JSON.stringify(request)}\n`));
+    socket.on('data', () => socket.destroy());
+    socket.on('close', () => {
+      clearTimeout(timeout);
+    });
+    socket.on('error', () => {
+      clearTimeout(timeout);
+    });
+  });
+}

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;
 };