mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-24 18:19:05 +02:00
## Thinking Path > - Paperclip is the open source control plane people use to manage AI-agent companies. > - Operators need a board-level way to monitor a changing slice of company work without repeatedly rebuilding filters or reading raw task threads. > - Existing summaries are useful snapshots, but they do not provide a dedicated query-backed card with refresh policy, change tracking, update history, and per-update cost visibility. > - The capability needs to be safe to evaluate before it becomes part of the default product surface. > - This pull request adds end-to-end experimental Status Cards, from schema and query compilation through update orchestration and operator UI. > - The entire feature is gated behind the `enableStatusCards` experimental toggle, including its route and sidebar entry. > - The benefit is a governed, inspectable way to keep focused operational rollups current while preserving explicit controls over refresh frequency and spend. ## Linked Issues or Issue Description ### Subsystem affected Cross-cutting (`packages/db`, `packages/shared`, `server/`, `ui/`, and bundled skills/docs). ### Problem or motivation Operators cannot currently define a reusable natural-language view of company work, compile it into an inspectable query, and keep its summary current as matching issues change. Rebuilding filters and rereading task threads makes board-level monitoring repetitive and hides the relationship between source changes, refresh cost, and the resulting summary. ### Proposed solution Add experimental Status Cards that compile operator intent into a query, summarize matched work, record each update, expose manual/interval/reactive refresh policies and costs, and preserve the last good result across stale, updating, paused, and error states. The capability is off by default and fully gated behind `enableStatusCards`, including its route and navigation entry. ### Alternatives considered - Extend existing one-off summaries: rejected because status cards require persistent query provenance, refresh policy, update history, and card-specific cost controls. - Add a dashboard-only filter widget: rejected because it would not provide governed background refresh, an update ledger, or an inspectable compile pipeline. - Ship the surface by default: rejected in favor of an experimental toggle while behavior and operator value are evaluated. ### Roadmap alignment This advances Paperclip’s board-level execution visibility and output-first product goals. `ROADMAP.md` was checked and no duplicate status-card initiative was found. ### Additional context No related open PR was found in the public GitHub search for status cards. The PR-only design wireframes were removed from the repository after review; the published prototype remains external to the production source tree. ## What Changed - Added company-scoped status-card schema, CRUD APIs, compile provenance, update ledger, shared contracts, validators, and OpenAPI coverage. - Added the text-to-query compile pipeline, bundled `status-card-query` agent skill, query versioning, and authorized write-back flow. - Added the experimental board, create flow, lifecycle tiles, detail/settings/debug drawers, archived view, routing, navigation, and instance setting. - Added a change-gated update engine with manual, interval, and reactive refresh policies, trigger selection, active hours, and daily token caps. - Added per-update token/cost recording, today and lifetime rollups, and policy-derived cost previews. - Added operator documentation and agent-authoring hardening for compile and update behavior. - Added PR-prep integration coverage for settings/startup wiring and replaced raw UI values with design-system tokens. - Removed the PR-only `design/pap-15023-status-cards` wireframe artifacts so the repository contains only production feature assets. ## Verification - `pnpm -r typecheck` — passes on the PR head; includes `ui` `tsc -b` passing. The UI compile gate was also independently recorded as passing at `6d7f3cf96b` on July 23, 2026. - `pnpm build` — passes. - `pnpm check:token-gates` — passes with all three gates clean. - `pnpm test:run` — 2,880 tests passed and 1 skipped; the sole failure was an unrelated 10-second `afterAll` database-cleanup timeout in `execution-workspaces-service.test.ts`. - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/execution-workspaces-service.test.ts` — passes on immediate focused rerun (25/25). - `pnpm --filter @paperclipai/server exec vitest run src/__tests__/instance-settings-service.test.ts src/__tests__/server-startup-feedback-export.test.ts` — passes (31/31). - `pnpm --filter @paperclipai/ui exec vitest run src/pages/StatusCards/StatusCardSettingsForm.test.tsx src/pages/StatusCards/StatusCardTile.test.tsx src/pages/StatusCards/format.test.ts src/lib/status-card-state.test.ts` — passes (26/26). - Recorded pre-PR QA: compile-pipeline e2e PASS; full lifecycle and cost QA PASS; security re-review PASS after write-back hardening; UX approved. - `pnpm exec vitest run packages/db/src/status-card-migrations.test.ts` — passes; reapplies migrations `0185`–`0189` against an already-migrated embedded Postgres database. - `pnpm --filter /db check:migrations` — passes migration numbering and safety checks. - `pnpm --filter /db typecheck` — passes. - Merged current `origin/master` on July 24, 2026 with no conflicts; migrations `0185`–`0189` remain unclaimed on master. ## Risks - The feature introduces five database migrations and a new background update path; all new DDL is repeat-safe after partial application, migration numbering/safety checks pass, and update execution is company-scoped and change-gated. - Natural-language compilation can produce invalid or overly broad queries; compile provenance, query validation, debug visibility, and version history make failures inspectable and recoverable. - Reactive or interval refresh could increase spend; active hours, max refresh frequency, daily token caps, per-update cost records, and budget-paused states bound and expose that risk. - The branch name contains an internal execution identifier because it is a fixed handoff branch; it was intentionally not renamed or rebased per the release handoff instructions. - Overall rollout risk is limited because the route, navigation, services, and UI are disabled by default behind `enableStatusCards`. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex using GPT-5.5 with reasoning, repository tool use, shell execution, GitHub CLI, and test/build execution. The runtime did not expose a context-window size. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change; the fixed execution-workspace identifier is documented as an authorized handoff exception - [x] I have run tests locally and they pass, with the one cleanup timeout passing on focused rerun - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
304 lines
13 KiB
TypeScript
304 lines
13 KiB
TypeScript
import { useMemo, type MouseEvent } from "react";
|
||
import { Link } from "react-router-dom";
|
||
import type { SummarySlotIssueRef } from "@paperclipai/shared";
|
||
import { AlertTriangle, ExternalLink, Loader2, MoreHorizontal, PauseCircle, RefreshCw, Wand2 } from "lucide-react";
|
||
|
||
import { MarkdownBody } from "@/components/MarkdownBody";
|
||
import { useSummaryDraftStream } from "@/components/useSummaryDraftStream";
|
||
import { Button } from "@/components/ui/button";
|
||
import {
|
||
DropdownMenu,
|
||
DropdownMenuContent,
|
||
DropdownMenuItem,
|
||
DropdownMenuSeparator,
|
||
DropdownMenuTrigger,
|
||
} from "@/components/ui/dropdown-menu";
|
||
import { createIssueDetailPath } from "@/lib/issueDetailBreadcrumb";
|
||
import { cn, relativeTime } from "@/lib/utils";
|
||
import {
|
||
deriveStatusCardLifecycle,
|
||
describeRefreshPolicy,
|
||
STATUS_CARD_LIFECYCLE_PRESENTATION,
|
||
} from "@/lib/status-card-state";
|
||
import { formatCents, formatTokens } from "./format";
|
||
import type { StatusCardView } from "./types";
|
||
|
||
export interface StatusCardTileProps {
|
||
card: StatusCardView;
|
||
companyId: string | null | undefined;
|
||
onOpen: () => void;
|
||
onRefresh: () => void;
|
||
onRecompile: () => void;
|
||
onEditInterest: () => void;
|
||
onOpenDebug: () => void;
|
||
onArchive: () => void;
|
||
refreshPending?: boolean;
|
||
recompilePending?: boolean;
|
||
}
|
||
|
||
function StateDot({ className }: { className: string }) {
|
||
return <span className={cn("mt-1 inline-block h-2.5 w-2.5 shrink-0 rounded-full", className)} aria-hidden="true" />;
|
||
}
|
||
|
||
/** Stop a nested control's click from also triggering the card-open handler. */
|
||
function stopClick(handler: () => void) {
|
||
return (event: MouseEvent) => {
|
||
event.stopPropagation();
|
||
handler();
|
||
};
|
||
}
|
||
|
||
export function StatusCardTile({
|
||
card,
|
||
companyId,
|
||
onOpen,
|
||
onRefresh,
|
||
onRecompile,
|
||
onEditInterest,
|
||
onOpenDebug,
|
||
onArchive,
|
||
refreshPending,
|
||
recompilePending,
|
||
}: StatusCardTileProps) {
|
||
const lifecycle = deriveStatusCardLifecycle(card);
|
||
const presentation = STATUS_CARD_LIFECYCLE_PRESENTATION[lifecycle];
|
||
// A setup run is actually in flight when the card is compiling AND has a
|
||
// generation task. When it's null the first run stalled/died and the card
|
||
// needs a manual re-kick — the only case where "Run now" is offered.
|
||
const setupRunning = lifecycle === "compiling" && Boolean(card.generatingIssueId);
|
||
|
||
// Stream the in-flight update into the delta banner (reuses the Summarizer
|
||
// draft-stream machinery). Inert unless the card is actively updating.
|
||
const generatingIssue = useMemo<SummarySlotIssueRef | null>(
|
||
() =>
|
||
lifecycle === "updating" && card.generatingIssueId
|
||
? { id: card.generatingIssueId, identifier: null, title: card.title ?? "Status update", status: "in_progress" }
|
||
: null,
|
||
[lifecycle, card.generatingIssueId, card.title],
|
||
);
|
||
const draftStream = useSummaryDraftStream(companyId, generatingIssue);
|
||
|
||
const policyLabel = describeRefreshPolicy(card.refreshPolicy);
|
||
const tokensLabel = formatTokens(card.todayTokens);
|
||
const costLabel = formatCents(card.todayCostCents);
|
||
const freshnessLabel = card.lastGeneratedAt ? relativeTime(card.lastGeneratedAt) : "no summary yet";
|
||
const hasSummary = Boolean(card.summaryBody && card.summaryBody.trim().length > 0);
|
||
|
||
return (
|
||
<div
|
||
role="button"
|
||
tabIndex={0}
|
||
onClick={onOpen}
|
||
onKeyDown={(event) => {
|
||
if (event.target === event.currentTarget && (event.key === "Enter" || event.key === " ")) {
|
||
event.preventDefault();
|
||
onOpen();
|
||
}
|
||
}}
|
||
className={cn(
|
||
"group flex h-72 cursor-pointer flex-col rounded-lg border border-border bg-card text-card-foreground transition-colors hover:border-muted-foreground/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
|
||
presentation.dashedBorder && "border-dashed",
|
||
)}
|
||
data-testid="status-card-tile"
|
||
data-lifecycle={lifecycle}
|
||
>
|
||
{/* Header */}
|
||
<div className="flex items-start gap-2 px-4 pt-4">
|
||
{lifecycle === "compiling" ? null : <StateDot className={presentation.dotClassName} />}
|
||
<span
|
||
className={cn(
|
||
"line-clamp-1 min-w-0 flex-1 text-sm font-semibold",
|
||
lifecycle === "compiling" && "text-muted-foreground",
|
||
)}
|
||
title={card.title ?? card.interestPrompt}
|
||
>
|
||
{card.title ?? "New card"}
|
||
</span>
|
||
<div onClick={(event) => event.stopPropagation()}>
|
||
<DropdownMenu>
|
||
<DropdownMenuTrigger asChild>
|
||
<Button variant="ghost" size="icon" className="-mr-1 -mt-1 h-7 w-7 text-muted-foreground" aria-label="Card actions">
|
||
<MoreHorizontal className="h-4 w-4" />
|
||
</Button>
|
||
</DropdownMenuTrigger>
|
||
<DropdownMenuContent align="end">
|
||
<DropdownMenuItem onSelect={onOpen}>Open detail</DropdownMenuItem>
|
||
<DropdownMenuItem onSelect={onRefresh} disabled={refreshPending || lifecycle === "updating"}>
|
||
Refresh now
|
||
</DropdownMenuItem>
|
||
{(lifecycle === "compiling" && !setupRunning) || lifecycle === "error" ? (
|
||
<DropdownMenuItem onSelect={onRecompile} disabled={recompilePending}>
|
||
Run now
|
||
</DropdownMenuItem>
|
||
) : null}
|
||
<DropdownMenuItem onSelect={onEditInterest}>Edit interest & settings</DropdownMenuItem>
|
||
<DropdownMenuItem onSelect={onOpenDebug}>Query debug</DropdownMenuItem>
|
||
<DropdownMenuSeparator />
|
||
<DropdownMenuItem onSelect={onArchive} variant="destructive">
|
||
Archive
|
||
</DropdownMenuItem>
|
||
</DropdownMenuContent>
|
||
</DropdownMenu>
|
||
</div>
|
||
</div>
|
||
|
||
{/* State banner */}
|
||
<div className="px-4 pt-2">
|
||
{lifecycle === "compiling" ? (
|
||
<div className="rounded-md bg-muted px-3 py-2 text-xs text-foreground" role="status" aria-live="polite">
|
||
<div className="flex items-center gap-2">
|
||
{setupRunning ? (
|
||
// A live spinner (not a fading pulse) so the in-flight setup
|
||
// reads as actual progress.
|
||
<Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin text-muted-foreground" />
|
||
) : (
|
||
<AlertTriangle className="h-3.5 w-3.5 shrink-0 text-amber-500" />
|
||
)}
|
||
<span>{setupRunning ? "Setting up your card…" : "Setup didn’t finish"}</span>
|
||
</div>
|
||
<p className="mt-1 line-clamp-2 text-muted-foreground">“{card.interestPrompt}”</p>
|
||
{setupRunning ? (
|
||
// The setup run is live — link to the task instead of offering
|
||
// "Run now", which would kick a duplicate run and race it.
|
||
<Link
|
||
to={`/issues/${card.generatingIssueId}`}
|
||
onClick={(event) => event.stopPropagation()}
|
||
className="mt-2 inline-flex items-center gap-1.5 font-medium text-foreground underline-offset-2 hover:underline"
|
||
>
|
||
<ExternalLink className="h-3.5 w-3.5" />
|
||
View setup task
|
||
</Link>
|
||
) : (
|
||
// The first run stalled (agent run died mid-setup) and the card
|
||
// can sit here forever, so offer a manual re-kick.
|
||
<button
|
||
type="button"
|
||
onClick={stopClick(onRecompile)}
|
||
disabled={recompilePending}
|
||
className="mt-2 inline-flex items-center gap-1.5 font-medium text-foreground underline-offset-2 hover:underline disabled:opacity-60"
|
||
>
|
||
<Wand2 className={cn("h-3.5 w-3.5", recompilePending && "animate-pulse")} />
|
||
{recompilePending ? "Starting…" : "Run now"}
|
||
</button>
|
||
)}
|
||
</div>
|
||
) : null}
|
||
|
||
{lifecycle === "updating" ? (
|
||
<div className="rounded-md bg-muted px-3 py-2 text-xs text-foreground" role="status" aria-live="polite">
|
||
<div className="flex items-center gap-2">
|
||
<Loader2 className="h-3.5 w-3.5 shrink-0 animate-spin text-muted-foreground" />
|
||
<span className="min-w-0 flex-1 truncate" title={draftStream.statusLine ?? undefined}>
|
||
{draftStream.statusLine
|
||
?? (card.pendingChangeCount > 0
|
||
? `Integrating ${card.pendingChangeCount} ${card.pendingChangeCount === 1 ? "change" : "changes"}…`
|
||
: "Updating now…")}
|
||
</span>
|
||
{card.generatingIssueId ? (
|
||
<Link
|
||
to={createIssueDetailPath(card.generatingIssueId)}
|
||
onClick={(event) => event.stopPropagation()}
|
||
className="inline-flex shrink-0 items-center gap-1 font-medium underline-offset-2 hover:underline"
|
||
>
|
||
<ExternalLink className="h-3.5 w-3.5" />
|
||
View update task
|
||
</Link>
|
||
) : null}
|
||
</div>
|
||
</div>
|
||
) : null}
|
||
|
||
{lifecycle === "stale" ? (
|
||
<button
|
||
type="button"
|
||
onClick={stopClick(onRefresh)}
|
||
disabled={refreshPending}
|
||
className="flex w-full items-center justify-between gap-2 rounded-md border border-amber-500/40 bg-amber-500/5 px-3 py-1.5 text-left text-xs text-foreground transition-colors hover:bg-amber-500/10 disabled:opacity-60"
|
||
>
|
||
<span>
|
||
{card.pendingChangeCount} {card.pendingChangeCount === 1 ? "change" : "changes"} since last update
|
||
</span>
|
||
<span className="shrink-0 font-medium text-amber-700 dark:text-amber-400">Refresh</span>
|
||
</button>
|
||
) : null}
|
||
|
||
{lifecycle === "error" ? (
|
||
<div className="flex items-center justify-between gap-2 rounded-md border border-destructive/40 bg-destructive/5 px-3 py-1.5 text-xs">
|
||
<span className="flex items-center gap-1.5 text-destructive">
|
||
<AlertTriangle className="h-3.5 w-3.5 shrink-0" />
|
||
Last update failed
|
||
</span>
|
||
<span className="flex shrink-0 items-center gap-3">
|
||
<button type="button" onClick={stopClick(onRefresh)} disabled={refreshPending} className="font-medium text-destructive hover:underline disabled:opacity-60">
|
||
Retry
|
||
</button>
|
||
<button type="button" onClick={stopClick(onOpen)} className="text-muted-foreground hover:underline">
|
||
Details
|
||
</button>
|
||
</span>
|
||
</div>
|
||
) : null}
|
||
|
||
{lifecycle === "paused_budget" || lifecycle === "paused_hours" ? (
|
||
<div className="flex items-center gap-2 rounded-md border border-orange-500/40 bg-orange-500/5 px-3 py-1.5 text-xs text-foreground">
|
||
<PauseCircle className="h-3.5 w-3.5 shrink-0 text-orange-500" />
|
||
<span>
|
||
{lifecycle === "paused_budget"
|
||
? "Daily token cap reached — auto-updates paused"
|
||
: "Outside active hours — auto-updates paused"}
|
||
</span>
|
||
</div>
|
||
) : null}
|
||
</div>
|
||
|
||
{/* Summary body — kept visible for stale/error/updating/paused (never blank) */}
|
||
<div className="min-h-0 flex-1 overflow-hidden px-4 pt-2">
|
||
{lifecycle === "error" && card.summaryBody ? (
|
||
<p className="mb-1 text-(length:--text-micro) text-muted-foreground">Showing last good summary:</p>
|
||
) : null}
|
||
{hasSummary ? (
|
||
<MarkdownBody className="text-xs leading-6 text-foreground [&_p]:my-0.5">{card.summaryBody!}</MarkdownBody>
|
||
) : lifecycle === "compiling" ? (
|
||
<p className="text-xs text-muted-foreground">
|
||
You can add instructions and pick an update policy while this runs.
|
||
</p>
|
||
) : lifecycle === "updating" && draftStream.draft ? (
|
||
<MarkdownBody className="text-xs leading-6 text-foreground [&_p]:my-0.5">{draftStream.draft}</MarkdownBody>
|
||
) : (
|
||
<p className="text-xs text-muted-foreground">No summary yet.</p>
|
||
)}
|
||
</div>
|
||
|
||
{/* Footer */}
|
||
<div className="mt-auto flex items-center justify-between gap-2 border-t border-border px-4 py-2.5">
|
||
<span className="truncate text-(length:--text-micro) text-muted-foreground">
|
||
{lifecycle === "compiling" ? (
|
||
"setting up · first summary pending"
|
||
) : (
|
||
<>
|
||
{freshnessLabel} · {policyLabel}
|
||
{tokensLabel ? ` · ${tokensLabel}` : ""}
|
||
{costLabel ? ` · ${costLabel}` : ""}
|
||
</>
|
||
)}
|
||
</span>
|
||
{/* Stale and error tiles already carry an inline Refresh/Retry action in
|
||
their banner, so the footer icon is only shown for states that have
|
||
no other refresh affordance (fresh + both paused states). */}
|
||
{lifecycle === "fresh" || lifecycle === "paused_budget" || lifecycle === "paused_hours" ? (
|
||
<Button
|
||
variant="ghost"
|
||
size="icon"
|
||
className="h-7 w-7 shrink-0 text-muted-foreground"
|
||
onClick={stopClick(onRefresh)}
|
||
disabled={refreshPending}
|
||
aria-label="Refresh card"
|
||
>
|
||
<RefreshCw className={cn("h-3.5 w-3.5", refreshPending && "animate-spin")} />
|
||
</Button>
|
||
) : null}
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|