@osolmaz/pi-workflows 0.11.2 → 0.12.1

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

@@ -9,25 +9,56 @@ import {
 import type { HumanDecisionReceipt, HumanDecisionResponse } from "../workflows/types.js";
 import { presentPlan } from "./plan-presentation.js";
 
+const DEFAULT_APPROVAL_AUDIENCE = "operator";
+const DEFAULT_APPROVAL_TIMEOUT_MINUTES = 10;
+const DEFAULT_MAX_REPLANS = 3;
+const MAX_APPROVAL_TIMEOUT_MINUTES = 24 * 60;
+const MAX_REPLANS = 20;
+
+export type PlanApprovalMode = "auto" | "required" | "skip";
+
+export type PlanApprovalPolicy = {
+  mode?: PlanApprovalMode;
+  audience?: string;
+  timeoutMinutes?: number;
+  maxReplans?: number;
+};
+
+export type ResolvedPlanApprovalPolicy = {
+  mode: PlanApprovalMode;
+  audience: string;
+  timeoutMinutes?: number;
+  maxReplans: number;
+};
+
 export type PlanApprovalInput = {
   task: string;
   plan: unknown;
   planDigest: string;
-  audience: string;
+  approval?: PlanApprovalPolicy;
   revision?: number;
 };
 
+export type NormalizedPlanApprovalInput = Omit<PlanApprovalInput, "approval"> & {
+  approval: ResolvedPlanApprovalPolicy;
+};
+
+export type PlanApprovalResolution =
+  | { provenance: "skipped"; revision: number }
+  | { provenance: "human"; decision: HumanDecisionReceipt }
+  | { provenance: "timeout"; decision: HumanDecisionReceipt };
+
 export type PlanApprovalContinue = {
   status: "continue";
   plan: unknown;
   planDigest: string;
-  decision: HumanDecisionReceipt;
+  resolution: PlanApprovalResolution;
 };
 
 export type PlanApprovalStop = {
   status: "stop";
   planDigest: string;
-  decision: HumanDecisionReceipt;
+  resolution: { provenance: "human"; decision: HumanDecisionReceipt };
 };
 
 export type PlanApprovalReplan = {
@@ -35,7 +66,7 @@ export type PlanApprovalReplan = {
   plan: unknown;
   planDigest: string;
   instructions: string;
-  decision: HumanDecisionReceipt;
+  resolution: { provenance: "human"; decision: HumanDecisionReceipt };
 };
 
 const planChoices = defineHumanChoices({
@@ -66,8 +97,78 @@ function requireString(value: unknown, label: string): string {
   return value.trim();
 }
 
-function parseInput(value: unknown): PlanApprovalInput {
+function requireExactKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): void {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0) {
+    throw new Error(`${label} has unknown field ${unexpected[0]}`);
+  }
+}
+
+export function parsePlanApprovalPolicy(value: unknown): ResolvedPlanApprovalPolicy {
+  if (value === undefined) {
+    return {
+      mode: "auto",
+      audience: DEFAULT_APPROVAL_AUDIENCE,
+      timeoutMinutes: DEFAULT_APPROVAL_TIMEOUT_MINUTES,
+      maxReplans: DEFAULT_MAX_REPLANS,
+    };
+  }
+  const policy = requireRecord(value, "plan approval policy");
+  requireExactKeys(
+    policy,
+    ["mode", "audience", "timeoutMinutes", "maxReplans"],
+    "plan approval policy",
+  );
+  const mode = policy.mode ?? "auto";
+  if (mode !== "auto" && mode !== "required" && mode !== "skip") {
+    throw new Error("plan approval mode must be auto, required, or skip");
+  }
+  if (mode !== "auto" && policy.timeoutMinutes !== undefined) {
+    throw new Error("plan approval timeoutMinutes is available only in auto mode");
+  }
+  const timeoutMinutes = policy.timeoutMinutes ?? DEFAULT_APPROVAL_TIMEOUT_MINUTES;
+  if (
+    mode === "auto" &&
+    (!Number.isInteger(timeoutMinutes) ||
+      (timeoutMinutes as number) < 1 ||
+      (timeoutMinutes as number) > MAX_APPROVAL_TIMEOUT_MINUTES)
+  ) {
+    throw new Error(
+      `plan approval timeoutMinutes must be from 1 through ${MAX_APPROVAL_TIMEOUT_MINUTES}`,
+    );
+  }
+  const maxReplans = policy.maxReplans ?? DEFAULT_MAX_REPLANS;
+  if (
+    !Number.isInteger(maxReplans) ||
+    (maxReplans as number) < 1 ||
+    (maxReplans as number) > MAX_REPLANS
+  ) {
+    throw new Error(`plan approval maxReplans must be from 1 through ${MAX_REPLANS}`);
+  }
+  return {
+    mode,
+    audience:
+      mode === "skip"
+        ? DEFAULT_APPROVAL_AUDIENCE
+        : policy.audience === undefined
+          ? DEFAULT_APPROVAL_AUDIENCE
+          : requireString(policy.audience, "plan approval audience"),
+    ...(mode === "auto" ? { timeoutMinutes: timeoutMinutes as number } : {}),
+    maxReplans: maxReplans as number,
+  };
+}
+
+function parseInput(value: unknown): NormalizedPlanApprovalInput {
   const input = requireRecord(value, "plan approval input");
+  requireExactKeys(
+    input,
+    ["task", "plan", "planDigest", "approval", "revision"],
+    "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");
@@ -77,29 +178,40 @@ function parseInput(value: unknown): PlanApprovalInput {
     task: requireString(input.task, "plan approval task"),
     plan: input.plan,
     planDigest: requireString(input.planDigest, "plan approval digest"),
-    audience: requireString(input.audience, "plan approval audience"),
+    approval: parsePlanApprovalPolicy(input.approval),
     ...(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 value as HumanDecisionResponse;
 }
 
-function gateResponse(value: unknown): HumanDecisionResponse {
-  return requireRecord(value, "plan approval response") as HumanDecisionResponse;
+function decisionResolution(
+  value: HumanDecisionReceipt | undefined,
+):
+  | { provenance: "human"; decision: HumanDecisionReceipt }
+  | { provenance: "timeout"; decision: HumanDecisionReceipt } {
+  if (value === undefined) throw new Error("plan approval decision receipt is missing");
+  return { provenance: value.provenance, decision: value };
+}
+
+function humanResolution(value: HumanDecisionReceipt | undefined): {
+  provenance: "human";
+  decision: HumanDecisionReceipt;
+} {
+  const resolution = decisionResolution(value);
+  if (resolution.provenance !== "human") {
+    throw new Error("plan approval stop and replan require a human decision");
+  }
+  return resolution;
 }
 
 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,
+  startAt: "routePolicy",
   exits: {
     continue: {
       from: "continued",
@@ -115,11 +227,25 @@ export const planApprovalWorkflow = defineWorkflow({
     },
   },
   nodes: {
+    routePolicy: compute({
+      run: ({ input }) => ({
+        route: (input as NormalizedPlanApprovalInput).approval.mode === "skip" ? "skip" : "ask",
+      }),
+    }),
     approve: humanDecision({
-      audience: ({ input }) => (input as PlanApprovalInput).audience,
+      audience: ({ input }) => (input as NormalizedPlanApprovalInput).approval.audience,
       choices: planChoices,
+      onTimeout: ({ input }) => {
+        const policy = (input as NormalizedPlanApprovalInput).approval;
+        return policy.mode === "auto"
+          ? {
+              afterMs: (policy.timeoutMinutes ?? DEFAULT_APPROVAL_TIMEOUT_MINUTES) * 60_000,
+              response: { choice: "continue" },
+            }
+          : undefined;
+      },
       request: ({ input }) => {
-        const request = input as PlanApprovalInput;
+        const request = input as NormalizedPlanApprovalInput;
         const revision = request.revision ?? 1;
         return {
           title: "Approve the implementation plan",
@@ -141,28 +267,31 @@ export const planApprovalWorkflow = defineWorkflow({
     }),
     continued: compute({
       run: ({ input, state }) => {
-        const request = input as PlanApprovalInput;
+        const request = input as NormalizedPlanApprovalInput;
         return {
           status: "continue",
           plan: request.plan,
           planDigest: request.planDigest,
-          decision: acceptedDecision(state.humanDecision),
+          resolution:
+            request.approval.mode === "skip"
+              ? { provenance: "skipped", revision: request.revision ?? 1 }
+              : decisionResolution(state.humanDecision),
         } satisfies PlanApprovalContinue;
       },
     }),
     stopped: compute({
       run: ({ input, state }) => {
-        const request = input as PlanApprovalInput;
+        const request = input as NormalizedPlanApprovalInput;
         return {
           status: "stop",
           planDigest: request.planDigest,
-          decision: acceptedDecision(state.humanDecision),
+          resolution: humanResolution(state.humanDecision),
         } satisfies PlanApprovalStop;
       },
     }),
     replan: compute({
       run: ({ input, outputs, state }) => {
-        const request = input as PlanApprovalInput;
+        const request = input as NormalizedPlanApprovalInput;
         const response = gateResponse(outputs.approve);
         const instructions = response.input?.instructions;
         if (typeof instructions !== "string" || instructions.length === 0) {
@@ -173,12 +302,16 @@ export const planApprovalWorkflow = defineWorkflow({
           plan: request.plan,
           planDigest: request.planDigest,
           instructions,
-          decision: acceptedDecision(state.humanDecision),
+          resolution: humanResolution(state.humanDecision),
         } satisfies PlanApprovalReplan;
       },
     }),
   },
   edges: [
+    {
+      from: "routePolicy",
+      switch: { on: "$.route", cases: { ask: "approve", skip: "continued" } },
+    },
     humanDecisionEdge({
       from: "approve",
       choices: planChoices,

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

@@ -0,0 +1,321 @@
+import {
+  compute,
+  defineWorkflow,
+  includeWorkflow,
+  includedResult,
+} from "../workflows/definition.js";
+import type { WorkflowNodeContext } from "../workflows/types.js";
+import autodocWorkflow, { type AutodocInput, type DocumentedPlan } from "./autodoc.workflow.js";
+import autoplanWorkflow, { type AutoplanInput, type AutoplanReady } from "./autoplan.workflow.js";
+import planApprovalWorkflow, {
+  parsePlanApprovalPolicy,
+  type PlanApprovalContinue,
+  type NormalizedPlanApprovalInput,
+  type PlanApprovalPolicy,
+  type PlanApprovalResolution,
+  type ResolvedPlanApprovalPolicy,
+} from "./plan-approval.workflow.js";
+
+export type PlanChangeInput = {
+  task: string;
+  scope?: string;
+  constraints?: string[];
+  repository?: string;
+  documents?: string[];
+  previousPlan?: unknown;
+  newEvidence?: unknown;
+  approval?: PlanApprovalPolicy;
+};
+
+export type NormalizedPlanChangeInput = Omit<PlanChangeInput, "approval"> & {
+  approval: ResolvedPlanApprovalPolicy;
+};
+
+export type PlanChangeReady = {
+  status: "ready";
+  plan: unknown;
+  planDigest: string;
+  documents: string[];
+  revision: number;
+  approval: PlanApprovalResolution;
+  documentation: DocumentedPlan["documentation"];
+};
+
+export type PlanChangeBlocked = {
+  status: "blocked";
+  reason: string;
+  evidence: unknown;
+};
+
+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 requireExactKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  label: string,
+): void {
+  const unexpected = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unexpected.length > 0) throw new Error(`${label} has unknown field ${unexpected[0]}`);
+}
+
+function parseStringArray(value: unknown, label: string): string[] | undefined {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return [...value] as string[];
+}
+
+function parseInput(value: unknown): NormalizedPlanChangeInput {
+  const input = requireRecord(value, "plan change input");
+  requireExactKeys(
+    input,
+    [
+      "task",
+      "scope",
+      "constraints",
+      "repository",
+      "documents",
+      "previousPlan",
+      "newEvidence",
+      "approval",
+    ],
+    "plan change input",
+  );
+  const constraints = parseStringArray(input.constraints, "plan change constraints");
+  const documents = parseStringArray(input.documents, "plan change documents");
+  return {
+    task: requireString(input.task, "plan change task"),
+    ...(input.scope !== undefined
+      ? { scope: requireString(input.scope, "plan change scope") }
+      : {}),
+    ...(constraints !== undefined ? { constraints } : {}),
+    ...(input.repository !== undefined
+      ? { repository: requireString(input.repository, "plan change repository") }
+      : {}),
+    ...(documents !== undefined ? { documents } : {}),
+    ...(input.previousPlan !== undefined ? { previousPlan: input.previousPlan } : {}),
+    ...(input.newEvidence !== undefined ? { newEvidence: input.newEvidence } : {}),
+    approval: parsePlanApprovalPolicy(input.approval),
+  };
+}
+
+function currentDesign(context: Pick<WorkflowNodeContext, "outputs">): AutoplanReady {
+  const result = includedResult(autoplanWorkflow, context.outputs.design);
+  if (result.exit !== "ready") throw new Error("plan change design did not return a ready plan");
+  return result.output;
+}
+
+function currentDocumentation(context: Pick<WorkflowNodeContext, "outputs">): DocumentedPlan {
+  const result = includedResult(autodocWorkflow, context.outputs.documentation);
+  if (result.exit !== "ready") {
+    throw new Error("plan change documentation did not return a ready plan");
+  }
+  return result.output;
+}
+
+function currentApproval(context: Pick<WorkflowNodeContext, "outputs">): PlanApprovalContinue {
+  const result = includedResult(planApprovalWorkflow, context.outputs.approval);
+  if (result.exit !== "continue") {
+    throw new Error("plan change approval did not return continue");
+  }
+  return result.output;
+}
+
+function latestReplanInstructions(outputs: Record<string, unknown>): string | undefined {
+  if (outputs.approval === undefined) return undefined;
+  const result = includedResult(planApprovalWorkflow, outputs.approval);
+  return result.exit === "replan" ? result.output.instructions : undefined;
+}
+
+function blockedResult(context: WorkflowNodeContext): PlanChangeBlocked {
+  if (context.outputs.approval !== undefined) {
+    const approval = includedResult(planApprovalWorkflow, context.outputs.approval);
+    if (approval.exit === "stop") {
+      return {
+        status: "blocked",
+        reason: "The operator stopped the proposed plan change.",
+        evidence: approval.output,
+      };
+    }
+  }
+  const candidates = ["replanGuard", "assessPlan", "approval", "documentation", "design"];
+  for (let index = context.state.steps.length - 1; index >= 0; index -= 1) {
+    const step = context.state.steps[index];
+    if (step === undefined || !candidates.some((candidate) => step.nodeId.startsWith(candidate))) {
+      continue;
+    }
+    const output = step.output as Record<string, unknown> | null;
+    if (output !== null && typeof output === "object") {
+      const reason = output.reason;
+      if (typeof reason === "string" && reason.length > 0) {
+        return { status: "blocked", reason, evidence: step.output };
+      }
+    }
+  }
+  return {
+    status: "blocked",
+    reason: "The plan change could not continue within its configured policy.",
+    evidence: null,
+  };
+}
+
+export const planChangeWorkflow = defineWorkflow({
+  source: import.meta.url,
+  name: "plan-change",
+  input: parseInput,
+  startAt: "start",
+  maxSteps: 400,
+  includes: {
+    design: includeWorkflow(autoplanWorkflow, {
+      input: ({ input, outputs }): AutoplanInput => {
+        const request = input as NormalizedPlanChangeInput;
+        const prior =
+          outputs.design === undefined
+            ? request.previousPlan
+            : (() => {
+                const result = includedResult(autoplanWorkflow, outputs.design);
+                return result.exit === "ready" ? result.output.plan : request.previousPlan;
+              })();
+        const instructions = latestReplanInstructions(outputs);
+        return {
+          problem: request.task,
+          ...(request.scope !== undefined ? { scope: request.scope } : {}),
+          ...(request.constraints !== undefined ? { constraints: request.constraints } : {}),
+          ...(prior !== undefined ? { previousPlan: prior } : {}),
+          ...(instructions === undefined
+            ? request.newEvidence !== undefined
+              ? { newEvidence: request.newEvidence }
+              : {}
+            : {
+                newEvidence: {
+                  priorEvidence: request.newEvidence,
+                  operatorInstructions: instructions,
+                },
+              }),
+        };
+      },
+    }),
+    documentation: includeWorkflow(autodocWorkflow, {
+      input: (context): AutodocInput => {
+        const request = context.input as NormalizedPlanChangeInput;
+        const design = currentDesign(context);
+        return {
+          task: request.task,
+          plan: design.plan,
+          ...(request.repository !== undefined ? { repository: request.repository } : {}),
+          ...(request.documents !== undefined ? { documents: request.documents } : {}),
+          evidence: request.newEvidence,
+        };
+      },
+    }),
+    approval: includeWorkflow(planApprovalWorkflow, {
+      input: (context): NormalizedPlanApprovalInput => {
+        const request = context.input as NormalizedPlanChangeInput;
+        const documented = currentDocumentation(context);
+        const revision =
+          context.state.steps.filter((step) => step.nodeId === "approval/routePolicy").length + 1;
+        return {
+          task: request.task,
+          plan: documented.plan,
+          planDigest: documented.planDigest,
+          approval: request.approval,
+          revision,
+        };
+      },
+    }),
+  },
+  exits: {
+    ready: {
+      from: "finalize",
+      validate: (value: unknown): PlanChangeReady => value as PlanChangeReady,
+    },
+    blocked: {
+      from: "blocked",
+      validate: (value: unknown): PlanChangeBlocked => value as PlanChangeBlocked,
+    },
+  },
+  nodes: {
+    start: compute({ run: () => ({ route: "design" }) }),
+    assessPlan: compute({
+      run: (context) => {
+        const request = context.input as NormalizedPlanChangeInput;
+        const design = currentDesign(context);
+        return request.previousPlan !== undefined && design.changed !== true
+          ? {
+              route: "blocked",
+              reason: "Planning returned the same plan for the unresolved evidence.",
+              evidence: design,
+            }
+          : { route: "document", planDigest: design.planDigest };
+      },
+    }),
+    replanGuard: compute({
+      run: (context) => {
+        const request = context.input as NormalizedPlanChangeInput;
+        const replans = context.state.steps.filter(
+          (step) => step.nodeId === "approval/replan",
+        ).length;
+        return replans > request.approval.maxReplans
+          ? {
+              route: "blocked",
+              reason: `Plan approval reached the ${request.approval.maxReplans}-replan safety limit.`,
+              replans,
+              limit: request.approval.maxReplans,
+            }
+          : { route: "design", replans, limit: request.approval.maxReplans };
+      },
+    }),
+    finalize: compute({
+      run: (context) => {
+        const documented = currentDocumentation(context);
+        const approval = currentApproval(context);
+        const revision = context.state.steps.filter(
+          (step) => step.nodeId === "approval/routePolicy",
+        ).length;
+        return {
+          status: "ready",
+          plan: documented.plan,
+          planDigest: documented.planDigest,
+          documents: documented.documentation.files,
+          revision,
+          approval: approval.resolution,
+          documentation: documented.documentation,
+        } satisfies PlanChangeReady;
+      },
+    }),
+    blocked: compute({ run: blockedResult }),
+  },
+  edges: [
+    { from: "start", to: "design" },
+    { from: "design.ready", to: "assessPlan" },
+    { from: "design.blocked", to: "blocked" },
+    {
+      from: "assessPlan",
+      switch: { on: "$.route", cases: { document: "documentation", blocked: "blocked" } },
+    },
+    { from: "documentation.ready", to: "approval" },
+    { from: "documentation.blocked", to: "blocked" },
+    { from: "approval.continue", to: "finalize" },
+    { from: "approval.stop", to: "blocked" },
+    { from: "approval.replan", to: "replanGuard" },
+    {
+      from: "replanGuard",
+      switch: { on: "$.route", cases: { design: "design", blocked: "blocked" } },
+    },
+  ],
+});
+
+export default planChangeWorkflow;

package/src/builtins/plan-presentation.ts

@@ -1,6 +1,6 @@
 import {
-  legacyDecisionPresentation,
   normalizeDecisionPresentation,
+  valueDecisionPresentation,
 } from "../workflows/decision-presentation.js";
 import type { DecisionPresentation } from "../workflows/types.js";
 
@@ -10,7 +10,7 @@ export function presentPlan(input: {
   planDigest: string;
   revision: number;
 }): DecisionPresentation {
-  const plan = legacyDecisionPresentation(input.plan);
+  const plan = valueDecisionPresentation(input.plan);
   const summary =
     readableSummary(planSummary(input.plan)) ??
     readableSummary(`Review the implementation plan for ${input.task}.`)!;