@osolmaz/pi-workflows 0.9.1 → 0.11.0

package/src/builtins/monitor.workflow.ts

@@ -1,4 +1,13 @@
-import { action, agent, compute, defineWorkflow, notify, shell } from "../workflows/definition.js";
+import {
+  action,
+  agent,
+  compute,
+  defineWorkflow,
+  includeWorkflow,
+  includedResult,
+  notify,
+  shell,
+} from "../workflows/definition.js";
 import {
   estimateProgress,
   formatProgressReport,
@@ -11,6 +20,10 @@ import type {
   WorkflowProgressData,
 } from "../workflows/types.js";
 import { validateProgressData } from "../workflows/updates.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;
@@ -27,22 +40,49 @@ const MAX_REASON_CHARS = 2_000;
 const SLEEP_TIMEOUT_MARGIN_MS = 60_000;
 const NODE_TIMEOUT_MARGIN_MS = 2 * 60_000;
 
+export type MonitorRepairPolicy = {
+  authorized: true;
+  scope?: string;
+  constraints?: string[];
+  repository?: string;
+  baseBranch?: string;
+  merge?: boolean;
+  approval?: {
+    audience: string;
+    maxReplans: number;
+  };
+};
+
 export type MonitorInput = {
   task: string;
   everyMinutes?: number;
   stopWhen?: string;
   maxChecks?: number;
   checkTimeoutMinutes?: number;
+  repair?: MonitorRepairPolicy;
 };
 
-type MonitorConfig = Required<MonitorInput>;
-type MonitorRoute = "continue" | "stop";
+type MonitorConfig = {
+  task: string;
+  everyMinutes: number;
+  stopWhen: string;
+  maxChecks: number;
+  checkTimeoutMinutes: number;
+  repair?: MonitorRepairPolicy;
+};
+type MonitorRoute = "continue" | "repair" | "stop";
 type MonitorTrack = { key: string; data: WorkflowProgressData };
+type MonitorRepairRequest = {
+  problem: string;
+  evidence: unknown;
+  issueFingerprint: string;
+};
 type MonitorCheck = {
   route: MonitorRoute;
   observation: string;
   report: string;
   progress?: { tracks: MonitorTrack[] };
+  repair?: MonitorRepairRequest;
   reason: string;
 };
 type MonitorEstimate = { tracks: ProgressTrackState[] };
@@ -79,7 +119,14 @@ async function waitForUpdateSlot(signal: AbortSignal): Promise<void> {
 
 export function prepareMonitorInput(input: unknown): MonitorConfig {
   const value = requireRecord(input, "monitor input") as Partial<MonitorInput>;
-  const allowed = new Set(["task", "everyMinutes", "stopWhen", "maxChecks", "checkTimeoutMinutes"]);
+  const allowed = new Set([
+    "task",
+    "everyMinutes",
+    "stopWhen",
+    "maxChecks",
+    "checkTimeoutMinutes",
+    "repair",
+  ]);
   for (const field of Object.keys(value)) {
     if (!allowed.has(field)) throw new Error(`monitor input field ${field} is not supported`);
   }
@@ -109,6 +156,51 @@ export function prepareMonitorInput(input: unknown): MonitorConfig {
       `checkTimeoutMinutes must be an integer from ${MIN_CHECK_TIMEOUT_MINUTES} through ${MAX_CHECK_TIMEOUT_MINUTES}`,
     );
   }
+  let repair: MonitorRepairPolicy | undefined;
+  if (value.repair !== undefined) {
+    const raw = requireRecord(value.repair, "repair policy");
+    if (raw.authorized !== true) throw new Error("repair policy must set authorized to true");
+    if (
+      raw.constraints !== undefined &&
+      (!Array.isArray(raw.constraints) || raw.constraints.some((item) => typeof item !== "string"))
+    ) {
+      throw new Error("repair constraints must be an array of strings");
+    }
+    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
+        ? { scope: requireBoundedString(raw.scope, "repair scope", 4_000) }
+        : {}),
+      ...(raw.constraints !== undefined ? { constraints: [...raw.constraints] as string[] } : {}),
+      ...(raw.repository !== undefined
+        ? { repository: requireBoundedString(raw.repository, "repair repository", 4_000) }
+        : {}),
+      ...(raw.baseBranch !== undefined
+        ? { baseBranch: requireBoundedString(raw.baseBranch, "repair base branch", 256) }
+        : {}),
+      ...(raw.merge !== undefined ? { merge: raw.merge !== false } : {}),
+      ...(approval !== undefined ? { approval } : {}),
+    };
+  }
   return {
     task,
     everyMinutes,
@@ -118,6 +210,7 @@ export function prepareMonitorInput(input: unknown): MonitorConfig {
         : requireBoundedString(value.stopWhen, "stopWhen", 4_000),
     maxChecks,
     checkTimeoutMinutes,
+    ...(repair !== undefined ? { repair } : {}),
   };
 }
 
@@ -130,13 +223,17 @@ function completedChecks(context: WorkflowNodeContext): number {
     .length;
 }
 
-export function validateMonitorCheck(output: unknown): MonitorCheck {
+export function validateMonitorCheck(output: unknown, repairAuthorized = false): MonitorCheck {
   const value = requireRecord(output, "monitor check output");
-  const allowed = new Set(["route", "observation", "report", "progress", "reason"]);
+  const allowed = new Set(["route", "observation", "report", "progress", "repair", "reason"]);
   for (const key of Object.keys(value))
     if (!allowed.has(key)) throw new Error(`monitor check field ${key} is not supported`);
-  if (value.route !== "continue" && value.route !== "stop")
-    throw new Error("route must be continue or stop");
+  if (value.route !== "continue" && value.route !== "repair" && value.route !== "stop") {
+    throw new Error("route must be continue, repair, or stop");
+  }
+  if (value.route === "repair" && !repairAuthorized) {
+    throw new Error("route repair requires explicit monitor repair authorization");
+  }
   const check: MonitorCheck = {
     route: value.route,
     observation: requireBoundedString(value.observation, "observation", MAX_OBSERVATION_CHARS),
@@ -144,6 +241,21 @@ export function validateMonitorCheck(output: unknown): MonitorCheck {
     reason: requireBoundedString(value.reason, "reason", MAX_REASON_CHARS),
   };
   if (value.progress !== undefined) check.progress = validateMonitorProgress(value.progress);
+  if (value.repair !== undefined) {
+    const repair = requireRecord(value.repair, "monitor repair request");
+    check.repair = {
+      problem: requireBoundedString(repair.problem, "repair problem", 8_000),
+      evidence: repair.evidence ?? null,
+      issueFingerprint: requireBoundedString(
+        repair.issueFingerprint,
+        "repair issue fingerprint",
+        256,
+      ),
+    };
+  }
+  if (value.route === "repair" && check.repair === undefined) {
+    throw new Error("route repair requires repair details");
+  }
   return check;
 }
 
@@ -190,6 +302,88 @@ function estimateTracks(outputs: Record<string, unknown>): MonitorEstimate {
   };
 }
 
+function repeatedRepairWithoutProgress(context: WorkflowNodeContext): boolean {
+  const current = context.outputs.check as MonitorCheck;
+  const fingerprint = current.repair?.issueFingerprint;
+  if (fingerprint === undefined) return false;
+  const steps = context.state.steps;
+  const currentCheckIndex = steps.findLastIndex((step) => step.nodeId === "check");
+  for (let index = currentCheckIndex - 1; index >= 0; index -= 1) {
+    const step = steps[index];
+    if (step?.nodeId !== "check") continue;
+    const prior = step.output as MonitorCheck;
+    if (prior.repair?.issueFingerprint !== fingerprint) continue;
+    return steps
+      .slice(index + 1, currentCheckIndex)
+      .some((candidate) => candidate.nodeId === "implementation");
+  }
+  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;
+  const design = outputs.initialDesign as
+    | { exit?: string; output?: { reason?: string } }
+    | undefined;
+  return (
+    implementation?.output?.reason ??
+    documentation?.output?.reason ??
+    design?.output?.reason ??
+    "The repair did not produce new verified progress."
+  );
+}
+
 function reportMessage(context: WorkflowNodeContext): string {
   const check = context.outputs.check as MonitorCheck;
   const estimate = context.outputs.estimate as MonitorEstimate;
@@ -219,7 +413,10 @@ function reportMessage(context: WorkflowNodeContext): string {
 }
 
 const monitorWorkflow: WorkflowDefinition = defineWorkflow({
+  source: import.meta.url,
+  contractId: "pi-workflows.monitor.v1",
   name: "monitor",
+  input: prepareMonitorInput,
   title: ({ input }) => {
     try {
       return `monitor: ${prepareMonitorInput(input).task.slice(0, 80)}`;
@@ -228,7 +425,104 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
     }
   },
   startAt: "prepare",
-  maxSteps: 9_010,
+  maxSteps: 200_000,
+  includes: {
+    initialDesign: includeWorkflow({
+      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 }
+            : {}),
+          ...(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,
+        };
+      },
+    }),
+    implementation: includeWorkflow({
+      workflow: "autoimplement",
+      contract: autoimplementWorkflow,
+      input: ({ outputs }) => {
+        const config = configFrom(outputs);
+        const repair = (outputs.check as MonitorCheck).repair;
+        const documented = currentRepairPlan(outputs);
+        if (repair === undefined) throw new Error("monitor repair details are missing");
+        const request: AutoimplementInput = {
+          task: repair.problem,
+          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 }
+            : {}),
+          ...(config.repair?.repository !== undefined
+            ? { repository: config.repair.repository }
+            : {}),
+          ...(config.repair?.baseBranch !== undefined
+            ? { baseBranch: config.repair.baseBranch }
+            : {}),
+          merge: config.repair?.merge === true,
+        };
+        return request;
+      },
+    }),
+  },
   nodes: {
     prepare: compute({ run: ({ input }) => prepareMonitorInput(input) }),
     check: agent({
@@ -248,15 +542,21 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
           priorEstimate?.tracks.length
             ? `Previous progress: ${formatProgressReport(priorEstimate.tracks.map((track) => track.estimate))}`
             : "There is no previous measured progress.",
-          "Use available tools to inspect the current source of truth. Observe only unless the task explicitly authorizes a mutation.",
+          config.repair === undefined
+            ? "Observe only. This monitor has no mutation authorization."
+            : "Repair is explicitly authorized within the supplied repair policy. Choose repair only for a concrete issue that can be changed within that scope. Include a stable issue fingerprint based on the issue and observed target state. Do not change protected model, benchmark, credential, hardware, spending, or scope decisions.",
+          "Use available tools to inspect the current source of truth.",
           "You are the regular Pi model running this check and the observation adapter. When useful measurable facts appear during the check, publish them with workflow action update. Include the latest tracks in the final submission. Do not require the monitored target to implement a Pi-specific progress API, file, store, schema, or command.",
           "Every accepted check must include a concise user-facing report. Add progress tracks only when the target provides measurable facts. Submit observed counts and target-provided finish times; do not invent rates or an ETA.",
-          "Choose route continue or stop.",
+          config.repair === undefined
+            ? "Choose route continue or stop."
+            : "Choose route continue, repair, or stop.",
         ].join("\n\n");
       },
       expectedOutput:
-        '{ "route": "continue" | "stop", "observation": "current factual state", "report": "concise status update", "progress": { "tracks": [{ "key": "stable-key", "data": { "schema": "pi-workflows.progress.v1", "status": "running", "completed": 1, "total": 2, "unit": "items" } }] } (optional), "reason": "short reason" }',
-      validate: (output) => validateMonitorCheck(output),
+        '{ "route": "continue" | "repair" | "stop", "observation": "current factual state", "report": "concise status update", "progress": { "tracks": [{ "key": "stable-key", "data": { "schema": "pi-workflows.progress.v1", "status": "running", "completed": 1, "total": 2, "unit": "items" } }] } (optional), "repair": { "problem": "fixable issue", "evidence": "observed evidence", "issueFingerprint": "stable issue and target-state fingerprint" } (required for repair), "reason": "short reason" }',
+      validate: (output, context) =>
+        validateMonitorCheck(output, configFrom(context.outputs).repair !== undefined),
     }),
     estimate: compute({ run: ({ outputs }) => estimateTracks(outputs) }),
     publish_progress: action({
@@ -289,9 +589,55 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
             checks,
           };
         }
+        if (check.route === "repair") return { route: "repair", reason: check.reason, checks };
         return { route: "continue", reason: check.reason, checks };
       },
     }),
+    repairGuard: compute({
+      run: (context) =>
+        repeatedRepairWithoutProgress(context)
+          ? {
+              route: "blocked",
+              reason:
+                "The same issue returned after a completed repair with no changed target evidence.",
+            }
+          : { 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),
+        observation: (context.outputs.check as MonitorCheck).observation,
+        checks: completedChecks(context),
+        reported: true,
+      }),
+    }),
+    repairReport: notify({
+      statusDetail: "reporting blocked monitor repair",
+      kind: "final",
+      message: ({ outputs }) => {
+        const result = outputs.repairBlocked as { reason: string };
+        return `Automatic repair stopped: ${result.reason}`;
+      },
+    }),
     schedule: action({
       statusDetail: "scheduling next monitor check",
       run: async ({ outputs, publishUpdate }) => {
@@ -331,11 +677,17 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
       run: ({ outputs }) => {
         const check = outputs.check as MonitorCheck;
         const decision = outputs.decide as { reason?: string; checks?: number } | undefined;
+        const repair = outputs.repairBlocked as { reason?: string } | undefined;
         return {
-          reason: decision?.reason ?? check.reason,
+          reason: repair?.reason ?? decision?.reason ?? check.reason,
           observation: check.observation,
           checks: decision?.checks ?? 1,
           reported: true,
+          ...(outputs.implementation !== undefined
+            ? { repair: outputs.implementation }
+            : repair !== undefined
+              ? { repair }
+              : {}),
         };
       },
     }),
@@ -346,7 +698,36 @@ const monitorWorkflow: WorkflowDefinition = defineWorkflow({
     { from: "estimate", to: "publish_progress" },
     { from: "publish_progress", to: "report" },
     { from: "report", to: "decide" },
-    { from: "decide", switch: { on: "$.route", cases: { stop: "finish", continue: "schedule" } } },
+    {
+      from: "decide",
+      switch: {
+        on: "$.route",
+        cases: { stop: "finish", continue: "schedule", repair: "repairGuard" },
+      },
+    },
+    {
+      from: "repairGuard",
+      switch: { on: "$.route", cases: { repair: "initialDesign", blocked: "repairBlocked" } },
+    },
+    { 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" },
+    { from: "repairReport", to: "finish" },
     { from: "schedule", to: "sleep" },
     { from: "sleep", to: "check" },
   ],