@osolmaz/pi-workflows 0.10.0 → 0.11.1

package/src/builtins/{autodevise.workflow.ts → autoplan.workflow.ts}

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { agent, compute, defineWorkflow } from "../workflows/definition.js";
 
-export type AutodeviseInput = {
+export type AutoplanInput = {
   problem: string;
   scope?: string;
   constraints?: string[];
@@ -9,7 +9,7 @@ export type AutodeviseInput = {
   newEvidence?: unknown;
 };
 
-export type AutodeviseReady = {
+export type AutoplanReady = {
   status: "ready";
   frame: unknown;
   proposal: unknown;
@@ -21,7 +21,7 @@ export type AutodeviseReady = {
   changed: boolean;
 };
 
-export type AutodeviseBlocked = {
+export type AutoplanBlocked = {
   status: "blocked";
   frame: unknown;
   proposal: unknown;
@@ -44,18 +44,18 @@ function requireString(value: unknown, label: string): string {
   return value.trim();
 }
 
-function parseInput(value: unknown): AutodeviseInput {
-  const input = requireRecord(value, "autodevise input");
+function parseInput(value: unknown): AutoplanInput {
+  const input = requireRecord(value, "autoplan input");
   const constraints = input.constraints;
   if (
     constraints !== undefined &&
     (!Array.isArray(constraints) || constraints.some((item) => typeof item !== "string"))
   ) {
-    throw new Error("autodevise constraints must be an array of strings");
+    throw new Error("autoplan constraints must be an array of strings");
   }
   return {
-    problem: requireString(input.problem, "autodevise problem"),
-    ...(input.scope !== undefined ? { scope: requireString(input.scope, "autodevise scope") } : {}),
+    problem: requireString(input.problem, "autoplan problem"),
+    ...(input.scope !== undefined ? { scope: requireString(input.scope, "autoplan scope") } : {}),
     ...(constraints !== undefined ? { constraints: [...constraints] as string[] } : {}),
     ...(input.previousPlan !== undefined ? { previousPlan: input.previousPlan } : {}),
     ...(input.newEvidence !== undefined ? { newEvidence: input.newEvidence } : {}),
@@ -63,13 +63,13 @@ function parseInput(value: unknown): AutodeviseInput {
 }
 
 function parseSelection(value: unknown): Record<string, unknown> {
-  const selection = requireRecord(value, "autodevise selection");
+  const selection = requireRecord(value, "autoplan selection");
   if (selection.status !== "ready" && selection.status !== "blocked") {
-    throw new Error("autodevise selection status must be ready or blocked");
+    throw new Error("autoplan selection status must be ready or blocked");
   }
-  requireString(selection.selected, "autodevise selected solution");
-  requireString(selection.why, "autodevise selection reason");
-  if (selection.status === "blocked") requireString(selection.blocker, "autodevise blocker");
+  requireString(selection.selected, "autoplan selected solution");
+  requireString(selection.why, "autoplan selection reason");
+  if (selection.status === "blocked") requireString(selection.blocker, "autoplan blocker");
   return selection;
 }
 
@@ -77,12 +77,12 @@ function digest(value: unknown): string {
   return `sha256:${createHash("sha256").update(JSON.stringify(value)).digest("hex")}`;
 }
 
-export const autodeviseWorkflow = defineWorkflow({
+export const autoplanWorkflow = defineWorkflow({
   source: import.meta.url,
-  contractId: "pi-workflows.autodevise.v1",
-  name: "autodevise",
+  contractId: "pi-workflows.autoplan.v1",
+  name: "autoplan",
   input: parseInput,
-  title: ({ input }) => `autodevise: ${input.problem.slice(0, 60)}`,
+  title: ({ input }) => `autoplan: ${input.problem.slice(0, 60)}`,
   presentationPrompt: [
     "Present the selected practical solution and its implementation plan.",
     "Briefly state how the ideal informed the choice and what was excluded as outside scope.",
@@ -93,18 +93,18 @@ export const autodeviseWorkflow = defineWorkflow({
   exits: {
     ready: {
       from: "finalize",
-      validate: (value: unknown): AutodeviseReady => value as AutodeviseReady,
+      validate: (value: unknown): AutoplanReady => value as AutoplanReady,
     },
     blocked: {
       from: "blocked",
-      validate: (value: unknown): AutodeviseBlocked => value as AutodeviseBlocked,
+      validate: (value: unknown): AutoplanBlocked => value as AutoplanBlocked,
     },
   },
   nodes: {
     frame: agent({
       statusDetail: "framing the problem",
       prompt: ({ input }) => {
-        const request = input as AutodeviseInput;
+        const request = input as AutoplanInput;
         return [
           `Frame this problem: ${request.problem}`,
           `Authorized scope: ${request.scope ?? "infer it conservatively from the request and current project"}.`,
@@ -116,7 +116,7 @@ export const autodeviseWorkflow = defineWorkflow({
         ].join("\n");
       },
       expectedOutput: `{ "problem": "concise statement", "success": ["criterion"], "inScope": ["change"], "outOfScope": ["change"], "constraints": ["constraint"], "controlBoundary": "what can change" }`,
-      validate: (value) => requireRecord(value, "autodevise frame"),
+      validate: (value) => requireRecord(value, "autoplan frame"),
     }),
     propose: agent({
       statusDetail: "devising a solution",
@@ -129,7 +129,7 @@ export const autodeviseWorkflow = defineWorkflow({
           `Problem frame: ${JSON.stringify(outputs.frame)}`,
         ].join("\n"),
       expectedOutput: `{ "solution": "proposal", "rationale": "why", "parts": ["part"], "tradeoffs": ["trade-off"] }`,
-      validate: (value) => requireRecord(value, "autodevise proposal"),
+      validate: (value) => requireRecord(value, "autoplan proposal"),
     }),
     ideal: agent({
       statusDetail: "describing the ideal end state",
@@ -141,10 +141,10 @@ export const autodeviseWorkflow = defineWorkflow({
           "Explain the practical value beyond the proposal.",
           `Problem frame: ${JSON.stringify(outputs.frame)}`,
           `Proposal: ${JSON.stringify(outputs.propose)}`,
-          `New evidence: ${JSON.stringify((input as AutodeviseInput).newEvidence ?? null)}`,
+          `New evidence: ${JSON.stringify((input as AutoplanInput).newEvidence ?? null)}`,
         ].join("\n"),
       expectedOutput: `{ "ideal": "ideal end state", "outsideDependencies": ["dependency"], "additionalValue": ["benefit"] }`,
-      validate: (value) => requireRecord(value, "autodevise ideal"),
+      validate: (value) => requireRecord(value, "autoplan ideal"),
     }),
     choose: agent({
       statusDetail: "choosing the practical solution",
@@ -177,11 +177,11 @@ export const autodeviseWorkflow = defineWorkflow({
           "Do not implement the plan.",
           `Frame: ${JSON.stringify(outputs.frame)}`,
           `Selection: ${JSON.stringify(outputs.choose)}`,
-          `Previous plan: ${JSON.stringify((input as AutodeviseInput).previousPlan ?? null)}`,
-          `New evidence: ${JSON.stringify((input as AutodeviseInput).newEvidence ?? null)}`,
+          `Previous plan: ${JSON.stringify((input as AutoplanInput).previousPlan ?? null)}`,
+          `New evidence: ${JSON.stringify((input as AutoplanInput).newEvidence ?? null)}`,
         ].join("\n"),
       expectedOutput: `{ "summary": "approach", "steps": [{ "change": "change", "where": "location", "verification": "evidence" }], "contracts": ["impact"], "tests": ["test"], "risks": [{ "risk": "risk", "mitigation": "mitigation" }], "boundaries": ["excluded work"] }`,
-      validate: (value) => requireRecord(value, "autodevise plan"),
+      validate: (value) => requireRecord(value, "autoplan plan"),
     }),
     blocked: compute({
       run: ({ outputs }) => {
@@ -192,13 +192,13 @@ export const autodeviseWorkflow = defineWorkflow({
           proposal: outputs.propose,
           ideal: outputs.ideal,
           selection,
-          reason: requireString(selection.blocker, "autodevise blocker"),
-        } satisfies AutodeviseBlocked;
+          reason: requireString(selection.blocker, "autoplan blocker"),
+        } satisfies AutoplanBlocked;
       },
     }),
     finalize: compute({
       run: ({ outputs, input }) => {
-        const request = input as AutodeviseInput;
+        const request = input as AutoplanInput;
         const planDigest = digest(outputs.plan);
         const previousPlanDigest =
           request.previousPlan === undefined ? undefined : digest(request.previousPlan);
@@ -212,7 +212,7 @@ export const autodeviseWorkflow = defineWorkflow({
           planDigest,
           ...(previousPlanDigest !== undefined ? { previousPlanDigest } : {}),
           changed: previousPlanDigest === undefined || previousPlanDigest !== planDigest,
-        } satisfies AutodeviseReady;
+        } satisfies AutoplanReady;
       },
     }),
   },
@@ -228,4 +228,4 @@ export const autodeviseWorkflow = defineWorkflow({
   ],
 });
 
-export default autodeviseWorkflow;
+export default autoplanWorkflow;

package/src/builtins/catalog.ts

@@ -1,14 +1,18 @@
 import { BuiltinWorkflowCatalog } from "../workflows/catalog.js";
-import autodeviseWorkflow from "./autodevise.workflow.js";
+import autodocWorkflow from "./autodoc.workflow.js";
 import autoimplementWorkflow from "./autoimplement.workflow.js";
+import autoplanWorkflow from "./autoplan.workflow.js";
 import monitorWorkflow from "./monitor.workflow.js";
+import planApprovalWorkflow from "./plan-approval.workflow.js";
 
 export const builtinWorkflowCatalog = new BuiltinWorkflowCatalog([
-  { id: "autodevise", revision: "1", definition: autodeviseWorkflow },
-  { id: "autoimplement", revision: "1", definition: autoimplementWorkflow },
+  { id: "autoplan", revision: "1", definition: autoplanWorkflow },
+  { id: "autodoc", revision: "1", definition: autodocWorkflow },
+  { id: "autoimplement", revision: "4", definition: autoimplementWorkflow },
+  { id: "plan-approval", revision: "2", definition: planApprovalWorkflow },
   {
     id: "monitor",
-    revision: "4",
+    revision: "7",
     definition: monitorWorkflow,
     legacySources: [
       {

package/src/builtins/index.ts

@@ -1,13 +1,32 @@
 export {
-  autodeviseWorkflow,
-  type AutodeviseBlocked,
-  type AutodeviseInput,
-  type AutodeviseReady,
-} from "./autodevise.workflow.js";
+  autoplanWorkflow,
+  type AutoplanBlocked,
+  type AutoplanInput,
+  type AutoplanReady,
+} from "./autoplan.workflow.js";
+export {
+  autodocWorkflow,
+  type AutodocBlocked,
+  type AutodocInput,
+  type DocumentedPlan,
+} from "./autodoc.workflow.js";
 export {
   autoimplementWorkflow,
   type AutoimplementBlocked,
   type AutoimplementCompleted,
   type AutoimplementInput,
+  type ExistingPlanDiscovery,
 } from "./autoimplement.workflow.js";
-export { default as monitorWorkflow, type MonitorInput } from "./monitor.workflow.js";
+export {
+  default as monitorWorkflow,
+  type MonitorInput,
+  type MonitorRepairPolicy,
+} from "./monitor.workflow.js";
+export { presentPlan } from "./plan-presentation.js";
+export {
+  planApprovalWorkflow,
+  type PlanApprovalContinue,
+  type PlanApprovalInput,
+  type PlanApprovalReplan,
+  type PlanApprovalStop,
+} from "./plan-approval.workflow.js";

package/src/builtins/monitor.workflow.ts

@@ -20,8 +20,10 @@ import type {
   WorkflowProgressData,
 } from "../workflows/types.js";
 import { validateProgressData } from "../workflows/updates.js";
-import autodeviseWorkflow from "./autodevise.workflow.js";
+import autodocWorkflow, { type AutodocInput } from "./autodoc.workflow.js";
 import autoimplementWorkflow, { type AutoimplementInput } from "./autoimplement.workflow.js";
+import autoplanWorkflow from "./autoplan.workflow.js";
+import planApprovalWorkflow, { type PlanApprovalInput } from "./plan-approval.workflow.js";
 
 const MIN_INTERVAL_MINUTES = 1;
 const MAX_INTERVAL_MINUTES = 24 * 60;
@@ -45,6 +47,10 @@ export type MonitorRepairPolicy = {
   repository?: string;
   baseBranch?: string;
   merge?: boolean;
+  approval?: {
+    audience: string;
+    maxReplans: number;
+  };
 };
 
 export type MonitorInput = {
@@ -163,6 +169,22 @@ export function prepareMonitorInput(input: unknown): MonitorConfig {
     if (raw.merge !== undefined && typeof raw.merge !== "boolean") {
       throw new Error("repair merge must be a boolean");
     }
+    let approval: MonitorRepairPolicy["approval"];
+    if (raw.approval !== undefined) {
+      const value = requireRecord(raw.approval, "repair approval");
+      const maxReplans = value.maxReplans ?? 3;
+      if (
+        !Number.isInteger(maxReplans) ||
+        (maxReplans as number) < 1 ||
+        (maxReplans as number) > 20
+      ) {
+        throw new Error("repair approval maxReplans must be from 1 through 20");
+      }
+      approval = {
+        audience: requireBoundedString(value.audience, "repair approval audience", 200),
+        maxReplans: maxReplans as number,
+      };
+    }
     repair = {
       authorized: true,
       ...(raw.scope !== undefined
@@ -176,6 +198,7 @@ export function prepareMonitorInput(input: unknown): MonitorConfig {
         ? { baseBranch: requireBoundedString(raw.baseBranch, "repair base branch", 256) }
         : {}),
       ...(raw.merge !== undefined ? { merge: raw.merge !== false } : {}),
+      ...(approval !== undefined ? { approval } : {}),
     };
   }
   return {
@@ -297,9 +320,56 @@ function repeatedRepairWithoutProgress(context: WorkflowNodeContext): boolean {
   return false;
 }
 
+function currentRepairPlan(outputs: Record<string, unknown>): {
+  plan: unknown;
+  planDigest: string;
+  documents: string[];
+} {
+  const documentation = outputs.documentation as
+    | {
+        exit?: string;
+        output?: {
+          plan?: unknown;
+          planDigest?: string;
+          documentation?: { files?: string[] };
+        };
+      }
+    | undefined;
+  if (
+    documentation?.exit === "ready" &&
+    documentation.output?.plan !== undefined &&
+    typeof documentation.output.planDigest === "string"
+  ) {
+    return {
+      plan: documentation.output.plan,
+      planDigest: documentation.output.planDigest,
+      documents: documentation.output.documentation?.files ?? [],
+    };
+  }
+  const design = includedResult(autoplanWorkflow, outputs.initialDesign);
+  if (design.exit !== "ready") throw new Error("monitor design did not return a ready plan");
+  return { plan: design.output.plan, planDigest: design.output.planDigest, documents: [] };
+}
+
+function latestReplanInstructions(outputs: Record<string, unknown>): string | undefined {
+  const approval = outputs.approval as
+    | { exit?: string; output?: { instructions?: unknown } }
+    | undefined;
+  return approval?.exit === "replan" && typeof approval.output?.instructions === "string"
+    ? approval.output.instructions
+    : undefined;
+}
+
 function repairBlockedReason(outputs: Record<string, unknown>): string {
   const guard = outputs.repairGuard as { reason?: string; route?: string } | undefined;
   if (guard?.route === "blocked" && guard.reason !== undefined) return guard.reason;
+  const replan = outputs.replanGuard as { reason?: string; route?: string } | undefined;
+  if (replan?.route === "blocked" && replan.reason !== undefined) return replan.reason;
+  const approval = outputs.approval as { exit?: string; output?: { status?: string } } | undefined;
+  if (approval?.exit === "stop") return "The operator stopped the proposed repair.";
+  const documentation = outputs.documentation as
+    | { exit?: string; output?: { reason?: string } }
+    | undefined;
   const implementation = outputs.implementation as
     | { exit?: string; output?: { reason?: string } }
     | undefined;
@@ -308,6 +378,7 @@ function repairBlockedReason(outputs: Record<string, unknown>): string {
     | undefined;
   return (
     implementation?.output?.reason ??
+    documentation?.output?.reason ??
     design?.output?.reason ??
     "The repair did not produce new verified progress."
   );
@@ -357,19 +428,66 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
   maxSteps: 200_000,
   includes: {
     initialDesign: includeWorkflow({
-      workflow: "autodevise",
-      contract: autodeviseWorkflow,
+      workflow: "autoplan",
+      contract: autoplanWorkflow,
       input: ({ outputs }) => {
         const config = configFrom(outputs);
         const repair = (outputs.check as MonitorCheck).repair;
         if (repair === undefined) throw new Error("monitor repair details are missing");
+        const prior = outputs.initialDesign as
+          | { exit?: string; output?: { plan?: unknown } }
+          | undefined;
+        const instructions = latestReplanInstructions(outputs);
         return {
           problem: repair.problem,
           ...(config.repair?.scope !== undefined ? { scope: config.repair.scope } : {}),
           ...(config.repair?.constraints !== undefined
             ? { constraints: config.repair.constraints }
             : {}),
-          newEvidence: repair.evidence,
+          ...(prior?.exit === "ready" && prior.output?.plan !== undefined
+            ? { previousPlan: prior.output.plan }
+            : {}),
+          newEvidence:
+            instructions === undefined
+              ? repair.evidence
+              : { observedEvidence: repair.evidence, operatorInstructions: instructions },
+        };
+      },
+    }),
+    documentation: includeWorkflow(autodocWorkflow, {
+      input: ({ outputs }): AutodocInput => {
+        const config = configFrom(outputs);
+        const repair = (outputs.check as MonitorCheck).repair;
+        const design = includedResult(autoplanWorkflow, outputs.initialDesign);
+        if (design.exit !== "ready") throw new Error("monitor design did not return a ready plan");
+        if (repair === undefined) throw new Error("monitor repair details are missing");
+        return {
+          task: repair.problem,
+          plan: design.output.plan,
+          ...(config.repair?.repository !== undefined
+            ? { repository: config.repair.repository }
+            : {}),
+          evidence: latestReplanInstructions(outputs) ?? repair.evidence,
+        };
+      },
+    }),
+    approval: includeWorkflow(planApprovalWorkflow, {
+      input: ({ outputs, state }): PlanApprovalInput => {
+        const config = configFrom(outputs);
+        const repair = (outputs.check as MonitorCheck).repair;
+        const approval = config.repair?.approval;
+        if (repair === undefined || approval === undefined) {
+          throw new Error("monitor approval was entered without an approval policy");
+        }
+        const current = currentRepairPlan(outputs);
+        const revision =
+          state.steps.filter((step) => step.nodeId === "approval/approve").length + 1;
+        return {
+          task: repair.problem,
+          plan: current.plan,
+          planDigest: current.planDigest,
+          audience: approval.audience,
+          revision,
         };
       },
     }),
@@ -379,12 +497,16 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
       input: ({ outputs }) => {
         const config = configFrom(outputs);
         const repair = (outputs.check as MonitorCheck).repair;
-        const design = includedResult(autodeviseWorkflow, outputs.initialDesign);
-        if (design.exit !== "ready") throw new Error("monitor design did not return a ready plan");
+        const documented = currentRepairPlan(outputs);
         if (repair === undefined) throw new Error("monitor repair details are missing");
         const request: AutoimplementInput = {
           task: repair.problem,
-          plan: design.output.plan,
+          plan: documented.plan,
+          documentation: {
+            status: "current",
+            planDigest: documented.planDigest,
+            documents: documented.documents,
+          },
           ...(config.repair?.scope !== undefined ? { scope: config.repair.scope } : {}),
           ...(config.repair?.constraints !== undefined
             ? { constraints: config.repair.constraints }
@@ -481,6 +603,25 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
             }
           : { route: "repair", reason: "The issue is new or has changed evidence." },
     }),
+    approvalRoute: compute({
+      run: ({ outputs }) => ({
+        route: configFrom(outputs).repair?.approval === undefined ? "implement" : "approve",
+      }),
+    }),
+    replanGuard: compute({
+      run: (context) => {
+        const limit = configFrom(context.outputs).repair?.approval?.maxReplans ?? 3;
+        const replans = context.state.steps.filter(
+          (step) => step.nodeId === "approval/replan",
+        ).length;
+        return replans > limit
+          ? {
+              route: "blocked",
+              reason: `Monitor repair reached the ${limit}-replan safety limit.`,
+            }
+          : { route: "design", replans, limit };
+      },
+    }),
     repairBlocked: compute({
       run: (context) => ({
         reason: repairBlockedReason(context.outputs),
@@ -568,8 +709,21 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
       from: "repairGuard",
       switch: { on: "$.route", cases: { repair: "initialDesign", blocked: "repairBlocked" } },
     },
-    { from: "initialDesign.ready", to: "implementation" },
+    { from: "initialDesign.ready", to: "documentation" },
     { from: "initialDesign.blocked", to: "repairBlocked" },
+    { from: "documentation.ready", to: "approvalRoute" },
+    { from: "documentation.blocked", to: "repairBlocked" },
+    {
+      from: "approvalRoute",
+      switch: { on: "$.route", cases: { approve: "approval", implement: "implementation" } },
+    },
+    { from: "approval.continue", to: "implementation" },
+    { from: "approval.stop", to: "repairBlocked" },
+    { from: "approval.replan", to: "replanGuard" },
+    {
+      from: "replanGuard",
+      switch: { on: "$.route", cases: { design: "initialDesign", blocked: "repairBlocked" } },
+    },
     { from: "implementation.completed", to: "check" },
     { from: "implementation.blocked", to: "repairBlocked" },
     { from: "repairBlocked", to: "repairReport" },