0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-08 12:33:05 +01:00

Files

T

DottaandClaude Opus 5.5 86a9d3ec6c feat(task-chat): tool rows that say what ran and how it went (#19265 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The task chat shows each tool call an agent makes as a short
activity row.
> - Real Claude runs showed Bash rows named "Terminal" with no command
and Write rows stuck at "Preparing file…". No row showed an exit code or
a duration, and a tool refused by policy looked like any other failure.
> - Codex already reported exit codes, durations and parsed command
actions, but the UI dropped them, and every Codex read looked like a
shell command.
> - This pull request gives both harnesses one row grammar: a verb icon,
the real subject, an exit chip and a duration.
> - The benefit is that a reviewer can see what ran and how it went
without opening each row.

## Linked Issues or Issue Description

Refs #19259 (this branch includes its `_meta` passthrough commit; merge
#19259 first or together).

**Problem or motivation**
Claude tool rows hide what ran: the runner keeps the first ACP title
("Terminal", "Preparing file…") and drops the refined one. `exitCode`
and `durationMs` are null on every Claude tool event. The UI ignores
`tool.execution.progressed`, `exitCode` and `durationMs` for every
harness.

**Proposed solution**
Read real tool facts in the runner (Claude `_meta.claudeCode`, raw input
and result text; Codex `commandActions`), carry them in the canonical
tool event, and render one row grammar in the task chat.

**Alternatives considered**
Enable Claude's `terminal_output` client capability to get
`terminal_exit`. That changes how command output arrives, and Claude's
own exit code is derived from the error flag anyway, so this PR reads
the error flag and the "Exit code N" text instead.

## What Changed

- **Runner (TS):** `createAcpxToolEventNormalizer` keeps the latest
concrete title instead of the first placeholder. It merges tool facts
across the lifecycle and measures the duration. New
`acpxToolDetailFromRuntimeEvent` reads the native tool name, the command
or pattern, the description, the exit code and a "Permission denied"
reason. Exit 0 is inferred only for Claude `Bash`, where a non-zero exit
is always a failed result.
- **ACPX sidecar:** reads the facts before `rawInput` is dropped and
sends a bounded `toolDetail`. A file path argument becomes an attested
workspace-relative location.
- **runner-core (Rust):** validates `toolDetail`.
`normalize_acpx_tool_call` uses the native name, exit code, duration,
subject, description and blocked reason. Codex `commandExecution` gets
its operation, a single-file target and a subject from `commandActions`.
The shell wrapper is removed, and a single search reads as `"TODO" in
src`.
- **Protocol:** `toolExecution` gains the optional fields `subject`,
`description` and `blockedReason`. Generated validators and the manifest
are regenerated.
- **UI:**
- `nativeRunEventsToTranscript` handles `tool.execution.progressed` and
passes a canonical `detail` on `tool_call` entries.
- The task-chat row shows `$ command`, a path or a pattern, a red `exit
N` chip (exit 0 only for commands) and a duration (0 is hidden).
  - Three or more consecutive reads fold into "Read N files a, b, c +1".
  - A refused tool shows "Blocked" with its reason.
- **Storybook:** `Tasks/Tool rows` compares the data recorded today with
the new runner data for Claude and Codex.

## Verification

- `cd packages/paperclip-runner && npx vitest run
src/provider-events.test.ts src/cli src/drivers/acpx` (1,957 pass)
- `cd packages/paperclip-runner/runner && cargo test -p
paperclip-runner-core --lib provider_events`
- `cd ui && npx vitest run src/components/transcript
src/components/task-chat` (973 pass)
- `pnpm check:token-gates`, `pnpm --filter paperclip-runner build`
(includes the protocol coverage and replay-golden checks)
- Live runs on a local instance with real harnesses:
- Codex (gpt-5.6-sol): the rows read `$ node --test` with `exit 1` and
then `exit 0`, plus real durations. A three-file `sed` shows as one
command and does not claim a single file.
- Claude (claude-sonnet-5-5 through ACPX): the rows show `Bash` and
`Edit` instead of "Terminal" and "Preparing file…". Commands show their
real text, `exit 0` and durations, and edits show `Edited temp.js`.
- Not seen live: a real Claude `Write`, a folded read run and a Claude
policy denial. Unit and Rust tests cover them.

## Risks

- The tool-execution schema gains only optional fields, so older events
stay valid. Older runs keep rendering with what they recorded.
- Commands now cross the sidecar boundary as `subject` (bounded to 4,000
characters). Codex already recorded commands as the tool name, and
server redaction still applies.
- The tool lifecycle now keeps the latest concrete title. A provider
that retitles a call to something less useful would show the newer
title.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use,
code execution and browser automation.

## 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
- [ ] 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 13:57:04 -06:00

src

feat(task-chat): tool rows that say what ran and how it went (#19265 )

2026-11-05 13:57:04 -06:00

CHANGELOG.md

fix: bound workspace Git scans (#11572 )

2026-08-17 22:11:30 -05:00

package.json

feat: configure company agent observability (#16874 )

2026-10-19 15:36:04 -05:00

README.md

fix: bound sandbox bridge waits and flag silent runs sooner (#14979 )

2026-10-02 15:29:41 -07:00

tsconfig.json

…

README.md

@paperclipai/adapter-utils

Shared utilities for Paperclip adapters: process spawning, environment injection, sandbox/SSH transport, workspace sync, and the round-trip helpers that move code between the local execution-workspace cwd and wherever the agent actually runs.

For the adapter-author guide see docs/adapters/creating-an-adapter.md and the in-repo notes at packages/adapters/AUTHORING.md.

Sandbox bridge deadlines

Command-managed bridge control operations (queue reads, input delivery, setup, and cleanup) have a host-enforced deadline of at most 30 seconds per shell command. A shorter configured timeout still applies. These operations cannot inherit the agent run's hours-long lifetime or wait forever on a provider that ignores its timeout. Long-lived agent session commands keep their own limits.

A control timeout reports a transport failure. It does not prove that the remote command stopped and does not replay an uncertain write. The process session closes failed input delivery and uses its existing shutdown path; normal execution settlement must still verify termination.

No-remote-git contract

The local execution-workspace cwd is the only persistence boundary across runs. No adapter may depend on a git remote for cross-run state.

Adapters that run the agent on a different host should use the SSH round-trip helpers in src/ssh.ts:

prepareWorkspaceForSshExecution({ spec, localDir, remoteDir }) — bundles the local cwd (tracked files, dirty edits, untracked additions, and the git history needed to reconstruct it) to remoteDir before the run starts. Runs with no git remote configured.
restoreWorkspaceFromSshExecution({ spec, localDir, remoteDir, ... }) — syncs the remote cwd back into localDir after the run, including any new commits the agent created. Also runs with no git remote configured.

prepareRemoteManagedRuntime in src/remote-managed-runtime.ts wraps both calls for adapters that want a per-run remote workspace and an automatic restoreWorkspace() finally hook.

The invariant is pinned by the no-remote-git contract case in src/ssh-fixture.test.ts, which asserts that a remote-only commit propagates to the local worktree through the prepare → restore round-trip with no git remote configured at any point. Do not regress that test.