Merge: coherent workflows — validator + richer ops + multi-instruction edit agent

Author: DylanMerigaud

app/api/workflow/edit/route.ts

@@ -2,8 +2,8 @@ import { z } from "zod";
 
 import { ApprovalWorkflow } from "@/lib/approval-workflow";
 import { checkRateLimit, clientIpFrom } from "@/lib/ratelimit";
-import { proposeEdit } from "@/lib/workflow-edit";
-import { anthropicEditModel } from "@/lib/workflow-edit-model";
+import { runEditAgent } from "@/lib/workflow-edit-agent";
+import { anthropicPlanModel } from "@/lib/workflow-edit-model";
 
 /**
  * POST /api/workflow/edit — propose a conversational edit to an approval workflow.
@@ -49,13 +49,13 @@ export const POST = async (request: Request): Promise<Response> => {
   }
 
   try {
-    const { proposed, op, changes } = await proposeEdit(
-      anthropicEditModel,
+    // The agent plans an ordered list of ops, applies them, and self-corrects
+    // against the validator until the workflow is sound (or its step budget).
+    const { proposed, changes, reason } = await runEditAgent(
+      anthropicPlanModel,
       workflow,
       instruction,
     );
-    // `op.reason` (only present on a `none`) explains why nothing changed.
-    const reason = op.op === "none" ? op.reason : null;
     return Response.json({ proposed, changes, reason });
   } catch {
     // A validation failure (the model produced an invalid graph) or a model error

components/onboarding.tsx

@@ -1,9 +1,14 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 
 import { Badge } from "@/components/ui/badge";
-import { BambooHrIcon } from "@/components/ui/brand-icon";
+import {
+  BambooHrIcon,
+  SlackIcon,
+  NetSuiteIcon,
+  JiraIcon,
+} from "@/components/ui/brand-icon";
 import { Button } from "@/components/ui/button";
 import { Card, CardHeader, CardTitle, Eyebrow } from "@/components/ui/card";
 import { WorkflowEditor } from "@/components/workflow-editor";
@@ -135,11 +140,7 @@ export const Onboarding = () => {
       <Card className="flex flex-col overflow-hidden">
         <CardHeader>
           <CardTitle>Derived approval workflow</CardTitle>
-          {state.status === "done" && (
-            <span className="hidden text-[11px] text-faint sm:inline">
-              edit in plain language · approve to apply
-            </span>
-          )}
+          {state.status === "done" && <WhatCanIChange />}
         </CardHeader>
         <div className="flex-1 overflow-hidden p-5">
           {state.status === "done" ? (
@@ -158,6 +159,110 @@ export const Onboarding = () => {
   );
 };
 
+/**
+ * A clickable "What can I change?" helper that opens a popover listing the edits
+ * the plain-language editor actually supports — so the capabilities are
+ * discoverable without overclaiming. (The editor maps your sentence to one of
+ * these structured ops; it's natural-language editing, not an open-ended agent.)
+ */
+const EDIT_ACTIONS: {
+  icon: React.ReactNode;
+  title: string;
+  example: string;
+}[] = [
+  {
+    icon: <span className="text-[11px]">✓</span>,
+    title: "Add an approval gate",
+    example: "“Require a CFO sign-off above $50k”",
+  },
+  {
+    icon: <SlackIcon size={14} />,
+    title: "Add a Slack notification",
+    example: "“Notify on Slack when a bill posts”",
+  },
+  {
+    icon: <JiraIcon size={14} />,
+    title: "Open a Jira ticket",
+    example: "“Open a Jira ticket for IT bills”",
+  },
+  {
+    icon: <NetSuiteIcon size={14} />,
+    title: "Post to NetSuite",
+    example: "“Post approved bills to NetSuite”",
+  },
+  {
+    icon: <span className="text-[11px]">$</span>,
+    title: "Change a threshold",
+    example: "“Lower the director threshold to $10k”",
+  },
+  {
+    icon: <span className="text-[11px]">@</span>,
+    title: "Change an approver",
+    example: "“Make Jordan Ellis the director approver”",
+  },
+  {
+    icon: <span className="text-[11px]">−</span>,
+    title: "Remove a step",
+    example: "“Drop the department review”",
+  },
+];
+
+const WhatCanIChange = () => {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!open) return;
+    const onDoc = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as globalThis.Node))
+        setOpen(false);
+    };
+    document.addEventListener("mousedown", onDoc);
+    return () => document.removeEventListener("mousedown", onDoc);
+  }, [open]);
+
+  return (
+    <div ref={ref} className="relative">
+      <button
+        onClick={() => setOpen((o) => !o)}
+        className="inline-flex items-center gap-1.5 rounded-full bg-subtle px-2.5 py-1 text-[11.5px] font-medium text-muted ring-1 ring-inset ring-line-strong transition-colors hover:text-ink"
+      >
+        <span className="grid size-3.5 place-items-center rounded-full bg-ink text-[9px] font-bold text-white">
+          ?
+        </span>
+        What can I change?
+      </button>
+      {open && (
+        <div className="absolute right-0 z-20 mt-2 w-80 rounded-xl bg-surface p-2 shadow-lift ring-1 ring-inset ring-line">
+          <p className="px-2 pb-1.5 pt-1 text-[11px] leading-snug text-faint">
+            Describe a change in plain language; it proposes a rewrite and you
+            review the diff before anything applies.
+          </p>
+          <ul className="space-y-0.5">
+            {EDIT_ACTIONS.map((a) => (
+              <li
+                key={a.title}
+                className="flex items-start gap-2.5 rounded-lg px-2 py-1.5 hover:bg-subtle"
+              >
+                <span className="mt-0.5 grid size-5 shrink-0 place-items-center rounded-md bg-subtle text-muted ring-1 ring-inset ring-line-strong">
+                  {a.icon}
+                </span>
+                <span className="min-w-0">
+                  <span className="block text-[12.5px] font-medium text-ink">
+                    {a.title}
+                  </span>
+                  <span className="block text-[11px] italic leading-snug text-faint">
+                    {a.example}
+                  </span>
+                </span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </div>
+  );
+};
+
 /** Initials for an avatar chip ("Riley Carter" → "RC"). */
 const initials = (name: string): string =>
   name

components/workflow-editor.tsx

@@ -1,20 +1,27 @@
 "use client";
 
-import { useState } from "react";
+import { useMemo, useState } from "react";
 
 import { Button } from "@/components/ui/button";
 import { WorkflowGraph } from "@/components/workflow-graph";
 import { API_ROUTES } from "@/lib/api-routes";
 import type { ApprovalWorkflow, StepChange } from "@/lib/approval-workflow";
+import {
+  validateWorkflow,
+  isActivatable,
+  type WorkflowIssue,
+} from "@/lib/workflow-validate";
 
 /**
  * The conversational workflow editor — the layer competitors don't have.
  *
- * You type what you want ("above $10k add a CFO approval") and the agent proposes
- * a rewrite. Nothing is applied until you APPROVE: the graph shows the proposal
- * with the diff (added / changed / removed), and you either keep it (the proposal
- * becomes the current workflow) or revert (discard it). The current workflow is
- * the only thing that would ever drive the pipeline — the proposal is preview-only.
+ * You type what you want ("above $10k add a CFO approval") and a structured-output
+ * model maps it to one edit op, which deterministic code applies to PROPOSE a
+ * rewrite (it's plain-language editing, not an open-ended agent). Nothing applies
+ * until you APPROVE: the graph shows the proposal with the diff (added / changed /
+ * removed), and you keep it (the proposal becomes current) or revert (discard it).
+ * The current workflow is the only thing that drives the pipeline — proposal is
+ * preview-only.
  *
  * Holds two workflows: `current` (the approved one) and an optional `proposal`
  * (a pending edit). Reads POST /api/workflow/edit.
@@ -83,14 +90,30 @@ export const WorkflowEditor = ({
     }
   };
 
+  // Validate whatever's on screen (the proposal if pending, else the live one).
+  // Errors block applying a proposal; warnings are surfaced but don't block.
+  const shown = proposal?.proposed ?? current;
+  const issues = useMemo(() => validateWorkflow(shown), [shown]);
+  const canApply = isActivatable(issues);
+
   const approve = () => {
-    if (!proposal) return;
+    if (!proposal || !isActivatable(validateWorkflow(proposal.proposed)))
+      return;
     setCurrent(proposal.proposed); // the proposal becomes live
     setProposal(null);
   };
   const revert = () => {
     setProposal(null); // discard — current is untouched
   };
+  // Reset = restore the originally-derived workflow (NOT recompute — that's the
+  // left pane's "Re-run discovery"). Instant, deterministic.
+  const isEdited = current !== initial;
+  const reset = () => {
+    setCurrent(initial);
+    setProposal(null);
+    setChips(suggestions);
+    setError(null);
+  };
 
   const changedCount = proposal
     ? proposal.changes.filter((c) => c.kind !== "unchanged").length
@@ -106,12 +129,16 @@ export const WorkflowEditor = ({
           <WorkflowGraph
             workflow={proposal.proposed}
             changes={proposal.changes}
+            issues={issues}
           />
         ) : (
-          <WorkflowGraph workflow={current} />
+          <WorkflowGraph workflow={current} issues={issues} />
         )}
       </div>
 
+      {/* Validation summary — "sound" or the list of issues (errors block apply). */}
+      <ValidationPanel issues={issues} />
+
       {/* Pending-edit bar: approve / revert */}
       {proposal && (
         <div className="flex items-center justify-between gap-2 rounded-xl bg-accent-soft/60 px-3.5 py-2.5 ring-1 ring-inset ring-accent/15">
@@ -123,7 +150,12 @@ export const WorkflowEditor = ({
             <Button variant="ghost" size="sm" onClick={revert}>
               Revert
             </Button>
-            <Button size="sm" onClick={approve}>
+            <Button
+              size="sm"
+              onClick={approve}
+              disabled={!canApply}
+              title={canApply ? undefined : "Fix the errors before applying"}
+            >
               Approve
             </Button>
           </div>
@@ -173,9 +205,26 @@ export const WorkflowEditor = ({
             value={instruction}
             onChange={(e) => setInstruction(e.target.value)}
             disabled={busy}
-            placeholder="Tell the agent how to change the workflow…"
+            placeholder="Describe a change in plain language…"
             className="h-10 flex-1 rounded-lg bg-surface px-3.5 text-[13px] text-ink shadow-card outline-none ring-1 ring-inset ring-line-strong transition-shadow placeholder:text-faint focus:ring-2 focus:ring-accent-ring disabled:opacity-60"
           />
+          {isEdited && !proposal && (
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={() => {
+                if (
+                  window.confirm(
+                    "Discard all edits and restore the workflow the agent first derived?",
+                  )
+                )
+                  reset();
+              }}
+              title="Restore the originally derived workflow"
+            >
+              Reset
+            </Button>
+          )}
           <Button
             type="submit"
             loading={busy}
@@ -189,6 +238,56 @@ export const WorkflowEditor = ({
   );
 };
 
+/**
+ * The validation summary. "Sound" when there's nothing to flag; otherwise the list
+ * of errors (red, block applying) and warnings (amber, control best-practices). This
+ * is what shows the tool understands the workflow, not just draws it.
+ */
+const ValidationPanel = ({ issues }: { issues: WorkflowIssue[] }) => {
+  if (issues.length === 0) {
+    return (
+      <div className="flex items-center gap-1.5 rounded-xl bg-ok-soft/50 px-3.5 py-2 text-[12px] font-medium text-ok ring-1 ring-inset ring-ok-line/60">
+        <span aria-hidden>✓</span> Sound — passes the approval-control checks
+      </div>
+    );
+  }
+  const errors = issues.filter((i) => i.severity === "error");
+  const warnings = issues.filter((i) => i.severity === "warning");
+  return (
+    <div className="space-y-1.5 rounded-xl bg-subtle/60 px-3 py-2.5 ring-1 ring-inset ring-line">
+      <div className="flex flex-wrap items-center gap-2 text-[11px] font-semibold uppercase tracking-wider text-faint">
+        Checks
+        {errors.length > 0 && (
+          <span className="rounded-full bg-danger-soft px-1.5 py-0.5 text-danger">
+            {errors.length} to fix
+          </span>
+        )}
+        {warnings.length > 0 && (
+          <span className="rounded-full bg-warn-soft px-1.5 py-0.5 text-warn">
+            {warnings.length} {warnings.length === 1 ? "warning" : "warnings"}
+          </span>
+        )}
+      </div>
+      <ul className="space-y-1">
+        {issues.map((iss, i) => (
+          <li
+            key={`${iss.code}-${i}`}
+            className="flex gap-2 text-[12px] leading-snug text-ink/90"
+          >
+            <span
+              aria-hidden
+              className={iss.severity === "error" ? "text-danger" : "text-warn"}
+            >
+              {iss.severity === "error" ? "✕" : "⚠"}
+            </span>
+            <span>{iss.message}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+
 /** A small four-point spark, marking the AI-generated suggestions. */
 const SparkIcon = () => {
   return (