mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-20 20:40:38 +09:00
[codex] Add blocked inbox attention view (#5603)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies through company-scoped issues, comments, approvals, and execution workspaces. > - Operators need the Inbox to show not only active work, but also blocked work that may need human or agent attention. > - The existing inbox experience did not have a dedicated blocked-work surface, so blocked tasks were harder to triage and resume deliberately. > - Backend consumers also needed a compact attention signal that distinguishes actionable blockers from covered or waiting blocker states. > - This pull request adds a Blocked Inbox tab backed by issue blocker-attention metadata, shared validators, and UI helpers. > - The benefit is a clearer triage path for stalled or blocked Paperclip work without exposing external wait internals in the operator-facing UI. ## What Changed - Added shared issue blocker-attention types, validators, and exports for the API/UI contract. - Added backend blocker-attention computation and issue route support for blocked inbox data. - Added the Blocked Inbox tab, blocked reason chips, filtering/search UI, responsive layouts, and Storybook stories. - Updated inbox helpers and page behavior so toolbar controls only appear where they apply. - Added coverage for shared validators, server blocker-attention behavior, blocked inbox UI helpers/components, and the Inbox page. - Added a screenshot helper script for the blocked inbox Storybook stories. - Addressed Greptile feedback by making urgency sorting deterministic for null stop times, avoiding full blocked-inbox list enrichment for counts, and hardening the screenshot helper. ## Verification - Rebased the branch cleanly onto `public-gh/master`. - Confirmed the diff does not include `pnpm-lock.yaml`. - Confirmed the diff does not include database migration files. - Ran `pnpm exec vitest run packages/shared/src/validators/issue.test.ts server/src/__tests__/issue-blocker-attention.test.ts ui/src/components/BlockedInboxView.test.tsx ui/src/components/BlockedReasonChip.test.tsx ui/src/lib/blockedInbox.test.ts ui/src/lib/inbox.test.ts ui/src/pages/Inbox.test.tsx`. - Ran `pnpm --filter @paperclipai/shared typecheck && pnpm --filter @paperclipai/server typecheck && pnpm --filter @paperclipai/ui typecheck`. - Checked `ROADMAP.md`; this is scoped inbox/operator triage work and does not duplicate a listed roadmap feature. - Greptile Review is green on the latest head and all four Greptile review threads are resolved. - GitHub PR checks are green on the latest head: policy, security/snyk, e2e, verify, Canary Dry Run, Greptile Review, and serialized server suites 1/4 through 4/4. ## Risks - Medium review surface because this touches the shared issue contract, server issue services, and the Inbox UI together. - Blocker-attention classification may need product tuning after operators use it on real blocked queues. - UI screenshots were not attached in this PR-opening pass; the branch includes `scripts/screenshot-blocked-inbox.mjs` and Storybook stories for visual capture. > 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, GPT-5-based coding agent with shell, git, GitHub CLI, GitHub connector, and Paperclip API tool use. Reasoning mode: medium. Context window: not exposed by the 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] 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:
Dotta
GitHub
parent
d1a8c873b2
commit
4142559c37
24 changed files with 3737 additions and 115 deletions
303
ui/storybook/stories/blocked-inbox.stories.tsx
Normal file
303
ui/storybook/stories/blocked-inbox.stories.tsx
Normal file
|
|
@ -0,0 +1,303 @@
|
|||
import { useMemo } from "react";
|
||||
import { useQueryClient } from "@tanstack/react-query";
|
||||
import type { Meta, StoryObj } from "@storybook/react-vite";
|
||||
import type { Issue, IssueBlockedInboxAttention } from "@paperclipai/shared";
|
||||
import { BlockedInboxView } from "@/components/BlockedInboxView";
|
||||
import { BlockedReasonChip } from "@/components/BlockedReasonChip";
|
||||
import { defaultIssueFilterState } from "@/lib/issue-filters";
|
||||
import { queryKeys } from "@/lib/queryKeys";
|
||||
import { storybookIssues } from "../fixtures/paperclipData";
|
||||
|
||||
const companyId = "company-storybook";
|
||||
const blockedViewDefaults = {
|
||||
groupBy: "none" as const,
|
||||
sortBy: "most_recent" as const,
|
||||
issueFilters: defaultIssueFilterState,
|
||||
currentUserId: "local-board",
|
||||
liveIssueIds: new Set<string>(),
|
||||
workspaceFilterContext: {},
|
||||
showStatusColumn: true,
|
||||
showIdentifierColumn: true,
|
||||
showUpdatedColumn: true,
|
||||
};
|
||||
|
||||
function attention(
|
||||
overrides: Partial<IssueBlockedInboxAttention> = {},
|
||||
): IssueBlockedInboxAttention {
|
||||
return {
|
||||
kind: "blocked",
|
||||
state: "needs_attention",
|
||||
reason: "blocked_chain_stalled",
|
||||
severity: "medium",
|
||||
stoppedSinceAt: new Date(Date.now() - 4 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "ClaudeCoder" },
|
||||
action: { label: "Resolve PAP-12", detail: null },
|
||||
sourceIssue: null,
|
||||
leafIssue: null,
|
||||
recoveryIssue: null,
|
||||
approvalId: null,
|
||||
interactionId: null,
|
||||
sampleIssueIdentifier: null,
|
||||
redaction: { externalDetailsRedacted: false, secretFieldsOmitted: true },
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
const baseIssue = storybookIssues[0]!;
|
||||
|
||||
const fixtureIssues: Issue[] = [
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-decision-1",
|
||||
identifier: "PAP-401",
|
||||
title: "Approve plan: rewrite onboarding flow",
|
||||
status: "in_review",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "pending_board_decision",
|
||||
state: "awaiting_decision",
|
||||
severity: "medium",
|
||||
stoppedSinceAt: new Date(Date.now() - 2 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "board", agentId: null, userId: null, label: "Board" },
|
||||
action: { label: "Accept or reject", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-disposition-1",
|
||||
identifier: "PAP-402",
|
||||
title: "Pick disposition for completed migration",
|
||||
status: "in_progress",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "missing_successful_run_disposition",
|
||||
state: "missing_disposition",
|
||||
severity: "medium",
|
||||
stoppedSinceAt: new Date(Date.now() - 30 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "QA" },
|
||||
action: { label: "Pick disposition", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-stalled-critical",
|
||||
identifier: "PAP-410",
|
||||
title: "Ship invoice export — blocker is stalled",
|
||||
status: "blocked",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "blocked_chain_stalled",
|
||||
state: "needs_attention",
|
||||
severity: "critical",
|
||||
stoppedSinceAt: new Date(Date.now() - 36 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "CodexCoder" },
|
||||
action: { label: "Resolve PAP-411", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-stalled-high",
|
||||
identifier: "PAP-412",
|
||||
title: "Run nightly compaction",
|
||||
status: "blocked",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "blocked_chain_stalled",
|
||||
severity: "high",
|
||||
stoppedSinceAt: new Date(Date.now() - 8 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "QA" },
|
||||
action: { label: "Resolve PAP-413", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-needs-attention",
|
||||
identifier: "PAP-420",
|
||||
title: "Resume parked permissions PR",
|
||||
status: "blocked",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "blocked_by_assigned_backlog_issue",
|
||||
severity: "medium",
|
||||
stoppedSinceAt: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "ClaudeCoder" },
|
||||
action: { label: "Resume parked blocker", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-recovery",
|
||||
identifier: "PAP-430",
|
||||
title: "Recover failed deploy run",
|
||||
status: "blocked",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "open_recovery_issue",
|
||||
state: "recovery_open",
|
||||
severity: "high",
|
||||
stoppedSinceAt: new Date(Date.now() - 6 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "RecoveryAgent" },
|
||||
action: { label: "Resolve PAP-431", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-external",
|
||||
identifier: "PAP-440",
|
||||
title: "Awaiting upstream provider response",
|
||||
status: "blocked",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "external_owner_action",
|
||||
state: "external_wait",
|
||||
severity: "low",
|
||||
stoppedSinceAt: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "external", agentId: null, userId: null, label: "Stripe" },
|
||||
action: { label: "Awaiting Stripe", detail: null },
|
||||
}),
|
||||
},
|
||||
{
|
||||
...baseIssue,
|
||||
id: "issue-paused",
|
||||
identifier: "PAP-450",
|
||||
title: "Owner paused — budget exceeded",
|
||||
status: "blocked",
|
||||
blockedInboxAttention: attention({
|
||||
reason: "blocked_by_uninvokable_assignee",
|
||||
severity: "critical",
|
||||
stoppedSinceAt: new Date(Date.now() - 12 * 60 * 60 * 1000).toISOString(),
|
||||
owner: { type: "agent", agentId: null, userId: null, label: "PausedAgent" },
|
||||
action: { label: "Reassign or unblock budget", detail: null },
|
||||
}),
|
||||
},
|
||||
];
|
||||
|
||||
function PrimeBlockedFixtures({ children }: { children: React.ReactNode }) {
|
||||
const queryClient = useQueryClient();
|
||||
useMemo(() => {
|
||||
queryClient.setQueryData(queryKeys.issues.listBlockedAttention(companyId), fixtureIssues);
|
||||
}, [queryClient]);
|
||||
return <>{children}</>;
|
||||
}
|
||||
|
||||
function BlockedTabSurface({ search = "" }: { search?: string }) {
|
||||
return (
|
||||
<PrimeBlockedFixtures>
|
||||
<div className="space-y-3">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Inbox / Blocked tab — desktop layout
|
||||
</div>
|
||||
<div className="rounded-lg border border-border bg-background p-4">
|
||||
<BlockedInboxView
|
||||
{...blockedViewDefaults}
|
||||
companyId={companyId}
|
||||
searchQuery={search}
|
||||
agentNameById={new Map()}
|
||||
issueLinkState={null}
|
||||
/>
|
||||
</div>
|
||||
</div>
|
||||
</PrimeBlockedFixtures>
|
||||
);
|
||||
}
|
||||
|
||||
function BlockedTabSurfaceMobile() {
|
||||
return (
|
||||
<div className="mx-auto max-w-[390px] space-y-3">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Inbox / Blocked tab — 390px mobile width
|
||||
</div>
|
||||
<div className="rounded-lg border border-border bg-background p-2">
|
||||
<BlockedTabSurface />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function BlockedReasonChipsCatalog() {
|
||||
return (
|
||||
<div className="grid gap-3 p-6 sm:grid-cols-2">
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Needs decision · medium
|
||||
</div>
|
||||
<BlockedReasonChip reason="pending_board_decision" severity="medium" />
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Blocked chain stalled · critical
|
||||
</div>
|
||||
<BlockedReasonChip reason="blocked_chain_stalled" severity="critical" />
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Needs attention · high
|
||||
</div>
|
||||
<BlockedReasonChip reason="blocked_by_assigned_backlog_issue" severity="high" />
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Recovery required · high
|
||||
</div>
|
||||
<BlockedReasonChip reason="open_recovery_issue" severity="high" />
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
External wait · low (no severity dot)
|
||||
</div>
|
||||
<BlockedReasonChip reason="external_owner_action" severity="low" />
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<div className="text-xs uppercase tracking-wide text-muted-foreground">
|
||||
Owner paused · critical
|
||||
</div>
|
||||
<BlockedReasonChip reason="blocked_by_uninvokable_assignee" severity="critical" />
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function BlockedTabEmptyState() {
|
||||
return (
|
||||
<div className="rounded-lg border border-border bg-background p-4">
|
||||
<BlockedInboxView
|
||||
{...blockedViewDefaults}
|
||||
companyId="company-empty"
|
||||
searchQuery=""
|
||||
agentNameById={new Map()}
|
||||
issueLinkState={null}
|
||||
/>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
const meta = {
|
||||
title: "Product/Inbox/Blocked tab",
|
||||
component: BlockedTabSurface,
|
||||
parameters: {
|
||||
docs: {
|
||||
description: {
|
||||
component:
|
||||
"Stopped-work triage Inbox tab. Rows group by reason variant and sort by severity → stoppedSinceAt. The reason chip + owner + action combo sits next to the issue title. No quick archive on this tab.",
|
||||
},
|
||||
},
|
||||
},
|
||||
} satisfies Meta<typeof BlockedTabSurface>;
|
||||
|
||||
export default meta;
|
||||
|
||||
type Story = StoryObj<typeof meta>;
|
||||
|
||||
export const DesktopLoaded: Story = {
|
||||
render: () => <BlockedTabSurface />,
|
||||
};
|
||||
|
||||
export const DesktopWithSearch: Story = {
|
||||
render: () => <BlockedTabSurface search="parked" />,
|
||||
};
|
||||
|
||||
export const MobileLayout: Story = {
|
||||
parameters: { viewport: { defaultViewport: "mobile1" } },
|
||||
render: () => <BlockedTabSurfaceMobile />,
|
||||
};
|
||||
|
||||
export const ReasonChipCatalog: Story = {
|
||||
render: () => <BlockedReasonChipsCatalog />,
|
||||
};
|
||||
|
||||
export const EmptyState: Story = {
|
||||
render: () => <BlockedTabEmptyState />,
|
||||
};
|
||||
Loading…
Add table
Add a link
Reference in a new issue