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 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>
128 lines
4.6 KiB
TypeScript
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>
|
|
);
|
|
}
|