mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - A native run ends with one semantic report. A `paperclip_block`
report names a blocker, its owner and the unblock action
> - The status arbiter binds a task-wide blocker. When the owner is not
a person, it binds the blocker to the same agent and wakes that agent
> - The dispatcher refuses those self-wakes
(`chat_control_recovery_proof_unresolved`), because only continuation
and retry effects are proof for a native wake. The task then rests
blocked with no owner, no wake and no Retry
> - #21959 continues a system blocker in a fresh session, but only for
the reason codes `environment_unavailable` and `tool_unavailable`. A
restart-chaos rerun showed the same dead end with the reason code
`tool_output_failure`
> - This pull request makes sure that a blocker that the agent reports
for itself always has a next owner: the automatic environment lane, one
bounded self-continuation, or a person with a Retry that works
> - The benefit is that no task rests blocked with nobody to act, and no
path wakes the agent in a loop
## Linked Issues or Issue Description
Refs #21959
**What happened?**
A native OpenCode run (DeepSeek) said that every tool call returned the
text "cryptic". It reported `paperclip_block` with owner `{kind:
system}`, scope `task_wide`, reason code `tool_output_failure`, and an
unblock action about the tool-output failure. The run succeeded with
disposition `blocked`. The arbiter bound the blocker to the same agent
(`task_wide_blocker_bound`). The `notify-owner` wake coalesced, and the
`blocker-owner` wake was skipped as
`chat_control_recovery_proof_unresolved`. The task rested blocked
(`needs_attention`, 0 blockers), with no Retry and no wake. An earlier
rerun showed the same shape with reason code `environment_unavailable`,
which #21959 fixed for those two codes only.
**Expected behavior**
A blocker that the agent reports for its own tools or environment is a
harness problem. Paperclip continues it automatically, with a bound. A
blocker that the agent says it owns gets one fresh session. A blocker
that needs a person goes to a person, with a clear prompt and a Retry
that starts the task again. Nothing is left with nobody.
**Steps to reproduce**
1. Run a native task. Make the agent call `paperclip_block` with owner
kind `system`, scope `task_wide` and a reason code other than
`environment_unavailable` or `tool_unavailable` (for example
`tool_output_failure`).
2. See the decision `task_wide_blocker_bound` with the agent as the
unblock owner.
3. See both owner wakes refused, and the task blocked with no Retry.
**Paperclip version or commit**
`master` at 9e1a85fb46.
## What Changed
- `native-environment-blocker.ts`: a system-owned blocker now uses the
bounded fresh-session environment lane for any reason code, except the
person-only codes `permission_denied`, `credential_missing`,
`policy_restricted` and `budget_exhausted`. An agent-owned blocker with
`environment_unavailable` or `tool_unavailable` also uses it. The lane
is unchanged: at most 2 retries on the shared failure counter, then a
board blocker.
- New `native-agent-blocker.ts` and a new arbiter branch for a task-wide
blocker that is not person-owned, from the current owner's own succeeded
run (not a chat, not a review):
- Owner kind `agent`: one fresh-session continuation
(`native_agent_blocker_continuation`). It uses the shared failure
counter with a maximum of 1, so it never runs after another automatic
retry in the same chain. A paused task does not get it.
- All other cases, and a repeated blocker: the blocker goes to the board
with the agent's unblock action (`native_agent_blocker_needs_person`).
There is no self-wake.
- `native-provider-capacity-retry.ts`, `status-decision-committer.ts`,
`native-run-finalizer.ts`: materialize the continuation through the
existing fresh-session retry lane (`forceFreshSession`, `retryOfRunId`,
30 s delay, refuses a stopped run). Both new reason codes need the
provider-failure owner recheck under the issue lock. The finalizer reads
the pause hold for every blocked result.
- `heartbeat.ts`, `run-dispatch/adapters/postgres.ts`: the continuation
gets the same dispatch ownership checks as the environment retry.
- `task-interruption-presentation.ts`, shared
`TaskInterruptionPresentation.userAction`: a task that is blocked by a
`native_agent_blocker_needs_person` decision on its latest run shows
`userAction: "unblock"` with `canRetry: true`. `ExecutionBlockerNotice`
shows "The agent stopped and needs your help to continue. Read its last
comment, do what it asks, then Retry." with a Retry button. The inbox
label is "The agent needs your help". The assigned-work invariant reads
it as `assignee_declared_block`.
- `blocked-question-answer.ts`: an answer to the agent's open question
still wakes it after the new hand-off.
- Runner `completion-result.ts`: the "Paperclip continues this blocker
automatically" message now matches the server's environment lane.
- I did not change `readChatControlNativeParent`. The fix removes the
self-bound blocker wakes instead of accepting them as proof, so a
self-wake loop cannot form.
## Verification
- `cd server && npx vitest run
src/services/native-runtime/native-agent-blocker.integration.test.ts`
(new, embedded Postgres, real executor, finalizer and committer). Red
before the fix (3 of 3 fail with `task_wide_blocker_bound`), green
after:
- The t205 shape (system owner, `tool_output_failure`) gets one
fresh-session retry, no owner wakes, and the retry run that reports done
moves the task to `done`.
- An agent-owned blocker continues once. The same blocker in the
continuation goes to the board, with no further retry and no owner
wakes.
- A system blocker with `credential_missing` goes to the board with no
automatic retry.
- An external-owned blocker goes to the board. The task shows
`userAction: "unblock"` and `canRetry: true`. `requestTaskRetry` accepts
the Retry and `resumeTaskRetry` starts exactly one new run of the task.
- `npx vitest run src/services/native-runtime/status-arbiter.test.ts`:
new case for the once-only continuation, the hand-off, the pause hold,
the chat exclusion and the non-owner exclusion.
- `cd ui && npx vitest run
src/components/ExecutionBlockerNotice.test.tsx`: new case for the help
prompt and its Retry.
- `cd packages/paperclip-runner && npx vitest run
src/contracts/completion-result.test.ts`: new cases for the conflict
message.
- Related suites pass (11 files, 523 tests): arbiter corpus,
task-interruption presentation and query, assigned-work invariant,
blocked-question answer, liveness escalation, run-dispatch adapter,
failed-turn continuation, tool-receipt limit and provider capacity.
- `tsc --noEmit` passes for `server`, `packages/shared`,
`packages/paperclip-runner` and `ui` (only the existing generated
Storybook catalog errors). `scripts/check-token-gates.mjs` is clean.
- `pnpm verify` exits 2: the source SDK pin refresh is a global CI
input, so required CI supplies the broad coverage.
## Risks
- More automatic runs: an agent-owned blocker can add 1 run per chain,
and a system blocker with a new reason code can add up to 2 (the
existing lane). Both share the failure-retry counter, so a chain never
gets more than the existing maximum. The company-wide automatic-run
brake admits these runs like any other recovery run. Judge the change by
company-wide automatic run starts per hour and their success rate.
- A blocker that only a person can resolve, but that the agent labels as
its own, now takes one extra run (about 30 s later) before it reaches a
person. This is intended.
- Board-owned blockers now show an attention card and a Retry, where
before they named the agent and showed nothing. A Retry starts a new run
of the task; the person decides when.
- Previous release: no persisted shape changes. The new reason codes are
new values in existing text columns. Decisions saved by the previous
release keep their saved effects.
- Chats keep their current behavior, because the person in the chat
answers directly.
> 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
- Claude Opus 5.5 (Anthropic), model ID `claude-opus-5-5`, used through
Claude Code with tool use (code search, editing, shell, test runs).
## 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
- [ ] All Paperclip CI gates are green
- [ ] 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>
154 lines
11 KiB
TypeScript
154 lines
11 KiB
TypeScript
import { describeError } from "../api/errors";
|
||
import type { IssueRelationIssueSummary, TaskInterruptionPresentation } from "@paperclipai/shared";
|
||
import { AlertCircle } from "lucide-react";
|
||
import { Link } from "@/lib/router";
|
||
import { createIssueDetailPath } from "../lib/issueDetailBreadcrumb";
|
||
import { Button } from "./ui/button";
|
||
import { cn } from "../lib/utils";
|
||
import { useSecondTick } from "../hooks/useSecondTick";
|
||
import { TaskProjectAccessNotice } from "./TaskProjectAccessNotice";
|
||
import { ProviderFailureNotice } from "./ProviderFailureNotice";
|
||
import { LockedIssueChip, isLockedIssueStub } from "./LockedIssueChip";
|
||
import { PreviousServerStopConfirmation } from "./WorkspaceExportRecovery";
|
||
import { issuesApi } from "../api/issues";
|
||
|
||
const recoveryStepText: Record<NonNullable<TaskInterruptionPresentation["recoveryStep"]>, string> = {
|
||
checking_previous_run: "Checking that the previous attempt stopped",
|
||
saving_previous_files: "Saving files from the previous attempt",
|
||
finishing_recovery: "Finishing recovery of saved work",
|
||
};
|
||
|
||
/** A budget hard stop holds saved work. Only a task that already ran has an
|
||
* attempt to report; a task refused before its first run just waits. */
|
||
function budgetWaitText(presentation: TaskInterruptionPresentation) {
|
||
const wait = "It is waiting for the budget to allow new work. Raise the budget in Costs.";
|
||
return presentation.observedRunId || presentation.sourceRunIds.length
|
||
? `Couldn’t finish this attempt. Your message is saved. ${wait}`
|
||
: `This task has not started. ${wait}`;
|
||
}
|
||
const isBudgetWait = (presentation: TaskInterruptionPresentation | null | undefined) =>
|
||
presentation?.state === "waiting_for_user" && presentation.userAction === "budget";
|
||
|
||
const blockerAction: Record<string, string> = {
|
||
blocked: "Blocked: open it to Retry",
|
||
cancelled: "Cancelled: remove or replace it",
|
||
done: "Saving its files",
|
||
};
|
||
|
||
/** One ordinary interruption surface. Technical records remain in diagnostics. */
|
||
export function ExecutionBlockerNotice({ presentation, canRetry, onRetry, optimistic, takingLonger, error, className, issueId, companyId, agentName, projectName, blockers }: {
|
||
presentation: TaskInterruptionPresentation | null | undefined;
|
||
companyId?: string;
|
||
blockers?: IssueRelationIssueSummary[];
|
||
canRetry: boolean;
|
||
onRetry: () => void;
|
||
optimistic?: boolean;
|
||
takingLonger?: boolean;
|
||
error?: Error | null;
|
||
className?: string;
|
||
issueId?: string;
|
||
agentName?: string;
|
||
projectName?: string;
|
||
}) {
|
||
useSecondTick(presentation?.state === "retry_scheduled");
|
||
if (presentation?.projectAccess && !optimistic && !takingLonger) return <TaskProjectAccessNotice
|
||
access={presentation.projectAccess} issueId={issueId} agentName={agentName} projectName={projectName}
|
||
canRetry={canRetry && presentation.canRetry} onRetry={onRetry} error={error} className={className} />;
|
||
if (error && !optimistic && !takingLonger) return <div role="alert" className={cn("flex items-center justify-between gap-2 text-sm text-destructive", className)}><span>{describeError(error).body}</span>{canRetry && <Button variant="outline" size="sm" onClick={onRetry} data-testid="task-execution-retry">Retry</Button>}</div>;
|
||
if (takingLonger) return <div role="status" className={cn("flex items-center justify-between gap-2 text-sm text-muted-foreground", className)}><span>Taking longer than usual…</span>{canRetry && <Button variant="outline" size="sm" onClick={onRetry} data-testid="task-execution-retry">Retry</Button>}</div>;
|
||
const step = !optimistic && presentation?.responsibility === "system" && presentation.recoveryStep
|
||
&& ["working", "retry_scheduled"].includes(presentation.state) ? recoveryStepText[presentation.recoveryStep] : null;
|
||
const seconds = Math.max(0, Math.ceil((Date.parse(presentation?.nextRetryAt ?? "") - Date.now()) / 1000));
|
||
const retryIn = `Trying again in ${seconds > 60 ? `${Math.ceil(seconds / 60)}m` : `${seconds}s`}…`;
|
||
if (!optimistic && !presentation?.retryWait && presentation?.providerFailure && ["failed", "retry_scheduled", "waiting_for_user"].includes(presentation.state)) {
|
||
// Saved-work recovery is what the task waits for, so name it over the
|
||
// generic automatic-retry line while keeping the provider explanation.
|
||
return <ProviderFailureNotice failure={presentation.providerFailure} className={className}
|
||
actions={canRetry && presentation.canRetry ? <Button variant="outline" size="sm" onClick={onRetry} data-testid="task-execution-retry">Retry</Button> : undefined}>
|
||
{presentation.state === "retry_scheduled" && <p>{step ? `${step}. ${retryIn}` : "Paperclip will retry automatically."}</p>}
|
||
{isBudgetWait(presentation) && <p data-testid="task-execution-waiting">It is waiting for the budget to allow new work. Raise the budget in Costs.</p>}
|
||
</ProviderFailureNotice>;
|
||
}
|
||
if (step && presentation?.state === "working") return <div role="status" aria-label="Task status"
|
||
className={cn("text-sm text-muted-foreground", className)}>{`${step}…`}</div>;
|
||
if (!optimistic && presentation?.state === "working" && presentation.retryAction === "move_forward" && presentation.canRetry)
|
||
return <div role="status" aria-label="Task status" className={cn("flex items-center justify-between gap-3 text-sm text-muted-foreground", className)}>
|
||
<span className="min-w-0 flex-1">Waiting for the agent to finish other work. Paperclip continues this task by itself.</span>
|
||
{canRetry && <Button variant="outline" size="sm" className="shrink-0" onClick={onRetry} data-testid="task-execution-move-forward">Move it forward now</Button>}
|
||
</div>;
|
||
// A task that has not started yet names the admission hold it waits for.
|
||
if (!optimistic && presentation?.state === "working" && presentation.retryWait) {
|
||
const dependencies = presentation.retryWait.reason === "dependency_blocked" ? blockers ?? [] : [];
|
||
const unfinished = dependencies.filter(blocker => isLockedIssueStub(blocker) || blocker.status !== "done");
|
||
const waitingOn = unfinished.length ? unfinished : dependencies;
|
||
return <div role="status" aria-label="Task status" className={cn("text-sm text-muted-foreground", className)}>
|
||
<p>{presentation.retryWait.message}</p>
|
||
{waitingOn.length ? <ul className="mt-1 space-y-0.5" data-testid="retry-waiting-on">
|
||
{waitingOn.map(blocker => isLockedIssueStub(blocker)
|
||
? <li key={blocker.id} className="flex min-w-0 items-center gap-2"><LockedIssueChip identifier={blocker.identifier} /></li>
|
||
: <li key={blocker.id} className="flex min-w-0 items-center gap-2">
|
||
<Link to={createIssueDetailPath(blocker.identifier ?? blocker.id)}
|
||
className="font-mono text-xs text-foreground underline-offset-2 hover:underline">
|
||
{blocker.identifier ?? "Task"}
|
||
</Link>
|
||
<span className="min-w-0 truncate">{blocker.title}</span>
|
||
<span className="shrink-0 text-xs">{blockerAction[blocker.status] ?? blocker.status.replace(/_/g, " ")}</span>
|
||
</li>)}
|
||
</ul> : null}
|
||
</div>;
|
||
}
|
||
if (!optimistic && presentation?.userAction === "confirm_run_stopped" && presentation.observedRunId && issueId && companyId) {
|
||
const runId = presentation.observedRunId;
|
||
return <PreviousServerStopConfirmation key={`${issueId}:${runId}`} runId={runId} formId={runId} issueId={issueId} companyId={companyId}
|
||
className={className} confirmStop={stopEvidence => issuesApi.confirmRunStopped(issueId, { runId, stopEvidence })}
|
||
copy={{ waiting: presentation.retryWait?.message ?? "Paperclip can't confirm that the previous run stopped. Your message is saved.",
|
||
question: "How did you confirm that no agent is still working on this task?",
|
||
placeholder: "For example: no codex or claude process for this task is running on the server host.",
|
||
resuming: "Starting your Retry…", confirm: "Confirm it stopped" }} />;
|
||
}
|
||
// Other person-owned decisions have their own card on the task (approval,
|
||
// project access, ...). A budget hold has none, so name it here and keep the
|
||
// failure visible. The saved attempt starts by itself once the budget allows.
|
||
if (!optimistic && presentation && isBudgetWait(presentation)) return (
|
||
<div className={cn("pt-4", className)}>
|
||
<div role="status" aria-label="Task status" data-testid="task-execution-waiting"
|
||
className="flex items-center gap-3 rounded-lg bg-destructive/10 p-4 text-sm text-foreground">
|
||
<AlertCircle className="size-5 shrink-0 text-destructive" aria-hidden="true" />
|
||
<span className="min-w-0 flex-1">{budgetWaitText(presentation)}</span>
|
||
</div>
|
||
</div>
|
||
);
|
||
if (!optimistic && presentation?.userAction === "unblock") return (
|
||
<div className={cn("pt-4", className)}>
|
||
<div role="status" aria-label="Task status" data-testid="task-execution-waiting"
|
||
className="flex items-center justify-between gap-3 rounded-lg bg-destructive/10 p-4 text-sm text-foreground">
|
||
<AlertCircle className="size-5 shrink-0 text-destructive" aria-hidden="true" />
|
||
<span className="min-w-0 flex-1">The agent stopped and needs your help to continue. Read its last comment, do what it asks, then Retry.</span>
|
||
{canRetry && presentation.canRetry && <Button variant="outline" size="sm" className="shrink-0" onClick={onRetry} data-testid="task-execution-retry">Retry</Button>}
|
||
</div>
|
||
</div>
|
||
);
|
||
if (optimistic || !presentation || presentation.responsibility !== "system" ||
|
||
!["failed", "retry_scheduled"].includes(presentation.state)) return null;
|
||
return (
|
||
<div className={cn(presentation.state === "failed" && "pt-4", className)}>
|
||
<div role="status" aria-label="Task status" className={cn(
|
||
"flex items-center justify-between gap-3 text-sm",
|
||
presentation.state === "failed" ? "rounded-lg bg-destructive/10 p-4 text-foreground" : "text-muted-foreground",
|
||
)}>
|
||
{presentation.state === "failed" && <AlertCircle className="size-5 shrink-0 text-destructive" aria-hidden="true" />}
|
||
<span className="min-w-0 flex-1">{presentation.state === "retry_scheduled"
|
||
? step ? `${step}. ${retryIn}`
|
||
: presentation.setupFailure ? `${presentation.setupFailure.message}. ${retryIn}` : retryIn
|
||
: presentation.retryWait ? presentation.retryWait.message
|
||
: presentation.workspaceFailure
|
||
? <>Couldn’t prepare the task folders. {presentation.workspaceFailure.message}</>
|
||
: presentation.setupFailure
|
||
? <>Couldn’t set up the task workspace. {presentation.setupFailure.message}. Fix the command in the project’s workspace settings, then retry.</>
|
||
: "Couldn’t finish this attempt. Your message is saved."}</span>
|
||
{canRetry && presentation.canRetry && <Button variant="outline" size="sm" className="shrink-0" onClick={onRetry} data-testid="task-execution-retry">Retry</Button>}
|
||
</div>
|
||
</div>
|
||
);
|
||
}
|