@osolmaz/pi-workflows 0.13.2 → 0.13.4

package/examples/workflows/live-settings.workflow.ts

@@ -0,0 +1,93 @@
+import {
+  agent,
+  allowSettingsPath,
+  compute,
+  defineWorkflow,
+  settingsRoute,
+  workflowSettings,
+} from "@osolmaz/pi-workflows";
+
+type Settings = {
+  instructions: string[];
+  route: "normal" | "careful";
+  variables: Record<string, unknown>;
+};
+
+function parseSettings(value: unknown): Settings {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("settings must be an object");
+  }
+  const settings = value as Partial<Settings>;
+  if (
+    !Array.isArray(settings.instructions) ||
+    !settings.instructions.every((item) => typeof item === "string") ||
+    (settings.route !== "normal" && settings.route !== "careful") ||
+    settings.variables === null ||
+    typeof settings.variables !== "object" ||
+    Array.isArray(settings.variables)
+  ) {
+    throw new Error("settings are invalid");
+  }
+  return {
+    instructions: [...settings.instructions],
+    route: settings.route,
+    variables: { ...settings.variables },
+  };
+}
+
+export default defineWorkflow({
+  name: "live-settings",
+  settings: workflowSettings<Settings>({
+    initial: { instructions: [], route: "normal", variables: {} },
+    parse: parseSettings,
+    description: "Instructions, variables, and the future route for this example.",
+    paths: [
+      allowSettingsPath("/instructions", {
+        read: ["session", "human"],
+        add: ["session", "human"],
+        remove: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+      allowSettingsPath("/route", {
+        read: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+      allowSettingsPath("/variables", {
+        read: ["session", "human"],
+        add: ["session", "human"],
+        remove: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+    ],
+  }),
+  startAt: "prepare",
+  nodes: {
+    prepare: agent({
+      prompt: ({ settings }) =>
+        [
+          "Prepare the requested work.",
+          `Current instructions and variables: ${JSON.stringify(settings)}`,
+          "The user can change future settings or queue several post-completion prompts while this step runs.",
+        ].join("\n"),
+      expectedOutput: `{ "prepared": "summary" }`,
+    }),
+    choose: settingsRoute({
+      run: ({ settings }) => ({ route: (settings as Settings).route }),
+    }),
+    normal: compute({
+      run: ({ settings }) => ({ mode: "normal", settings }),
+    }),
+    careful: compute({
+      run: ({ settings }) => ({ mode: "careful", settings }),
+    }),
+  },
+  edges: [
+    { from: "prepare", to: "choose" },
+    {
+      from: "choose",
+      switch: { on: "$.route", cases: { normal: "normal", careful: "careful" } },
+    },
+  ],
+  presentationPrompt:
+    "Explain which route and settings were used. Any queued follow-up prompts run only after this response settles.",
+});

package/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "osolmaz.pi-workflows"
 name = "pi-workflows"
-version = "0.13.2"
+version = "0.13.4"
 min_herdr_version = "0.7.0"
 description = "Open the active pi-workflows run in piw from a managed Herdr pane."
 platforms = ["linux", "macos"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@osolmaz/pi-workflows",
-  "version": "0.13.2",
+  "version": "0.13.4",
   "description": "Workflow and controller runtime with a live terminal viewer for the pi coding agent",
   "keywords": [
     "pi-package"

package/skills/autoplan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: autoplan
-description: Use when the user asks to devise, choose, or plan the most elegant long-term production-ready solution, compare it with the ideal end state, and produce the best practical in-scope implementation plan without asking the user to resolve the gap.
+description: Use when the user asks to devise, choose, or plan the most Long term elegant and production ready solution, compare it with the Holy grail, and produce the best practical in-scope implementation plan without asking the user to resolve the gap.
 compatibility: Requires pi-workflows and the built-in autoplan workflow.
 ---
 
@@ -37,12 +37,12 @@ When this skill is loaded inside an active workflow step, do not start another w
 Outside Pi, or when the workflow is unavailable:
 
 1. Frame the problem, observable success criteria, scope, constraints, and interfaces under our control.
-2. Record two through four distinct practical candidates. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
-3. Describe the holy grail separately. Name every dependency outside our authority.
+2. Record two through four distinct practical candidates. Ask whether each is a Long term elegant and production ready solution. Give each one a stable id, short title, plain gist, full solution, rationale, parts, and trade-offs.
+3. Describe the Holy grail separately. Ask whether it is the Holy grail for the problem. Name every dependency outside our authority.
 4. Choose the right option without asking the user to decide between them. Record one rejection reason for every other explicit candidate.
-   - Choose the ideal when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
-   - Otherwise choose the strongest practical in-scope solution with a clear path toward the ideal.
-   - Do not block only because the ideal requires an upstream or external change.
+   - Choose the Holy grail when it is proportionate, production-ready, in scope, and implementable through interfaces we control.
+   - Otherwise choose the strongest practical in-scope solution with a clear path toward the Holy grail.
+   - Do not block only because the Holy grail requires an upstream or external change.
 5. Write a detailed implementation plan. For each step, state what changes, where it changes, and how to verify it.
 6. Present one short plain assistant message with the chosen plan, its main steps, and a one-line gist and rejection reason for every other candidate. Call it selected for approval when a later human decision still applies.
 7. Stop as blocked only when no truthful in-scope solution can meet the success criteria.

package/src/builtins/autoimplement.workflow.ts

@@ -13,6 +13,7 @@ import {
   includedResult,
 } from "../workflows/definition.js";
 import { digest } from "../workflows/human-decision.js";
+import { allowSettingsPath, workflowSettings } from "../workflows/settings.js";
 import type { WorkflowActionContext, WorkflowNodeContext } from "../workflows/types.js";
 import autodocWorkflow, { type AutodocInput } from "./autodoc.workflow.js";
 import {
@@ -40,6 +41,11 @@ import workspacePreparationWorkflow, {
   type WorkspacePreparationInput,
 } from "./workspace-preparation.workflow.js";
 
+export type AutoimplementSettings = {
+  merge: boolean;
+  addedInstructions: string[];
+};
+
 export type AutoimplementInput = {
   task: string;
   plan?: unknown;
@@ -577,6 +583,27 @@ function parseInput(value: unknown): AutoimplementInput {
   };
 }
 
+function parseAutoimplementSettings(value: unknown): AutoimplementSettings {
+  const settings = requireRecord(value, "autoimplement settings");
+  if (typeof settings.merge !== "boolean") {
+    throw new Error("autoimplement settings merge must be a boolean");
+  }
+  if (
+    !Array.isArray(settings.addedInstructions) ||
+    settings.addedInstructions.some((item) => typeof item !== "string")
+  ) {
+    throw new Error("autoimplement settings addedInstructions must be an array of strings");
+  }
+  return {
+    merge: settings.merge,
+    addedInstructions: [...settings.addedInstructions] as string[],
+  };
+}
+
+function autoimplementSettings(context: WorkflowNodeContext): AutoimplementSettings {
+  return parseAutoimplementSettings(context.settings);
+}
+
 function parseExistingPlan(value: unknown): ExistingPlanDiscovery {
   const result = requireRecord(value, "existing plan discovery");
   if (result.route !== "found" && result.route !== "blocked") {
@@ -790,7 +817,7 @@ function createBlockerClaim(context: WorkflowNodeContext): BlockerClaim {
     unrelatedFailures: Array.isArray(result.unrelatedFailures) ? result.unrelatedFailures : [],
     recoveryAttempts: Array.isArray(result.repairAttempts) ? result.repairAttempts : [],
     alternativesChecked: [],
-    authorityFact: `scope=${(context.input as AutoimplementInput).scope ?? "unspecified"}; merge=${(context.input as AutoimplementInput).merge === true}`,
+    authorityFact: `scope=${(context.input as AutoimplementInput).scope ?? "unspecified"}; merge=${autoimplementSettings(context).merge}`,
   };
 }
 
@@ -919,8 +946,8 @@ function parseDeliveryResult(
   if (result.status !== "completed" && result.status !== "blocked") {
     throw new Error("delivery status must be completed or blocked");
   }
-  const request = context.input as AutoimplementInput;
-  if (request.merge !== true && result.merged === true) {
+  const settings = autoimplementSettings(context);
+  if (settings.merge !== true && result.merged === true) {
     throw new Error("delivery cannot merge without explicit merge: true");
   }
   if (result.status === "blocked") return result;
@@ -960,7 +987,7 @@ function parseDeliveryResult(
     }
     actual.set(repository.repository, repository);
   }
-  const mergeExpected = request.merge === true;
+  const mergeExpected = settings.merge === true;
   for (const expected of published) {
     const repository = actual.get(path.resolve(expected.repository));
     if (repository === undefined || repository.pr !== expected.pr) {
@@ -1298,6 +1325,28 @@ export const autoimplementWorkflow = defineWorkflow({
   contractId: "pi-workflows.autoimplement.v1",
   name: "autoimplement",
   input: parseInput,
+  settings: workflowSettings<AutoimplementSettings, AutoimplementInput>({
+    initial: (input) => ({ merge: input.merge === true, addedInstructions: [] }),
+    parse: parseAutoimplementSettings,
+    description: "Future merge behavior and instructions added during this run.",
+    paths: [
+      allowSettingsPath("/merge", {
+        read: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+      allowSettingsPath("/addedInstructions", {
+        read: ["session", "human"],
+        add: ["session", "human"],
+        remove: ["session", "human"],
+        replace: ["session", "human"],
+      }),
+    ],
+    validateChange: ({ before, after, actor }) => {
+      if (actor.type === "session" && before.merge === false && after.merge === true) {
+        throw new Error("A model workflow step cannot grant merge authority");
+      }
+    },
+  }),
   title: ({ input }) => `autoimplement: ${input.task.slice(0, 60)}`,
   presentationPrompt:
     "Summarize what was implemented, the review rounds by severity, the CI result, the PR or merge result, and any remaining limitation. Include exact validation commands.",
@@ -1616,7 +1665,7 @@ export const autoimplementWorkflow = defineWorkflow({
           `Current result and claimed blocker: ${JSON.stringify(latestBlockerClaim(context))}`,
           `Authorized scope: ${request.scope ?? request.repository ?? "the current repository and task"}`,
           `Constraints and authority: ${JSON.stringify(request.constraints ?? [])}`,
-          `Merge authorized: ${request.merge === true}`,
+          `Merge currently allowed: ${autoimplementSettings(context).merge === true}`,
           `Previous blocker challenges: ${JSON.stringify(blockerChallenges(context))}`,
           `Recent workflow attempts: ${JSON.stringify(recentWorkflowAttempts(context))}`,
         ].join("\n");
@@ -1925,10 +1974,9 @@ export const autoimplementWorkflow = defineWorkflow({
       timeoutMs: 30 * 60_000,
       statusDetail: "finalizing PRs",
       prompt: (context) => {
-        const request = context.input as AutoimplementInput;
         return [
-          request.merge === false
-            ? "Leave every verified PR ready without merging because input disabled merge."
+          autoimplementSettings(context).merge === false
+            ? "Leave every verified PR ready without merging because current workflow settings disable merge."
             : "Handle verified PRs one at a time and merge each unless repository policy or explicit user instructions prohibit it.",
           "Before each mutation, inspect the current PR head, merge state, and existing final report. Do not merge an already merged expected head or post a duplicate report.",
           "Use each repository's required merge method.",

package/src/builtins/autoplan.workflow.ts

@@ -96,9 +96,11 @@ function originalUserInstructions(outputs: Record<string, unknown>): string {
 }
 
 function originalInstructionsPrompt(outputs: Record<string, unknown>): string {
-  return ["Original user instructions (authoritative):", originalUserInstructions(outputs)].join(
-    "\n",
-  );
+  return [
+    "Continue in this Pi session. Do not delegate this workflow step or start another session.",
+    "Original user instructions (authoritative):",
+    originalUserInstructions(outputs),
+  ].join("\n");
 }
 
 function requireString(value: unknown, label: string): string {
@@ -286,7 +288,7 @@ function candidateSummary(
   ideal: AutoplanIdeal,
   id: string,
 ): { id: string; title: string; gist: string } {
-  if (id === "ideal") return { id, title: "Ideal end state", gist: ideal.ideal };
+  if (id === "ideal") return { id, title: "Holy grail", gist: ideal.ideal };
   const candidate = proposal.candidates.find((item) => item.id === id);
   if (candidate === undefined)
     throw new Error(`autoplan candidate ${JSON.stringify(id)} is missing`);
@@ -298,9 +300,9 @@ function summaryInput(
   blocked: boolean,
   input: AutoplanInput,
 ): PlainSummaryInput {
-  const proposal = outputs.propose as AutoplanProposal;
-  const selection = outputs.choose as AutoplanSelection;
-  const ideal = outputs.ideal as AutoplanIdeal;
+  const proposal = outputs.solutions as AutoplanProposal;
+  const selection = outputs.select as AutoplanSelection;
+  const ideal = outputs.holyGrail as AutoplanIdeal;
   const selected = candidateSummary(proposal, ideal, selection.selectedId);
   return {
     source: {
@@ -368,6 +370,7 @@ export const autoplanWorkflow = defineWorkflow({
       statusDetail: "capturing the user's instructions",
       prompt: () =>
         [
+          "Continue in this Pi session. Do not delegate this workflow step or start another session.",
           "Read the conversation that came before this workflow step.",
           "Return one text string named originalUserInstructions.",
           "Include everything that the user has instructed for the intended purpose in the given context.",
@@ -398,12 +401,13 @@ export const autoplanWorkflow = defineWorkflow({
       expectedOutput: `{ "problem": "concise statement", "success": ["criterion"], "inScope": ["change"], "outOfScope": ["change"], "constraints": ["constraint"], "controlBoundary": "what can change" }`,
       validate: (value) => requireRecord(value, "autoplan frame"),
     }),
-    propose: agent({
-      statusDetail: "devising candidate solutions",
+    solutions: agent({
+      statusDetail: "devising long-term solutions",
       prompt: ({ outputs, input }) =>
         [
           originalInstructionsPrompt(outputs),
           "Give two to four practical options that fit the allowed scope.",
+          "For each option, ask: Is this a Long term elegant and production ready solution?",
           "For each option return a stable lowercase id and a short title. Add a plain gist and full solution, explain the reason and trade-offs, and list the parts.",
           "Favor a few reusable parts with clear owners and use interfaces that already exist.",
           "Reject one-off machinery and infrastructure that the task does not need.",
@@ -416,42 +420,46 @@ export const autoplanWorkflow = defineWorkflow({
       validate: (value, { input }) =>
         parseProposal(value, (input as AutoplanInput).previousPlan !== undefined),
     }),
-    ideal: agent({
-      statusDetail: "describing the ideal end state",
+    holyGrail: agent({
+      statusDetail: "describing the Holy grail",
       prompt: ({ outputs, input }) =>
         [
           originalInstructionsPrompt(outputs),
-          "Describe the best possible end state separately from the practical options.",
-          "It may match one option or go beyond the current scope.",
+          "Describe the Holy grail separately from the practical options.",
+          "Ask: Is this the Holy grail for the problem?",
+          "The Holy grail may match one option or go beyond the current scope.",
+          "Explain what makes it more Long term elegant and production ready than the practical options.",
           "List each dependency we do not control. Do not assume that it can change.",
-          "State what this end state would improve beyond the practical options.",
+          "State what the Holy grail would improve beyond the practical options.",
           `Problem frame: ${JSON.stringify(outputs.frame)}`,
-          `Candidates: ${JSON.stringify(outputs.propose)}`,
+          `Candidates: ${JSON.stringify(outputs.solutions)}`,
           `New evidence: ${JSON.stringify((input as AutoplanInput).newEvidence ?? null)}`,
         ].join("\n"),
-      expectedOutput: `{ "ideal": "ideal end state", "outsideDependencies": ["dependency"], "additionalValue": ["benefit"] }`,
+      expectedOutput: `{ "ideal": "Holy grail end state", "outsideDependencies": ["dependency"], "additionalValue": ["benefit"] }`,
       validate: parseIdeal,
     }),
-    choose: agent({
-      statusDetail: "choosing the practical solution",
+    select: agent({
+      statusDetail: "selecting the solution",
       prompt: ({ outputs }) =>
         [
           originalInstructionsPrompt(outputs),
           "Select one option. Do not ask the user to choose.",
-          "Select the ideal only when it fits the allowed scope and is ready for production. Its value must justify the added complexity.",
-          "Otherwise select the best option we can build now that still moves toward the ideal.",
+          "Select the most Long term elegant and production ready option that is proportionate, in scope, and implementable through interfaces we control.",
+          "Select the Holy grail when it meets those conditions and its value justifies the added complexity.",
+          "Otherwise select the strongest practical option we can build now with a clear path toward the Holy grail.",
           "Work outside our control does not by itself make the plan blocked.",
           "Do not require changes to an upstream project or an unrelated repository. Do not require a new service or resource without approval.",
           "When two options solve the problem equally well, choose the simpler one.",
-          "Give one specific rejection reason for every option you do not select, including the ideal.",
+          "Give one specific rejection reason for every option you do not select, including the Holy grail.",
           "Return blocked only if no option inside the allowed scope can meet the success criteria.",
           `Frame: ${JSON.stringify(outputs.frame)}`,
-          `Candidates: ${JSON.stringify(outputs.propose)}`,
-          `Ideal candidate id: ideal`,
-          `Ideal: ${JSON.stringify(outputs.ideal)}`,
+          `Candidates: ${JSON.stringify(outputs.solutions)}`,
+          `Holy grail candidate id: ideal`,
+          `Holy grail: ${JSON.stringify(outputs.holyGrail)}`,
         ].join("\n"),
       expectedOutput: `{ "status": "ready" | "blocked", "selectedId": "candidate-id-or-ideal", "why": "reason", "relationshipToIdeal": "relationship", "rejected": [{ "id": "other-id", "reason": "why it lost" }], "compromises": ["compromise"], "blocker": "required only when blocked" }`,
-      validate: (value, { outputs }) => parseSelection(value, outputs.propose as AutoplanProposal),
+      validate: (value, { outputs }) =>
+        parseSelection(value, outputs.solutions as AutoplanProposal),
     }),
     plan: agent({
       timeoutMs: 30 * 60_000,
@@ -466,8 +474,8 @@ export const autoplanWorkflow = defineWorkflow({
           "Correct the earlier plan when the new evidence proves it wrong.",
           "Do not change files.",
           `Frame: ${JSON.stringify(outputs.frame)}`,
-          `Selection: ${JSON.stringify(outputs.choose)}`,
-          `Candidates: ${JSON.stringify(outputs.propose)}`,
+          `Selection: ${JSON.stringify(outputs.select)}`,
+          `Candidates: ${JSON.stringify(outputs.solutions)}`,
           `Previous plan: ${JSON.stringify((input as AutoplanInput).previousPlan ?? null)}`,
           `New evidence: ${JSON.stringify((input as AutoplanInput).newEvidence ?? null)}`,
         ].join("\n"),
@@ -476,13 +484,13 @@ export const autoplanWorkflow = defineWorkflow({
     }),
     blocked: compute({
       run: ({ outputs }) => {
-        const selection = outputs.choose as AutoplanSelection;
+        const selection = outputs.select as AutoplanSelection;
         return {
           status: "blocked",
           originalUserInstructions: originalUserInstructions(outputs),
           frame: outputs.frame,
-          proposal: outputs.propose as AutoplanProposal,
-          ideal: outputs.ideal as AutoplanIdeal,
+          proposal: outputs.solutions as AutoplanProposal,
+          ideal: outputs.holyGrail as AutoplanIdeal,
           selection,
           plainSummary: plainSummaryResult(outputs.blockedSummary, "autoplan blocked summary"),
           reason: requireString(selection.blocker, "autoplan blocker"),
@@ -499,9 +507,9 @@ export const autoplanWorkflow = defineWorkflow({
           status: "ready",
           originalUserInstructions: originalUserInstructions(outputs),
           frame: outputs.frame,
-          proposal: outputs.propose as AutoplanProposal,
-          ideal: outputs.ideal as AutoplanIdeal,
-          selection: outputs.choose as AutoplanSelection,
+          proposal: outputs.solutions as AutoplanProposal,
+          ideal: outputs.holyGrail as AutoplanIdeal,
+          selection: outputs.select as AutoplanSelection,
           plan: outputs.plan,
           plainSummary: plainSummaryResult(outputs.readySummary, "autoplan ready summary"),
           planDigest,
@@ -513,11 +521,11 @@ export const autoplanWorkflow = defineWorkflow({
   },
   edges: [
     { from: "captureIntent", to: "frame" },
-    { from: "frame", to: "propose" },
-    { from: "propose", to: "ideal" },
-    { from: "ideal", to: "choose" },
+    { from: "frame", to: "solutions" },
+    { from: "solutions", to: "holyGrail" },
+    { from: "holyGrail", to: "select" },
     {
-      from: "choose",
+      from: "select",
       switch: { on: "$.status", cases: { ready: "plan", blocked: "blockedSummary" } },
     },
     { from: "plan", to: "readySummary" },

package/src/builtins/catalog.ts

@@ -9,9 +9,9 @@ import sanityCheckWorkflow from "./sanity-check.workflow.js";
 
 export const builtinWorkflowCatalog = new BuiltinWorkflowCatalog([
   { id: "plain-summary", revision: "3", definition: plainSummaryWorkflow },
-  { id: "autoplan", revision: "5", definition: autoplanWorkflow },
+  { id: "autoplan", revision: "6", definition: autoplanWorkflow },
   { id: "autodoc", revision: "2", definition: autodocWorkflow },
-  { id: "autoimplement", revision: "10", definition: autoimplementWorkflow },
+  { id: "autoimplement", revision: "11", definition: autoimplementWorkflow },
   { id: "plan-approval", revision: "4", definition: planApprovalWorkflow },
   { id: "sanity-check", revision: "6", definition: sanityCheckWorkflow },
   {

package/src/controllers/index.ts

@@ -49,6 +49,7 @@ export {
 } from "./workflow-engine-scheduler.js";
 export {
   ControllerWorkflowCoordinator,
+  type ControllerWorkflowControlRequest,
   type ControllerWorkflowScheduler,
   type WorkflowSchedulerRequest,
   type WorkflowSchedulerResult,
@@ -64,6 +65,11 @@ export type {
   ControllerConditionStatus,
   ControllerDefinition,
   ControllerEffects,
+  ControllerFollowUpResult,
+  ControllerQueueFollowUpRequest,
+  ControllerRemoveFollowUpRequest,
+  ControllerSettingsChangeRequest,
+  ControllerSettingsChangeResult,
   ControllerEvent,
   ControllerQueueClaim,
   ControllerResource,