@wichayutdew/pi-workflows 2.6.0 → 2.7.0

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/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);
+    });
+  });
+}