@wichayutdew/pi-workflows 2.6.0 → 2.7.0

package/README.md

@@ -36,6 +36,36 @@ dictating your language, framework, or delivery process.
   `reviewer`, or `scout`; customize profiles under your user workflow
   directory's `agents/` folder.
 
+## Herdr workflow status
+
+When Pi runs delegated workflow steps, the parent agent may be idle while child work continues. Pi Workflows includes a Herdr companion extension that reports workflow lifecycle state so the pane remains **working** until the workflow completes, pauses, or is interrupted.
+
+The companion is inactive unless Herdr provides `HERDR_ENV=1`, `HERDR_SOCKET_PATH`, and `HERDR_PANE_ID`. It uses Herdr's existing managed Pi reporter, so it does not create a competing pane agent.
+
+### Install from npm
+
+```bash
+pi install npm:@wichayutdew/pi-workflows
+```
+
+Start a new Pi session in Herdr, then run a workflow normally. Herdr should show the pane as working while the workflow is active and display the terminal workflow message after completion or interruption.
+
+### Reapply after a Herdr update
+
+Herdr manages `~/.pi/agent/extensions/herdr-agent-state.ts`; an integration update can replace the workflow lifecycle patch. Locate the installed package with `pi list`, change into that package directory, and run:
+
+```bash
+npm run patch:herdr
+```
+
+The script patches the managed integration at its default location. It is idempotent, so it is safe to run after every Herdr update. To patch a non-default integration path, set `HERDR_PI_EXTENSION_PATH` before running the script:
+
+```bash
+HERDR_PI_EXTENSION_PATH=/path/to/herdr-agent-state.ts npm run patch:herdr
+```
+
+Restart Pi or run `/reload` after patching. If Herdr's managed extension changes shape and the script reports an unsupported layout, do not edit it manually; update Pi Workflows or report the integration change.
+
 ## Explore
 
 - [Getting started guide](./GETTING_STARTED.md) — install Pi Workflows and

package/dist/index.js

@@ -518,6 +518,75 @@ function parseTransitions(value, path, errors) {
   }
   return transitions;
 }
+function parseArtifactContract(value, path, errors) {
+  if (value === undefined)
+    return;
+  if (!isJsonObject(value)) {
+    errors.push(`${path}: expected an object`);
+    return;
+  }
+  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, 200000, `${path}.maxChars`, errors, { min: 1, max: 200000 });
+  const parseSubstrings = (field) => {
+    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 > 1024) {
+        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((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 > 1024) {
+          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, path, errors) {
   if (value === undefined)
     return;
@@ -530,7 +599,8 @@ function parseGate(value, path, errors) {
     "submitOutcome",
     "approvedOutcome",
     "rejectedOutcome",
-    "timeoutMs"
+    "timeoutMs",
+    "artifactContract"
   ], path, errors);
   const providerValue = value.provider === undefined ? "prompt" : readString(value.provider, `${path}.provider`, errors);
   const provider = providerValue === "prompt" || providerValue === "plannotator" ? providerValue : undefined;
@@ -540,6 +610,7 @@ function parseGate(value, path, errors) {
   const submitOutcome = readString(value.submitOutcome, `${path}.submitOutcome`, errors, { pattern: OUTCOME_PATTERN });
   const approvedOutcome = readString(value.approvedOutcome, `${path}.approvedOutcome`, errors, { pattern: OUTCOME_PATTERN });
   const rejectedOutcome = readString(value.rejectedOutcome, `${path}.rejectedOutcome`, 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"`);
   }
@@ -553,12 +624,14 @@ function parseGate(value, path, errors) {
     provider,
     submitOutcome,
     approvedOutcome,
-    rejectedOutcome
+    rejectedOutcome,
+    ...artifactContract ? { artifactContract } : {}
   } : {
     provider,
     submitOutcome,
     approvedOutcome,
     rejectedOutcome,
+    ...artifactContract ? { artifactContract } : {},
     timeoutMs: readInteger(value.timeoutMs, 30000, `${path}.timeoutMs`, errors, { min: 1000, max: 30000 })
   };
 }
@@ -649,6 +722,9 @@ function parseWorkflowStep(value, stepId, path, errors) {
     if (Object.hasOwn(transitions, gate.submitOutcome)) {
       errors.push(`${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) => {
@@ -1595,19 +1671,6 @@ function createSubagentDelegationClient(spawnWorker = spawn) {
   };
 }
 
-class SubagentDelegationClient {
-  #client = createSubagentDelegationClient();
-  get activeRequestId() {
-    return this.#client.activeRequestId;
-  }
-  delegate(request, options) {
-    return this.#client.delegate(request, options);
-  }
-  cancelActiveAndWait(waitMs) {
-    return this.#client.cancelActiveAndWait(waitMs);
-  }
-}
-
 // src/policy/completion-batch.ts
 var isRecord3 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 var toolCalls = (message) => {
@@ -4005,6 +4068,13 @@ function workflowStatusSnapshot() {
 }
 function updateStatus() {
   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) {
@@ -6700,6 +6770,44 @@ function createDelegationControlActions() {
   };
 }
 
+// src/harness/artifact-contract.ts
+function countOccurrences(value, substring) {
+  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;
+  }
+}
+function validateArtifactContract(artifact, contract) {
+  if (!contract)
+    return;
+  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;
+}
+
 // src/harness/gate-submission-action.ts
 function isCurrentGateRequest(run, originalRun, requestId) {
   return run !== undefined && run.runId === originalRun.runId && run.currentStepId === originalRun.currentStepId && run.pendingGate?.requestId === requestId && run.pendingGate.reviewId === undefined && (run.status === "awaiting-gate" || run.status === "paused");
@@ -6710,6 +6818,22 @@ async function submitGate(workflow, originalRun, outcome, summary, artifact) {
   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, originalRun, outcome, artifact, requestId, this.dependencies.now(), summary);
   this.persist();
   this.restoreBaselineTools();
@@ -7696,6 +7820,6 @@ function createPiWorkflowsExtension(dependencies) {
 var piWorkflowsExtension = createPiWorkflowsExtension(DEFAULT_DEPENDENCIES4);
 var src_default = piWorkflowsExtension;
 export {
-  src_default as default,
-  createPiWorkflowsExtension
+  createPiWorkflowsExtension,
+  src_default as default
 };

package/examples/starter-kit/agents/planner.md

@@ -1,3 +1,7 @@
+---
+thinking: high
+---
+
 You are the planning role for one workflow step.
 
 Stay within the step's declared permissions. Establish facts before conclusions,

package/examples/starter-kit/agents/reviewer.md

@@ -1,3 +1,7 @@
+---
+thinking: xhigh
+---
+
 You are the independent review role for one workflow step.
 
 Remain read-only unless the step explicitly grants a different authority.

package/examples/starter-kit/agents/scout.md

@@ -1,3 +1,7 @@
+---
+thinking: medium
+---
+
 You are the investigation role for one workflow step.
 
 Stay read-only. Gather the smallest set of decisive evidence, distinguish facts

package/examples/starter-kit/agents/worker.md

@@ -1,3 +1,7 @@
+---
+thinking: high
+---
+
 You are the implementation role for one workflow step.
 
 Treat the approved workflow artifact and declared permissions as the complete

package/examples/starter-kit/agents/workspace-preparer.md

@@ -1,3 +1,7 @@
+---
+thinking: low
+---
+
 You are the workspace preparation role for one workflow step.
 
 Inspect the current repository state before mutation. Create or reuse only the

package/examples/starter-kit/investigate.workflow.yaml

@@ -1,7 +1,7 @@
 version: 1
 id: investigate
 command: investigate
-description: Derive, approve, investigate, and independently validate an evidence-backed finding
+description: 'Derive, approve, investigate, and independently validate an evidence-backed finding. Example: /investigate PROJ-123 Root cause of elevated 500 error rates in checkout service'
 start: retrieve
 maxStepVisits: 12
 summaryMaxChars: 30000
@@ -12,48 +12,30 @@ steps:
       file: steps/investigate/retrieve.md
     agent: scout
     permissions:
-      tools: [read, ls, bash]
-      mcp: &jira-read-mcp
-        - atlassian/atlassian_getAccessibleAtlassianResources
-        - atlassian/atlassian_getJiraIssue
-        - atlassian/atlassian_getJiraIssueRemoteIssueLinks
-        - atlassian/atlassian_searchJiraIssuesUsingJql
-      extensions: [pi-web-tools]
-      skills: &retrieve-skills [caveman, coding-standards, brainstorming]
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian, context7, sourcegraph, glean, grafana]
+      extensions: [/]
+      skills: [jira-ticket, start-triage, search-code-sourcegraph, caveman]
       bash:
-        mode: allow-list
-        allow: &inspection-bash
-          - executable: grep
-          - executable: head
-          - executable: ls
-          - executable: pwd
-          - executable: rg
-          - executable: stat
-          - executable: tail
-          - executable: wc
-          - executable: git
-            argsPrefixes:
-              [
-                [status],
-                [diff],
-                [grep],
-                [log],
-                [ls-files],
-                [rev-parse],
-                [show],
-                [merge-base],
-                [rev-list],
-                [worktree, list],
-              ]
-    requires:
-      tools: [read, ls, bash]
-      skills: *retrieve-skills
+        mode: unrestricted
     gate:
       provider: plannotator
       submitOutcome: submit
       approvedOutcome: approved
       rejectedOutcome: changes-requested
       timeoutMs: 30000
+      artifactContract:
+        maxChars: 6000
+        requiredSubstrings:
+          - '## Brief description'
+          - '## Goals'
+          - '## Boundaries'
+          - '## Evidence & sources'
+          - '## Report destination'
+          - '## Open evidence gaps'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
     transitions:
       approved: investigate
       changes-requested: retrieve
@@ -65,23 +47,20 @@ steps:
       file: steps/investigate/investigate.md
     agent: worker
     permissions:
-      tools: [read, ls, bash, edit, write]
-      mcp: &investigation-mcp
-        - atlassian
-        - gitlab
-        - glean
-        - superset
-        - sourcegraph
-        - context7/resolve-library-id
-        - context7/query-docs
-        - gh_grep/searchGitHub
-      extensions: [pi-web-tools]
-      skills: &investigation-skills [caveman, coding-standards]
+      tools: [read, ls, bash, write, mcp]
+      mcp: [atlassian, context7, sourcegraph, glean, grafana, gitlab]
+      extensions: [/]
+      skills:
+        [
+          coding-standards,
+          systematic-debugging,
+          start-triage,
+          grafana-logs,
+          search-code-sourcegraph,
+          caveman,
+        ]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash, edit, write]
-      skills: *investigation-skills
     transitions:
       ready: validate
       retry: investigate
@@ -92,21 +71,12 @@ steps:
       file: steps/investigate/validate.md
     agent: reviewer
     permissions:
-      tools: [read, ls, bash]
-      mcp: *investigation-mcp
-      extensions: [pi-web-tools]
-      skills:
-        &validation-skills [
-          caveman,
-          coding-standards,
-          systematic-debugging,
-          verification-before-completion,
-        ]
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian, sourcegraph, glean, gitlab]
+      extensions: [/]
+      skills: [verification-before-completion, caveman]
       bash:
         mode: unrestricted
-    requires:
-      tools: [read, ls, bash]
-      skills: *validation-skills
     transitions:
       approved: $done
       gaps: investigate

package/examples/starter-kit/jira.workflow.yaml

@@ -0,0 +1,75 @@
+version: 1
+id: jira
+command: jira
+description: 'Draft, approve, and create a Jira Epic with ordered Stories. Example: /jira ACTB Implement multi-region failover for pricing service'
+start: draft
+maxStepVisits: 12
+summaryMaxChars: 30000
+steps:
+  draft:
+    title: Normalize Epic and Story input
+    prompt:
+      file: steps/jira/draft.md
+    agent: scout
+    permissions:
+      tools: [read, ls, bash]
+      mcp: []
+      extensions: [/]
+      skills: [jira-ticket, caveman]
+      bash:
+        mode: unrestricted
+    transitions:
+      ready: plan
+      retry: draft
+      blocked: $pause
+  plan:
+    title: Validate Jira schema and approve Epic and Story plan
+    prompt:
+      file: steps/jira/plan.md
+    agent: planner
+    permissions:
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian]
+      extensions: [/]
+      skills: [jira-ticket, caveman]
+      bash:
+        mode: unrestricted
+    gate:
+      provider: plannotator
+      submitOutcome: submit
+      approvedOutcome: approved
+      rejectedOutcome: changes-requested
+      timeoutMs: 30000
+      artifactContract:
+        maxChars: 16000
+        requiredSubstrings:
+          - '# Create Jira Epic and Stories'
+          - '## Jira field contract'
+          - '## Epic'
+          - '## Ordered Stories'
+          - '## Creation sequence'
+          - '## Safety limits'
+        forbiddenSubstrings:
+          - 'The complete gate artifact is the exact Markdown saved at'
+        onValidationFailure: retry
+    transitions:
+      approved: create
+      changes-requested: plan
+      retry: plan
+      blocked: $pause
+  create:
+    title: Create approved Jira Epic and Stories
+    prompt:
+      file: steps/jira/create.md
+    agent: worker
+    permissions:
+      tools: [read, ls, bash, mcp]
+      mcp: [atlassian]
+      extensions: [/]
+      skills: [jira-ticket, caveman]
+      bash:
+        mode: unrestricted
+    transitions:
+      ready: $done
+      retry: create
+      blocked: $pause