Files
kandev/apps/web/components/settings/workflow-pipeline-editor-step-actions.tsx
T
João Salavisa 97c1f689e4 feat(workflow): explicit step-completion signal for auto-advance (#1276)
* feat(workflow): explicit step-completion signal for auto-advance

Adds `step_complete_kandev` MCP tool + `WorkflowStep.auto_advance_requires_signal`
column so workflow steps can gate their `on_turn_complete` transitions on an
agent-emitted completion signal instead of inferring "done" from any turn-end.
See docs/decisions/0015-explicit-completion-signal-for-auto-advance.md for the
motivation, alternatives considered, and trade-offs.

* fix(workflow): address PR review feedback for explicit completion signal

- Dedup `LoadPendingStepSignal` into `internal/task/models` so the MCP
  handler (write site) and the orchestrator (read site) share one decoder.
- Gate the out-of-band subscriber on `WorkflowStep.AutoAdvanceRequiresSignal`
  so `step_complete_kandev` is not an unintended manual-advance path for
  signalless steps.
- Fail closed on step-load errors in `processOnTurnCompleteViaEngine`: a
  loader hiccup must block the transition rather than silently bypass the
  gate.
- Reject `step_complete_kandev` for terminal sessions
  (Completed / Failed / Cancelled) so the agent gets a clear error instead
  of `accepted: true` followed by a no-op.
- Surface bus-publish failures back to the agent instead of swallowing
  them — the idempotency guard makes the retry safe and prevents the
  session from getting stuck.
- New `TestOnStepCompletionSignaled` covers the subscriber paths
  (RUNNING / WAITING+match / stale step / not signal-gated).
- ADR doc fixes: payload field list now matches the wire shape, writer
  ownership is documented, the unsubstantiated 250ms-debounce claim is
  removed, and the late-signal re-close race is recorded as a deferred
  open question.
- Drop the new toggle's HelpTip in favour of an inline description — the
  shadcn tooltip portal was intercepting clicks on the agent-profile
  dropdown options in the workflow settings E2E.

* fix(workflow): round-2 review fixes for explicit completion signal

- Split `handleStepComplete` into `resolveStepCompleteTarget` +
  `publishStepCompletionEvent` helpers so the entrypoint clears funlen
  (88 → under 80 lines) and the two halves are independently testable.
- Classify session/task load errors instead of returning `NotFound` for
  every failure: use the exported `taskrepo.ErrTaskNotFound` sentinel for
  task lookups, substring-match for the session repo (no sentinel today),
  and surface anything else as `InternalError` with the raw error logged
  but not leaked to the agent — so a transient DB hiccup triggers a retry
  rather than session abandonment.
- Pin `step_complete_kandev` explicitly in the mode-specific tool-count
  tests: `Contains` in `ModeTask`, `NotContains` in `ModeConfig` and
  `ModeOffice`, so accidental dereg or cross-mode registration is caught
  by the diff instead of by a still-equal count.

* fix(workflow): round-3 review fixes + defer pipeline-editor toggle

- Defer the "Wait for agent completion signal" sub-toggle to a follow-up
  PR. Adding it to the step config card shifts the layout enough that the
  agent profile select's Radix popper opens into a sibling tooltip's hover
  path, breaking workflow-agent-profile.spec.ts on shard 7. The backend
  column ships in this PR — workflows can opt in via the YAML import or
  the MCP `update_workflow_step_kandev` tool — and the UI affordance gets
  its own iteration where the test interference can be investigated
  without blocking the rest of the change.
- Re-publish the bus event on the `already_signaled` short-circuit when
  the session is WAITING_FOR_INPUT. Without this, an agent's retry after
  the first call's publish failed would short-circuit on the persisted
  bag, never fire the subscriber, and leave the session stuck.
- handleStepComplete docstring: drop the non-existent feature-flag claim
  and the "audit entry" wording — gating is purely
  `WorkflowStep.AutoAdvanceRequiresSignal` and the bag is cleared on the
  next turn start with no separate audit trail.
- `step_complete_kandev` tool description: same fix — clarify that the
  call succeeds for non-gated steps but the signal is discarded on the
  next turn start (no audit history to query later).

* test(workflow): cover handleStepComplete + reword defer-comment

- Add `TestHandleStepComplete_*` (6 subtests, all passing) covering the
  uncovered handler paths flagged by Claude/cubic on round 3:
  missing-fields validation, session-does-not-belong-to-task ownership
  guard, terminal-session rejection (Completed/Failed/Cancelled),
  first-call happy path (bag persisted + bus payload shape pinned), dedup
  while RUNNING (no re-publish), and dedup while WAITING_FOR_INPUT (the
  retry-after-publish-failure path — must re-publish so the subscriber
  fires).
- Reword the deferred-toggle comment to drop the YAML-export claim:
  the workflow export model doesn't yet serialize
  `auto_advance_requires_signal`, so MCP `update_workflow_step_kandev`
  is the only configuration path that round-trips today. Note the
  follow-up needs to extend the export schema alongside the UI toggle.

* test(workflow): pin signaled_at + drop redundant GetTaskSession on bag-clear

- Assert `signaled_at` is present and parses as RFC3339Nano in
  `TestHandleStepComplete_FirstCallAccepted`. The field is part of the
  handler's documented response contract; pinning it catches accidental
  drop/rename regressions.
- Add `clearPendingStepSignalByID(ctx, sessionID)` as a thin DB-only
  variant of `clearPendingStepSignal` and use it from
  `executeStepTransition`, where the session struct isn't read after the
  clear. Avoids an extra `GetTaskSession` round-trip per transition.
  `clearPendingStepSignal(session)` still exists for the
  in-memory-mutation case (subscriber's stale-step path).

* fix(workflow): subscriber stale-clear guard + ADR/comment drift fixes

- onStepCompletionSignaled's stale-step path now reads the bag and only
  clears it when its current StepID matches the (stale) event's stepID.
  Previously the unconditional clear could destroy a valid signal that
  the new step's agent had just written when sessions are reused across
  steps without auto_start_agent. (Greptile P1.)
- Drop the "feature flag" phrase from WorkflowStep.AutoAdvanceRequiresSignal
  docstring — leftover from an earlier draft. The gating is purely the
  boolean field; the global flag was removed two rounds ago.
- Merge the two adjacent `if triggerOnEnter` blocks in
  executeStepTransition so the full triggerOnEnter=true path reads top-
  to-bottom in one place. (CodeRabbit + cubic.)
- ADR 0015 Mechanism section: re-label the SessionStepHistory.Metadata
  audit annotation, the `step_complete_signaled` system message, and the
  expvar telemetry counters as deferred. They're planned shapes, not
  current behaviour — calling them "Audit" / "Chat visibility" /
  "Telemetry" in present tense was misleading for future readers.

* fix(workflow): drop subscriber complexity + reload session on stale-clear

- Extract `parseStepCompletionEvent` and `stepIsSignalGated` helpers from
  `onStepCompletionSignaled`. Cyclomatic complexity goes 17 → under 15
  (cyclop on new code, CI lint regression after the round-6
  stale-clear guard).
- The stale-step branch now re-loads the session from the DB before
  deciding whether to clear the bag. The previous round-6 fix checked
  the local `session.Metadata` snapshot, which can be older than a
  concurrent write from the new step's agent — that check could see a
  stale signal that had since been overwritten with a valid one and
  erase the new bag entry. The narrower load-on-clear is cheap and
  closes the cubic P1 hole. (The broader race in
  `processOnTurnCompleteViaEngine` reading session.Metadata is the
  monotonic-marker open question in ADR 0015; out of scope here.)

* test(workflow): pin stale-event guard's preserve-current-bag side + dedup StringFromAny

- Add `TestOnStepCompletionSignaled` subtest "stale event → valid bag
  for CURRENT step is preserved" — fires a stale step-A event while
  the bag holds a valid step-B signal, asserts the bag still contains
  StepID=step_b after the subscriber runs. Pins the negative side of
  the round-6 `existing.StepID == stepID` guard, so a regression that
  drops or inverts the guard (and would silently leave signal-gated
  steps stuck) fails the test instead of slipping through.
- Promote `pendingSignalString` to exported `models.StringFromAny`
  and reuse it from the orchestrator subscriber's
  `parseStepCompletionEvent`. Eliminates the byte-for-byte duplicate
  helper across the two packages; the bag-shape decoder and the bus-
  event decoder now share one source of truth for "missing string".

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
2026-06-05 18:32:27 +01:00

265 lines
9.4 KiB
TypeScript

"use client";
import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@kandev/ui/select";
import { Checkbox } from "@kandev/ui/checkbox";
import { Label } from "@kandev/ui/label";
import type {
WorkflowStep,
OnEnterAction,
OnTurnStartAction,
OnTurnCompleteAction,
OnExitAction,
} from "@/lib/types/http";
import { cn } from "@/lib/utils";
import {
HelpTip,
getTransitionType,
getOnTurnStartTransitionType,
hasDisablePlanMode,
} from "./workflow-pipeline-editor-helpers";
// --- useStepActions hook ---
type UseStepActionsArgs = {
step: WorkflowStep;
onUpdate: (updates: Partial<WorkflowStep>) => void;
};
export function useStepActions({ step, onUpdate }: UseStepActionsArgs) {
const toggleOnEnterAction = (type: string) => {
const currentEvents = step.events ?? {};
const onEnter = currentEvents.on_enter ?? [];
const exists = onEnter.some((a) => a.type === type);
const newOnEnter = exists
? onEnter.filter((a) => a.type !== type)
: [...onEnter, { type } as OnEnterAction];
onUpdate({ events: { ...currentEvents, on_enter: newOnEnter } });
};
const setTransition = (type: string) => {
const currentEvents = step.events ?? {};
const onTurnComplete = (currentEvents.on_turn_complete ?? []).filter(
(a) => !["move_to_next", "move_to_previous", "move_to_step"].includes(a.type),
);
if (type !== "none") onTurnComplete.push({ type } as OnTurnCompleteAction);
onUpdate({ events: { ...currentEvents, on_turn_complete: onTurnComplete } });
};
const setOnTurnStartTransition = (type: string) => {
const currentEvents = step.events ?? {};
const onTurnStart = (currentEvents.on_turn_start ?? []).filter(
(a) => !["move_to_next", "move_to_previous", "move_to_step"].includes(a.type),
);
if (type !== "none") onTurnStart.push({ type } as OnTurnStartAction);
onUpdate({ events: { ...currentEvents, on_turn_start: onTurnStart } });
};
const toggleDisablePlanMode = () => {
const currentEvents = step.events ?? {};
const onTurnComplete = currentEvents.on_turn_complete ?? [];
const exists = onTurnComplete.some((a) => a.type === "disable_plan_mode");
const newOnTurnComplete = exists
? onTurnComplete.filter((a) => a.type !== "disable_plan_mode")
: [...onTurnComplete, { type: "disable_plan_mode" } as OnTurnCompleteAction];
onUpdate({ events: { ...currentEvents, on_turn_complete: newOnTurnComplete } });
};
const toggleOnExitAction = (type: string) => {
const currentEvents = step.events ?? {};
const onExit = currentEvents.on_exit ?? [];
const exists = onExit.some((a) => a.type === type);
const newOnExit = exists
? onExit.filter((a) => a.type !== type)
: [...onExit, { type } as OnExitAction];
onUpdate({ events: { ...currentEvents, on_exit: newOnExit } });
};
return {
toggleOnEnterAction,
setTransition,
setOnTurnStartTransition,
toggleDisablePlanMode,
toggleOnExitAction,
};
}
// --- TurnStartSelect ---
type StepSelectProps = {
step: WorkflowStep;
otherSteps: WorkflowStep[];
onUpdate: (updates: Partial<WorkflowStep>) => void;
readOnly: boolean;
};
export function TurnStartSelect({
step,
otherSteps,
onUpdate,
setOnTurnStartTransition,
readOnly,
}: StepSelectProps & { setOnTurnStartTransition: (t: string) => void }) {
const transitionType = getOnTurnStartTransitionType(step);
return (
<div className="space-y-2">
<div className="flex items-center gap-1.5">
<Label className="text-xs font-medium">On Turn Start</Label>
<HelpTip text="Runs when a user sends a message. Use for review cycles (e.g., move back to In Progress on feedback)." />
</div>
<Select
value={transitionType}
onValueChange={(value) => {
if (readOnly) return;
setOnTurnStartTransition(value);
}}
disabled={readOnly}
>
<SelectTrigger className="w-full h-8">
<SelectValue placeholder="Select action" />
</SelectTrigger>
<SelectContent position="popper" side="bottom" align="start">
<SelectItem value="none">Do nothing</SelectItem>
<SelectItem value="move_to_next">Move to next step</SelectItem>
<SelectItem value="move_to_previous">Move to previous step</SelectItem>
<SelectItem value="move_to_step">Move to specific step</SelectItem>
</SelectContent>
</Select>
{transitionType === "move_to_step" && (
<Select
value={
(step.events?.on_turn_start?.find((a) => a.type === "move_to_step")?.config
?.step_id as string) ?? ""
}
onValueChange={(value) => {
if (readOnly) return;
const currentEvents = step.events ?? {};
const onTurnStart = (currentEvents.on_turn_start ?? []).map((a) =>
a.type === "move_to_step" ? { ...a, config: { step_id: value } } : a,
);
onUpdate({ events: { ...currentEvents, on_turn_start: onTurnStart } });
}}
disabled={readOnly}
>
<SelectTrigger className="w-full h-8">
<SelectValue placeholder="Select step" />
</SelectTrigger>
<SelectContent position="popper" side="bottom" align="start">
{otherSteps.map((s) => (
<SelectItem key={s.id} value={s.id}>
<div className="flex items-center gap-2">
<div className={cn("w-2 h-2 rounded-full", s.color)} />
{s.name}
</div>
</SelectItem>
))}
</SelectContent>
</Select>
)}
</div>
);
}
// --- TurnCompleteSelect ---
type TurnCompleteSelectProps = StepSelectProps & {
setTransition: (t: string) => void;
toggleDisablePlanMode: () => void;
planModeEnabled: boolean;
};
export function TurnCompleteSelect({
step,
otherSteps,
onUpdate,
setTransition,
toggleDisablePlanMode,
planModeEnabled,
readOnly,
}: TurnCompleteSelectProps) {
const transitionType = getTransitionType(step);
return (
<div className="space-y-2">
<div className="flex items-center gap-1.5">
<Label className="text-xs font-medium">On Turn Complete</Label>
<HelpTip text="Runs after the agent finishes a turn. Use to auto-advance tasks through the pipeline." />
</div>
<Select
value={transitionType}
onValueChange={(value) => {
if (readOnly) return;
setTransition(value);
}}
disabled={readOnly}
>
<SelectTrigger className="w-full h-8">
<SelectValue placeholder="Select action" />
</SelectTrigger>
<SelectContent position="popper" side="bottom" align="start">
<SelectItem value="none">Do nothing (wait for user)</SelectItem>
<SelectItem value="move_to_next">Move to next step</SelectItem>
<SelectItem value="move_to_previous">Move to previous step</SelectItem>
<SelectItem value="move_to_step">Move to specific step</SelectItem>
</SelectContent>
</Select>
{transitionType === "move_to_step" && (
<Select
value={
(step.events?.on_turn_complete?.find((a) => a.type === "move_to_step")?.config
?.step_id as string) ?? ""
}
onValueChange={(value) => {
if (readOnly) return;
const currentEvents = step.events ?? {};
const onTurnComplete = (currentEvents.on_turn_complete ?? []).map((a) =>
a.type === "move_to_step" ? { ...a, config: { step_id: value } } : a,
);
onUpdate({ events: { ...currentEvents, on_turn_complete: onTurnComplete } });
}}
disabled={readOnly}
>
<SelectTrigger className="w-full h-8">
<SelectValue placeholder="Select step" />
</SelectTrigger>
<SelectContent position="popper" side="bottom" align="start">
{otherSteps.map((s) => (
<SelectItem key={s.id} value={s.id}>
<div className="flex items-center gap-2">
<div className={cn("w-2 h-2 rounded-full", s.color)} />
{s.name}
</div>
</SelectItem>
))}
</SelectContent>
</Select>
)}
{planModeEnabled && (
<div className="flex items-center gap-2 pt-1">
<Checkbox
id={`${step.id}-disable-plan`}
checked={hasDisablePlanMode(step)}
onCheckedChange={() => {
if (readOnly) return;
toggleDisablePlanMode();
}}
disabled={readOnly}
/>
<Label htmlFor={`${step.id}-disable-plan`} className="text-sm">
Disable plan mode on complete
</Label>
<HelpTip text="Turn off plan mode after the agent finishes this step." />
</div>
)}
</div>
);
}
// ADR 0015 explicit-completion-signal UI (the "Wait for agent completion
// signal" toggle) is deferred to a follow-up PR. The backend column ships
// here so workflow steps can opt in via the MCP
// `update_workflow_step_kandev` tool. The pipeline-editor toggle needs its
// own iteration to avoid an unrelated E2E flake in
// `workflow-agent-profile.spec.ts` caused by additional UI shifting the
// Radix select dropdown into a sibling tooltip's hover path. The workflow
// import/export YAML also needs to be extended to serialize this flag in
// the follow-up so the toggle setting round-trips through export.