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>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-05 22:07:12 -06:00
1 parent 240d46e2ec
commit 6ca7b151f7
48 files changed
+1431 -66

No files matched your search

@@ -0,0 +1,106 @@
import { randomUUID } from "node:crypto";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import { agents, companies, createDb, heartbeatRuns, issues } from "@paperclipai/db";
import {
ContextCompactionError,
contextCompactionService,
contextCompactionSupport,
isContextCompactionRun,
readContextCompactionRequest,
} from "../services/context-compaction.js";
import { getEmbeddedPostgresTestSupport, startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
describe("context compaction support", () => {
it("supports Codex and Claude on the Paperclip runner only", () => {
expect(contextCompactionSupport({ adapterType: "paperclip_runner", adapterConfig: { provider: "codex" } }).supported).toBe(true);
expect(contextCompactionSupport({ adapterType: "paperclip_runner", adapterConfig: {} }).supported).toBe(true);
expect(contextCompactionSupport({ adapterType: "paperclip_runner", adapterConfig: { provider: "acpx", acpxAgent: "claude" } }).supported).toBe(true);
expect(contextCompactionSupport({ adapterType: "paperclip_runner", adapterConfig: { provider: "acpx", acpxAgent: "pi" } }).supported).toBe(false);
expect(contextCompactionSupport({ adapterType: "paperclip_runner", adapterConfig: { provider: "opencode" } }).supported).toBe(false);
expect(contextCompactionSupport({ adapterType: "codex_local", adapterConfig: {} }).supported).toBe(false);
});
it("recognizes a compaction run from its context", () => {
expect(readContextCompactionRequest({ contextCompactionRequestId: "req-1" })).toEqual({ requestId: "req-1" });
expect(isContextCompactionRun({ contextCompactionRequestId: " " })).toBe(false);
expect(isContextCompactionRun({ goalControlRequestId: "goal-1" })).toBe(false);
expect(isContextCompactionRun(null)).toBe(false);
});
});
const support = await getEmbeddedPostgresTestSupport();
const suite = support.supported ? describe : describe.skip;
suite("context compaction availability", () => {
let db: ReturnType<typeof createDb>;
let temporaryDb: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
beforeAll(async () => {
temporaryDb = await startEmbeddedPostgresTestDatabase("context-compaction-");
db = createDb(temporaryDb.connectionString);
}, 60_000);
afterAll(async () => { await temporaryDb?.cleanup(); });
async function fixture(adapterConfig: Record<string, unknown> = { provider: "codex" }, adapterType = "paperclip_runner") {
const companyId = randomUUID(), agentId = randomUUID(), issueId = randomUUID();
await db.insert(companies).values({ id: companyId, name: "Compaction fixture", issuePrefix: `C${companyId.slice(0, 6)}` });
await db.insert(agents).values({ id: agentId, companyId, name: "Codie", role: "engineer", status: "idle", adapterType, adapterConfig });
await db.insert(issues).values({ id: issueId, companyId, title: "Compact", status: "in_progress", assigneeAgentId: agentId });
return { companyId, agentId, issue: { id: issueId, assigneeAgentId: agentId as string | null, status: "in_progress" } };
}
it("is available for an idle supported agent and queues a compaction run", async () => {
const { companyId, agentId, issue } = await fixture();
const wakeup = vi.fn(async () => ({ id: randomUUID() }));
const service = contextCompactionService(db, { wakeup });
expect(await service.availability(companyId, issue)).toEqual({ status: "available", reasonCode: null, reason: null });
const accepted = await service.request({ companyId, issue, userId: "board-user" });
expect(wakeup).toHaveBeenCalledWith(agentId, expect.objectContaining({
reason: "context_compaction",
requestedByActorType: "user",
requestedByActorId: "board-user",
allowRunCoalescing: false,
manualUserWake: true,
contextSnapshot: expect.objectContaining({
issueId: issue.id,
contextCompactionRequestId: accepted.requestId,
skipIssueComment: true,
}),
}));
});
it("waits for an active run and reports a compaction already underway", async () => {
const { companyId, agentId, issue } = await fixture();
const service = contextCompactionService(db, { wakeup: vi.fn() });
const runId = randomUUID();
await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId, scopeKind: "issue", issueId: issue.id, status: "running" });
expect(await service.availability(companyId, issue)).toMatchObject({ status: "unavailable", reasonCode: "agent_busy" });
await expect(service.request({ companyId, issue, userId: "board-user" })).rejects.toMatchObject({ code: "agent_busy" });
const { companyId: otherCompanyId, agentId: otherAgentId, issue: otherIssue } = await fixture();
const compactionRunId = randomUUID();
await db.insert(heartbeatRuns).values({
id: compactionRunId, companyId: otherCompanyId, agentId: otherAgentId, scopeKind: "issue", status: "queued",
contextSnapshot: { issueId: otherIssue.id, contextCompactionRequestId: "req-1" },
});
expect(await service.availability(otherCompanyId, otherIssue)).toEqual({
status: "pending", reasonCode: null, reason: null, runId: compactionRunId,
});
await expect(service.request({ companyId: otherCompanyId, issue: otherIssue, userId: "board-user" }))
.rejects.toBeInstanceOf(ContextCompactionError);
});
it("explains unsupported harnesses, closed tasks, and missing assignees", async () => {
const unsupported = await fixture({ provider: "opencode" });
const service = contextCompactionService(db);
expect(await service.availability(unsupported.companyId, unsupported.issue)).toMatchObject({
status: "unavailable", reasonCode: "unsupported",
});
const closed = await fixture();
expect(await service.availability(closed.companyId, { ...closed.issue, status: "done" })).toMatchObject({
status: "unavailable", reasonCode: "task_closed",
});
expect(await service.availability(closed.companyId, { ...closed.issue, assigneeAgentId: null })).toMatchObject({
status: "unavailable", reasonCode: "no_assignee",
});
});
});
@@ -10,6 +10,7 @@ describe("shouldAutoCheckoutIssueForWake", () => {
{ contextSnapshot: {} }, { contextSnapshot: { wakeReason: "issue_comment_mentioned" } },
{ contextSnapshot: { wakeReason: "source_scoped_recovery_action" } },
{ contextSnapshot: { wakeReason: "execution_resumed" } },
{ contextSnapshot: { wakeReason: "context_compaction", contextCompactionRequestId: "req-1" } },
])("does not grant an automatic checkout outside the eligible assigned wake: %j", override => {
expect(shouldAutoCheckoutIssueForWake({
contextSnapshot: { wakeReason: "issue_assigned" }, issueStatus: "todo",
@@ -44,6 +44,9 @@ suite("issue context usage", () => {
createdAt: new Date("2026-11-05T10:00:00Z") },
{ ...base, runId, seq: 2, eventType: "context.compacted", payload: prp(runId, "session-a", "context.compacted", {
schema: "paperclip.context.compacted.v1", compactionId: "c-1" }), createdAt: new Date("2026-11-05T10:00:01Z") },
// The same compaction reported twice (item completion and thread/compacted) counts once.
{ ...base, runId, seq: 5, eventType: "context.compacted", payload: prp(runId, "session-a", "context.compacted", {
schema: "paperclip.context.compacted.v1", compactionId: "c-1" }), createdAt: new Date("2026-11-05T10:00:01Z") },
{ ...base, runId, seq: 3, eventType: "item.completed", payload: prp(runId, "session-a", "item.completed", usage(38_200)),
createdAt: new Date("2026-11-05T10:00:02Z") },
{ ...base, runId, seq: 4, eventType: "item.completed", payload: prp(runId, "session-a", "item.completed", { kind: "usage", usage: { total: {} } }),
@@ -144,3 +144,14 @@ describe("enrichPromotedWakeContext", () => {
expect(queued.contextSnapshot).toMatchObject({ issueId: "issue-1", taskId: "task-1", taskKey: "TASK-1" });
});
});
describe("context compaction wakes", () => {
it("never merge with ordinary wakes, in either order", async () => {
const { wakeMustNotJoinActiveRun } = await import("./context.js");
const compaction = { issueId: "issue-1", contextCompactionRequestId: "req-1" };
const comment = { issueId: "issue-1", wakeCommentId: "comment-1" };
expect(wakeMustNotJoinActiveRun(compaction, comment, false)).toBe(true);
expect(wakeMustNotJoinActiveRun(comment, compaction, false)).toBe(true);
expect(wakeMustNotJoinActiveRun(comment, { issueId: "issue-1", wakeCommentId: "comment-2" }, false)).toBe(false);
});
});
@@ -81,7 +81,11 @@ export function wakeMustNotJoinActiveRun(
wakeContext: Record<string, unknown>,
interactionReceipt: boolean,
): boolean {
// A context compaction run does no task work, so ordinary wakes and
// compactions never merge, in either arrival order.
return interactionReceipt || Boolean(parseObject(activeRunContext).interactionId) ||
Boolean(readNonEmptyString(parseObject(activeRunContext).contextCompactionRequestId)) ||
Boolean(readNonEmptyString(wakeContext.contextCompactionRequestId)) ||
wakeChatConversationsConflict(activeRunContext, wakeContext);
}
+5 -1
View File
@@ -11,6 +11,7 @@ import { badRequest, forbidden } from "../errors.js";
import { agentActionAuditService } from "../services/agent-action-audit.js";
import { logActivity } from "../services/activity-log.js";
import { issueContextUsage } from "../services/issue-context-usage.js";
import { contextCompactionService } from "../services/context-compaction.js";
import { canActorReadHeartbeatRun } from "../services/heartbeat-run-privacy.js";
import { issueReadSqlCondition } from "../services/authorization.js";
import { caseActivityReadSqlCondition } from "../services/case-activity-access.js";
@@ -392,7 +393,10 @@ export function activityRoutes(db: Db) {
const issue = await getAccessibleResource(req, res, resolveIssueByRef(req.params.id as string), "Issue not found");
if (!issue) return;
if (!(await assertIssueReadAllowed(req, res, issue))) return;
res.json(await issueContextUsage(db, issue.companyId, issue));
const usage = await issueContextUsage(db, issue.companyId, issue);
res.json(usage
? { ...usage, compaction: await contextCompactionService(db).availability(issue.companyId, issue) }
: null);
});
router.get("/heartbeat-runs/:runId/issues", async (req, res) => {
+59
View File
@@ -229,6 +229,8 @@ import {
RunnerGoalActionError,
RunnerGoalConflictError,
} from "../services/runner-goals.js";
import { ContextCompactionError, contextCompactionService } from "../services/context-compaction.js";
import { issueContextUsage } from "../services/issue-context-usage.js";
import { queueLiveRunnerPrpCommand } from "../realtime/runner-prp-ws.js";
import { questionResponseDeliveryService } from "../services/question-response-delivery.js";
import { emitAgentTaskRunById } from "../services/agent-task-run-telemetry.js";
@@ -3534,6 +3536,9 @@ export function issueRoutes(
resolveNativeQuestion: (interaction) =>
deliverNativeQuestionResponse(db, interaction),
});
const contextCompaction = contextCompactionService(db, {
wakeup: (agentId, options) => heartbeat.wakeup(agentId, options),
});
const runnerGoals = runnerGoalService(db, {
enqueueOfflineControl: async ({ issueId, agentId, requestId, control }) => {
const run = await heartbeat.wakeup(agentId, {
@@ -9290,6 +9295,60 @@ export function issueRoutes(
},
);
router.post("/issues/:id/context/compact", async (req, res) => {
assertBoard(req);
if (!req.actor.userId) throw forbidden("Board user context required");
const issue = await getAccessibleResource(
req,
res,
getIssueById(req, req.params.id as string),
"Issue not found",
);
if (!issue) return;
const decision = await decideIssueAccess(req, issue, "issue:mutate");
if (!decision.allowed) throw forbidden(decision.explanation, authorizationDeniedDetails(decision));
// An Agent Chat run starts only for the conversation's owner.
if (issue.conversationAgentId) {
if (!(await instanceSettings.getExperimental()).enableAgentChat) throw notFound("Agent Chat is disabled");
if (req.actor.userId !== issue.conversationUserId)
throw forbidden("Only the conversation owner can compact a chat agent's context");
}
try {
const reading = await issueContextUsage(db, issue.companyId, issue);
const accepted = await contextCompaction.request({
companyId: issue.companyId,
issue,
userId: req.actor.userId,
contextTokensBefore: reading?.usedTokens ?? null,
});
const actor = getActorInfo(req);
await logActivity(db, {
companyId: issue.companyId,
actorType: actor.actorType,
actorId: actor.actorId,
agentId: actor.agentId,
runId: actor.runId,
action: "issue.context_compaction_requested",
entityType: "issue",
entityId: issue.id,
issueId: issue.id,
details: {
requestId: accepted.requestId,
compactionRunId: accepted.runId,
assigneeAgentId: issue.assigneeAgentId,
},
});
res.status(202).json(accepted);
} catch (error) {
if (error instanceof ContextCompactionError) {
const status = error.code === "agent_busy" || error.code === "already_pending" ? 409 : 422;
res.status(status).json({ error: error.message, code: error.code });
return;
}
throw error;
}
});
router.get("/issues/:id/heartbeat-context", async (req, res) => {
const id = req.params.id as string;
const issue = await getAccessibleResource(
+10
View File
@@ -6178,6 +6178,16 @@ registry.registerPath({
responses: { 200: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound },
});
registry.registerPath({
method: "post",
path: "/api/issues/{id}/context/compact",
tags: ["issues"],
summary: "Ask the assignee agent to compact its context window",
description: "Board only. Queues a short run that resumes the assignee's runner session and compacts it (Codex and Claude on the Paperclip runner). Unavailable while the agent is running on the task.",
request: { params: z.object({ id: z.string() }) },
responses: { 202: r.ok(), 401: r.unauthorized, 403: r.forbidden, 404: r.notFound, 409: r.conflict, 422: r.unprocessable },
});
registry.registerPath({
method: "get",
path: "/api/heartbeat-runs/{runId}/issues",
+201
View File
@@ -0,0 +1,201 @@
import { randomUUID } from "node:crypto";
import { and, desc, eq, inArray, or, sql } from "drizzle-orm";
import type { Db } from "@paperclipai/db";
import { agents, heartbeatRuns } from "@paperclipai/db";
import type { IssueContextCompaction } from "@paperclipai/shared";
/**
* On-demand context compaction ("Compact now").
*
* Agents run with a per-turn session lifecycle: the harness session exists
* only during a run. A compaction therefore runs as its own short heartbeat
* run that resumes the assignee's session, asks the harness to compact (Codex
* `thread/compact/start`, Claude's ACP `/compact` command), and settles
* without changing the task. The run is marked by
* `contextSnapshot.contextCompactionRequestId`.
*/
export const CONTEXT_COMPACTION_WAKE_REASON = "context_compaction";
const ACTIVE_RUN_STATUSES = ["queued", "scheduled_retry", "running"] as const;
type AgentBinding = Pick<typeof agents.$inferSelect, "adapterType" | "adapterConfig">;
function asRecord(value: unknown): Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value)
? value as Record<string, unknown>
: {};
}
function nonEmptyString(value: unknown): string | null {
return typeof value === "string" && value.trim().length > 0 ? value : null;
}
/** The compaction request a run was admitted for, if it is a compaction run. */
export function readContextCompactionRequest(
context: unknown,
): { requestId: string; contextTokensBefore?: number } | null {
const record = asRecord(context);
const requestId = nonEmptyString(record.contextCompactionRequestId);
if (!requestId) return null;
const before = record.contextCompactionTokensBefore;
return typeof before === "number" && Number.isSafeInteger(before) && before >= 0
? { requestId, contextTokensBefore: before }
: { requestId };
}
export function isContextCompactionRun(context: unknown): boolean {
return readContextCompactionRequest(context) !== null;
}
/**
* Harnesses that can compact on request. Compaction needs the Paperclip
* runner, which resumes the provider session: Codex through its app-server,
* Claude through ACP.
*/
export function contextCompactionSupport(agent: AgentBinding): { supported: true } | { supported: false; reason: string } {
const unsupported = { supported: false as const, reason: "This agent's harness can't compact on request." };
if (agent.adapterType !== "paperclip_runner") return unsupported;
const config = asRecord(agent.adapterConfig);
const provider = typeof config.provider === "string" ? config.provider : "codex";
if (provider === "codex") return { supported: true };
if (provider === "acpx" && config.acpxAgent === "claude") return { supported: true };
return unsupported;
}
export class ContextCompactionError extends Error {
constructor(
readonly code: "no_assignee" | "task_closed" | "unsupported" | "agent_busy" | "already_pending" | "wake_skipped",
message: string,
) {
super(message);
}
}
type WakeupFn = (
agentId: string,
options: {
source: "on_demand";
triggerDetail: "manual";
reason: string;
payload: Record<string, unknown>;
idempotencyKey: string;
requestedByActorType: "user";
requestedByActorId: string;
contextSnapshot: Record<string, unknown>;
allowRunCoalescing: false;
manualUserWake: true;
},
) => Promise<{ id: string } | null>;
export function contextCompactionService(db: Db, deps: { wakeup?: WakeupFn } = {}) {
/** The assignee's newest unfinished run for this task, if any. */
async function activeRun(companyId: string, issueId: string, agentId: string) {
return db
.select({ id: heartbeatRuns.id, contextSnapshot: heartbeatRuns.contextSnapshot })
.from(heartbeatRuns)
.where(and(
eq(heartbeatRuns.companyId, companyId),
eq(heartbeatRuns.agentId, agentId),
inArray(heartbeatRuns.status, [...ACTIVE_RUN_STATUSES]),
or(
eq(heartbeatRuns.issueId, issueId),
eq(heartbeatRuns.nativeIssueId, issueId),
sql`${heartbeatRuns.contextSnapshot} ->> 'issueId' = ${issueId}`,
),
))
.orderBy(desc(heartbeatRuns.createdAt))
.limit(1)
.then((rows) => rows[0] ?? null);
}
async function availability(
companyId: string,
issue: { id: string; assigneeAgentId: string | null; status: string },
): Promise<IssueContextCompaction> {
if (issue.status === "done" || issue.status === "cancelled") {
return { status: "unavailable", reasonCode: "task_closed", reason: "Available while the task is open." };
}
if (!issue.assigneeAgentId) {
return { status: "unavailable", reasonCode: "no_assignee", reason: "Assign an agent to compact its context." };
}
const agent = await db
.select({ adapterType: agents.adapterType, adapterConfig: agents.adapterConfig })
.from(agents)
.where(and(eq(agents.id, issue.assigneeAgentId), eq(agents.companyId, companyId)))
.then((rows) => rows[0] ?? null);
if (!agent) {
return { status: "unavailable", reasonCode: "no_assignee", reason: "Assign an agent to compact its context." };
}
const support = contextCompactionSupport(agent);
if (!support.supported) return { status: "unavailable", reasonCode: "unsupported", reason: support.reason };
const run = await activeRun(companyId, issue.id, issue.assigneeAgentId);
if (run && isContextCompactionRun(run.contextSnapshot)) {
return { status: "pending", reasonCode: null, reason: null, runId: run.id };
}
if (run) {
// Compacting interrupts a turn, so wait for the current run to end.
return {
status: "unavailable",
reasonCode: "agent_busy",
reason: "Available when the agent finishes its current run.",
};
}
return { status: "available", reasonCode: null, reason: null };
}
/** Queues a compaction run for the task's assignee. */
async function request(input: {
companyId: string;
issue: { id: string; assigneeAgentId: string | null; status: string };
userId: string;
/** The session's last context reading, shown as the divider's "before" size. */
contextTokensBefore?: number | null;
}): Promise<{ requestId: string; runId: string }> {
const current = await availability(input.companyId, input.issue);
if (current.status === "pending") {
throw new ContextCompactionError("already_pending", "The agent is already compacting its context.");
}
if (current.status === "unavailable") {
throw new ContextCompactionError(
current.reasonCode ?? "unsupported",
current.reason ?? "Context compaction is unavailable.",
);
}
if (!deps.wakeup) throw new Error("context compaction wakeup is not configured");
const agentId = input.issue.assigneeAgentId!;
const requestId = randomUUID();
const run = await deps.wakeup(agentId, {
source: "on_demand",
triggerDetail: "manual",
reason: CONTEXT_COMPACTION_WAKE_REASON,
payload: { issueId: input.issue.id, requestId, intent: CONTEXT_COMPACTION_WAKE_REASON },
idempotencyKey: `${CONTEXT_COMPACTION_WAKE_REASON}:${requestId}`,
requestedByActorType: "user",
requestedByActorId: input.userId,
// A compaction never joins, or absorbs, another run's work.
allowRunCoalescing: false,
// An explicit board click; admission and dispatch recheck its owner.
manualUserWake: true,
contextSnapshot: {
issueId: input.issue.id,
taskKey: input.issue.id,
resumeIntent: true,
contextCompactionRequestId: requestId,
...(typeof input.contextTokensBefore === "number"
? { contextCompactionTokensBefore: input.contextTokensBefore }
: {}),
skipIssueComment: true,
},
});
if (!run) {
throw new ContextCompactionError(
"wake_skipped",
"Compaction did not start. Check that task execution is enabled for this instance and agent, then retry.",
);
}
return { requestId, runId: run.id };
}
return { availability, request };
}
+7
View File
@@ -1,4 +1,5 @@
import { resolveProviderApiPlacement } from "./native-runtime/provider-api-placement.js";
import { isContextCompactionRun } from "./context-compaction.js";
import { registerDeferredReceiptWork } from "./heartbeat/deferred-receipt-work.js";
import { reconcileTaskChatRetryReceipts } from "./task-retry.js";
import { registerIssueRecoveryWork } from "./recovery/work.js";
@@ -721,6 +722,8 @@ export function shouldAutoCheckoutIssueForWake(input: {
return false;
}
// A compaction run does no task work, so it never claims a parked task.
if (isContextCompactionRun(input.contextSnapshot)) return false;
const wakeReason = readNonEmptyString(input.contextSnapshot?.wakeReason);
if (!wakeReason) return false;
if (wakeReason === "issue_comment_mentioned") return false;
@@ -3287,6 +3290,10 @@ export function heartbeatService(
const durableGoalControlRun =
readNonEmptyString(context.goalControlRequestId) !== null ||
context.resumeSessionGoalHeartbeat === true;
// Compaction resumes a runner session; a direct adapter would run it as a prompt.
if (isContextCompactionRun(context) && agent.adapterType !== "paperclip_runner") {
throw new Error("context_compaction_requires_paperclip_runner");
}
// Goals must use the selected durable runner, never silently convert a
// direct adapter or let an old goal-control wake become a normal prompt.
if (durableGoalControlRun && agent.adapterType !== "paperclip_runner") {
@@ -31,11 +31,27 @@ function planWriteCondition(runId: string) {
))`;
}
/**
* Context readings of a run that compacted its context. The compaction divider
* reads its "before → after" sizes from the readings around the compaction.
* Runs that never compacted keep their usage out of the conversation view.
*/
function compactionUsageCondition(runId: string) {
return sql`(${heartbeatRunEvents.eventType} = 'item.completed'
and (${heartbeatRunEvents.payload} -> 'prpEvent' -> 'payload' ->> 'kind') = 'usage'
and ${heartbeatRunEvents.payload} -> 'prpEvent' -> 'payload' -> 'usage' ? 'context'
and exists (
select 1 from heartbeat_run_events c
where c.run_id = ${runId} and c.event_type = 'context.compacted'
))`;
}
/**
* Canonical PRP conversation data, excluding ordinary historical tool activity.
* Successful document writes retain a body-free boundary for saved Plan cards.
* Keep request lifecycles so a cold open cannot hide a question or approval.
* Keep MCP startup failures so a settled run still explains missing tools.
* Keep context compactions, with their run's context readings, for the divider.
* Item identity may occur on started/completed rather than each text delta.
*/
export function conversationEventCondition(runId: string) {
@@ -49,6 +65,10 @@ export function conversationEventCondition(runId: string) {
${heartbeatRunEvents.eventType} = 'provider.notice.recorded'
and ${heartbeatRunEvents.payload} #>> '{prpEvent,payload,category}' = 'mcp_server_startup_failed'
)
or ${heartbeatRunEvents.eventType} = 'context.compacted'
or (
${compactionUsageCondition(runId)}
)
or (
${heartbeatRunEvents.eventType} in ('item.started', 'item.delta', 'item.completed')
and (lower(replace(coalesce(${heartbeatRunEvents.payload} #>> '{prpEvent,payload,kind}', ${heartbeatRunEvents.payload} #>> '{prpEvent,payload,item,kind}', ${heartbeatRunEvents.payload} #>> '{prpEvent,payload,item,type}', ''), '_', '')) in ('agentmessage', 'assistantmessage')
@@ -1,4 +1,5 @@
import { preserveAcceptedRunUsageProjectionSql } from "../usage-receipts.js";
import { isContextCompactionRun } from "../context-compaction.js";
import { providerFailureFromError } from "../../vendor/paperclip-runner/index.js";
import { nativeTaskSessionPublicationHandled } from "../native-runtime/native-task-session-publication.js";
import { settledResponsePublicationSql } from "../native-runtime/native-response-publication-receipt.js";
@@ -987,6 +988,7 @@ export function createHeartbeatRunCompletion(db: Db, dependencies: HeartbeatRunC
readNonEmptyString(
parseObject(livenessRun.contextSnapshot).goalControlRequestId,
) !== null ||
isContextCompactionRun(livenessRun.contextSnapshot) ||
parseObject(livenessRun.contextSnapshot)
.resumeSessionGoalHeartbeat === true,
});
@@ -1570,6 +1572,7 @@ export function createHeartbeatRunCompletion(db: Db, dependencies: HeartbeatRunC
readNonEmptyString(
parseObject(livenessRun.contextSnapshot).goalControlRequestId,
) !== null ||
isContextCompactionRun(livenessRun.contextSnapshot) ||
parseObject(livenessRun.contextSnapshot)
.resumeSessionGoalHeartbeat === true,
}).catch((releaseError) => {
+11 -3
View File
@@ -1,4 +1,5 @@
import { readNativeStartupCleanup } from "../native-runtime/native-startup-cleanup.js";
import { isContextCompactionRun } from "../context-compaction.js";
import { notifyStrandedAgentStatus } from "../live-run-recovery-notifications.js";
import { notifyRunDispatch } from "../run-dispatch-notifications.js";
import { wakeWorkspaceBusyWaitersInTx } from "../../modules/run-dispatch/index.js";
@@ -1515,7 +1516,8 @@ export function createHeartbeatLifecycle(db: Db, dependencies: HeartbeatLifecycl
const context = parseObject(run.contextSnapshot);
if (
readNonEmptyString(context.goalControlRequestId) ||
context.resumeSessionGoalHeartbeat === true
context.resumeSessionGoalHeartbeat === true ||
isContextCompactionRun(context)
)
return;
const livenessState = run.livenessState as RunLivenessState | null;
@@ -1723,6 +1725,8 @@ export function createHeartbeatLifecycle(db: Db, dependencies: HeartbeatLifecycl
) {
if (run.status !== "succeeded") return;
const context = parseObject(run.contextSnapshot);
// A compaction run did no task work, so it hands nothing off.
if (isContextCompactionRun(context)) return;
const issueId =
readNonEmptyString(context.issueId) ?? readNonEmptyString(context.taskId);
if (!issueId) return;
@@ -2040,7 +2044,7 @@ export function createHeartbeatLifecycle(db: Db, dependencies: HeartbeatLifecycl
run: typeof heartbeatRuns.$inferSelect,
) {
const contextSnapshot = parseObject(run.contextSnapshot);
if (readNonEmptyString(contextSnapshot.goalControlRequestId)) return;
if (readNonEmptyString(contextSnapshot.goalControlRequestId) || isContextCompactionRun(contextSnapshot)) return;
const issueId =
readNonEmptyString(contextSnapshot.issueId) ??
readNonEmptyString(contextSnapshot.taskId);
@@ -2615,7 +2619,11 @@ export function createHeartbeatLifecycle(db: Db, dependencies: HeartbeatLifecycl
const contextSnapshot = parseObject(run.contextSnapshot);
// The explicit receipt admitted one turn. A prose-only follow-up cannot
// reuse it or renew it under the separate transient-failure retry policy.
if (readNonEmptyString(contextSnapshot.goalControlRequestId) || contextSnapshot.explicitUserContinuation) {
if (
readNonEmptyString(contextSnapshot.goalControlRequestId) ||
isContextCompactionRun(contextSnapshot) ||
contextSnapshot.explicitUserContinuation
) {
if (run.issueCommentStatus !== "not_applicable") {
await patchRunIssueCommentStatus(run.id, {
issueCommentStatus: "not_applicable",
@@ -1,4 +1,5 @@
import { readClaimedNativeStopRecovery } from "../native-runtime/native-cancellation-request.js";
import { readContextCompactionRequest } from "../context-compaction.js";
import { remoteWorkspaceFailureCause } from "../remote-workspace-transport.js";
import { readNativePostResultFailureDiagnostic } from "../native-runtime/native-post-result-failure.js";
import { NativeStartupCleanupPendingError } from "../native-runtime/native-startup-cleanup.js";
@@ -634,6 +635,7 @@ export async function executeHeartbeatRuntime(db: Db, input: HeartbeatRuntimeExe
useRunnerd: agent.adapterType === "paperclip_runner",
adapterType: agent.adapterType,
sessionGoalControl,
sessionCompaction: readContextCompactionRequest(context),
resumeSessionGoalHeartbeat:
context.resumeSessionGoalHeartbeat === true ||
completedGoalControl,
+5 -2
View File
@@ -87,9 +87,12 @@ export async function issueContextUsage(
const windowTokens = count(context?.windowTokens);
if (usedTokens === null || windowTokens === null || windowTokens < 1) return null;
// Every compaction of the session, across all of its runs.
// Every compaction of the session, across all of its runs. A provider can
// report one compaction through more than one notification; count each id once.
const [compactions] = await db
.select({ count: sql<number>`count(*)::int` })
.select({
count: sql<number>`count(distinct coalesce(${heartbeatRunEvents.payload} -> 'prpEvent' -> 'payload' ->> 'compactionId', ${heartbeatRunEvents.id}::text))::int`,
})
.from(heartbeatRunEvents)
.where(and(
eq(heartbeatRunEvents.companyId, companyId),
@@ -1,4 +1,5 @@
import { notifyNativeEnvironmentSettlement } from "../native-environment-settlement-notifications.js";
import { isContextCompactionRun } from "../context-compaction.js";
import { notifyExternalAgentSettlement } from "../../modules/external-agents/index.js";
import { notifyNativeRecoveryNotices } from "../native-recovery-notice-notifications.js";
import { resolveCommittedNativeRecoveryNotices } from "./native-recovery-notices.js";
@@ -1543,6 +1544,7 @@ export async function finalizeNativeRun(input: {
boardResponseWaitOrigin: boardResponseWaitOrigin !== null,
isConversation: isConversation(authoritativeIssue),
hasActivePauseHold: pauseHold !== null,
contextCompactionRun: isContextCompactionRun(run.contextSnapshot),
reviewOwnerUserId:
authoritativeIssue.responsibleUserId ??
authoritativeIssue.createdByUserId ??
@@ -8512,6 +8512,8 @@ export async function executePaperclipNativeSession(input: {
taskSessionPublication?: NativeTaskSessionPublicationContext;
sessionGoalControl?: NativeSessionGoalControl | null;
resumeSessionGoalHeartbeat?: boolean;
/** Compact the resumed provider session instead of running a task turn. */
sessionCompaction?: { requestId: string; contextTokensBefore?: number } | null;
preparationSpans?: NativeRunHistoricalSpan[];
/** Use a session-owned GitHub broker, rebound only after run ownership is acquired. */
managedGitHub?: boolean;
@@ -10276,6 +10278,7 @@ async function executePaperclipNativeSessionWithinScope(
keepSessionOpen: warmSessionId !== null,
sessionGoalControl: input.sessionGoalControl,
resumeSessionGoalHeartbeat: input.resumeSessionGoalHeartbeat,
sessionCompaction: input.sessionCompaction,
requireSessionCloseBeforeReturn: runnerdBackend !== null || input.instructionWorkingCopy !== undefined,
onSessionClosed: input.instructionWorkingCopy?.collectStopped,
onCheckpoint: async (snapshot) => {
@@ -77,6 +77,18 @@ describe("native status authority", () => {
});
});
it("preserves the task status after a context compaction run", () => {
for (const priorIssueStatus of ["in_progress", "in_review", "blocked", "todo"] as const) {
expect(arbitrate({
contextCompactionRun: true,
priorIssueStatus,
assessment: assessment({ reportedDisposition: "yielded", objectiveSatisfied: false, allCriteriaSatisfied: false }),
})).toMatchObject({
statusAction: "preserve", toStatus: priorIssueStatus, reasonCode: "context_compaction_status_preserved", effects: [],
});
}
});
it("keeps workspace repair ahead of an accepted case handoff", () => {
expect(arbitrate({ caseHandoffAuthorized: true, workspaceFinalizeStatus: "failed" })).toMatchObject({
statusAction: "preserve", reasonCode: "finalization_failed_claim_preserved",
@@ -154,6 +154,8 @@ export function arbitrateNativeStatus(input: {
boardResponseWaitOrigin?: boolean;
isConversation?: boolean;
hasActivePauseHold?: boolean;
/** The run only compacted the agent's context; it carries no task outcome. */
contextCompactionRun?: boolean;
reviewOwnerUserId?: string | null;
/** Review decisions own task state; a reviewer's finish report cannot override them. */
nativeReviewOutcome?: "resolved" | "pending" | "stale";
@@ -165,6 +167,16 @@ export function arbitrateNativeStatus(input: {
agentId: string;
priorIssueStatus: NativeAuthoritativeIssueStatus;
}): NativeStatusDecision {
if (input.contextCompactionRun) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
statusAction: "preserve",
toStatus: input.priorIssueStatus,
reasonCode: "context_compaction_status_preserved",
unblockDescriptor: null,
effects: [],
};
}
if (["done", "cancelled"].includes(input.priorIssueStatus)) {
return {
policyVersion: NATIVE_STATUS_ARBITER_POLICY_VERSION,
+2
View File
@@ -1,4 +1,5 @@
import { notifyScheduledRetryDispatch } from "../run-dispatch-notifications.js";
import { isContextCompactionRun } from "../context-compaction.js";
import { notifyNativeEnvironmentSettlement } from "../native-environment-settlement-notifications.js";
import { notifyExternalAgentSettlement } from "../../modules/external-agents/index.js";
import { notifyNativeStatusReassessment } from "../native-status-reassessment-notifications.js";
@@ -3791,6 +3792,7 @@ export function recoveryService(
activeExecution: state.hasActiveExecutionPath || latest?.id !== (dispatchRunId ?? run.id),
ownedLifecycle: run.issueCommentStatus === "retry_queued" || run.issueCommentStatus === "retry_exhausted" ||
Boolean(readNonEmptyString(context.goalControlRequestId)) || context.resumeSessionGoalHeartbeat === true ||
isContextCompactionRun(context) ||
isPluginManagedIssueLifecycle(issue) || routine.length > 0 || workspaceChildren.length > 0 ||
Boolean(goal[0]?.status && goal[0].status !== "complete") || Boolean(active && !ownsRepair),
conversation: Boolean(issue.conversationAgentId) || isWaitingConversation(issue),