mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-13 07:12:00 +01: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>
127 lines
4.8 KiB
TypeScript
127 lines
4.8 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import type { StatusCardUpdate } from "@paperclipai/shared";
|
|
|
|
import {
|
|
estimateStatusCardCost,
|
|
rollupUpdates,
|
|
rollupUpdatesToday,
|
|
} from "./format";
|
|
|
|
function update(overrides: Partial<StatusCardUpdate>): StatusCardUpdate {
|
|
return {
|
|
id: "00000000-0000-0000-0000-000000000000",
|
|
cardId: "00000000-0000-0000-0000-000000000001",
|
|
kind: "full",
|
|
trigger: "manual",
|
|
generationIssueId: null,
|
|
runId: null,
|
|
changes: [],
|
|
inputTokens: 1000,
|
|
outputTokens: 500,
|
|
costCents: 2,
|
|
model: null,
|
|
queryVersion: 1,
|
|
changeSummary: null,
|
|
startedAt: new Date().toISOString(),
|
|
finishedAt: null,
|
|
status: "ok",
|
|
error: null,
|
|
...overrides,
|
|
};
|
|
}
|
|
|
|
function iso(daysAgo: number): string {
|
|
const d = new Date();
|
|
d.setDate(d.getDate() - daysAgo);
|
|
// Noon avoids DST/midnight edge cases in the local-day filter.
|
|
d.setHours(12, 0, 0, 0);
|
|
return d.toISOString();
|
|
}
|
|
|
|
describe("rollupUpdates (lifetime)", () => {
|
|
it("sums the whole ledger and excludes compile rows from the update count", () => {
|
|
const rollup = rollupUpdates([
|
|
update({ kind: "full", inputTokens: 3000, outputTokens: 1000, costCents: 3, startedAt: iso(0) }),
|
|
update({ kind: "compile", inputTokens: 500, outputTokens: 100, costCents: 1, startedAt: iso(0) }),
|
|
update({ kind: "incremental", inputTokens: 1000, outputTokens: 200, costCents: 2, startedAt: iso(5) }),
|
|
]);
|
|
// full + incremental = 2 updates (compile excluded from count)
|
|
expect(rollup.updateCount).toBe(2);
|
|
// tokens/cost still include the compile spend
|
|
expect(rollup.totalTokens).toBe(3000 + 1000 + 500 + 100 + 1000 + 200);
|
|
expect(rollup.totalCostCents).toBe(3 + 1 + 2);
|
|
});
|
|
});
|
|
|
|
describe("rollupUpdatesToday", () => {
|
|
it("only counts updates started today and drops older ledger rows", () => {
|
|
const rollup = rollupUpdatesToday([
|
|
update({ kind: "full", inputTokens: 2000, outputTokens: 600, costCents: 3, startedAt: iso(0) }),
|
|
update({ kind: "compile", inputTokens: 400, outputTokens: 100, costCents: 1, startedAt: iso(0) }),
|
|
// yesterday + last week — must not be counted as "today"
|
|
update({ kind: "full", inputTokens: 9999, outputTokens: 9999, costCents: 99, startedAt: iso(1) }),
|
|
update({ kind: "incremental", inputTokens: 9999, outputTokens: 9999, costCents: 99, startedAt: iso(7) }),
|
|
]);
|
|
// Only today's full rebuild counts as an update (compile excluded).
|
|
expect(rollup.updateCount).toBe(1);
|
|
// Today's tokens/cost include today's compile but not older days.
|
|
expect(rollup.totalTokens).toBe(2000 + 600 + 400 + 100);
|
|
expect(rollup.totalCostCents).toBe(3 + 1);
|
|
});
|
|
|
|
it("uses the UTC day boundary used by the server token cap", () => {
|
|
const now = new Date("2026-07-23T01:00:00.000Z");
|
|
const rollup = rollupUpdatesToday([
|
|
update({ startedAt: "2026-07-23T00:30:00.000Z", inputTokens: 200, outputTokens: 50 }),
|
|
update({ startedAt: "2026-07-22T23:30:00.000Z", inputTokens: 900, outputTokens: 100 }),
|
|
], now);
|
|
|
|
expect(rollup.updateCount).toBe(1);
|
|
expect(rollup.totalTokens).toBe(250);
|
|
});
|
|
});
|
|
|
|
describe("estimateStatusCardCost", () => {
|
|
it("manual mode = a single per-refresh rebuild", () => {
|
|
const est = estimateStatusCardCost({ mode: "manual", triggers: {} as never });
|
|
expect(est.primary).toContain("per refresh");
|
|
expect(est.note).toMatch(/only cost/i);
|
|
});
|
|
|
|
it("interval mode scales with the interval and reacts to the daily token cap", () => {
|
|
const uncapped = estimateStatusCardCost({ mode: "interval", intervalMinutes: 60, triggers: {} as never });
|
|
// 24h / 60min = 24 updates/day upper bound
|
|
expect(uncapped.primary).toContain("Up to ~24 updates/day");
|
|
expect(uncapped.primary).toContain("every 60 min");
|
|
|
|
const capped = estimateStatusCardCost({
|
|
mode: "interval",
|
|
intervalMinutes: 60,
|
|
dailyTokenCap: 10_000,
|
|
triggers: {} as never,
|
|
});
|
|
// 10_000 / 2_000 est tokens = 5 updates before the cap bites
|
|
expect(capped.primary).toContain("Up to ~5 updates/day");
|
|
expect(capped.note).toMatch(/daily token cap/i);
|
|
});
|
|
|
|
it("reactive mode reports the per-hour ceiling", () => {
|
|
const est = estimateStatusCardCost({ mode: "reactive", maxUpdatesPerHour: 4, debounceSeconds: 60, triggers: {} as never });
|
|
expect(est.primary).toContain("up to 4/hour");
|
|
// 24h * 4/hr = 96 updates/day upper bound
|
|
expect(est.primary).toContain("Up to ~96 updates/day");
|
|
});
|
|
|
|
it("interval mode honours the active-hours window", () => {
|
|
const est = estimateStatusCardCost({
|
|
mode: "interval",
|
|
intervalMinutes: 60,
|
|
activeHours: { start: "08:00", end: "20:00", timezone: "UTC" },
|
|
triggers: {} as never,
|
|
});
|
|
// 12h window / 60min = 12 updates/day
|
|
expect(est.primary).toContain("Up to ~12 updates/day");
|
|
expect(est.primary).toContain("during active hours");
|
|
});
|
|
});
|