mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The task chat shows what an agent did during a run, including each tool call > - Codex and Claude both report the patch for every file edit, but Paperclip dropped it. Claude's ACP `diff` content was never read. The Codex `fileChange` item became a generic item with no patch. Codex `turn/diff/updated` had no native-runner mapping > - A reviewer could not see what an agent changed without opening the workspace > - This pull request carries a bounded patch on each edit call and shows it in the edit row. Each turn that changed files ends with a "Changed in this turn" card > - The benefit is that a reviewer can check every change in the conversation, with the same view for Codex and Claude ## Linked Issues or Issue Description Refs #19252 (precedent: canonical `plan.updated` events as a docked plan card). **Subsystem affected** Paperclip runner (Rust and TypeScript canonical event mapping), PRP provider-event schema, and the task-chat UI. **Problem or motivation** Edit rows say "Edited a file" with no content. Claude Edit/Write `diff` content is lost after the ACPX sidecar. The Codex native runner drops `fileChange.changes` and `turn/diff/updated`. The existing workspace-changes card showed a raw text patch in a dialog, and only on the in-process Codex path. **Proposed solution** Add an optional, bounded `fileChanges` list to `paperclip.tool.execution.v1`. Fill it from Codex `fileChange` items and Claude ACP `diff` content. Map Codex `turn/diff/updated` to `workspace.change.updated` on the native runner. In the UI, show `+N −M` on each edit row, open a compact colored diff, and end the turn with the change set. **Alternatives considered** A runner-side git diff at turn end. It needs workspace access and extra cost on every turn. The harness patches are already available. For Claude, the UI builds the turn card from the edit rows instead of new per-turn runner state. ## What Changed - Protocol: optional `fileChanges[]` on `toolExecution` in `provider-event.schema.json`, with the regenerated schema bundle, validators and manifest. Paths are workspace-relative. A patch is at most 32 KiB, and a call has at most 32 files. - Runner (Rust): new `tool_file_changes.rs`. A Codex `fileChange` item now also emits `tool.execution.*` with `fileChanges`; the native item event stays for the recovery and progress projections. `turn/diff/updated` becomes `workspace.change.updated`. `normalize_acpx_tool_call` re-validates the sidecar's `fileChanges`. `normalize_codex_notification_in` resolves absolute paths against the session cwd. - Runner (Rust): `has_bounded_rich_display_shape` accepts schema-valid workspace diffs. Without this change, durable storage cut each patch string to a 4 KiB preview. Patches use the uncapped secret redactor. - Runner (TS): new `tool-file-changes.ts`. The ACPX sidecar computes `fileChanges` from ACP `diff` content with the working directory. The in-process Codex and ACPX mappers do the same, with an optional `context` argument. - UI: new `TaskChatDiffView` (colored rows, hunk labels, a height cap, "Show N more lines"). Edit rows show counts and the diff. Collapsed activity groups show edit totals. The workspace card is now "Changed in this turn", with in-place per-file diffs, and it sits at the end of the turn. When a harness sends no whole-turn diff (Claude), the card is built from the edit rows. A change set is marked complete when its run ends. - UI: `native-run-events.ts` maps `workspace.change.updated` and attaches each edit's latest patch to its row (the `diff` transcript entries now carry `toolUseId`). - Design tokens: `--diff-add-*`, `--diff-remove-*` and `--sz-edit-diff-max-h` come from the status icon hues. - Storybook: `Tasks/Edit diffs` story. Docs: `doc/run-log-events.md`. ## Verification - Real runs on a local instance (`test-drive`, native runner): - Codex (`gpt-5.6-sol`): the "Applied a patch" rows show `+9` and `+35 −2` with their diffs. The turn ends with "Changed in this turn", 2 files, `+42`, from `turn/diff/updated`. - Claude (`claude-opus-5-5` via ACPX): the Write and Edit rows show `+5`, `+14 −1` and `+9` with correct hunks. The turn card is built from the edit rows. - Codex model note: with `gpt-5.4`, pinned Codex 0.160 reports "model metadata not found". The model then wrote files through the shell, so no `fileChange` items occurred. - `pnpm check:token-gates`: all gates clean. - `pnpm --filter @paperclipai/ui exec vitest run src/components/task-chat src/components/transcript src/adapters`: 1073 passed. - `packages/paperclip-runner`: `vitest run src/provider-events.test.ts src/tool-file-changes.test.ts src/cli/acpx-runtime-sidecar.test.ts` passed. `check:protocol-types` and `check:protocol-manifest` match. - `cargo test -p paperclip-runner-core --lib provider_events tool_file_changes`: passed. `cargo fmt --check`: clean. - Storybook: open `Tasks and conversations/…/Tasks/Edit diffs`. ## Risks - Larger payloads: an edit call can carry up to 96 KiB of patch in Rust, and the sidecar keeps 48 KiB under its 128 KiB frame. Above the budget, a file keeps its counts and drops its patch (`diffTruncated`). - Redaction: each patch goes through the shared secret redactor. Before this change, a 4 KiB preview cap also applied. - Claude turn card: it joins each edit's patch in order. It is not a net diff. For a file the turn created, the counts are net and exact. For an existing file, the counts are summed over its edits. - The workspace card moves to the end of the turn. One adapter test changed to match. - Local only: four Linux cgroup `task_memory` Rust tests fail on macOS. They do not touch these modules. ## Model Used Claude Opus 5.5 (`claude-opus-5-5`), via Claude Code with tool use (shell, browser and file editing) and a long context window. ## 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>
251 lines
10 KiB
TypeScript
251 lines
10 KiB
TypeScript
import { realpathSync } from "node:fs";
|
|
import path from "node:path";
|
|
|
|
/**
|
|
* One file touched by a single edit tool call, carried on the canonical
|
|
* `paperclip.tool.execution.v1` payload so the edit row can show its own diff.
|
|
* Paths are workspace-relative; the patch is bounded per file and per call.
|
|
*/
|
|
export interface ToolFileChange {
|
|
path: string;
|
|
operation: "create" | "modify" | "delete" | "rename";
|
|
previousPath: string | null;
|
|
additions: number;
|
|
deletions: number;
|
|
diff: string | null;
|
|
diffTruncated: boolean;
|
|
}
|
|
|
|
export const MAX_TOOL_FILE_CHANGES = 32;
|
|
/** UTF-8 bytes of one file's patch (also within the schema's 32768-character bound). */
|
|
export const MAX_TOOL_FILE_DIFF_BYTES = 32 * 1024;
|
|
/**
|
|
* Serialized JSON bytes of all patches in one edit call. The ACPX sidecar frame
|
|
* is 128 KiB including up to 64 KiB of tool output, so patches stay well below
|
|
* the remainder; a file over budget keeps its counts and drops only its patch.
|
|
*/
|
|
export const MAX_TOOL_CALL_DIFF_BYTES = 48 * 1024;
|
|
|
|
function serializedBytes(value: string): number {
|
|
return Buffer.byteLength(JSON.stringify(value));
|
|
}
|
|
|
|
function withinCallBudget(files: ToolFileChange[]): ToolFileChange[] {
|
|
let budget = MAX_TOOL_CALL_DIFF_BYTES;
|
|
return files.map((file) => {
|
|
const size = file.diff === null ? 0 : serializedBytes(file.diff);
|
|
if (size > budget) return { ...file, diff: null, diffTruncated: true };
|
|
budget -= size;
|
|
return file;
|
|
});
|
|
}
|
|
|
|
/** Cut a patch to at most `maxBytes` UTF-8 bytes, at the last whole line. */
|
|
function boundedPatch(diff: string, maxBytes: number): { diff: string; truncated: boolean } {
|
|
const bytes = Buffer.from(diff, "utf8");
|
|
if (bytes.length <= maxBytes) return { diff, truncated: false };
|
|
const prefix = bytes.subarray(0, maxBytes).toString("utf8").replace(/\uFFFD+$/u, "");
|
|
const cut = prefix.lastIndexOf("\n");
|
|
return { diff: cut > 0 ? prefix.slice(0, cut) : prefix, truncated: true };
|
|
}
|
|
|
|
const MAX_LCS_CELLS = 4_000_000;
|
|
|
|
/** Workspace roots an absolute provider path may be relative to (e.g. a path and its realpath). */
|
|
export type WorkspaceRoots = string | readonly string[] | undefined;
|
|
|
|
/** A working directory and its resolved realpath, for providers that report either. */
|
|
export function workspaceRootsFor(directory: string | null | undefined): string[] {
|
|
if (!directory) return [];
|
|
try {
|
|
const resolved = realpathSync(directory);
|
|
return resolved === directory ? [directory] : [directory, resolved];
|
|
} catch {
|
|
return [directory];
|
|
}
|
|
}
|
|
|
|
function relativeWorkspacePath(value: unknown, workingDirectory: WorkspaceRoots): string | null {
|
|
if (typeof value !== "string" || !value.trim()) return null;
|
|
let candidate = value.trim().replace(/^file:\/\//, "").replaceAll("\\", "/");
|
|
if (/^[A-Za-z]:\//.test(candidate) || candidate.startsWith("/")) {
|
|
const roots = typeof workingDirectory === "string" ? [workingDirectory] : workingDirectory ?? [];
|
|
const absolute = path.posix.normalize(candidate);
|
|
const relative = roots
|
|
.map((root) => path.posix.relative(root.replaceAll("\\", "/").replace(/\/+$/, ""), absolute))
|
|
.find((value) => value && value !== ".." && !value.startsWith("../") && !path.posix.isAbsolute(value));
|
|
if (!relative) return null;
|
|
candidate = relative;
|
|
}
|
|
candidate = path.posix.normalize(candidate);
|
|
if (
|
|
!candidate || candidate === "." || candidate.length > 1_024 ||
|
|
candidate.startsWith("/") || candidate.split("/").includes("..")
|
|
) return null;
|
|
return candidate;
|
|
}
|
|
|
|
/** Bound a unified diff at a line boundary, keeping counts from the full patch. */
|
|
export function boundedToolFileChange(change: Omit<ToolFileChange, "diffTruncated" | "additions" | "deletions"> & {
|
|
additions?: number;
|
|
deletions?: number;
|
|
}): ToolFileChange {
|
|
const diff = change.diff ?? null;
|
|
let additions = change.additions ?? 0;
|
|
let deletions = change.deletions ?? 0;
|
|
if (diff !== null && change.additions === undefined && change.deletions === undefined) {
|
|
// `---`/`+++` are file headers only before a hunk; inside one they are
|
|
// changed lines such as a removed `-- comment`.
|
|
let inHunk = false;
|
|
for (const line of diff.split("\n")) {
|
|
if (line.startsWith("diff --git ")) inHunk = false;
|
|
else if (line.startsWith("@@")) inHunk = true;
|
|
else if (!inHunk && (line.startsWith("+++ ") || line.startsWith("--- "))) continue;
|
|
else if (line.startsWith("+")) additions += 1;
|
|
else if (line.startsWith("-")) deletions += 1;
|
|
}
|
|
}
|
|
const bounded = diff === null ? null : boundedPatch(diff, MAX_TOOL_FILE_DIFF_BYTES);
|
|
return { ...change, additions, deletions, diff: bounded?.diff ?? null, diffTruncated: bounded?.truncated ?? false };
|
|
}
|
|
|
|
function splitLines(value: string): string[] {
|
|
if (!value) return [];
|
|
const lines = value.split("\n");
|
|
if (lines.at(-1) === "") lines.pop();
|
|
return lines;
|
|
}
|
|
|
|
/**
|
|
* Unified hunk for one old/new text pair (an ACP `diff` content block). Uses a
|
|
* bounded LCS; very large blocks fall back to a whole-block replacement.
|
|
*/
|
|
export function unifiedHunkFromTexts(oldText: string | null, newText: string, newStart = 1): string {
|
|
const before = splitLines(oldText ?? "");
|
|
const after = splitLines(newText);
|
|
const rows: string[] = [];
|
|
if (before.length * after.length > MAX_LCS_CELLS) {
|
|
for (const line of before) rows.push(`-${line}`);
|
|
for (const line of after) rows.push(`+${line}`);
|
|
} else {
|
|
const n = before.length;
|
|
const m = after.length;
|
|
const table: Uint32Array[] = Array.from({ length: n + 1 }, () => new Uint32Array(m + 1));
|
|
for (let i = n - 1; i >= 0; i -= 1) {
|
|
for (let j = m - 1; j >= 0; j -= 1) {
|
|
table[i]![j] = before[i] === after[j]
|
|
? table[i + 1]![j + 1]! + 1
|
|
: Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
|
|
}
|
|
}
|
|
let i = 0;
|
|
let j = 0;
|
|
while (i < n || j < m) {
|
|
if (i < n && j < m && before[i] === after[j]) {
|
|
rows.push(` ${before[i]}`);
|
|
i += 1;
|
|
j += 1;
|
|
} else if (i < n && (j >= m || table[i + 1]![j]! >= table[i]![j + 1]!)) {
|
|
rows.push(`-${before[i]}`);
|
|
i += 1;
|
|
} else {
|
|
rows.push(`+${after[j]}`);
|
|
j += 1;
|
|
}
|
|
}
|
|
}
|
|
const start = Math.max(newStart, 1);
|
|
const oldStart = before.length === 0 ? 0 : start;
|
|
const newHeaderStart = after.length === 0 ? 0 : start;
|
|
return [`@@ -${oldStart},${before.length} +${newHeaderStart},${after.length} @@`, ...rows].join("\n");
|
|
}
|
|
|
|
/**
|
|
* File changes from ACP tool content (`{ type: "diff", path, oldText, newText }`).
|
|
* Several blocks for one path (one per hunk after Claude's PostToolUse update)
|
|
* join into one patch. Paths outside the workspace are dropped.
|
|
*/
|
|
export function toolFileChangesFromAcpContent(
|
|
content: unknown,
|
|
locations: unknown,
|
|
workingDirectory: WorkspaceRoots,
|
|
): ToolFileChange[] | null {
|
|
if (!Array.isArray(content)) return null;
|
|
const lineByPath = new Map<string, number[]>();
|
|
if (Array.isArray(locations)) {
|
|
for (const value of locations) {
|
|
if (!value || typeof value !== "object") continue;
|
|
const location = value as Record<string, unknown>;
|
|
const filePath = relativeWorkspacePath(location.path, workingDirectory);
|
|
if (filePath && typeof location.line === "number" && Number.isSafeInteger(location.line)) {
|
|
lineByPath.set(filePath, [...(lineByPath.get(filePath) ?? []), location.line]);
|
|
}
|
|
}
|
|
}
|
|
const byPath = new Map<string, { hunks: string[]; created: boolean; nextLine: number }>();
|
|
let blocks = 0;
|
|
for (const value of content) {
|
|
if (!value || typeof value !== "object") continue;
|
|
const block = value as Record<string, unknown>;
|
|
if (block.type !== "diff" || typeof block.newText !== "string") continue;
|
|
const filePath = relativeWorkspacePath(block.path, workingDirectory);
|
|
if (!filePath) continue;
|
|
const oldText = typeof block.oldText === "string" ? block.oldText : null;
|
|
const entry = byPath.get(filePath) ?? { hunks: [], created: true, nextLine: 1 };
|
|
// ACP may report one location per hunk or one per file. Without a location
|
|
// for this hunk, continue after the previous one so later hunks never all
|
|
// read "line 1".
|
|
const start = lineByPath.get(filePath)?.[entry.hunks.length] ?? entry.nextLine;
|
|
entry.hunks.push(unifiedHunkFromTexts(oldText, block.newText, start));
|
|
entry.nextLine = start + splitLines(block.newText).length;
|
|
entry.created &&= oldText === null;
|
|
byPath.set(filePath, entry);
|
|
blocks += 1;
|
|
if (blocks >= 256) break;
|
|
}
|
|
if (byPath.size === 0) return null;
|
|
return withinCallBudget([...byPath.entries()].slice(0, MAX_TOOL_FILE_CHANGES).map(([filePath, entry]) =>
|
|
boundedToolFileChange({
|
|
path: filePath,
|
|
operation: entry.created ? "create" : "modify",
|
|
previousPath: null,
|
|
diff: `${entry.hunks.join("\n")}\n`,
|
|
})));
|
|
}
|
|
|
|
/** File changes from a Codex `fileChange` item's `changes[]` (`{ path, kind, diff }`). */
|
|
export function toolFileChangesFromCodexChanges(
|
|
changes: unknown,
|
|
workingDirectory: WorkspaceRoots,
|
|
): ToolFileChange[] | null {
|
|
if (!Array.isArray(changes)) return null;
|
|
const files = changes.slice(0, MAX_TOOL_FILE_CHANGES).flatMap((value): ToolFileChange[] => {
|
|
if (!value || typeof value !== "object") return [];
|
|
const change = value as Record<string, unknown>;
|
|
const filePath = relativeWorkspacePath(change.path, workingDirectory);
|
|
if (!filePath) return [];
|
|
const kind = change.kind && typeof change.kind === "object" ? change.kind as Record<string, unknown> : {};
|
|
const kindText = (typeof change.kind === "string" ? change.kind : typeof kind.type === "string" ? kind.type : "update").toLowerCase();
|
|
const movePath = relativeWorkspacePath(kind.move_path ?? kind.movePath, workingDirectory);
|
|
const rawDiff = typeof change.diff === "string" ? change.diff : null;
|
|
const operation: ToolFileChange["operation"] = movePath
|
|
? "rename"
|
|
: kindText.includes("add") ? "create" : kindText.includes("delete") ? "delete" : "modify";
|
|
// Codex reports a created file's full content and a deleted file's prior
|
|
// content rather than a patch. Present both as a one-sided hunk.
|
|
const diff = rawDiff === null
|
|
? null
|
|
: (operation === "create" || operation === "delete") && !/^@@ /m.test(rawDiff)
|
|
? `${operation === "create" ? unifiedHunkFromTexts(null, rawDiff) : unifiedHunkFromTexts(rawDiff, "")}\n`
|
|
: rawDiff;
|
|
return [boundedToolFileChange({
|
|
path: movePath ?? filePath,
|
|
operation,
|
|
previousPath: movePath ? filePath : null,
|
|
diff,
|
|
})];
|
|
});
|
|
return files.length > 0 ? withinCallBudget(files) : null;
|
|
}
|
|
|