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",