mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-29 12:59:13 +01:00
feat(decisions): add desk workflow and retention (#10672)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Decisions desk shows work that needs a human decision > - The queue foundation can group and rank decision work > - Operators also need a focused daily view and a safe way to handle old work > - This pull request adds the desk controls, the aging shelf, and reversible retention > - It also binds bulk archive decisions to the exact reviewed item set > - The benefit is a smaller daily queue without lost or orphaned work ## Linked Issues or Issue Description **Subsystem affected** Cross-cutting: server, UI, database, and shared contracts. **Problem or motivation** Decision work can grow into one large company list. Operators need quick queue and date controls. Old items also need a safe retention path that does not delete work. **Proposed solution** Add queue and date controls to the Decisions desk. Compute the aging shelf on the server. Archive idle items after 90 days unless an operator keeps them. Keep archived items searchable and revivable. Notify origin agents in one batch per sweep. Bind bulk archive proposals to a signed, exact item manifest. **Alternatives considered** Client-only aging can drift across browsers and source kinds. Deleting old rows removes audit and recovery paths. An unsigned dynamic bulk query can archive items that the reviewer did not inspect. **Roadmap alignment** This work supports the Work Queues and decision-memory directions in `ROADMAP.md`. It extends the Decisions and attention-feed foundation from #10651. Related earlier work includes #9380, #10010, and #10474. ## What Changed - Added the queue rail, date chips, decide split, triage strip, queue page, and aging shelf UI. - Added server-owned shelf state with per-queue retention overrides. - Added reversible retention state, archive history, and an idempotent notification outbox. - Added the 90-day archive sweeper, Keep exemption, archived feed query, and revive actions. - Added one origin-agent notification per agent and sweep. - Added signed bulk archive proposals with exact-set and version checks. - Persisted queue-exclusion reasons atomically and kept cross-domain source resolution per-item until it has an exact-set transaction contract. - Added API contracts, OpenAPI entries, migration coverage, focused tests, and Storybook screens. ## Verification - `pnpm -r typecheck` - `pnpm test:run` (server: 329 files and 3,453 tests passed; UI: 408 files and 3,362 tests passed) - `env -u AWS_ACCESS_KEY_ID -u AWS_SECRET_ACCESS_KEY pnpm exec vitest run cli/src/__tests__/secrets.test.ts` - `pnpm build` - `pnpm check:token-gates` - Focused retention, attention, decisions, migration replay, startup, and UI API tests. - Complete queue snapshot regression with 51 items across the normal 50-item page boundary. The unmodified CLI test reports one warning assertion in this runtime because the harness injects static AWS credential variables. The isolated test passes when those two variables are removed. ## Risks - The migration adds retention and notification outbox tables. It uses idempotent table, index, and foreign-key creation. - Retention runs on the heartbeat scheduler interval. Compare-and-set version checks prevent stale archive writes. - Bulk archive acceptance fails closed when authority, activity, version, or the reviewed set changes. - Archive is reversible and does not delete source records. > 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 with `gpt-5.6-sol`. The model used tool calls, code execution, database migration generation, and test execution. The context-window size is not exposed in this runtime. ## 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 (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [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 Opus 4.8 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
46 files changed
+41814
-71
No files matched your search
@@ -49,6 +49,11 @@ function buildItem(overrides: Partial<AttentionItem> = {}): AttentionItem {
|
||||
ruleKey: null,
|
||||
originAgentName: null,
|
||||
queues: [],
|
||||
shelf: false,
|
||||
retentionDays: 30,
|
||||
keep: false,
|
||||
archivedAt: null,
|
||||
retentionVersion: 1,
|
||||
decideBy: null,
|
||||
decideByAttribution: null,
|
||||
snoozedUntil: null,
|
||||
|
||||
@@ -263,6 +263,193 @@ export function attentionBadgeCount(feed: AttentionFeed | null | undefined): num
|
||||
return feed?.decideNowCount ?? 0;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Decide-by / today's desk (PAP-16032 §4.3)
|
||||
//
|
||||
// The desk splits items into "Decide now" and "Can wait" and orders them by a
|
||||
// per-item `decideBy` field. The server owns the authoritative ranking
|
||||
// (`sort=decide`) and the badge's `decideNowCount`; these client helpers mirror
|
||||
// that logic *exactly* (same UTC day/week boundaries) so the on-page split and
|
||||
// the badge never disagree. Keep in lockstep with
|
||||
// `server/src/services/attention.ts` (`decideOrder`/`isDecideNow`).
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
const MS_PER_DAY_DECIDE = 24 * 60 * 60 * 1_000;
|
||||
|
||||
function startOfUtcDay(now: number): number {
|
||||
const value = new Date(now);
|
||||
return Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate());
|
||||
}
|
||||
|
||||
function endOfUtcDay(now: number): number {
|
||||
return startOfUtcDay(now) + MS_PER_DAY_DECIDE - 1;
|
||||
}
|
||||
|
||||
function endOfUtcWeek(now: number): number {
|
||||
const start = startOfUtcDay(now);
|
||||
const weekday = new Date(start).getUTCDay();
|
||||
const daysUntilSunday = weekday === 0 ? 0 : 7 - weekday;
|
||||
return start + (daysUntilSunday + 1) * MS_PER_DAY_DECIDE - 1;
|
||||
}
|
||||
|
||||
/** [bucket, deadline] — lower bucket / earlier deadline sorts first. */
|
||||
export function attentionDecideOrder(item: AttentionItem, now: number): [number, number] {
|
||||
if (item.decideBy === "today") return [0, endOfUtcDay(now)];
|
||||
if (item.decideBy === "this_week") return [0, endOfUtcWeek(now)];
|
||||
if (item.decideBy && /^\d{4}-\d{2}-\d{2}$/.test(item.decideBy)) {
|
||||
const deadline = Date.parse(`${item.decideBy}T23:59:59.999Z`);
|
||||
if (Number.isFinite(deadline)) return [0, deadline];
|
||||
}
|
||||
if (item.decideBy === "whenever") return [1, Number.MAX_SAFE_INTEGER];
|
||||
return [2, Number.MAX_SAFE_INTEGER];
|
||||
}
|
||||
|
||||
/** Due today or overdue — the "Decide now" shelf, and what the badge counts. */
|
||||
export function attentionIsDecideNow(item: AttentionItem, now: number): boolean {
|
||||
const [bucket, deadline] = attentionDecideOrder(item, now);
|
||||
return bucket === 0 && deadline <= endOfUtcDay(now);
|
||||
}
|
||||
|
||||
/** Split the desk into its two shelves, preserving input order within each. */
|
||||
export function partitionDecideNow(
|
||||
items: AttentionItem[],
|
||||
now: number,
|
||||
): { decideNow: AttentionItem[]; canWait: AttentionItem[] } {
|
||||
const decideNow: AttentionItem[] = [];
|
||||
const canWait: AttentionItem[] = [];
|
||||
for (const item of items) {
|
||||
if (attentionIsDecideNow(item, now)) decideNow.push(item);
|
||||
else canWait.push(item);
|
||||
}
|
||||
return { decideNow, canWait };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Aging shelf (PAP-16032 §4.4) — items idle past the threshold leave the desk.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
/** Default idle threshold before an item drops from the desk to the shelf. */
|
||||
export const ATTENTION_AGING_DAYS = 30;
|
||||
|
||||
/** Milliseconds since the item last saw activity. */
|
||||
export function attentionIdleMs(item: AttentionItem, now: number): number {
|
||||
const ts = new Date(item.activityAt).getTime();
|
||||
return Number.isFinite(ts) ? Math.max(0, now - ts) : 0;
|
||||
}
|
||||
|
||||
/** Server-computed shelf membership, including per-queue retention overrides. */
|
||||
export function attentionIsAging(item: AttentionItem): boolean {
|
||||
return item.shelf;
|
||||
}
|
||||
|
||||
/** Idle duration in whole days, for the shelf's "idle N days" label. */
|
||||
export function attentionIdleDays(item: AttentionItem, now: number): number {
|
||||
return Math.floor(attentionIdleMs(item, now) / MS_PER_DAY_DECIDE);
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Decide-by control (triage strip) — the segmented options an operator/agent
|
||||
// picks from. `date` is handled separately by a date input.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type DecideByPreset = "today" | "this_week" | "whenever";
|
||||
|
||||
export const DECIDE_BY_OPTIONS: ReadonlyArray<[DecideByPreset, string]> = [
|
||||
["today", "Today"],
|
||||
["this_week", "This week"],
|
||||
["whenever", "Whenever"],
|
||||
];
|
||||
|
||||
/** Human label for any stored `decideBy` value (preset or `YYYY-MM-DD`). */
|
||||
export function decideByLabel(decideBy: string | null): string {
|
||||
if (!decideBy) return "Not set";
|
||||
if (decideBy === "today") return "Today";
|
||||
if (decideBy === "this_week") return "This week";
|
||||
if (decideBy === "whenever") return "Whenever";
|
||||
if (/^\d{4}-\d{2}-\d{2}$/.test(decideBy)) {
|
||||
const parsed = new Date(`${decideBy}T00:00:00.000Z`);
|
||||
return Number.isFinite(parsed.getTime())
|
||||
? parsed.toLocaleDateString(undefined, { month: "short", day: "numeric", timeZone: "UTC" })
|
||||
: decideBy;
|
||||
}
|
||||
return decideBy;
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Date-range chips (PAP-16032 §4.2) — resolve to server-side activity bounds.
|
||||
// The desk filters `activityAt` server-side (activitySince/Until) rather than
|
||||
// shipping the whole feed and filtering on the client.
|
||||
// ---------------------------------------------------------------------------
|
||||
|
||||
export type AttentionDateRangeId = "all" | "today" | "yesterday" | "last_7_days" | "this_month" | "custom";
|
||||
|
||||
export const ATTENTION_DATE_RANGE_OPTIONS: ReadonlyArray<[AttentionDateRangeId, string]> = [
|
||||
["all", "All"],
|
||||
["today", "Today"],
|
||||
["yesterday", "Yesterday"],
|
||||
["last_7_days", "Last 7 days"],
|
||||
["this_month", "This month"],
|
||||
];
|
||||
|
||||
export interface AttentionActivityBounds {
|
||||
activitySince?: string;
|
||||
activityUntil?: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve a range chip to `{activitySince, activityUntil}` ISO bounds. Uses
|
||||
* local calendar boundaries (what the operator means by "today"); `custom`
|
||||
* takes the caller's explicit from/to dates.
|
||||
*/
|
||||
export function resolveAttentionDateRange(
|
||||
range: AttentionDateRangeId,
|
||||
now: number,
|
||||
custom?: { from?: string | null; to?: string | null },
|
||||
): AttentionActivityBounds {
|
||||
const startOfLocalDay = (ms: number) => {
|
||||
const d = new Date(ms);
|
||||
d.setHours(0, 0, 0, 0);
|
||||
return d;
|
||||
};
|
||||
const endOfLocalDay = (ms: number) => {
|
||||
const d = new Date(ms);
|
||||
d.setHours(23, 59, 59, 999);
|
||||
return d;
|
||||
};
|
||||
switch (range) {
|
||||
case "all":
|
||||
return {};
|
||||
case "today":
|
||||
return { activitySince: startOfLocalDay(now).toISOString() };
|
||||
case "yesterday": {
|
||||
const start = startOfLocalDay(now - MS_PER_DAY_DECIDE);
|
||||
const end = endOfLocalDay(now - MS_PER_DAY_DECIDE);
|
||||
return { activitySince: start.toISOString(), activityUntil: end.toISOString() };
|
||||
}
|
||||
case "last_7_days":
|
||||
return { activitySince: startOfLocalDay(now - 6 * MS_PER_DAY_DECIDE).toISOString() };
|
||||
case "this_month": {
|
||||
const d = new Date(now);
|
||||
const start = new Date(d.getFullYear(), d.getMonth(), 1, 0, 0, 0, 0);
|
||||
return { activitySince: start.toISOString() };
|
||||
}
|
||||
case "custom": {
|
||||
const bounds: AttentionActivityBounds = {};
|
||||
if (custom?.from) {
|
||||
const from = new Date(`${custom.from}T00:00:00`);
|
||||
if (Number.isFinite(from.getTime())) bounds.activitySince = from.toISOString();
|
||||
}
|
||||
if (custom?.to) {
|
||||
const to = new Date(`${custom.to}T23:59:59.999`);
|
||||
if (Number.isFinite(to.getTime())) bounds.activityUntil = to.toISOString();
|
||||
}
|
||||
return bounds;
|
||||
}
|
||||
default:
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// Grouping / sorting / filtering (PAP-13408 — Inbox-style toolbar)
|
||||
//
|
||||
|
||||
@@ -395,6 +395,13 @@ export const queryKeys = {
|
||||
forTargetIssue: (companyId: string, issueId: string) =>
|
||||
["decisions", companyId, "target", issueId] as const,
|
||||
},
|
||||
decisionQueues: {
|
||||
list: (companyId: string) => ["decision-queues", companyId] as const,
|
||||
items: (companyId: string, key: string) => ["decision-queues", companyId, "items", key] as const,
|
||||
seedRules: (companyId: string) => ["decision-queues", companyId, "seed-rules"] as const,
|
||||
triage: (companyId: string, sourceKind: string, sourceId: string) =>
|
||||
["decision-triage", companyId, sourceKind, sourceId] as const,
|
||||
},
|
||||
workTimeline: (companyId: string, lens?: string) => ["work-timeline", companyId, lens ?? "all"] as const,
|
||||
userProfile: (companyId: string, userSlug: string) =>
|
||||
["user-profile", companyId, userSlug] as const,
|
||||
|
||||
Reference in new issue
Block a user