@osolmaz/pi-workflows 0.10.0 → 0.11.0

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" },

package/src/builtins/plan-approval.workflow.ts

@@ -0,0 +1,190 @@
+import { compute, defineWorkflow } from "../workflows/definition.js";
+import {
+  choice,
+  defineHumanChoices,
+  humanDecision,
+  humanDecisionEdge,
+  textInput,
+} from "../workflows/human-decision.js";
+import type { HumanDecisionReceipt, HumanDecisionResponse } from "../workflows/types.js";
+import { presentPlan } from "./plan-presentation.js";
+
+export type PlanApprovalInput = {
+  task: string;
+  plan: unknown;
+  planDigest: string;
+  audience: string;
+  revision?: number;
+};
+
+export type PlanApprovalContinue = {
+  status: "continue";
+  plan: unknown;
+  planDigest: string;
+  decision: HumanDecisionReceipt;
+};
+
+export type PlanApprovalStop = {
+  status: "stop";
+  planDigest: string;
+  decision: HumanDecisionReceipt;
+};
+
+export type PlanApprovalReplan = {
+  status: "replan";
+  plan: unknown;
+  planDigest: string;
+  instructions: string;
+  decision: HumanDecisionReceipt;
+};
+
+const planChoices = defineHumanChoices({
+  continue: choice({ label: "Yes, continue" }),
+  stop: choice({ label: "No, stop" }),
+  replan: choice({
+    label: "Replan",
+    input: textInput({
+      name: "instructions",
+      prompt: "What should change?",
+      minLength: 1,
+      maxLength: 4_000,
+    }),
+  }),
+});
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function parseInput(value: unknown): PlanApprovalInput {
+  const input = requireRecord(value, "plan approval input");
+  const revision = input.revision;
+  if (revision !== undefined && (!Number.isInteger(revision) || (revision as number) < 1)) {
+    throw new Error("plan approval revision must be a positive integer");
+  }
+  if (input.plan === undefined) throw new Error("plan approval requires a plan");
+  return {
+    task: requireString(input.task, "plan approval task"),
+    plan: input.plan,
+    planDigest: requireString(input.planDigest, "plan approval digest"),
+    audience: requireString(input.audience, "plan approval audience"),
+    ...(revision !== undefined ? { revision: revision as number } : {}),
+  };
+}
+
+function acceptedDecision(value: HumanDecisionReceipt | undefined): HumanDecisionReceipt {
+  if (value === undefined)
+    throw new Error("plan approval continuation is missing its accepted decision");
+  return value;
+}
+
+function gateResponse(value: unknown): HumanDecisionResponse {
+  return requireRecord(value, "plan approval response") as HumanDecisionResponse;
+}
+
+export const planApprovalWorkflow = defineWorkflow({
+  source: import.meta.url,
+  contractId: "pi-workflows.plan-approval.v1",
+  name: "plan-approval",
+  input: parseInput,
+  title: ({ input }) => `plan approval: ${input.task.slice(0, 60)}`,
+  startAt: "approve",
+  maxSteps: 8,
+  exits: {
+    continue: {
+      from: "continued",
+      validate: (value: unknown): PlanApprovalContinue => value as PlanApprovalContinue,
+    },
+    stop: {
+      from: "stopped",
+      validate: (value: unknown): PlanApprovalStop => value as PlanApprovalStop,
+    },
+    replan: {
+      from: "replan",
+      validate: (value: unknown): PlanApprovalReplan => value as PlanApprovalReplan,
+    },
+  },
+  nodes: {
+    approve: humanDecision({
+      audience: ({ input }) => (input as PlanApprovalInput).audience,
+      choices: planChoices,
+      request: ({ input }) => {
+        const request = input as PlanApprovalInput;
+        const revision = request.revision ?? 1;
+        return {
+          title: "Approve the implementation plan",
+          subject: {
+            task: request.task,
+            plan: request.plan,
+            planDigest: request.planDigest,
+            revision,
+          },
+          presentation: presentPlan({
+            task: request.task,
+            plan: request.plan,
+            planDigest: request.planDigest,
+            revision,
+          }),
+          revision,
+        };
+      },
+    }),
+    continued: compute({
+      run: ({ input, state }) => {
+        const request = input as PlanApprovalInput;
+        return {
+          status: "continue",
+          plan: request.plan,
+          planDigest: request.planDigest,
+          decision: acceptedDecision(state.humanDecision),
+        } satisfies PlanApprovalContinue;
+      },
+    }),
+    stopped: compute({
+      run: ({ input, state }) => {
+        const request = input as PlanApprovalInput;
+        return {
+          status: "stop",
+          planDigest: request.planDigest,
+          decision: acceptedDecision(state.humanDecision),
+        } satisfies PlanApprovalStop;
+      },
+    }),
+    replan: compute({
+      run: ({ input, outputs, state }) => {
+        const request = input as PlanApprovalInput;
+        const response = gateResponse(outputs.approve);
+        const instructions = response.input?.instructions;
+        if (typeof instructions !== "string" || instructions.length === 0) {
+          throw new Error("replan answer is missing exact instructions");
+        }
+        return {
+          status: "replan",
+          plan: request.plan,
+          planDigest: request.planDigest,
+          instructions,
+          decision: acceptedDecision(state.humanDecision),
+        } satisfies PlanApprovalReplan;
+      },
+    }),
+  },
+  edges: [
+    humanDecisionEdge({
+      from: "approve",
+      choices: planChoices,
+      cases: { continue: "continued", stop: "stopped", replan: "replan" },
+    }),
+  ],
+});
+
+export default planApprovalWorkflow;

package/src/builtins/plan-presentation.ts

@@ -0,0 +1,57 @@
+import {
+  legacyDecisionPresentation,
+  normalizeDecisionPresentation,
+} from "../workflows/decision-presentation.js";
+import type { DecisionPresentation } from "../workflows/types.js";
+
+export function presentPlan(input: {
+  task: string;
+  plan: unknown;
+  planDigest: string;
+  revision: number;
+}): DecisionPresentation {
+  const plan = legacyDecisionPresentation(input.plan);
+  const summary =
+    readableSummary(planSummary(input.plan)) ??
+    readableSummary(`Review the implementation plan for ${input.task}.`)!;
+  return normalizeDecisionPresentation({
+    schema: "pi-workflows.decision-presentation.v1",
+    summary,
+    blocks: [
+      { kind: "section", title: "Task" },
+      { kind: "paragraph", text: input.task },
+      { kind: "section", title: "Plan" },
+      ...plan.blocks.filter(
+        (block, index) =>
+          !(index === 0 && block.kind === "section" && block.title === "Decision details"),
+      ),
+      { kind: "section", title: "Plan identity" },
+      {
+        kind: "fields",
+        items: [
+          { label: "Revision", value: String(input.revision) },
+          { label: "Digest", value: input.planDigest },
+        ],
+      },
+    ],
+  });
+}
+
+function readableSummary(value: string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  const text = [...value]
+    .map((character) => {
+      const code = character.codePointAt(0) ?? 0;
+      return code <= 31 || code === 127 ? " " : character;
+    })
+    .join("")
+    .replaceAll(/\s+/gu, " ")
+    .trim();
+  return text.length === 0 ? undefined : text;
+}
+
+function planSummary(plan: unknown): string | undefined {
+  if (plan === null || typeof plan !== "object" || Array.isArray(plan)) return undefined;
+  const summary = (plan as Record<string, unknown>).summary;
+  return typeof summary === "string" && summary.trim().length > 0 ? summary : undefined;
+}