Files
PaperClipAI/ui/src/components/issue-properties/context-usage-row.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

128 lines
4.6 KiB
TypeScript

import { useEffect, useRef } from "react";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import type { IssueContextCompaction, IssueContextUsage } from "@paperclipai/shared";
import { issuesApi } from "../../api/issues";
import { queryKeys } from "../../lib/queryKeys";
import { useOptionalToastActions } from "../../context/ToastContext";
import { QueryErrorState, useQueryView } from "../QueryView";
import { ContextUsageMeter, type ContextCompactState, type ContextUsage } from "../ContextUsageMeter";
import { PropertyRow } from "./primitives";
/** Refresh cadence while an agent run is reporting usage. */
const ACTIVE_RUN_REFRESH_MS = 8_000;
export function contextUsageFromIssue(value: IssueContextUsage): ContextUsage {
return {
usedTokens: value.usedTokens,
contextWindow: value.windowTokens,
totals: value.totals
? {
inputTokens: value.totals.inputTokens,
cachedInputTokens: value.totals.cachedInputTokens,
outputTokens: value.totals.outputTokens,
}
: null,
costUsd: value.costUsd,
observedAt: value.observedAt,
compactions: value.compactions,
};
}
/** Maps the server's Compact now state, with a click in flight shown as pending. */
export function contextCompactState(
compaction: IssueContextCompaction | undefined,
requesting: boolean,
onCompact: () => void,
): ContextCompactState | null {
if (!compaction) return null;
if (requesting || compaction.status === "pending") return { status: "pending" };
if (compaction.status === "unavailable") {
return { status: "unavailable", reason: compaction.reason ?? "Compaction is unavailable right now." };
}
return { status: "available", onCompact };
}
/**
* Context row for the task Properties panel. Renders nothing until the
* agent's harness has reported a context window for this task. A cached
* reading stays visible through a failed refresh; a failed first load shows
* the shared error state with Retry.
*/
export function IssueContextUsageRow({
issueId,
assigneeAgentId,
issueStatus,
hasActiveRun,
}: {
issueId: string;
/** The reading belongs to the assignee's session, so a reassignment refetches it. */
assigneeAgentId: string | null;
/** Compact now depends on the task being open, so a status change refreshes it. */
issueStatus?: string;
hasActiveRun: boolean;
}) {
const query = useQuery({
queryKey: queryKeys.issues.contextUsage(issueId, assigneeAgentId),
queryFn: () => issuesApi.getContextUsage(issueId),
refetchInterval: hasActiveRun ? ACTIVE_RUN_REFRESH_MS : false,
staleTime: hasActiveRun ? 0 : 60_000,
});
const view = useQueryView(query);
const queryClient = useQueryClient();
const toast = useOptionalToastActions();
const compact = useMutation({
mutationFn: () => issuesApi.compactContext(issueId),
onSettled: async () => {
// The compaction runs as a short agent run; refresh the run state that
// drives polling, then the reading itself.
await Promise.all([
queryClient.invalidateQueries({ queryKey: queryKeys.issues.activeRun(issueId) }),
queryClient.invalidateQueries({ queryKey: queryKeys.issues.liveRuns(issueId) }),
queryClient.invalidateQueries({ queryKey: queryKeys.issues.contextUsage(issueId, assigneeAgentId) }),
]);
},
onError: (error) => {
toast?.pushToast({
title: "Could not compact the context",
body: error instanceof Error ? error.message : "Try again in a moment.",
tone: "error",
});
},
});
// Pick up the final measurement once the run settles.
const wasActive = useRef(hasActiveRun);
const { refetch } = query;
useEffect(() => {
if (wasActive.current && !hasActiveRun) void refetch();
wasActive.current = hasActiveRun;
}, [hasActiveRun, refetch]);
const previousStatus = useRef(issueStatus);
useEffect(() => {
if (previousStatus.current !== issueStatus) void refetch();
previousStatus.current = issueStatus;
}, [issueStatus, refetch]);
if (view.data) {
return (
<PropertyRow label="Context">
<ContextUsageMeter
usage={contextUsageFromIssue(view.data)}
compact={contextCompactState(view.data.compaction, compact.isPending, () => compact.mutate())}
/>
</PropertyRow>
);
}
if (view.kind !== "error") return null;
return (
<PropertyRow label="Context">
<QueryErrorState
error={view.error}
size="inline"
action="load the context window"
onRetry={view.retry}
retrying={view.isFetching}
/>
</PropertyRow>
);
}