Files
PaperClipAI/ui/src/components/issue-properties/context-usage-row.test.tsx
T
DottaandClaude Opus 5.5 6ca7b151f7 feat: compact an agent's context from the task Properties panel (#19378)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - A task's Properties panel shows the assignee agent's context window
(paperclipai/paperclip#19273)
> - The board can see that the context is nearly full, but it cannot act
on it
> - A full context makes the agent compact at an unplanned time, often
in the middle of work
> - This pull request adds "Compact now" to the Context hover card
> - The benefit is that the board can compact the agent's context
between runs, at a time it chooses

## Linked Issues or Issue Description

Refs paperclipai/paperclip#19273

**Problem**
The Context row shows how full the agent's context window is. The board
cannot ask the agent to compact it.

**Proposed solution**
A "Compact now" button in the Context hover card. It runs the harness's
own compaction: Codex `thread/compact/start`, and Claude's `/compact`
command through ACP.

**Alternatives considered**
A separate PRP `session.compact` command. Both harnesses run compaction
as a turn, so a compaction turn keeps the existing durable turn binding,
interruption, and recovery. A separate command needs a second turn
lifecycle.

## What Changed

- UI: the Context hover card shows Compact now with three states:
available, Compacting…, and unavailable with a reason (agent mid-run,
harness unsupported, task closed). The Storybook story shows each state.
- Server: `POST /api/issues/:id/context/compact` (board only,
`decideIssueAccess` `issue:mutate`, activity log
`issue.context_compaction_requested`). It queues a short run marked by
`contextSnapshot.contextCompactionRequestId`. `GET
/issues/:id/context-usage` returns the `compaction` state.
- Server: a compaction run does no task work. The native status arbiter
preserves the task status. The lifecycle skips handoff, liveness
continuation, review-path disposition and the issue comment, as it does
for goal-control runs.
- Runner TS: `startTurn({ compact: true })`. The Codex harness session
sends `thread/compact/start`. The runnerd transport maps it to PRP
`turn.start` with `compact: true` (Codex) or `text: "/compact"`
(Claude/ACPX). The native runtime option `sessionCompaction` requires a
resumed session and settles with a synthesized yielded result.
- Runner Rust: `turn.start` accepts `compact: true` for Codex.
`CodexProvider::start_compaction_turn` sends `thread/compact/start` and
binds the turn from the `turn/started` that follows the empty response.
- Fix (from #19273): Codex emitted `context.compacted` on both the start
and the end of one compaction item. It now emits it once, and the count
is distinct by `compactionId`.
- Fix (from #19273): the conversation event view dropped
`context.compacted`, so a finished run never showed the divider. The
view now keeps compactions, plus context readings for runs that
compacted. A finished run's compactions show as thread dividers.
- Fix: the Codex harness stamps before/after sizes on the compaction
event. Codex reports the compacted size before the compaction item ends,
so the old neighbour-based guess showed the wrong size.

## Verification

- `pnpm -r typecheck`, `pnpm build`, `pnpm check:token-gates`, `node
scripts/storybook-catalog.mjs`: pass.
- New tests: `server/src/__tests__/context-compaction.test.ts`,
`status-arbiter.test.ts`, `issue-context-usage.test.ts` (duplicate
compaction counts once), `ui/.../context-usage-row.test.tsx`,
`native-session-runtime.test.ts` (context compaction), Codex driver and
runnerd transport tests, Rust
`codex_compaction_turn_binds_the_turn_reported_after_its_empty_response`.
Rust `codex_provider` suite: 115 passed.
- `pnpm test:run` locally: one failure in
`chat-channels.integration.test.ts`. It reads
`.claude/skills/slack/SKILL.md` from the main checkout, which is not
present in this worktree. It is not related to this change.
- Live, local worktree instance, Codex agent on the Paperclip runner:
clicked Compact now. The run succeeded. Context went from 35k to 9.4k
tokens, and later 9.4k to 9.2k. The task stayed In Review. The thread
shows "Context compacted · 9.4k → 9.2k tokens" and the meter dropped.
- Live Claude proof: pending. The local Claude agent needs an Anthropic
API key. claude-agent-acp handles `/compact` as an echo-less turn, and
the runner already maps its "Compacting completed." notice to
`context.compacted`.

## Risks

- A compaction run resumes the agent's session. If the session cannot
resume, the run fails with `native_context_compaction_unavailable` and
the task is unchanged.
- Compact now is not available while the agent runs on the task, because
compaction interrupts the active turn.
- The conversation view now returns context readings for runs that
compacted. Runs that never compacted return the same events as before.
- An old runner binary ignores `compact` and rejects the `turn.start`
because it has no text. It does not start an ordinary turn.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, 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
- [ ] 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>
2026-11-05 22:07:12 -06:00

133 lines
5.7 KiB
TypeScript

// @vitest-environment jsdom
import { flushSync } from "react-dom";
import { createRoot, type Root } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
const api = vi.hoisted(() => ({ getContextUsage: vi.fn(), compactContext: vi.fn() }));
vi.mock("@/api/issues", () => ({ issuesApi: { getContextUsage: api.getContextUsage, compactContext: api.compactContext } }));
import { ApiError } from "@/api/api-error";
import { IssueContextUsageRow } from "./context-usage-row";
async function settle() {
for (let i = 0; i < 8; i++) { await new Promise(resolve => setTimeout(resolve, 0)); flushSync(() => {}); }
}
let root: Root;
let container: HTMLDivElement;
let client: QueryClient;
beforeEach(() => {
vi.resetAllMocks();
container = document.createElement("div");
document.body.append(container);
root = createRoot(container);
client = new QueryClient({ defaultOptions: { queries: { retry: false } } });
});
afterEach(() => {
flushSync(() => root.unmount());
client.clear();
document.body.innerHTML = "";
});
function render(assigneeAgentId: string | null = "agent-1", issueStatus = "in_progress") {
flushSync(() => root.render(
<QueryClientProvider client={client}>
<IssueContextUsageRow issueId="issue-1" assigneeAgentId={assigneeAgentId} issueStatus={issueStatus} hasActiveRun={false} />
</QueryClientProvider>,
));
}
const reading = {
runId: "run-1", agentId: "agent-1", sessionId: "session-1", usedTokens: 26_672, windowTokens: 258_400,
observedAt: new Date().toISOString(), totals: null, costUsd: null, compactions: 0,
};
describe("IssueContextUsageRow", () => {
it("stays hidden until the session reports a context window", async () => {
api.getContextUsage.mockResolvedValue(null);
render(); await settle();
expect(container.textContent).toBe("");
});
it("shows the reading", async () => {
api.getContextUsage.mockResolvedValue(reading);
render(); await settle();
expect(container.textContent).toContain("10%");
expect(container.textContent).toContain("of 258k");
});
it("shows a failed request with a retry that recovers", async () => {
api.getContextUsage
.mockRejectedValueOnce(new ApiError("Internal error", 500, { error: "internal" }))
.mockResolvedValue(reading);
render(); await settle();
const retry = [...container.querySelectorAll("button")].find((button) => button.textContent?.includes("Retry"));
expect(retry).toBeTruthy();
retry!.click(); await settle();
expect(container.textContent).toContain("10%");
});
it("drops the previous assignee's reading after an idle reassignment", async () => {
api.getContextUsage.mockResolvedValueOnce(reading).mockResolvedValueOnce(null);
render("agent-1"); await settle();
expect(container.textContent).toContain("10%");
render("agent-2"); await settle();
expect(api.getContextUsage).toHaveBeenCalledTimes(2);
expect(container.textContent).toBe("");
});
function openCard() {
const trigger = container.querySelector<HTMLButtonElement>("[data-testid=context-usage-meter]");
expect(trigger).toBeTruthy();
flushSync(() => trigger!.click());
return document.body.querySelector<HTMLButtonElement>("[data-testid=context-usage-compact]");
}
it("asks the agent to compact from the hover card", async () => {
api.getContextUsage.mockResolvedValue({ ...reading, compaction: { status: "available", reasonCode: null, reason: null } });
api.compactContext.mockReturnValue(new Promise(() => {}));
render(); await settle();
const button = openCard();
expect(button?.textContent).toContain("Compact now");
expect(button?.disabled).toBe(false);
flushSync(() => button!.click()); await settle();
expect(api.compactContext).toHaveBeenCalledWith("issue-1");
expect(document.body.querySelector("[data-testid=context-usage-compact]")?.textContent).toContain("Compacting…");
});
it("explains why compaction is unavailable", async () => {
api.getContextUsage.mockResolvedValue({
...reading,
compaction: { status: "unavailable", reasonCode: "agent_busy", reason: "Available when the agent finishes its current run." },
});
render(); await settle();
const button = openCard();
expect(button?.disabled).toBe(true);
expect(document.body.textContent).toContain("Available when the agent finishes its current run.");
});
it("refreshes Compact now when the task status changes", async () => {
api.getContextUsage
.mockResolvedValueOnce({ ...reading, compaction: { status: "available", reasonCode: null, reason: null } })
.mockResolvedValue({ ...reading, compaction: { status: "unavailable", reasonCode: "task_closed", reason: "Available while the task is open." } });
render("agent-1", "in_progress"); await settle();
render("agent-1", "done"); await settle();
expect(api.getContextUsage).toHaveBeenCalledTimes(2);
expect(openCard()?.disabled).toBe(true);
});
it("shows a compaction already in progress", async () => {
api.getContextUsage.mockResolvedValue({ ...reading, compaction: { status: "pending", reasonCode: null, reason: null, runId: "run-2" } });
render(); await settle();
const button = openCard();
expect(button?.disabled).toBe(true);
expect(button?.textContent).toContain("Compacting…");
});
it("keeps the last reading when a refresh fails", async () => {
api.getContextUsage.mockResolvedValueOnce(reading).mockRejectedValue(new ApiError("Internal error", 500, { error: "internal" }));
render(); await settle();
await client.refetchQueries(); await settle();
expect(container.textContent).toContain("10%");
});
});