forked from farhoodlabs/paperclip
Add accepted-plan decomposition exact-once guards and UI state (#6831)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies, so planning approvals and child-issue fan-out are part of the core control-plane loop. > - Accepted plans are supposed to be a safe bridge from planning into execution, especially when agents wake from review decisions and reuse isolated workspaces. > - The duplicate-subtask incident showed that an accepted plan revision could be interpreted more than once across overlapping runs, which broke the single-source-of-truth model for issue decomposition. > - Fixing that required tightening the backend contract first: accepted-plan decomposition needs an exact-once fingerprint, durable claim state, and retry-safe child creation. > - Once that backend behavior existed, the board still needed visibility into what happened, so the issue detail view needed a dedicated decomposition section instead of forcing operators to reconstruct child creation from raw activity. > - This pull request adds the exact-once decomposition primitive, hardens wake routing and regressions around the incident, and surfaces decomposition state in the UI so future incidents are both prevented and easier to inspect. ## What Changed - Added accepted-plan decomposition semantics to `doc/execution-semantics.md`, including the exact-once fingerprint, durable claim/result expectations, and retry/resume behavior. - Added persistent accepted-plan decomposition claims in the backend, including schema, shared types/validators, service logic, and issue routes for creating and listing decomposition state. - Hardened heartbeat routing so an accepted-plan continuation stays scoped to the relevant planning issue instead of opportunistically re-decomposing another accepted issue on the same assignee. - Added regression coverage for the original failure modes: concurrent same-parent retries, cross-issue accepted-plan isolation, and partial child recreation under the same fingerprint. - Added the `Plan decomposition` issue-detail section plus supporting API/query-key/activity formatting updates so operators can see revision status, owner, child counts, and the linked child issues directly in the UI. - Included the small follow-up UI fix so the decomposition section still renders when the issue work mode is no longer `planning`. ## Verification - `pnpm --filter @paperclipai/server typecheck` - `pnpm --filter @paperclipai/ui typecheck` - `pnpm --filter @paperclipai/db typecheck` - `pnpm exec vitest run server/src/__tests__/issues-service.test.ts` - `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t "lists persisted decompositions with child issue summaries"` - `pnpm exec vitest run server/src/__tests__/issues-service.test.ts -t "accepted plan decomposition" server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts server/src/__tests__/heartbeat-context-summary.test.ts` - Manual UI path: create a planning issue without an isolated execution workspace, add a `plan` document, accept the `request_confirmation`, let Paperclip create child issues, then reopen the parent issue detail page and confirm the `Plan decomposition` section shows the accepted revision, status, idempotent-claim badge, and child links. - Separate follow-up bug noted during manual UI validation: accepting a plan on an issue whose run never records `workspace_finalize` is tracked in `PAPA-445` and is not part of this PR’s fix scope. ## Risks - This adds a new migration and a large Drizzle snapshot update; reviewers should confirm the schema shape and generated metadata match the intended decomposition table. - The exact-once claim changes sit on the accepted-plan fan-out path, so regressions there could block legitimate child creation or mis-handle retries if the claim state machine is wrong. - The new UI only appears when decomposition records exist; reviewers should use the manual verification path above rather than expecting existing issues on a stale local instance to show the section automatically. - `PAPA-445` remains an open follow-up for the `workspace_finalize` accept gate when a planning handoff never records finalize; that bug can interfere with reproducing the UI flow on isolated workspaces but does not change the correctness of the exact-once decomposition feature itself. > Checked `ROADMAP.md`: this PR is a bug fix / control-plane hardening change for accepted-plan decomposition, not a new uncoordinated roadmap feature. ## Model Used - OpenAI Codex via Paperclip `codex_local` (GPT-5-based coding agent; exact backend model ID/context window not exposed in the run context), with repository tool use, shell execution, and code-editing capabilities. <img width="806" height="1069" alt="Screenshot 2026-05-27 at 11 05 48 PM" src="https://github.com/user-attachments/assets/5b00b670-96cd-4470-b0a3-581743bcae28" /> ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Devin Foley
@@ -0,0 +1,160 @@
|
||||
import { useMemo } from "react";
|
||||
import { useQuery } from "@tanstack/react-query";
|
||||
import type { Agent, AcceptedPlanDecompositionSummary } from "@paperclipai/shared";
|
||||
import { ChevronRight, GitBranch, Repeat, CheckCircle2, Loader2 } from "lucide-react";
|
||||
import { Link } from "@/lib/router";
|
||||
import { issuesApi } from "../api/issues";
|
||||
import { queryKeys } from "../lib/queryKeys";
|
||||
import { cn, formatDateTime, relativeTime } from "../lib/utils";
|
||||
|
||||
interface IssuePlanDecompositionsSectionProps {
|
||||
issueId: string;
|
||||
issueIdentifier: string | null;
|
||||
agentMap?: Map<string, Agent>;
|
||||
}
|
||||
|
||||
function StatusBadge({ status }: { status: AcceptedPlanDecompositionSummary["status"] }) {
|
||||
if (status === "completed") {
|
||||
return (
|
||||
<span className="inline-flex items-center gap-1 rounded-sm border border-emerald-500/50 bg-emerald-500/10 px-2 py-0.5 text-[11px] font-medium text-emerald-900 dark:text-emerald-100">
|
||||
<CheckCircle2 className="h-3 w-3" />
|
||||
Completed
|
||||
</span>
|
||||
);
|
||||
}
|
||||
return (
|
||||
<span className="inline-flex items-center gap-1 rounded-sm border border-amber-500/50 bg-amber-500/10 px-2 py-0.5 text-[11px] font-medium text-amber-900 dark:text-amber-100">
|
||||
<Loader2 className="h-3 w-3 animate-spin" />
|
||||
In flight
|
||||
</span>
|
||||
);
|
||||
}
|
||||
|
||||
export function IssuePlanDecompositionsSection({
|
||||
issueId,
|
||||
issueIdentifier,
|
||||
agentMap,
|
||||
}: IssuePlanDecompositionsSectionProps) {
|
||||
const { data: decompositions } = useQuery({
|
||||
queryKey: queryKeys.issues.acceptedPlanDecompositions(issueId),
|
||||
queryFn: () => issuesApi.listAcceptedPlanDecompositions(issueId),
|
||||
});
|
||||
|
||||
const items = useMemo(() => decompositions ?? [], [decompositions]);
|
||||
if (items.length === 0) return null;
|
||||
|
||||
return (
|
||||
<div className="space-y-3">
|
||||
<div className="flex items-center justify-between gap-2">
|
||||
<h3 className="text-sm font-medium text-muted-foreground">Plan decomposition</h3>
|
||||
<span className="text-[11px] text-muted-foreground/80">
|
||||
{items.length === 1 ? "1 accepted plan revision" : `${items.length} accepted plan revisions`}
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<ul className="space-y-3">
|
||||
{items.map((record) => {
|
||||
const requested = record.requestedChildCount ?? 0;
|
||||
const created = record.childIssueIds?.length ?? 0;
|
||||
const ownerName = record.ownerAgentId
|
||||
? agentMap?.get(record.ownerAgentId)?.name ?? "agent"
|
||||
: null;
|
||||
const revisionLabel =
|
||||
record.acceptedPlanRevisionNumber != null
|
||||
? `revision ${record.acceptedPlanRevisionNumber}`
|
||||
: `revision ${record.acceptedPlanRevisionId.slice(0, 8)}`;
|
||||
const completedAt =
|
||||
record.completedAt && typeof record.completedAt === "string"
|
||||
? record.completedAt
|
||||
: record.completedAt instanceof Date
|
||||
? record.completedAt.toISOString()
|
||||
: null;
|
||||
const updatedAt =
|
||||
typeof record.updatedAt === "string"
|
||||
? record.updatedAt
|
||||
: record.updatedAt instanceof Date
|
||||
? record.updatedAt.toISOString()
|
||||
: null;
|
||||
const startedAt =
|
||||
typeof record.createdAt === "string"
|
||||
? record.createdAt
|
||||
: record.createdAt instanceof Date
|
||||
? record.createdAt.toISOString()
|
||||
: null;
|
||||
|
||||
return (
|
||||
<li
|
||||
key={record.id}
|
||||
className="rounded-md border border-border bg-card/50 p-3 text-sm"
|
||||
>
|
||||
<div className="flex flex-wrap items-center gap-2">
|
||||
<StatusBadge status={record.status} />
|
||||
<span className="text-xs text-muted-foreground">
|
||||
Plan {revisionLabel}
|
||||
</span>
|
||||
<span className="text-xs text-muted-foreground/70">·</span>
|
||||
<span className="inline-flex items-center gap-1 text-xs text-foreground">
|
||||
<GitBranch className="h-3 w-3 text-muted-foreground" />
|
||||
{created} of {requested} child {requested === 1 ? "issue" : "issues"} created
|
||||
</span>
|
||||
{record.status === "completed" && requested > 0 ? (
|
||||
<span
|
||||
className="inline-flex items-center gap-1 rounded-sm border border-sky-500/40 bg-sky-500/10 px-1.5 py-0.5 text-[10px] font-medium text-sky-900 dark:text-sky-100"
|
||||
title="Repeat attempts with this fingerprint reuse this record instead of creating new children"
|
||||
>
|
||||
<Repeat className="h-3 w-3" />
|
||||
Idempotent claim
|
||||
</span>
|
||||
) : null}
|
||||
</div>
|
||||
|
||||
<div className="mt-1 flex flex-wrap gap-x-3 gap-y-0.5 text-[11px] text-muted-foreground">
|
||||
{ownerName ? <span>Owner: {ownerName}</span> : null}
|
||||
{startedAt ? (
|
||||
<span title={formatDateTime(startedAt)}>Started {relativeTime(startedAt)}</span>
|
||||
) : null}
|
||||
{completedAt ? (
|
||||
<span title={formatDateTime(completedAt)}>Completed {relativeTime(completedAt)}</span>
|
||||
) : updatedAt ? (
|
||||
<span title={formatDateTime(updatedAt)}>Updated {relativeTime(updatedAt)}</span>
|
||||
) : null}
|
||||
{issueIdentifier ? (
|
||||
<Link
|
||||
to={`/issues/${issueIdentifier}#document-plan`}
|
||||
className="underline-offset-2 hover:underline"
|
||||
>
|
||||
Plan document
|
||||
</Link>
|
||||
) : null}
|
||||
</div>
|
||||
|
||||
{record.childIssues && record.childIssues.length > 0 ? (
|
||||
<ul className="mt-2 flex flex-wrap gap-1.5">
|
||||
{record.childIssues.map((child) => (
|
||||
<li key={child.id}>
|
||||
<Link
|
||||
to={`/issues/${child.identifier ?? child.id}`}
|
||||
className={cn(
|
||||
"inline-flex max-w-full items-center gap-1 rounded-sm border border-border bg-background px-2 py-0.5 text-[11px] text-foreground transition-colors hover:bg-accent/40",
|
||||
)}
|
||||
title={child.title}
|
||||
>
|
||||
<span className="font-medium">
|
||||
{child.identifier ?? child.id.slice(0, 8)}
|
||||
</span>
|
||||
<span className="truncate max-w-[24ch] text-muted-foreground">
|
||||
{child.title}
|
||||
</span>
|
||||
<ChevronRight className="h-3 w-3 text-muted-foreground" />
|
||||
</Link>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
) : null}
|
||||
</li>
|
||||
);
|
||||
})}
|
||||
</ul>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user