mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-16 03:31:44 +01:00
fix(runs): say who started a retry run in the issue run read (#21486)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The chat agent answers questions about failed runs by reading the
task's run list (`GET /api/issues/{id}/runs`)
> - For a retry run, that read returned only raw invocation fields
(`on_demand`, `manual`) and an owner id. It did not say who started the
retry
> - In chat-eval cohort 13, the agent told the person "Paperclip retried
automatically" about a run that the board started with Retry
> - This pull request adds a plain-words `retriedBy` field to each retry
run, and tells the chat agent to use it
> - The benefit is that people get a true account of who retried their
work, with a name and no raw ids
## Linked Issues or Issue Description
**What happened?**
Chat-eval cohort 13 ran OpenCode with
`openrouter/deepseek/deepseek-v4.1-flash-1017` on master `df1b12ad8e`.
In `runs-adapters.inspect-failed-run`, the reply said "Paperclip retried
automatically on a supported model". The successful run was a person's
manual Retry: `invocationSource: on_demand`, `triggerDetail: manual`,
wake reason `retry_failed_run`, and the responsible user was the board.
The agent's own reasoning hedged ("probably automatic"), because the run
read did not say who started the retry.
**Expected behavior**
The run reads that the agent uses say who started each retry: a person,
by display name, or Paperclip's automatic recovery, in plain words and
with no raw ids.
**Steps to reproduce**
1. Let a run fail on a task.
2. Press Retry on the failed run as a board user.
3. Read `GET /api/issues/{id}/runs`. Before this change, nothing in the
retry row says that a person pressed Retry.
## What Changed
- `runsForIssue` (`server/src/services/activity.ts`) reads the wake
request of each retry run. It adds `retriedBy` to each row:
- `{ kind: "person", personName, summary }` when a user wake with reason
`retry_failed_run` or `task_retry` started the run. The name comes from
the user record, or "Board" for the local board, with the same fallback
as activity actor names.
- `{ kind: "automatic", summary }` for an `automation` retry run.
- `null` for a run that is not a retry, or a retry whose starter is not
recorded. The read does not guess. It does not use `responsibleUserId`,
because automatic retries keep the original responsible user.
- The OpenAPI description of `GET /api/issues/{id}/runs` and the chat
agent directive tell the agent to use `retriedBy` and not to call a
retry automatic unless `retriedBy` says so.
- The UI `RunForIssue` type has the new optional field.
## Verification
- `cd server && npx vitest run src/__tests__/activity-service.test.ts
src/__tests__/agent-conversations.test.ts
src/__tests__/activity-routes.test.ts
src/__tests__/openapi-routes.test.ts` passes.
- Red/green: the new test "says who started each retry run" fails
without the service change (`expected undefined to be null`) and passes
with it. It covers a board Retry, a named member's Retry, an automatic
retry that keeps the board as responsible user, a retry with no recorded
wake, and no raw ids in the output.
- `npx tsc --noEmit -p server` passes.
- A narrow paid run of `runs-adapters.inspect-failed-run` (with the two
sibling cohort-13 PRs) ran on a combined branch. The results are in a PR
comment.
## Risks
- Low risk. The change adds one read-only field and one bounded query by
primary key on the wake requests of retry runs in the page.
- No persisted state changes.
> 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
- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), used through Claude
Code with tool use and code execution.
## 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 <noreply@anthropic.com>
This commit is contained in:
1 parent
95a6ab31e6
commit
8a97037bd2
5 files changed
+122
-4
No files matched your search
@@ -129,6 +129,59 @@ describeEmbeddedPostgres("activity service", () => {
|
||||
await db.delete(authUsers).where(eq(authUsers.id, userId));
|
||||
});
|
||||
|
||||
// Recorded in chat-eval cohort 13 (runs-adapters.inspect-failed-run): the
|
||||
// agent told the person "Paperclip retried automatically" about a run the
|
||||
// board started with Retry, because the run read gave only raw invocation
|
||||
// fields (on_demand, manual) and an owner id.
|
||||
it("says who started each retry run: a named person's Retry or automatic recovery", async () => {
|
||||
const companyId = randomUUID(), agentId = randomUUID(), issueId = randomUUID(), userId = `member-${companyId}`;
|
||||
const failedRunId = randomUUID(), boardRetryId = randomUUID(), memberRetryId = randomUUID(), autoRetryId = randomUUID(), unknownRetryId = randomUUID();
|
||||
await db.insert(companies).values({ id: companyId, name: "Retries", issuePrefix: `R${companyId.slice(0, 6)}` });
|
||||
await db.insert(agents).values({ id: agentId, companyId, name: "Morgan", adapterType: "process" });
|
||||
await db.insert(authUsers).values({ id: userId, name: "Sam Rivera", email: `${userId}@example.test`, createdAt: new Date(), updatedAt: new Date() });
|
||||
await db.insert(issues).values({ id: issueId, companyId, title: "Website", assigneeAgentId: agentId });
|
||||
const wake = async (reason: string, requestedByActorType: string | null, requestedByActorId: string | null, source = "on_demand") => {
|
||||
const [row] = await db.insert(agentWakeupRequests).values({ companyId, agentId, source, triggerDetail: source === "automation" ? "system" : "manual",
|
||||
reason, requestedByActorType, requestedByActorId, status: "completed", payload: { issueId } }).returning();
|
||||
return row!.id;
|
||||
};
|
||||
const base = { companyId, agentId, issueId, scopeKind: "issue", contextSnapshot: { issueId } } as const;
|
||||
const memberTaskRetryId = await wake("task_retry", "user", userId), inheritedRetryId = randomUUID();
|
||||
const at = (seconds: number) => new Date(Date.UTC(2026, 10, 13, 18, 0, seconds));
|
||||
await db.insert(heartbeatRuns).values([
|
||||
{ ...base, id: failedRunId, status: "failed", errorCode: "native_provider_model_rejected", invocationSource: "assignment", createdAt: at(0) },
|
||||
{ ...base, id: boardRetryId, status: "succeeded", invocationSource: "on_demand", triggerDetail: "manual", responsibleUserId: "local-board",
|
||||
retryOfRunId: failedRunId, wakeupRequestId: await wake("retry_failed_run", "user", "local-board"), createdAt: at(1) },
|
||||
// Task Retry, as the queue saves it: the person's request is linked from
|
||||
// the run context with the source run as previousRunId, and retryOfRunId stays empty.
|
||||
{ ...base, id: memberRetryId, status: "succeeded", invocationSource: "on_demand", triggerDetail: "manual",
|
||||
wakeupRequestId: await wake("issue_assigned", "user", userId),
|
||||
contextSnapshot: { issueId, previousRunId: failedRunId, forceFreshSession: true, taskRetryRequestId: memberTaskRetryId }, createdAt: at(2) },
|
||||
// Automatic recovery keeps the original responsible user; that is not who started it.
|
||||
{ ...base, id: autoRetryId, status: "succeeded", invocationSource: "automation", triggerDetail: "system", responsibleUserId: "local-board",
|
||||
retryOfRunId: failedRunId, wakeupRequestId: await wake("transient_failure_retry", null, null, "automation"), createdAt: at(3) },
|
||||
// Automatic recovery after that Task Retry inherits the person's request in its context.
|
||||
{ ...base, id: inheritedRetryId, status: "succeeded", invocationSource: "automation", triggerDetail: "system", retryOfRunId: memberRetryId,
|
||||
wakeupRequestId: await wake("transient_failure_retry", null, null, "automation"),
|
||||
contextSnapshot: { issueId, previousRunId: failedRunId, taskRetryRequestId: memberTaskRetryId }, createdAt: at(5) },
|
||||
{ ...base, id: unknownRetryId, status: "succeeded", invocationSource: "on_demand", triggerDetail: "manual", retryOfRunId: failedRunId, createdAt: at(4) },
|
||||
]);
|
||||
|
||||
const rows = await activityService(db).runsForIssue(companyId, issueId);
|
||||
const byId = new Map(rows.map(row => [row.runId, row.retriedBy]));
|
||||
expect(byId.get(failedRunId)).toBeNull();
|
||||
expect(byId.get(boardRetryId)).toEqual({ kind: "person", personName: "Board",
|
||||
summary: "Board pressed Retry on the failed run. Paperclip did not retry it automatically." });
|
||||
expect(byId.get(memberRetryId)).toEqual({ kind: "person", personName: "Sam Rivera",
|
||||
summary: "Sam Rivera pressed Retry on the failed run. Paperclip did not retry it automatically." });
|
||||
expect(byId.get(autoRetryId)).toEqual({ kind: "automatic",
|
||||
summary: "Paperclip retried the failed run automatically; no person pressed Retry." });
|
||||
expect(byId.get(inheritedRetryId)).toMatchObject({ kind: "automatic" });
|
||||
expect(byId.get(unknownRetryId)).toBeNull();
|
||||
expect(JSON.stringify([...byId.values()])).not.toMatch(/local-board|member-/);
|
||||
await db.delete(authUsers).where(eq(authUsers.id, userId));
|
||||
});
|
||||
|
||||
it("limits company activity lists", async () => {
|
||||
const companyId = randomUUID();
|
||||
|
||||
|
||||
@@ -6487,6 +6487,7 @@ registry.registerPath({
|
||||
path: "/api/issues/{id}/runs",
|
||||
tags: ["activity"],
|
||||
summary: "List runs for an issue",
|
||||
description: "A retry run's retriedBy says in plain words who started it: a person who pressed Retry (named), or Paperclip's automatic recovery. It is null for a run that is not a retry. Use it rather than inferring the starter from invocationSource or triggerDetail.",
|
||||
request: { params: z.object({ id: z.string() }), query: z.object({ view: z.literal("recent").optional().describe("At most two recent run summaries."), runIds: z.string().optional().describe("Comma-separated list of 1 to 100 run UUIDs. Returns only those runs linked to this accessible issue.") }) },
|
||||
responses: { 200: r.ok(), 400: r.badRequest, 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
|
||||
});
|
||||
|
||||
@@ -6,6 +6,7 @@ import { and, asc, desc, eq, inArray, isNull, or, sql, type SQL } from "drizzle-
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import {
|
||||
activityLog,
|
||||
agentWakeupRequests,
|
||||
agents,
|
||||
authUsers,
|
||||
documentRevisions,
|
||||
@@ -61,6 +62,37 @@ export function activityActorFallbackName(actorType: string, actorId: string) {
|
||||
return "Paperclip";
|
||||
}
|
||||
|
||||
/** Wake reasons recorded when a person presses Retry on a failed run or task. */
|
||||
const PERSON_RETRY_WAKE_REASONS = new Set(["retry_failed_run", "task_retry"]);
|
||||
|
||||
export type RunRetriedBy = { kind: "person"; personName: string; summary: string } | { kind: "automatic"; summary: string };
|
||||
|
||||
/**
|
||||
* Who started a retry run, in plain words. A run's own invocation fields do
|
||||
* not say this: a person's Retry is an on-demand run whose responsible user
|
||||
* may also own automatic retries. The run's wake request records whether a
|
||||
* person pressed Retry; automatic recovery creates an automation run. Returns
|
||||
* null for a run that is not a retry or whose starter is not recorded, rather
|
||||
* than guessing.
|
||||
*/
|
||||
export function describeRunRetry(
|
||||
run: { retryOfRunId: string | null; taskRetryRequestId?: string | null; invocationSource: string | null },
|
||||
wake: { reason: string | null; requestedByActorType: string | null } | null,
|
||||
personName: string | null,
|
||||
): RunRetriedBy | null {
|
||||
if (!run.retryOfRunId && !run.taskRetryRequestId) return null;
|
||||
// The run's own start decides first: automatic recovery after a person's
|
||||
// Task Retry inherits that Retry's request, but the person did not start it.
|
||||
if (run.invocationSource === "automation") {
|
||||
return { kind: "automatic", summary: "Paperclip retried the failed run automatically; no person pressed Retry." };
|
||||
}
|
||||
if (wake?.requestedByActorType === "user" && wake.reason && PERSON_RETRY_WAKE_REASONS.has(wake.reason)) {
|
||||
const name = personName?.trim() || "A board member";
|
||||
return { kind: "person", personName: name, summary: `${name} pressed Retry on the failed run. Paperclip did not retry it automatically.` };
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
export function activityService(db: Db) {
|
||||
const scheduledLivenessBackfills = new Set<string>();
|
||||
// Issues whose last backfill pass left no missing liveness, keyed like
|
||||
@@ -521,6 +553,8 @@ export function activityService(db: Db) {
|
||||
wakeCommentId: sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'wakeCommentId'`,
|
||||
contextCommentId: sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'commentId'`,
|
||||
contextIssueId: sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'issueId'`,
|
||||
// A person's Task Retry links its saved request here instead of retryOfRunId.
|
||||
taskRetryRequestId: sql<string | null>`${heartbeatRuns.contextSnapshot} ->> 'taskRetryRequestId'`,
|
||||
})
|
||||
.from(heartbeatRuns)
|
||||
.innerJoin(
|
||||
@@ -554,9 +588,9 @@ export function activityService(db: Db) {
|
||||
.orderBy(desc(heartbeatRuns.createdAt), desc(heartbeatRuns.id));
|
||||
const runs = await (limit === undefined ? runsQuery : runsQuery.limit(limit));
|
||||
|
||||
if (runs.length === 0) return runs;
|
||||
if (runs.length === 0) return [];
|
||||
const runIds = runs.map((run) => run.runId);
|
||||
if (runIds.length === 0) return runs;
|
||||
if (runIds.length === 0) return [];
|
||||
|
||||
const exhaustionRowsQuery = db
|
||||
.select({
|
||||
@@ -602,12 +636,39 @@ export function activityService(db: Db) {
|
||||
.where(and(eq(issueDocuments.companyId, companyId), eq(issueDocuments.issueId, issueId), eq(issueDocuments.key, "plan")))
|
||||
.limit(1)
|
||||
: Promise.resolve([]);
|
||||
const [exhaustionRows, leaseRows, executionByRunId, [savedPlan]] = await Promise.all([
|
||||
const retryWakeId = (run: (typeof runs)[number]) => run.taskRetryRequestId && UUID_PATTERN.test(run.taskRetryRequestId)
|
||||
? run.taskRetryRequestId : run.retryOfRunId ? run.wakeupRequestId : null;
|
||||
const retryWakeIds = [...new Set(runs.flatMap(run => { const id = retryWakeId(run); return id ? [id] : []; }))];
|
||||
const retryWakesQuery = retryWakeIds.length
|
||||
? db.select({
|
||||
id: agentWakeupRequests.id,
|
||||
reason: agentWakeupRequests.reason,
|
||||
requestedByActorType: agentWakeupRequests.requestedByActorType,
|
||||
requestedByActorId: agentWakeupRequests.requestedByActorId,
|
||||
}).from(agentWakeupRequests)
|
||||
.where(and(eq(agentWakeupRequests.companyId, companyId), inArray(agentWakeupRequests.id, retryWakeIds)))
|
||||
: Promise.resolve([]);
|
||||
const [exhaustionRows, leaseRows, executionByRunId, [savedPlan], retryWakes] = await Promise.all([
|
||||
exhaustionRowsQuery,
|
||||
leaseRowsQuery,
|
||||
executionProjectionsForRuns(db, companyId, runIds, new Date(), { retryDatabaseReads: true }),
|
||||
savedPlanQuery,
|
||||
retryWakesQuery,
|
||||
]);
|
||||
const retryWakeById = new Map(retryWakes.map(wake => [wake.id, wake]));
|
||||
const retryPersonIds = [...new Set(retryWakes.flatMap(wake =>
|
||||
wake.requestedByActorType === "user" && wake.requestedByActorId && wake.requestedByActorId !== "local-board" ? [wake.requestedByActorId] : []))];
|
||||
const retryPersonNames = new Map((retryPersonIds.length
|
||||
? await db.select({ id: authUsers.id, name: authUsers.name }).from(authUsers).where(inArray(authUsers.id, retryPersonIds))
|
||||
: []).filter(row => row.name?.trim()).map(row => [row.id, row.name!.trim()]));
|
||||
const retriedBy = (run: (typeof runs)[number]) => {
|
||||
const wakeId = retryWakeId(run);
|
||||
const wake = wakeId ? retryWakeById.get(wakeId) ?? null : null;
|
||||
const actorId = wake?.requestedByActorId ?? null;
|
||||
const personName = wake?.requestedByActorType === "user" && actorId
|
||||
? retryPersonNames.get(actorId) ?? activityActorFallbackName("user", actorId) : null;
|
||||
return describeRunRetry(run, wake, personName);
|
||||
};
|
||||
const retryExhaustedReasonByRunId = new Map<string, string>();
|
||||
for (const row of exhaustionRows) {
|
||||
if (!row.message || retryExhaustedReasonByRunId.has(row.runId)) continue;
|
||||
@@ -666,6 +727,7 @@ export function activityService(db: Db) {
|
||||
}
|
||||
: null,
|
||||
retryExhaustedReason: retryExhaustedReasonByRunId.get(run.runId) ?? null,
|
||||
retriedBy: retriedBy(run),
|
||||
};
|
||||
});
|
||||
},
|
||||
|
||||
@@ -122,7 +122,7 @@ When the person says an existing task must not start until another task is done
|
||||
|
||||
For review or follow-up tasks, include the existing source materials the assignee needs, not just task identifiers or a rubric. Read the source task's saved documents and comments, then copy the relevant existing content into the handoff or attach resources the recipient can actually read. A new task's tools may only expose its own documents and history. Supplying existing source material is coordination, not creating the assigned deliverable.
|
||||
|
||||
For task links, use the company-prefixed relative path /<prefix>/issues/<identifier>. The company prefix is the part of a task identifier before its final hyphen and number: for task RUN-1 the prefix is RUN. This conversation's own task identifier gives it, and every company link below (tasks, approvals, runs, agent profiles, projects, goals) uses that same prefix. Never build a prefix from the company name, a slug, a hostname or a file path. Write every company link as a Markdown link, such as [Review the approval](/<prefix>/approvals/<approvalId>): a bare path or a path in inline code is not clickable in this conversation. Start each link target with exactly one slash: a target beginning with //, such as //<prefix>/issues/<identifier>, points to a different website. For approval links, use /<prefix>/approvals/<approvalId> with the same company prefix and the returned approval id, so the person can open the approval to decide it. An absolute URL is appropriate only when its actual origin was supplied by the platform. Never invent a hostname for a Paperclip link. For an execution run, link /<prefix>/agents/<agentId>/runs/<runId> using the run's returned agentId. Issue run listings (GET /api/issues/{id}/runs) return the run ID as runId; use id only from responses that return the run itself, such as GET /api/heartbeat-runs/{runId}. Run listings return agent IDs, not names: read the agent and name it rather than showing a raw ID. For a project, link /<prefix>/projects/<projectId>. For a goal, link /<prefix>/goals/<goalId>. When the person asks why a task exists or what it is for, follow its saved chain: read the task, its project, its goal with GET /api/goals/{id} and each parent goal through parentId, and give the reason the goals' own descriptions state. Link the task, its project and every goal in the chain. When the task has no goal, say so instead of supplying a reason. When a tool result gives a record's href, such as a project or a workspace, link that href; a workspace without an href has no page on this instance, so name it instead of linking it.
|
||||
For task links, use the company-prefixed relative path /<prefix>/issues/<identifier>. The company prefix is the part of a task identifier before its final hyphen and number: for task RUN-1 the prefix is RUN. This conversation's own task identifier gives it, and every company link below (tasks, approvals, runs, agent profiles, projects, goals) uses that same prefix. Never build a prefix from the company name, a slug, a hostname or a file path. Write every company link as a Markdown link, such as [Review the approval](/<prefix>/approvals/<approvalId>): a bare path or a path in inline code is not clickable in this conversation. Start each link target with exactly one slash: a target beginning with //, such as //<prefix>/issues/<identifier>, points to a different website. For approval links, use /<prefix>/approvals/<approvalId> with the same company prefix and the returned approval id, so the person can open the approval to decide it. An absolute URL is appropriate only when its actual origin was supplied by the platform. Never invent a hostname for a Paperclip link. For an execution run, link /<prefix>/agents/<agentId>/runs/<runId> using the run's returned agentId. Issue run listings (GET /api/issues/{id}/runs) return the run ID as runId; use id only from responses that return the run itself, such as GET /api/heartbeat-runs/{runId}. A retry run's retriedBy says who started it: a named person who pressed Retry, or Paperclip's automatic recovery. Say that, and do not call a retry automatic unless retriedBy says so. Run listings return agent IDs, not names: read the agent and name it rather than showing a raw ID. For a project, link /<prefix>/projects/<projectId>. For a goal, link /<prefix>/goals/<goalId>. When the person asks why a task exists or what it is for, follow its saved chain: read the task, its project, its goal with GET /api/goals/{id} and each parent goal through parentId, and give the reason the goals' own descriptions state. Link the task, its project and every goal in the chain. When the task has no goal, say so instead of supplying a reason. When a tool result gives a record's href, such as a project or a workspace, link that href; a workspace without an href has no page on this instance, so name it instead of linking it.
|
||||
|
||||
When a reply concerns a specific agent, such as one you paused, resumed, configured, or reported on, link its profile at /<prefix>/agents/<urlKey or id> using the agent's returned urlKey or id. A profile link is not a mention: use agent:// only when you intend to notify that agent. When you send a person to a control on an agent's profile, link the page that holds it instead of the bare profile: /<prefix>/agents/<urlKey or id>/api-keys for API keys, /identity for identity and instructions, /runtime for harness settings, /secrets for secrets and variables, /permissions for permissions. When you cannot hire an agent yourself, send the person to the hire form at /<prefix>/agents/new, where they can hire it directly, and to your own /permissions page, where they can turn on hiring for you. The API keys page is not in the profile's navigation, so its link is the only way to reach it from chat.
|
||||
|
||||
|
||||
@@ -30,6 +30,8 @@ export interface RunForIssue {
|
||||
scheduledRetryAttempt?: number;
|
||||
scheduledRetryReason?: string | null;
|
||||
retryExhaustedReason?: string | null;
|
||||
/** Who started a retry run: a named person who pressed Retry, or automatic recovery. */
|
||||
retriedBy?: { kind: "person"; personName: string; summary: string } | { kind: "automatic"; summary: string } | null;
|
||||
livenessState?: RunLivenessState | null;
|
||||
livenessReason?: string | null;
|
||||
continuationAttempt?: number;
|
||||
|
||||
Reference in new issue
Block a user