mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-17 03:10: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
|
|
@ -2,12 +2,16 @@ import { randomUUID } from "node:crypto";
|
|||
import { eq } from "drizzle-orm";
|
||||
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
|
||||
import {
|
||||
activityLog,
|
||||
agents,
|
||||
agentWakeupRequests,
|
||||
approvals,
|
||||
companies,
|
||||
createDb,
|
||||
heartbeatRuns,
|
||||
issueApprovals,
|
||||
issueRelations,
|
||||
issueThreadInteractions,
|
||||
issues,
|
||||
} from "@paperclipai/db";
|
||||
import {
|
||||
|
|
@ -15,6 +19,7 @@ import {
|
|||
startEmbeddedPostgresTestDatabase,
|
||||
} from "./helpers/embedded-postgres.js";
|
||||
import { issueService } from "../services/issues.js";
|
||||
import { buildIssueGraphLivenessIncidentKey } from "../services/recovery/origins.js";
|
||||
|
||||
const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();
|
||||
const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;
|
||||
|
|
@ -37,6 +42,10 @@ describeEmbeddedPostgres("issue blocker attention", () => {
|
|||
}, 20_000);
|
||||
|
||||
afterEach(async () => {
|
||||
await db.delete(issueThreadInteractions);
|
||||
await db.delete(issueApprovals);
|
||||
await db.delete(approvals);
|
||||
await db.delete(activityLog);
|
||||
await db.delete(heartbeatRuns);
|
||||
await db.delete(agentWakeupRequests);
|
||||
await db.delete(issueRelations);
|
||||
|
|
@ -52,20 +61,30 @@ describeEmbeddedPostgres("issue blocker attention", () => {
|
|||
async function createCompany(prefix = "PBA") {
|
||||
const companyId = randomUUID();
|
||||
const agentId = randomUUID();
|
||||
const pausedAgentId = randomUUID();
|
||||
await db.insert(companies).values({
|
||||
id: companyId,
|
||||
name: `Company ${prefix}`,
|
||||
issuePrefix: prefix,
|
||||
requireBoardApprovalForNewAgents: false,
|
||||
});
|
||||
await db.insert(agents).values({
|
||||
id: agentId,
|
||||
companyId,
|
||||
name: `${prefix} Agent`,
|
||||
role: "engineer",
|
||||
status: "idle",
|
||||
});
|
||||
return { companyId, agentId };
|
||||
await db.insert(agents).values([
|
||||
{
|
||||
id: agentId,
|
||||
companyId,
|
||||
name: `${prefix} Agent`,
|
||||
role: "engineer",
|
||||
status: "idle",
|
||||
},
|
||||
{
|
||||
id: pausedAgentId,
|
||||
companyId,
|
||||
name: `${prefix} Paused`,
|
||||
role: "engineer",
|
||||
status: "paused",
|
||||
},
|
||||
]);
|
||||
return { companyId, agentId, pausedAgentId };
|
||||
}
|
||||
|
||||
async function insertIssue(input: {
|
||||
|
|
@ -80,6 +99,8 @@ describeEmbeddedPostgres("issue blocker attention", () => {
|
|||
originKind?: string | null;
|
||||
originId?: string | null;
|
||||
originFingerprint?: string | null;
|
||||
executionState?: Record<string, unknown> | null;
|
||||
description?: string | null;
|
||||
}) {
|
||||
const id = input.id ?? randomUUID();
|
||||
await db.insert(issues).values({
|
||||
|
|
@ -95,6 +116,8 @@ describeEmbeddedPostgres("issue blocker attention", () => {
|
|||
originKind: input.originKind ?? "manual",
|
||||
originId: input.originId ?? null,
|
||||
originFingerprint: input.originFingerprint ?? "default",
|
||||
executionState: input.executionState ?? null,
|
||||
description: input.description ?? null,
|
||||
});
|
||||
return id;
|
||||
}
|
||||
|
|
@ -483,4 +506,192 @@ describeEmbeddedPostgres("issue blocker attention", () => {
|
|||
sampleBlockerIdentifier: "PBY-2",
|
||||
});
|
||||
});
|
||||
|
||||
it("returns blocked inbox attention for an unassigned blocker leaf and supports count/search", async () => {
|
||||
const { companyId } = await createCompany("BIA");
|
||||
const parentId = await insertIssue({ companyId, identifier: "BIA-1", title: "Blocked source", status: "blocked" });
|
||||
const blockerId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BIA-2",
|
||||
title: "Unassigned leaf",
|
||||
status: "todo",
|
||||
});
|
||||
await block({ companyId, blockerIssueId: blockerId, blockedIssueId: parentId });
|
||||
|
||||
const rows = await svc.list(companyId, { attention: "blocked", q: "BIA-2" });
|
||||
|
||||
expect(rows).toHaveLength(1);
|
||||
expect(rows[0]?.id).toBe(parentId);
|
||||
expect(rows[0]?.blockedBy).toEqual([
|
||||
expect.objectContaining({ id: blockerId, identifier: "BIA-2" }),
|
||||
]);
|
||||
expect(rows[0]?.blockedInboxAttention).toMatchObject({
|
||||
kind: "blocked",
|
||||
state: "needs_attention",
|
||||
reason: "blocked_by_unassigned_issue",
|
||||
severity: "critical",
|
||||
owner: { type: "unknown", agentId: null, userId: null },
|
||||
action: { label: "Assign blocker" },
|
||||
leafIssue: { id: blockerId, identifier: "BIA-2" },
|
||||
redaction: { secretFieldsOmitted: true },
|
||||
});
|
||||
await expect(svc.count(companyId, { attention: "blocked" })).resolves.toBe(1);
|
||||
});
|
||||
|
||||
it("redacts external wait details from blocked inbox payloads and search", async () => {
|
||||
const { companyId } = await createCompany("BIX");
|
||||
const owner = "Private Vendor Security Team";
|
||||
const action = "Send the confidential access token for customer Alpha";
|
||||
const issueId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BIX-1",
|
||||
title: "Blocked on vendor",
|
||||
status: "blocked",
|
||||
description: [
|
||||
"Public context stays visible.",
|
||||
`external owner: ${owner}`,
|
||||
`external action: ${action}`,
|
||||
"Continue after the vendor confirms receipt.",
|
||||
].join("\n"),
|
||||
});
|
||||
|
||||
const rows = await svc.list(companyId, { attention: "blocked" });
|
||||
const issue = rows.find((row) => row.id === issueId);
|
||||
|
||||
expect(issue?.description).toContain("Public context stays visible.");
|
||||
expect(issue?.description).toContain("Continue after the vendor confirms receipt.");
|
||||
expect(issue?.description).not.toContain(owner);
|
||||
expect(issue?.description).not.toContain(action);
|
||||
expect(issue?.blockedInboxAttention).toMatchObject({
|
||||
state: "external_wait",
|
||||
reason: "external_owner_action",
|
||||
owner: { type: "external", label: null },
|
||||
action: { label: "External owner action", detail: null },
|
||||
redaction: { externalDetailsRedacted: true, secretFieldsOmitted: true },
|
||||
});
|
||||
expect(JSON.stringify(issue?.blockedInboxAttention)).not.toContain(owner);
|
||||
expect(JSON.stringify(issue?.blockedInboxAttention)).not.toContain(action);
|
||||
|
||||
await expect(svc.list(companyId, { attention: "blocked", q: owner })).resolves.toEqual([]);
|
||||
await expect(svc.count(companyId, { attention: "blocked", q: action })).resolves.toBe(0);
|
||||
await expect(svc.count(companyId, { attention: "blocked", q: "Public context" })).resolves.toBe(1);
|
||||
});
|
||||
|
||||
it("excludes healthy active blockers from blocked inbox attention", async () => {
|
||||
const { companyId, agentId } = await createCompany("BIB");
|
||||
const parentId = await insertIssue({ companyId, identifier: "BIB-1", title: "Blocked source", status: "blocked" });
|
||||
const blockerId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BIB-2",
|
||||
title: "Running leaf",
|
||||
status: "todo",
|
||||
assigneeAgentId: agentId,
|
||||
});
|
||||
await block({ companyId, blockerIssueId: blockerId, blockedIssueId: parentId });
|
||||
await activeRun({ companyId, agentId, issueId: blockerId });
|
||||
|
||||
expect(await svc.list(companyId, { attention: "blocked" })).toEqual([]);
|
||||
});
|
||||
|
||||
it("classifies assigned backlog and invalid review leaves for blocked inbox attention", async () => {
|
||||
const { companyId, agentId, pausedAgentId } = await createCompany("BIC");
|
||||
const backlogParentId = await insertIssue({ companyId, identifier: "BIC-1", title: "Blocked by parked work", status: "blocked" });
|
||||
const backlogLeafId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BIC-2",
|
||||
title: "Parked blocker",
|
||||
status: "backlog",
|
||||
assigneeAgentId: agentId,
|
||||
});
|
||||
await block({ companyId, blockerIssueId: backlogLeafId, blockedIssueId: backlogParentId });
|
||||
|
||||
const reviewId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BIC-3",
|
||||
title: "Invalid review",
|
||||
status: "in_review",
|
||||
assigneeAgentId: agentId,
|
||||
executionState: {
|
||||
status: "pending",
|
||||
currentStageId: null,
|
||||
currentStageIndex: null,
|
||||
currentStageType: "review",
|
||||
currentParticipant: { type: "agent", agentId: pausedAgentId },
|
||||
returnAssignee: null,
|
||||
reviewRequest: null,
|
||||
completedStageIds: [],
|
||||
lastDecisionId: null,
|
||||
lastDecisionOutcome: null,
|
||||
},
|
||||
});
|
||||
|
||||
const rows = await svc.list(companyId, { attention: "blocked" });
|
||||
const byId = new Map(rows.map((row) => [row.id, row]));
|
||||
|
||||
expect(byId.get(backlogParentId)?.blockedInboxAttention).toMatchObject({
|
||||
reason: "blocked_by_assigned_backlog_issue",
|
||||
severity: "high",
|
||||
owner: { type: "agent", agentId },
|
||||
leafIssue: { id: backlogLeafId },
|
||||
});
|
||||
expect(byId.get(reviewId)?.blockedInboxAttention).toMatchObject({
|
||||
reason: "invalid_review_participant",
|
||||
severity: "critical",
|
||||
action: { label: "Repair review participant" },
|
||||
});
|
||||
});
|
||||
|
||||
it("classifies recovery issues and missing successful-run dispositions", async () => {
|
||||
const { companyId, agentId } = await createCompany("BID");
|
||||
const sourceId = await insertIssue({ companyId, identifier: "BID-1", title: "Stopped source", status: "blocked" });
|
||||
const leafId = await insertIssue({ companyId, identifier: "BID-2", title: "Stopped leaf", status: "todo" });
|
||||
const recoveryId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BID-3",
|
||||
title: "Recovery issue",
|
||||
status: "todo",
|
||||
assigneeAgentId: agentId,
|
||||
originKind: "harness_liveness_escalation",
|
||||
originId: buildIssueGraphLivenessIncidentKey({
|
||||
companyId,
|
||||
issueId: sourceId,
|
||||
state: "blocked_by_unassigned_issue",
|
||||
blockerIssueId: leafId,
|
||||
}),
|
||||
});
|
||||
const handoffId = await insertIssue({
|
||||
companyId,
|
||||
identifier: "BID-4",
|
||||
title: "Needs disposition",
|
||||
status: "in_progress",
|
||||
assigneeAgentId: agentId,
|
||||
});
|
||||
await db.insert(activityLog).values({
|
||||
companyId,
|
||||
actorType: "system",
|
||||
actorId: "system",
|
||||
action: "issue.successful_run_handoff_required",
|
||||
entityType: "issue",
|
||||
entityId: handoffId,
|
||||
agentId,
|
||||
details: { sourceRunId: randomUUID(), detectedProgressSummary: "Progress was made" },
|
||||
});
|
||||
|
||||
const rows = await svc.list(companyId, { attention: "blocked" });
|
||||
const byId = new Map(rows.map((row) => [row.id, row]));
|
||||
|
||||
expect(byId.get(recoveryId)?.blockedInboxAttention).toMatchObject({
|
||||
state: "recovery_open",
|
||||
reason: "open_recovery_issue",
|
||||
sourceIssue: { id: sourceId },
|
||||
leafIssue: { id: leafId },
|
||||
recoveryIssue: { id: recoveryId },
|
||||
});
|
||||
expect(byId.get(handoffId)?.blockedInboxAttention).toMatchObject({
|
||||
state: "missing_disposition",
|
||||
reason: "missing_successful_run_disposition",
|
||||
owner: { type: "agent", agentId },
|
||||
action: { label: "Choose disposition" },
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
|
|||
|
|
@ -1444,6 +1444,7 @@ export function issueRoutes(
|
|||
const parsedOffset = rawOffset !== undefined && /^\d+$/.test(rawOffset)
|
||||
? Number.parseInt(rawOffset, 10)
|
||||
: null;
|
||||
const attention = req.query.attention as string | undefined;
|
||||
|
||||
if (assigneeUserFilterRaw === "me" && (!assigneeUserId || req.actor.type !== "board")) {
|
||||
res.status(403).json({ error: "assigneeUserId=me requires board authentication" });
|
||||
|
|
@ -1461,6 +1462,10 @@ export function issueRoutes(
|
|||
res.status(403).json({ error: "unreadForUserId=me requires board authentication" });
|
||||
return;
|
||||
}
|
||||
if (attention !== undefined && attention !== "blocked") {
|
||||
res.status(400).json({ error: "attention must be 'blocked' when provided" });
|
||||
return;
|
||||
}
|
||||
if (rawLimit !== undefined && (parsedLimit === null || !Number.isInteger(parsedLimit) || parsedLimit <= 0)) {
|
||||
res.status(400).json({ error: `limit must be a positive integer up to ${ISSUE_LIST_MAX_LIMIT}` });
|
||||
return;
|
||||
|
|
@ -1472,6 +1477,7 @@ export function issueRoutes(
|
|||
const offset = parsedOffset ?? 0;
|
||||
|
||||
const result = await svc.list(companyId, {
|
||||
attention: attention === "blocked" ? "blocked" : undefined,
|
||||
status: req.query.status as string | undefined,
|
||||
assigneeAgentId: req.query.assigneeAgentId as string | undefined,
|
||||
participantAgentId: req.query.participantAgentId as string | undefined,
|
||||
|
|
@ -1495,6 +1501,8 @@ export function issueRoutes(
|
|||
includePluginOperations:
|
||||
req.query.includePluginOperations === "true" || req.query.includePluginOperations === "1",
|
||||
includeBlockedBy: req.query.includeBlockedBy === "true" || req.query.includeBlockedBy === "1",
|
||||
includeBlockedInboxAttention:
|
||||
req.query.includeBlockedInboxAttention === "true" || req.query.includeBlockedInboxAttention === "1",
|
||||
q: req.query.q as string | undefined,
|
||||
limit,
|
||||
offset,
|
||||
|
|
@ -1511,6 +1519,47 @@ export function issueRoutes(
|
|||
})));
|
||||
});
|
||||
|
||||
router.get("/companies/:companyId/issues/count", async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
assertCompanyAccess(req, companyId);
|
||||
const attention = req.query.attention as string | undefined;
|
||||
if (attention !== "blocked") {
|
||||
res.status(400).json({ error: "issues/count currently requires attention=blocked" });
|
||||
return;
|
||||
}
|
||||
if (req.query.limit !== undefined || req.query.offset !== undefined) {
|
||||
res.status(400).json({ error: "issues/count does not accept limit or offset" });
|
||||
return;
|
||||
}
|
||||
|
||||
const count = await svc.count(companyId, {
|
||||
attention: "blocked",
|
||||
status: req.query.status as string | undefined,
|
||||
assigneeAgentId: req.query.assigneeAgentId as string | undefined,
|
||||
participantAgentId: req.query.participantAgentId as string | undefined,
|
||||
assigneeUserId: req.query.assigneeUserId as string | undefined,
|
||||
projectId: req.query.projectId as string | undefined,
|
||||
workspaceId: req.query.workspaceId as string | undefined,
|
||||
executionWorkspaceId: req.query.executionWorkspaceId as string | undefined,
|
||||
parentId: req.query.parentId as string | undefined,
|
||||
descendantOf: req.query.descendantOf as string | undefined,
|
||||
labelId: req.query.labelId as string | undefined,
|
||||
originKind: req.query.originKind as string | undefined,
|
||||
originKindPrefix: req.query.originKindPrefix as string | undefined,
|
||||
originId: req.query.originId as string | undefined,
|
||||
includeRoutineExecutions:
|
||||
req.query.includeRoutineExecutions === "true" || req.query.includeRoutineExecutions === "1",
|
||||
excludeRoutineExecutions:
|
||||
req.query.excludeRoutineExecutions === "true" || req.query.excludeRoutineExecutions === "1",
|
||||
includePluginOperations:
|
||||
req.query.includePluginOperations === "true" || req.query.includePluginOperations === "1",
|
||||
includeBlockedBy: true,
|
||||
includeBlockedInboxAttention: true,
|
||||
q: req.query.q as string | undefined,
|
||||
});
|
||||
res.json({ count });
|
||||
});
|
||||
|
||||
router.get("/companies/:companyId/labels", async (req, res) => {
|
||||
const companyId = req.params.companyId as string;
|
||||
assertCompanyAccess(req, companyId);
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
Loading…
Add table
Add a link
Reference in a new issue