From b7774a01cfc425cd05e5d810b0327e34a28a45dd Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 13 Nov 2026 09:53:25 -0600 Subject: [PATCH] fix: name activity actors and explain stopped tasks in plain words (#21406) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - People must never see internal jargon or raw ids in chat replies or task comments > - Chat eval cohort 12 found three sources: activity records show the board user only as the raw id `local-board`, agents turn internal field names such as `checkoutRunId` into words like "no checkout", and a recovery notice says "the original assignee is not invokable" > - The recovery notice appeared on 170 fixture tasks. It is not a loop: each task got it once, because recovery blocked every in-progress task of an agent that a person had paused > - This pull request names activity actors, lists these internal terms in the chat guidance, rewords the notice, and leaves in-progress work of a manually paused agent alone > - The benefit is plain replies and no false "blocked" tasks after a person pauses an agent ## Linked Issues or Issue Description **What happened?** - `activity.audit-change`: the agent read `GET /api/issues/{id}/activity` and wrote that the change was made by "the board user identity (`local-board`)". Activity rows carry only `actorType` and `actorId`. - `activity.company-overview`: the agent wrote "no checkout" to explain why no one is working on a task. - `tasks.organize-open-work`: 170 of 501 fixture tasks got one system comment each: "Paperclip cannot safely continue automatic recovery because the original assignee is not invokable...". The owners were paused by a person, and the stranded-work sweep blocked each in-progress task. The existing rule already keeps `todo` work of a manually paused agent, because blocking it fights the pause and strands the task after resume. **Expected behavior** Replies name actors by name ("Board", a member's name, an agent's name) and describe states in plain words. A person's pause does not block the agent's in-progress work. A stopped-task notice says what happened and what to do, in plain words. **Steps to reproduce** 1. Change a task's priority as the local board user, then ask the chat agent who changed it. 2. Pause an agent that owns in-progress tasks with no active run, and let the stranded-work sweep run. ## What Changed - `server/src/services/activity.ts`, `server/src/routes/activity.ts`, `packages/shared/src/types/activity.ts`: company and task activity reads add `actorName` (agent name, member name, "Board" for `local-board`, "Paperclip" for the system). Raw ids stay in their existing fields. - `server/src/services/agent-conversations.ts`: the existing "no raw IDs or internal codes" rule now names checkout, native run and local-board as internal terms, and tells the agent to name an actor by `actorName`. - `server/src/services/recovery/service.ts`: the notice is now " can't run right now, so Paperclip stopped this task instead of retrying it. It is still assigned to them. To continue, resume or fix the agent, or assign the task to someone else." The manual-pause skip now covers `in_progress` as well as `todo` work with no run. ## Verification - `cd server && npx vitest run src/__tests__/heartbeat-paused-assignee-new-task.test.ts`: 4 pass. With the old recovery service the two new tests fail (`expected 'blocked' to be 'in_progress'`, and the old notice text). - `cd server && npx vitest run src/__tests__/activity-service.test.ts -t "names each activity actor"`: passes (the method did not exist before). - `cd server && npx vitest run src/__tests__/agent-conversations.test.ts`: passes. - `src/__tests__/activity-routes.test.ts` has three tests that time out locally on unchanged master code too; CI runs them. - Paid eval run of `activity.audit-change` and `budgets-costs.spend-breakdown` on a branch with this change. ## Risks - The chat prompt grows by about 40 words. This is a small part of the existing directive, so time to first token does not change in a measurable way. - A budget- or error-paused agent still gets the notice, now in plain words. Only a manual pause keeps in-progress work as is; the sweep picks it up after resume. ## Model Used - Claude, claude-opus-5-5, with tool use and code execution in Claude Code. ## 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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 --- packages/shared/src/types/activity.ts | 2 ++ server/src/__tests__/activity-routes.test.ts | 2 ++ server/src/__tests__/activity-service.test.ts | 21 +++++++++++++++ .../src/__tests__/agent-conversations.test.ts | 3 ++- ...heartbeat-paused-assignee-new-task.test.ts | 24 +++++++++++++++-- server/src/routes/activity.ts | 4 +-- server/src/routes/issues.ts | 2 +- server/src/services/activity.ts | 26 +++++++++++++++++++ server/src/services/agent-conversations.ts | 2 +- server/src/services/recovery/service.ts | 6 ++--- .../runner-e2e/source-sdk-public-inputs.json | 2 +- 11 files changed, 83 insertions(+), 11 deletions(-) diff --git a/packages/shared/src/types/activity.ts b/packages/shared/src/types/activity.ts index 9d383f85775..6f5f27417a0 100644 --- a/packages/shared/src/types/activity.ts +++ b/packages/shared/src/types/activity.ts @@ -3,6 +3,8 @@ export interface ActivityEvent { companyId: string; actorType: "agent" | "user" | "system" | "plugin"; actorId: string; + /** Person-facing name of the actor, such as an agent's or member's name, or "Board". */ + actorName?: string; action: string; entityType: string; entityId: string; diff --git a/server/src/__tests__/activity-routes.test.ts b/server/src/__tests__/activity-routes.test.ts index 0c507b0a157..77d3354b1ec 100644 --- a/server/src/__tests__/activity-routes.test.ts +++ b/server/src/__tests__/activity-routes.test.ts @@ -9,6 +9,7 @@ const mockActivityService = vi.hoisted(() => ({ runsForIssue: vi.fn(), issuesForRun: vi.fn(), create: vi.fn(), + withActorNames: vi.fn(), })); const mockHeartbeatService = vi.hoisted(() => ({ @@ -120,6 +121,7 @@ async function requestApp( describe("activity routes", () => { beforeEach(() => { for (const mock of Object.values(mockActivityService)) mock.mockReset(); + mockActivityService.withActorNames.mockImplementation(async (rows: unknown[]) => rows); for (const mock of Object.values(mockHeartbeatService)) mock.mockReset(); mockHeartbeatService.getRun.mockImplementation(() => { throw new Error("Run issue links must use the narrow authorization read"); diff --git a/server/src/__tests__/activity-service.test.ts b/server/src/__tests__/activity-service.test.ts index 54c4d26bd62..35f58a138c2 100644 --- a/server/src/__tests__/activity-service.test.ts +++ b/server/src/__tests__/activity-service.test.ts @@ -5,6 +5,7 @@ import { activityLog, agentWakeupRequests, agents, + authUsers, companies, createDb, documentRevisions, @@ -108,6 +109,26 @@ describeEmbeddedPostgres("activity service", () => { expect((await service.getById(task.id))?.workMode).toBe(nextMode); }); + it("names each activity actor for the person instead of showing a raw id such as local-board", async () => { + const companyId = randomUUID(), agentId = randomUUID(), userId = `member-${companyId}`; + await db.insert(companies).values({ id: companyId, name: "Names", issuePrefix: `N${companyId.slice(0, 6)}` }); + await db.insert(agents).values({ id: agentId, companyId, name: "Morgan", role: "engineer", status: "idle", adapterType: "codex_local" }); + await db.insert(authUsers).values({ id: userId, name: "Sam Rivera", email: `${userId}@example.test`, createdAt: new Date(), updatedAt: new Date() }); + const base = { companyId, action: "issue.updated", entityType: "company", entityId: companyId }; + await db.insert(activityLog).values([ + { ...base, actorType: "user", actorId: "local-board" }, + { ...base, actorType: "user", actorId: userId }, + { ...base, actorType: "agent", actorId: agentId }, + { ...base, actorType: "system", actorId: "system" }, + { ...base, actorType: "agent", actorId: "external-agent" }, + ]); + const named = await activityService(db).withActorNames(await activityService(db).list({ companyId })); + expect(Object.fromEntries(named.map(row => [row.actorId, row.actorName]))).toEqual({ + "local-board": "Board", [userId]: "Sam Rivera", [agentId]: "Morgan", system: "Paperclip", "external-agent": "An agent", + }); + await db.delete(authUsers).where(eq(authUsers.id, userId)); + }); + it("limits company activity lists", async () => { const companyId = randomUUID(); diff --git a/server/src/__tests__/agent-conversations.test.ts b/server/src/__tests__/agent-conversations.test.ts index cbf516110c1..6feed91153f 100644 --- a/server/src/__tests__/agent-conversations.test.ts +++ b/server/src/__tests__/agent-conversations.test.ts @@ -990,7 +990,8 @@ describe("chat prompt policy", () => { it("tells chat to name records the way the person sees them instead of raw IDs, internal codes, tool names or server paths", () => { expect(AGENT_CHAT_DIRECTIVE).toContain("give the specific reason returned by the platform, in plain words"); expect(AGENT_CHAT_DIRECTIVE).toContain("Write replies for the person, not for the API."); - expect(AGENT_CHAT_DIRECTIVE).toContain("Do not write raw IDs (UUIDs or their short forms for runs, revisions, handoffs, interactions, routines, triggers, attachments, workspaces, incidents, users or agents), internal codes (status, error, cause or reason codes such as native_session_retry_exhausted or board_access_required), field or setting keys, tool names, internal process names or server file paths in a reply, even in parentheses or inline code."); + expect(AGENT_CHAT_DIRECTIVE).toContain("Do not write raw IDs (UUIDs or their short forms for runs, revisions, handoffs, interactions, routines, triggers, attachments, workspaces, incidents, users or agents), internal codes (status, error, cause or reason codes such as native_session_retry_exhausted or board_access_required), field or setting keys, tool names, internal process names, internal terms such as checkout, native run or local-board, or server file paths in a reply, even in parentheses or inline code."); + expect(AGENT_CHAT_DIRECTIVE).toContain("Name an actor by the actorName a record returns."); expect(AGENT_CHAT_DIRECTIVE).toContain("The only exceptions are link targets, values inside a command the person must run, and an ID the person explicitly asks for."); const prompt = buildPaperclipTaskMarkdown({ issue: { id: "chat", identifier: null, title: "Chat", workMode: "ask", conversationAgentId: "agent" } }); expect(prompt).toContain("Write replies for the person, not for the API."); diff --git a/server/src/__tests__/heartbeat-paused-assignee-new-task.test.ts b/server/src/__tests__/heartbeat-paused-assignee-new-task.test.ts index f579deea71f..7de301480fe 100644 --- a/server/src/__tests__/heartbeat-paused-assignee-new-task.test.ts +++ b/server/src/__tests__/heartbeat-paused-assignee-new-task.test.ts @@ -47,7 +47,7 @@ describePostgres("new task for a manually paused assignee", () => { if (home) await rm(home, { recursive: true, force: true }); }); - async function seed(holds: string[]) { + async function seed(holds: string[], status = "todo") { const companyId = randomUUID(), agentId = randomUUID(), issueId = randomUUID(); const userId = `paused-user-${companyId}`; await db.insert(authUsers).values({ id: userId, name: "Board user", email: `${userId}@example.test`, createdAt: new Date(), updatedAt: new Date() }); @@ -55,7 +55,7 @@ describePostgres("new task for a manually paused assignee", () => { await db.insert(companyMemberships).values({ companyId, principalId: userId, principalType: "user", status: "active", membershipRole: "member" }); await db.insert(agents).values({ id: agentId, companyId, name: "Morgan", adapterType, adapterConfig: {}, status: "paused", lifecycleState: "paused", lifecycleHolds: holds, pauseReason: holds[0] ?? null, pausedAt: new Date() }); - await db.insert(issues).values({ id: issueId, companyId, title: "Task created while Morgan is paused", status: "todo", + await db.insert(issues).values({ id: issueId, companyId, title: "Task created while Morgan is paused", status, assigneeAgentId: agentId, responsibleUserId: userId, issueNumber: 1 }); return { companyId, agentId, issueId }; } @@ -82,6 +82,26 @@ describePostgres("new task for a manually paused assignee", () => { expect(finished.status).toBe("done"); }, 180_000); + it("leaves in-progress work of a manually paused assignee alone instead of blocking it", async () => { + const f = await seed(["manual"], "in_progress"); + await heartbeat.reconcileStrandedAssignedIssues({ companyId: f.companyId }); + const [saved] = await db.select().from(issues).where(eq(issues.id, f.issueId)); + expect(saved.status).toBe("in_progress"); + expect(await db.select().from(issueComments).where(eq(issueComments.issueId, f.issueId))).toHaveLength(0); + expect(await runs(f)).toHaveLength(0); + }, 180_000); + + it("explains a stopped task in plain words when the assignee cannot run", async () => { + const f = await seed(["budget"], "in_progress"); + await heartbeat.reconcileStrandedAssignedIssues({ companyId: f.companyId }); + const [saved] = await db.select().from(issues).where(eq(issues.id, f.issueId)); + expect(saved.status).toBe("blocked"); + const comments = await db.select().from(issueComments).where(eq(issueComments.issueId, f.issueId)); + expect(comments.map(comment => comment.body)).toEqual([ + "Morgan can't run right now, so Paperclip stopped this task instead of retrying it. It is still assigned to them. To continue, resume or fix the agent, or assign the task to someone else.", + ]); + }, 180_000); + it("still escalates a new task whose assignee is paused by something other than a person", async () => { const f = await seed(["budget"]); await heartbeat.reconcileStrandedAssignedIssues({ companyId: f.companyId }); diff --git a/server/src/routes/activity.ts b/server/src/routes/activity.ts index d1642e02d43..7e724832574 100644 --- a/server/src/routes/activity.ts +++ b/server/src/routes/activity.ts @@ -243,7 +243,7 @@ export function activityRoutes(db: Db) { caseReadCondition: await caseActivityReadSqlCondition(db, req.actor), }; const result = await svc.list(filters); - res.json(result); + res.json(await svc.withActorNames(result)); }); router.get("/companies/:companyId/audit/agent-actions", async (req, res) => { @@ -366,7 +366,7 @@ export function activityRoutes(db: Db) { return; } const result = await (req.query.view === "recent" ? svc.forIssue(issue.id, 50) : svc.forIssue(issue.id)); - res.json(result); + res.json(await svc.withActorNames(result)); }); router.get("/issues/:id/runs", async (req, res) => { diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts index a13c0bba7a0..c9340bcce9d 100644 --- a/server/src/routes/issues.ts +++ b/server/src/routes/issues.ts @@ -8882,7 +8882,7 @@ export function issueRoutes( recentComments.comments.map((comment) => comment.id).sort(), ), })), - activitySvc.forIssue(issue.id, 50), + activitySvc.forIssue(issue.id, 50).then(rows => activitySvc.withActorNames(rows)), activitySvc.runsForIssue(issue.companyId, issue.id, viewerUserId, 2, undefined, { skipLivenessBackfill: true }), issueThreadInteractionService(db).listForIssue(issue.id), svc.listAttachments(issue.id).then((rows) => rows.map(withContentPath)), diff --git a/server/src/services/activity.ts b/server/src/services/activity.ts index 3b8a5f1f105..69922166e5d 100644 --- a/server/src/services/activity.ts +++ b/server/src/services/activity.ts @@ -7,6 +7,7 @@ import type { Db } from "@paperclipai/db"; import { activityLog, agents, + authUsers, documentRevisions, documents, environmentLeases, @@ -50,6 +51,16 @@ const RUN_LIVENESS_BACKFILL_BATCH = 20; const RUN_LIVENESS_CLEAN_TTL_MS = 10 * 60_000; const RUN_LIVENESS_CLEAN_MAX_ENTRIES = 10_000; +const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; + +/** A person-facing name for an activity actor, so readers never see a raw id such as local-board. */ +export function activityActorFallbackName(actorType: string, actorId: string) { + if (actorType === "user") return actorId === "local-board" ? "Board" : "A board member"; + if (actorType === "agent") return "An agent"; + if (actorType === "plugin") return "A plugin"; + return "Paperclip"; +} + export function activityService(db: Db) { const scheduledLivenessBackfills = new Set(); // Issues whose last backfill pass left no missing liveness, keyed like @@ -427,6 +438,21 @@ export function activityService(db: Db) { .orderBy(commentId, activityLog.action, asc(activityLog.createdAt), asc(activityLog.id)); }, + /** Adds actorName to each row; agents and API readers name the actor without its raw id. */ + withActorNames: async (rows: T[]): Promise> => { + // actorId is free text; only a UUID can name a row in agents. + const agentIds = [...new Set(rows.filter(row => row.actorType === "agent" && UUID_PATTERN.test(row.actorId)).map(row => row.actorId))]; + const userIds = [...new Set(rows.filter(row => row.actorType === "user" && row.actorId !== "local-board").map(row => row.actorId))]; + const [agentRows, userRows] = await Promise.all([ + agentIds.length ? db.select({ id: agents.id, companyId: agents.companyId, name: agents.name }).from(agents).where(inArray(agents.id, agentIds)) : [], + userIds.length ? db.select({ id: authUsers.id, name: authUsers.name }).from(authUsers).where(inArray(authUsers.id, userIds)) : [], + ]); + const agentNames = new Map(agentRows.map(row => [`${row.companyId}:${row.id}`, row.name])); + const userNames = new Map(userRows.filter(row => row.name?.trim()).map(row => [row.id, row.name!.trim()])); + return rows.map(row => ({ ...row, actorName: (row.actorType === "agent" ? agentNames.get(`${row.companyId}:${row.actorId}`) + : row.actorType === "user" ? userNames.get(row.actorId) : undefined) ?? activityActorFallbackName(row.actorType, row.actorId) })); + }, + forIssue: (issueId: string, limit?: number) => { const query = db .select() diff --git a/server/src/services/agent-conversations.ts b/server/src/services/agent-conversations.ts index 21f9dc62933..104b927a01f 100644 --- a/server/src/services/agent-conversations.ts +++ b/server/src/services/agent-conversations.ts @@ -128,7 +128,7 @@ When a reply concerns a specific agent, such as one you paused, resumed, configu When a reply lists many tasks, write each task identifier in full, such as RUN-12, RUN-13, RUN-14. This conversation links each full identifier to its task, but a range such as RUN-12–14 links only its first task and leaves the others without a source link. When a complete list is too long to read in the reply, save it as a document on this conversation's task and link it, such as [Open work by owner](//issues/#document-), keeping a short summary with the counts in the reply. -Write replies for the person, not for the API. Name each record by what the person sees in Paperclip: a task, case or approval by its identifier (such as RUN-12) or title, a person or agent by name, and link it. Name a document revision by its number as Paperclip shows it, such as revision 4, including the revision a restore or edit created. When you discuss a run, such as a failed or retried run, link it, such as [the failed run](//agents//runs/), instead of describing it without a link. Do not write raw IDs (UUIDs or their short forms for runs, revisions, handoffs, interactions, routines, triggers, attachments, workspaces, incidents, users or agents), internal codes (status, error, cause or reason codes such as native_session_retry_exhausted or board_access_required), field or setting keys, tool names, internal process names or server file paths in a reply, even in parentheses or inline code. Say what each means in plain words instead, such as "automatic recovery gave up after 3 attempts" or "only a board user can do this". The only exceptions are link targets, values inside a command the person must run, and an ID the person explicitly asks for. +Write replies for the person, not for the API. Name each record by what the person sees in Paperclip: a task, case or approval by its identifier (such as RUN-12) or title, a person or agent by name, and link it. Name a document revision by its number as Paperclip shows it, such as revision 4, including the revision a restore or edit created. When you discuss a run, such as a failed or retried run, link it, such as [the failed run](//agents//runs/), instead of describing it without a link. Do not write raw IDs (UUIDs or their short forms for runs, revisions, handoffs, interactions, routines, triggers, attachments, workspaces, incidents, users or agents), internal codes (status, error, cause or reason codes such as native_session_retry_exhausted or board_access_required), field or setting keys, tool names, internal process names, internal terms such as checkout, native run or local-board, or server file paths in a reply, even in parentheses or inline code. Say what each means in plain words instead, such as "automatic recovery gave up after 3 attempts", "no one is working on it now", "a work session" or "you", or "only a board user can do this". Name an actor by the actorName a record returns. The only exceptions are link targets, values inside a command the person must run, and an ID the person explicitly asks for. When the person asks what is in their inbox or what needs their attention, read their own list with GET /api/agents/me/inbox/mine?userId=, using the authorUserId of their message. Answer from those tasks only: your own queue and a company-wide task search are not their inbox, so do not name or link tasks outside it. Link each task you cite and their list as [Mine](//inbox/mine), which opens their personal Mine view in every layout; do not send them to look through an inbox page for it. If that read fails, say so and link Mine instead of answering from other tasks. diff --git a/server/src/services/recovery/service.ts b/server/src/services/recovery/service.ts index 43c5e890322..591bb30dd57 100644 --- a/server/src/services/recovery/service.ts +++ b/server/src/services/recovery/service.ts @@ -4931,7 +4931,7 @@ export function recoveryService( agent?.status === "paused" && agent.companyId === issue.companyId && agent.lifecycleHolds.includes("manual") && - issue.status === "todo" && + (issue.status === "todo" || issue.status === "in_progress") && !latestRun ) { result.skipped += 1; @@ -4956,8 +4956,8 @@ export function recoveryService( previousStatus: issue.status as StrandedPreviousStatus, latestRun, comment: - "Paperclip cannot safely continue automatic recovery because the original assignee is not invokable. " + - "The source assignment is unchanged and the board must choose the next action.", + `${agent && agent.companyId === issue.companyId ? agent.name : "The assigned agent"} can't run right now, so Paperclip stopped this task instead of retrying it. ` + + "It is still assigned to them. To continue, resume or fix the agent, or assign the task to someone else.", }); if (updated) { result.escalated += 1; diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index 52e94651755..17c1021cc14 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -368,7 +368,7 @@ "packages/shared/src/telemetry/types.ts": "083d4341a72ac47bc1a3bbff163965de8b06f90a", "packages/shared/src/trust-policy.ts": "88001a8d629a2af66dcd8d75b7b4d36298455ef6", "packages/shared/src/types/access.ts": "015d51792da07acaebe59e0e395698d207811d0d", - "packages/shared/src/types/activity.ts": "9d383f85775bf3657a7f9bdfb32a6e58e58c12a3", + "packages/shared/src/types/activity.ts": "6f5f27417a0bb26ec4daba6ec16a04ce31e484f2", "packages/shared/src/types/adapter-registry.ts": "bd9b0a1f7980bf444f7f3d75a4687874014c4bca", "packages/shared/src/types/adapter-skills.ts": "ac77f7e013e8fb8de6fcbe916b7f7923554de815", "packages/shared/src/types/agent-lifecycle.ts": "dcc5105d57856cc8ca34a122cf54117c950184ea",