Files
PaperClipAI/server/src
DottaandClaude Opus 5.5 56654adecd perf(server): reuse sandbox provider schemas for five seconds on the remote-run path (#21758)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Agent runs can use remote sandboxes that a sandbox provider plugin
supplies (for example Daytona)
> - Each sandbox operation resolves the environment config, and that
step reads the provider config schema to find the secret-ref fields
> - On a hosted instance with 7 remote runs, this schema read was the
most frequent statement: 17.95 per second, about 2.5 per second for each
run
> - The server runs all agents on one Node main thread, so each
statement costs main-thread time; at 1,000 agents this read alone is
about 2,500 statements per second
> - This pull request reuses the retained schema for a short, bounded
time and drops it at once when the plugin registry changes a plugin
manifest
> - The benefit is that a live remote run reads the schema about once
per 5 seconds for each provider, not once per operation

## Linked Issues or Issue Description

**What existing behavior does this improve?**
Every plugin sandbox operation (exec, file sync in/out, runner ingress
attach, capability snapshot, workspace realize, lease resume, lease
release) calls `resolveEnvironmentDriverConfigForRuntime`. That call
runs the `with selected_provider as materialized ...` statement in
`resolvePluginSandboxProviderConfigSchema`, every time.

**Subsystem affected**
Server: plugin environment driver
(`server/src/services/plugin-environment-driver.ts`) and the plugin
registry manifest writes.

**Current behavior**
The schema read runs once per operation. A census test that drives the
real runtime calls of one remote run counts 19 schema reads for 19
operations (see the table below). The hosted measurement was 17.95
executions per second with 7 runs.

**Proposed behavior**
The read runs at most once per 5 seconds for each provider and database
client. A plugin install, upgrade or uninstall through the plugin
registry in the same process takes effect on the next operation.

**Reason and benefit**
The schema is instance-wide plugin manifest data. It does not change
during normal runs. Re-reading it per operation spends main-thread and
database time for no new information.

**Breaking changes**
None. No API, schema or saved-state change.

## What Changed

- `resolvePluginSandboxProviderConfigSchema` now returns the retained
schema without a database read when the entry was checked less than
`PROVIDER_SCHEMA_REUSE_MS` (5,000 ms) ago and the plugin manifest
revision did not change. After that, it uses the existing cheap revision
check, as before.
- A lookup sequence number stops an older, slower lookup from replacing
a newer retained entry.
- A missing provider is still never retained, so a provider that becomes
available is used on the next operation.
- New module `plugin-manifest-revision.ts` holds an in-process manifest
revision counter. It is a separate module so that the registry and the
driver do not import each other.
- `plugin-registry.ts`: `install` (both the new-row and the reinstall
paths), `update` and `uninstall` announce a manifest change after the
write completes. This is 5 changed lines plus 1 import line. Status-only
writes do not announce, because the schema read does not use plugin
status.
- `plugin-loader.ts`: `installPlugin` runs `registry.install` inside an
outer transaction. It now announces the manifest change again after that
transaction settles, so a schema read made before the commit cannot be
reused after it. This is 1 changed line plus 1 import line.
- Statement census per operation, before and after. One remote run, one
secret-ref field in the provider config, embedded test database, fake
in-process plugin worker:

| Operation | Count | Schema reads before | Schema reads after | All
statements before | All statements after |
| --- | --- | --- | --- | --- | --- |
| Lease acquire | 1 | 1 | 1 | 26 | 26 |
| Runner attach (ingress endpoint) | 1 | 2 | 0 | 11 | 9 |
| Capability snapshot | 1 | 1 | 0 | 6 | 5 |
| Exec | 10 | 10 | 0 | 50 | 40 |
| File write (sync in) | 1 | 1 | 0 | 5 | 4 |
| File read (sync out) | 1 | 1 | 0 | 5 | 4 |
| Workspace realize | 1 | 1 | 0 | 5 | 4 |
| Lease resume (reattach) | 1 | 1 | 0 | 6 | 5 |
| Lease release | 1 | 1 | 0 | 18 | 17 |
| **Total** | 18 | **19** | **1** | 132 | 114 |

- Other reads that stay on each operation (reported, not changed in this
pull request): each exec resolves each secret-ref field with 3 reads
(secret, binding, version) and 1 `secret_access_events` insert. Runner
attach and the capability snapshot also read the plugin row by id. These
are part of the secret authorization and audit path, so they keep their
own checks.

## Verification

- `cd server && npx vitest run
src/__tests__/plugin-sandbox-provider-schema-census.test.ts` (new). On
master the census test fails with 19 schema reads. With this change it
passes with 1.
- The new tests also prove these points:
- A registry upgrade that changes the secret-ref fields takes effect on
the next call in the same process.
- A direct manifest change (as from another server process) takes effect
after the 5-second bound, and no read occurs inside the bound.
  - A registry uninstall takes effect at once.
- A plugin reinstall through `pluginLoader.installPlugin` takes effect
after its install transaction commits, even when a schema read ran
inside the uncommitted transaction. This test failed before the
post-commit announcement and passes with it.
- A missing provider is not retained. The next call after install reads
and uses it.
- Two companies share the provider schema but each gets only its own
secret values. A cross-company secret id still fails with "Secret must
belong to same company".
  - A new database client (a process restart) starts cold, as before.
- `cd server && npx vitest run src/__tests__/plugin-database.test.ts`:
passed (plugin install transaction paths).
- `cd server && npx vitest run
src/__tests__/sandbox-provider-schema-reads.test.ts`: the existing tests
now step the clock past the bound where they change the database
directly.
- `cd server && npx vitest run
src/__tests__/environment-runtime.test.ts`: 210 passed.
- `cd server && npx vitest run
src/__tests__/bundled-plugin-registration.test.ts
src/__tests__/external-object-refresh-work.test.ts
src/__tests__/plugin-lifecycle-restart.test.ts
src/__tests__/plugin-loader-error-retry.test.ts
src/__tests__/plugin-environment-driver-sandbox-capabilities.test.ts
src/__tests__/plugin-sandbox-provider-config-validation.test.ts
src/__tests__/environment-probe.test.ts`: 82 passed, 1 skipped.
- `cd server && pnpm typecheck`: passed.

## Risks

- Staleness bound: a plugin manifest change made by a different server
process (for example during an overlapping deploy) can take up to 5
seconds to apply here. During that time, a secret-ref field that an
upgrade adds is not resolved yet, and a field that an upgrade removes is
still resolved. The bound is short and it applies only to which config
paths are secret refs.
- The retained value is instance-wide plugin manifest data, keyed by
database client and driver key. It contains no company data and no
secret values. It does not take part in an authorization decision.
Secret resolution, the environment binding check and the access audit
still run on each operation for the calling company.
- Memory stays bounded by the existing limits: 32 entries per database
client, 64 KiB per schema.
- `plugin-registry.ts` has a small edit in `install`, `update` and
`uninstall`. Other open work in that file can cause a simple merge
conflict.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edit, test runs).

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

Refs #17581

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 08:09:04 -06:00
..
…
…
…
…
…