mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 11:54:35 +01:00
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - The task page shows one execution notice above the conversation
(`ExecutionBlockerNotice`). A red, tinted notice with an error icon is
for an attempt that failed and stopped retrying
> - #22140 sends a task-wide blocker to the board when its owner is not
a person kind (for example `external`), or when an agent blocker
repeats. The task shows `userAction: "unblock"`
> - For `unblock`, the notice showed the red failure notice: "The agent
stopped and needs your help to continue. Read its last comment, do what
it asks, then Retry."
> - But nothing failed. The agent finished its run and correctly
reported that it waits for a person. A blocker with owner kind `user`
shows no notice at all, so the two cases look different for the same
situation
> - This pull request removes the red notice for `unblock`. The task
looks like any other task that is blocked on a person
> - The benefit is that a red error notice appears only for a real
failure
## Linked Issues or Issue Description
Refs #22140
**What happened?**
An agent reported a task-wide blocker. The owner was an outside operator
(owner kind `external`). Paperclip sent the blocker to the board and set
the task to Blocked. The task page then showed a large red notice: "The
agent stopped and needs your help to continue. Read its last comment, do
what it asks, then Retry." The task did not fail. It waits for a person.
**Expected behavior**
A task that waits for a person shows no failure notice. The Blocked
status, the agent's last comment and the reply box tell the person what
to do, as for a blocker with owner kind `user`.
**Steps to reproduce**
1. Run a native task. Make the agent call `paperclip_block` with owner
kind `external`, scope `task_wide`.
2. See the decision `native_agent_blocker_needs_person` and the task
status Blocked.
3. Open the task. See the red "The agent stopped and needs your help"
notice with Retry.
**Paperclip version or commit**
`master` at 1355f93546.
## What Changed
- `ui/src/components/ExecutionBlockerNotice.tsx`: removed the red notice
for `userAction: "unblock"`. The component now shows no notice for it,
the same as for other person-owned blockers.
- `ui/src/components/ExecutionBlockerNotice.test.tsx`: the `unblock`
test now expects no notice.
- No server change. The server still projects `userAction: "unblock"`
with `canRetry: true`. The inbox row label ("The agent needs your
help"), the board attention item ("Unblock") and the Retry API stay the
same.
## Verification
- Red before the fix: `cd ui && npx vitest run
src/components/ExecutionBlockerNotice.test.tsx` failed. The notice
rendered "The agent stopped and needs your help to continue. … Retry".
- Green after the fix: the same command passes (24 tests).
- `cd ui && npx vitest run` on all 17 UI test files that reference the
task interruption, `ExecutionBlockerNotice`, or its Retry and waiting
handles (including `IssueDetail.test.tsx`, `Inbox.test.tsx`,
`useTaskRetry.test.tsx`, `TaskChatThread.test.tsx`): 1327 passed, 1
skipped.
- `cd ui && npx tsc --noEmit`: no errors in the changed files. The local
run showed 21 errors in other files: the generated Storybook catalog,
`PluginOrganizationSwitcher` and `paperclip-runner`
`replay-contract.ts`. The local install was partial (UI packages only,
no build scripts) because the disk was full, so these errors come from
the environment. Required CI covers the full typecheck.
- Not run: `pnpm verify`. It selects 616 test files conservatively and
needs the CLI packages, which the partial install did not include. Not
run: a live browser check. Required CI supplies the broad coverage.
## Risks
- Low risk. This is a UI-only change.
- The task page no longer shows a Retry button for this hand-off. A
person continues the task with a reply: a person's comment on a Blocked
task that has an agent assignee moves it to Todo and wakes the agent.
Retry is still available from the inbox row, and the Retry API is
unchanged.
> 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
- [ ] 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>
238 lines
16 KiB
TypeScript
238 lines
16 KiB
TypeScript
// @vitest-environment jsdom
|
||
import { act } from "react";
|
||
import { createRoot, type Root } from "react-dom/client";
|
||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||
import type { TaskInterruptionPresentation } from "@paperclipai/shared";
|
||
import type { AnchorHTMLAttributes } from "react";
|
||
import { ExecutionBlockerNotice } from "./ExecutionBlockerNotice";
|
||
|
||
vi.mock("@/lib/router", () => ({
|
||
Link: ({ children, to, ...props }: AnchorHTMLAttributes<HTMLAnchorElement> & { to: string }) => <a href={to} {...props}>{children}</a>,
|
||
}));
|
||
|
||
const failed: TaskInterruptionPresentation = {
|
||
intentId: "intent", responsibility: "system", state: "failed", nextRetryAt: null,
|
||
canRetry: true, userAction: null, sourceRunIds: ["source"], observedRunId: "source",
|
||
};
|
||
describe("ordinary task interruption", () => {
|
||
let root: Root;
|
||
let container: HTMLDivElement;
|
||
const retry = vi.fn();
|
||
beforeEach(() => {
|
||
retry.mockReset(); container = document.createElement("div"); document.body.append(container);
|
||
root = createRoot(container);
|
||
});
|
||
afterEach(async () => { await act(async () => root.unmount()); container.remove(); vi.useRealTimers(); });
|
||
const render = async (presentation = failed, options: { canRetry?: boolean; optimistic?: boolean; takingLonger?: boolean; error?: Error } = {}) => {
|
||
await act(async () => root.render(<ExecutionBlockerNotice presentation={presentation} canRetry onRetry={retry} {...options} />));
|
||
};
|
||
it("offers one Retry without delegating infrastructure chores", async () => {
|
||
await render();
|
||
expect(container.textContent).toContain("Couldn’t finish this attempt. Your message is saved.");
|
||
expect(container.querySelectorAll("button")).toHaveLength(1);
|
||
// A stable handle for the task's own Retry, the supported path after
|
||
// automatic recovery stops.
|
||
expect(container.querySelector('[data-testid="task-execution-retry"]')?.textContent).toBe("Retry");
|
||
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
|
||
expect(retry).toHaveBeenCalledOnce();
|
||
expect(container.querySelector("a, details, input, textarea")).toBeNull();
|
||
expect(container.textContent).not.toMatch(/service attention|process|receipt|workspace/i);
|
||
});
|
||
it("does not report a failed attempt for a task the agent handed to a person", async () => {
|
||
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "unblock" });
|
||
expect(container.textContent).toBe("");
|
||
});
|
||
|
||
it.each([false, true])("names the question without repeating a historical failure (manual Retry=%s)", async canRetry => {
|
||
const presentation = { ...failed, responsibility: "user" as const, state: "waiting_for_user" as const, userAction: "question" as const, canRetry,
|
||
providerFailure: { schema: "paperclip.provider-failure.v1", provider: "anthropic", phase: "startup",
|
||
category: "rate_limit", httpStatus: 429, retryability: "unknown", message: "API error: 429" } } satisfies TaskInterruptionPresentation;
|
||
await render(presentation);
|
||
expect(container.textContent).toContain("Respond to the pending question to continue.");
|
||
expect(container.textContent).not.toMatch(/429|rate limit|failed/i);
|
||
expect(Boolean(container.querySelector("button"))).toBe(canRetry);
|
||
if (canRetry) {
|
||
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
|
||
expect(retry).toHaveBeenCalledOnce();
|
||
}
|
||
await render(presentation, { canRetry: false });
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
|
||
it("keeps the failure visible and names the gate while a saved Retry waits on the budget", async () => {
|
||
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "budget", canRetry: false });
|
||
const notice = container.querySelector('[data-testid="task-execution-waiting"]');
|
||
expect(notice?.textContent).toContain("Couldn’t finish this attempt. Your message is saved.");
|
||
expect(notice?.textContent).toContain("waiting for the budget to allow new work");
|
||
// The saved Retry starts by itself; a second Retry would only duplicate it.
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
|
||
it("does not report a failed attempt for a task the budget held before its first run", async () => {
|
||
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "budget", canRetry: false,
|
||
sourceRunIds: [], observedRunId: null });
|
||
const notice = container.querySelector('[data-testid="task-execution-waiting"]');
|
||
expect(notice?.textContent).toContain("This task has not started.");
|
||
expect(notice?.textContent).not.toContain("Couldn’t finish this attempt");
|
||
});
|
||
|
||
it("shows persisted backoff with a usable Retry", async () => {
|
||
vi.useFakeTimers(); vi.setSystemTime(new Date("2026-10-20T00:00:00Z"));
|
||
await render({ ...failed, state: "retry_scheduled", nextRetryAt: "2026-10-20T00:00:30Z" });
|
||
expect(container.textContent).toContain("Trying again in 30s");
|
||
await act(async () => { await vi.advanceTimersByTimeAsync(5_000); });
|
||
expect(container.textContent).toContain("Trying again in 25s");
|
||
expect(container.querySelector("button")?.textContent).toBe("Retry");
|
||
});
|
||
it.each(["working", "resolved"] as const)("does not duplicate the thread indicator for %s", async state => {
|
||
await render({ ...failed, state }); expect(container.textContent).toBe("");
|
||
});
|
||
it("offers to move a waiting continuation forward in plain words, without reporting a failure", async () => {
|
||
await render({ ...failed, state: "working", retryAction: "move_forward" });
|
||
expect(container.textContent).toContain("Paperclip continues this task by itself.");
|
||
expect(container.textContent).not.toMatch(/Couldn’t finish|failed|continuation|queue|run\b/i);
|
||
const button = container.querySelector<HTMLButtonElement>('[data-testid="task-execution-move-forward"]');
|
||
expect(button?.textContent).toBe("Move it forward now");
|
||
expect(container.querySelectorAll("button")).toHaveLength(1);
|
||
await act(async () => button!.click());
|
||
expect(retry).toHaveBeenCalledOnce();
|
||
});
|
||
|
||
it("shows a waiting continuation without the button to a read-only user, or once the move was requested", async () => {
|
||
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", retryAction: "move_forward" }}
|
||
canRetry={false} onRetry={retry} />));
|
||
expect(container.textContent).toContain("Paperclip continues this task by itself.");
|
||
expect(container.querySelector("button")).toBeNull();
|
||
await render({ ...failed, state: "working", canRetry: false });
|
||
expect(container.textContent).toBe("");
|
||
});
|
||
|
||
it("names the admission hold a task that has not started waits for", async () => {
|
||
await render({ ...failed, state: "working", canRetry: false, sourceRunIds: [], observedRunId: null,
|
||
retryWait: { reason: "budget.blocked", message: "Waiting for the budget to allow new work. The task starts automatically when it does." } });
|
||
expect(container.textContent).toBe("Waiting for the budget to allow new work. The task starts automatically when it does.");
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
it("names and links the readable blockers a saved Retry waits on, with no second Retry (restart chaos t05)", async () => {
|
||
const message = "Retry is waiting on a blocked task this one depends on. Retry or unblock it; this task continues when it is done. Your Retry is saved.";
|
||
const summary = (id: string, identifier: string, title: string, status: string) =>
|
||
({ id, identifier, title, status, priority: "medium", assigneeAgentId: null, assigneeUserId: null }) as never;
|
||
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", canRetry: false,
|
||
retryWait: { reason: "dependency_blocked", message } }} canRetry onRetry={retry}
|
||
blockers={[summary("child", "CHA-10", "Part 2", "blocked"), summary("gone", "CHA-11", "Part 3", "cancelled"),
|
||
summary("done", "CHA-9", "Part 1", "done")]} />));
|
||
expect(container.textContent).toContain(message);
|
||
const links = [...container.querySelectorAll<HTMLAnchorElement>("[data-testid='retry-waiting-on'] a")].map(link => link.getAttribute("href"));
|
||
expect(links).toHaveLength(2);
|
||
expect(links[0]).toContain("CHA-10");
|
||
expect(container.textContent).toContain("Blocked: open it to Retry");
|
||
expect(container.textContent).toContain("Cancelled: remove or replace it");
|
||
expect(container.textContent).not.toContain("Part 1");
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
it("shows a locked blocker without reading its status, and a finished blocker still saving files", async () => {
|
||
const message = "Retry is waiting for a finished task this one depends on to save its files. Your Retry is saved.";
|
||
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", canRetry: false,
|
||
retryWait: { reason: "dependency_blocked", message } }} canRetry onRetry={retry}
|
||
blockers={[{ id: "secret", identifier: "CHA-12", locked: true } as never]} />));
|
||
expect(container.querySelector("[data-testid='locked-issue-chip']")?.textContent).toContain("CHA-12");
|
||
await act(async () => root.render(<ExecutionBlockerNotice presentation={{ ...failed, state: "working", canRetry: false,
|
||
retryWait: { reason: "dependency_blocked", message } }} canRetry onRetry={retry}
|
||
blockers={[{ id: "done", identifier: "CHA-9", title: "Part 1", status: "done", priority: "medium",
|
||
assigneeAgentId: null, assigneeUserId: null } as never]} />));
|
||
expect(container.querySelector("[data-testid='retry-waiting-on'] a")?.getAttribute("href")).toContain("CHA-9");
|
||
expect(container.textContent).toContain("Saving its files");
|
||
});
|
||
it("names the saved-work recovery step instead of a bare queue", async () => {
|
||
await render({ ...failed, state: "working", canRetry: false, recoveryStep: "saving_previous_files" });
|
||
expect(container.textContent).toBe("Saving files from the previous attempt…");
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
it("names the step a scheduled recovery will retry", async () => {
|
||
vi.useFakeTimers(); vi.setSystemTime(new Date("2026-10-20T00:00:00Z"));
|
||
await render({ ...failed, state: "retry_scheduled", nextRetryAt: "2026-10-20T00:00:30Z", recoveryStep: "checking_previous_run" });
|
||
expect(container.textContent).toContain("Checking that the previous attempt stopped. Trying again in 30s…");
|
||
expect(container.querySelector("button")?.textContent).toBe("Retry");
|
||
});
|
||
it("names the recovery step inside a provider failure notice", async () => {
|
||
vi.useFakeTimers(); vi.setSystemTime(new Date("2026-10-20T00:00:00Z"));
|
||
await render({ ...failed, state: "retry_scheduled", nextRetryAt: "2026-10-20T00:00:30Z", recoveryStep: "checking_previous_run",
|
||
providerFailure: { schema: "paperclip.provider-failure.v1", provider: "openai", phase: "startup", category: "overloaded",
|
||
retryability: "unknown", message: "Try later." } });
|
||
expect(container.textContent).toContain("Checking that the previous attempt stopped. Trying again in 30s…");
|
||
expect(container.textContent).not.toContain("Paperclip will retry automatically.");
|
||
});
|
||
it("leaves genuine user decisions to their specific action surface", async () => {
|
||
await render({ ...failed, responsibility: "user", state: "waiting_for_user", userAction: "approval", canRetry: false });
|
||
expect(container.textContent).toBe("");
|
||
});
|
||
it("does not give read-only users a mutation", async () => {
|
||
await render(failed, { canRetry: false }); expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
it("removes the stale failure immediately while admission is pending", async () => {
|
||
await render(failed, { optimistic: true }); expect(container.textContent).toBe("");
|
||
await render(failed, { optimistic: true, takingLonger: true });
|
||
expect(container.textContent).toContain("Taking longer than usual…");
|
||
});
|
||
it("shows a definitive admission rejection instead of silently dropping Retry", async () => {
|
||
await render(failed, { error: new Error("Your task access changed. Refresh the task.") });
|
||
expect(container.querySelector('[role="alert"]')?.textContent).toContain("Your task access changed.");
|
||
expect(container.querySelectorAll("button")).toHaveLength(1);
|
||
});
|
||
it("shows workspace preparation failures as plain text while keeping retry permissions", async () => {
|
||
const workspaceFailure = { message: 'Could not prepare the project folder <img src=x onerror=alert(1)>.' };
|
||
await render({ ...failed, workspaceFailure }, { canRetry: false });
|
||
expect(container.textContent).toContain("Couldn’t prepare the task folders.");
|
||
expect(container.textContent).toContain(workspaceFailure.message);
|
||
expect(container.querySelector("img, button")).toBeNull();
|
||
await render({ ...failed, workspaceFailure });
|
||
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
|
||
expect(retry).toHaveBeenCalledOnce();
|
||
await render({ ...failed, workspaceFailure, state: "working" });
|
||
expect(container.textContent).toBe("");
|
||
});
|
||
it("names a failed workspace setup command and what to change, keeping Retry", async () => {
|
||
const setupFailure = { step: "workspace_provision" as const, command: "bash ./scripts/provision-worktree.sh", exitCode: 127,
|
||
output: "bash: ./scripts/provision-worktree.sh: No such file or directory",
|
||
message: "The project's workspace provision command \"bash ./scripts/provision-worktree.sh\" failed with exit code 127: bash: ./scripts/provision-worktree.sh: No such file or directory" };
|
||
await render({ ...failed, setupFailure });
|
||
expect(container.textContent).toContain("Couldn’t set up the task workspace.");
|
||
expect(container.textContent).toContain(setupFailure.message);
|
||
expect(container.textContent).toContain("Fix the command in the project’s workspace settings");
|
||
expect(container.textContent).not.toContain("Couldn’t finish this attempt.");
|
||
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
|
||
expect(retry).toHaveBeenCalledOnce();
|
||
});
|
||
it("shows why an accepted Retry is waiting and keeps another attempt available", async () => {
|
||
const retryWait = { reason: "remote_cleanup", message: "Retry is waiting for the previous environment to stop. Your message is saved." };
|
||
await render({ ...failed, retryWait });
|
||
expect(container.textContent).toContain(retryWait.message);
|
||
expect(container.textContent).not.toContain("Couldn’t finish this attempt.");
|
||
await act(async () => container.querySelector<HTMLButtonElement>("button")!.click());
|
||
expect(retry).toHaveBeenCalledOnce();
|
||
await render({ ...failed, retryWait }, { canRetry: false });
|
||
expect(container.textContent).toContain(retryWait.message);
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
it("names the budget wait alongside a provider failure while a saved Retry is held", async () => {
|
||
const providerFailure = { schema: "paperclip.provider-failure.v1" as const, provider: "openai", phase: "startup" as const,
|
||
category: "overloaded" as const, retryability: "transient" as const, message: "Provider overloaded" };
|
||
await render({ ...failed, providerFailure, responsibility: "user", state: "waiting_for_user", userAction: "budget", canRetry: false });
|
||
expect(container.textContent).toContain("Provider overloaded");
|
||
expect(container.querySelector('[data-testid="task-execution-waiting"]')?.textContent).toContain("waiting for the budget to allow new work");
|
||
expect(container.querySelector("button")).toBeNull();
|
||
});
|
||
it("shows an unknown provider's original explanation as text and preserves read-only access", async () => {
|
||
const providerFailure = { schema: "paperclip.provider-failure.v1" as const, provider: "new-provider", phase: "startup" as const,
|
||
category: "unknown" as const, retryability: "unknown" as const, httpStatus: 429,
|
||
message: "Upstream failure <img src=x onerror=alert(1)>" };
|
||
await render({ ...failed, providerFailure }, { canRetry: false });
|
||
expect(container.textContent).toContain(providerFailure.message);
|
||
expect(container.textContent).toContain("Failed before work started");
|
||
expect(container.textContent).toContain("HTTP 429");
|
||
expect(container.querySelector("img, button")).toBeNull();
|
||
await render({ ...failed, providerFailure, state: "resolved" });
|
||
expect(container.textContent).toBe("");
|
||
});
|
||
});
|