## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Sandbox-backed runs need more precise startup observability so
operators can see where time is spent before an adapter is invoked
> - Aggregate startup timing hides which boundary is actually slow,
especially in remote execution where the bottleneck can move between
host round-trips, provider-boundary latency, and handshake phases
> - This pull request keeps the existing startup timing channel additive
while attributing the latency to the specific startup steps that caused
it
> - The benefit is better diagnosis of sandbox startup regressions
without changing control flow or introducing a schema migration
## Linked Issues or Issue Description
Refs: #10204
This PR extends the existing sandbox run-startup timing observability
with per-step round-trip and provider-latency attribution for the
Daytona startup path. It keeps the event payload additive and free-form,
and it leaves the control flow, database schema, and external adapter
interfaces unchanged.
## What Changed
- Added per-step round-trip counting for the host-to-sandbox execute
seam
- Added provider-boundary duration accumulation for the Daytona execute
and re-fetch steps
- Split the ACP handshake timing into `createRuntimeMs` and
`ensureSessionMs` while preserving the warm-handle skip
- Kept the startup timing payload additive and did not add a schema
migration
## Verification
- `adapter-utils` acpx-engine and startup-timing suites: pass
- Daytona plugin suite: pass with mocked SDK and injected-clock duration
assertions
- `server` environment-execution-target suite: pass
- `tsc --noEmit` for adapter-utils and server: pass
- Git validation: fetched
`origin/feat/sandbox-start-step-timing-attribution`, confirmed it
matches the authorized submit SHA
`53c573266e618af05c57a0720aaa9d9e0452de61`, and confirmed the branch
contains only the expected commit on top of `origin/master`
- Searched GitHub for duplicate or related PRs/issues; found one closely
related merged PR and no open duplicate on this branch
- Checked `ROADMAP.md`; the broad sandbox-agent roadmap section does not
call out this specific startup-timing attribution work as a duplicate
## Risks
- Low risk: the change is additive and only enriches existing timing
data
- Downstream consumers that assume aggregate-only startup timing may
need to tolerate the additional per-step fields
- The finer spawn/initialize/session split remains a follow-up in the
external ACP client because that hook is not available here yet
## Model Used
OpenAI GPT-5, tool-using coding agent
## 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: Harold Kim <harold@paperclip.ing>
Co-authored-by: Paperclip <noreply@paperclip.ing>
197718bc00