feat(acpx-engine): give sandbox.exec spans real parents (#10852)

Browse Source

## Thinking Path

> - Paperclip uses spans and traces to show how work moves through
agents and tools
> - sandbox.exec spans need a real parent so the trace tree matches the
work tree
> - Wrong parent links make execution history hard to read and hard to
debug
> - This pull request adds a single task.run root span and re-parents
live work to the nearest active span
> - The change keeps detached work under the closest live span instead
of the HTTP root
> - The benefit is a clear trace tree for sandbox.exec work and better
execution diagnosis

## Linked Issues or Issue Description

**What happened?**

sandbox.exec spans attached to the wrong parent or to no live parent in
some paths.

**Expected behavior**

Each sandbox.exec span should attach to the nearest live span.

**Steps to reproduce**

1. Run work that creates sandbox.exec spans during startup and callback
bridge paths.
2. Inspect the trace tree.
3. Observe an orphaned span or a span with the wrong parent.

**Paperclip version or commit**

`672e9de9c8b004aebc1f08e24b612ab067735ad1`

**Deployment mode**

Local dev.

**Additional context**

The branch adds the task.run root span, parents sandbox.startup to it,
and re-parents detached bridge work to the nearest live span.

## What Changed

- Added a task.run root span for the run tree.
- Re-parented sandbox.startup, agent.turn, and detached bridge work to
the nearest live span.
- Added end-to-end trace-tree assertions for the full parent chain.
- Added negative coverage so sandbox.exec does not parent to the HTTP
root.

## Verification

- Focused Vitest suite passed:
`packages/adapter-utils/src/acpx-engine/execute.test.ts`,
`packages/adapter-utils/src/acpx-engine/startup-timing.test.ts`,
`packages/adapter-utils/src/execution-target-sandbox.test.ts`,
`packages/adapter-utils/src/sandbox-callback-bridge.test.ts`, and
`server/src/__tests__/environment-execution-target.test.ts`.
- Result: 5 files passed, 204 tests passed.
- The submitted branch also reported `adapter-utils` checks, `server`
seam checks, and `tsc` exit 0 in the handoff state.

## Risks

- This change can alter trace tree shape in tools that read parent
spans.
- A missed bridge path could still point to the wrong live span.
- Low risk for runtime behavior, because the change only changes span
parent attribution.

## Model Used

OpenAI GPT-5, tool-use capable.

## 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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

...

This commit is contained in:

Nicky LeachandPaperclip authored and GitHub committed 2026-08-04 15:32:41 -07:00

1 parent 74416e9cd1

commit c647b8cc2e

9 files changed

+2058 -631

Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL

Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

packages/adapter-utils/src/acpx-engine/execute.ts

+789 -583

File diff suppressed because it is too large. Load diff