## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `doc/observability.md` and `doc/run-log-events.md` described every OpenTelemetry span and every run-log event > - `rules/data-paths.mdc` told authors to update `doc/run-log-events.md` for each event, so both files only grew: 2,313 and 1,263 lines > - Each span and event is already defined next to the code that writes it, and its name is a literal string that a search finds in one step > - This pull request removes the per-span and per-event catalogs and keeps only what code does not say > - The benefit is two short docs that do not drift from the code, and no rule that makes them grow again ## Linked Issues or Issue Description Refs #21670, #21700, and #21743 (the same cleanup for other docs). **Issue type** Outdated or confusing documentation. **Where is the issue?** `doc/observability.md`, `doc/run-log-events.md`, and `rules/data-paths.mdc` **What's wrong?** The two docs repeated span names, span attributes, and event payloads that the code defines. Operator setup started at line 138 of `doc/observability.md`. The rule required a doc edit for every new run-log event. **Suggested fix** Keep operator setup and the Sentry privacy contract. Point to the code for span and event definitions. Remove the rule line that requires a doc entry per event. ## What Changed - `doc/observability.md` is now 619 lines. It keeps: how to enable tracing, `service.version` resolution, scope, how to enable Sentry, DSN delivery, environment attribution, privacy settings, server request data, the core of "Run failure context", browser data, fail-open behavior, the default capture set, and operator responsibilities. Kept text is unchanged except the intro and two sentences noted below. - Deleted from `doc/observability.md`: budget, Slack receipt, task detail, and browser tracing notes; controller preparation phases; native Runner spans; sandbox startup spans; sandbox duplex transport; shared skill preparation; invocation attribution; and about 500 lines of per-failure detail in "Run failure context". - Replaced that per-failure detail with one paragraph. It names the failures that `unexpected` mode keeps out of Sentry, and says the remaining diagnostic contexts are defined in `server/src/sentry.ts`. "Default capture set" now says the same. - `doc/run-log-events.md` is now 23 lines. It says what the run log is, where events are defined and appended, and keeps the payload storage note. - `rules/data-paths.mdc`: the run-log line now says to define an event where it is written, not in a doc. The span-allowlist line now says the allowlist is in the code that opens the span. The review levels and globs do not change. - Repointed links in two feature maps, two agent-access map files, `tests/runner-e2e/SUITES.md`, `doc/runner-api-tools.md`, and the Telemetry README. Updated the `honeycomb-tracing` skill and one code comment in `packages/adapter-utils/src/http2-bridge-server.ts`. ## Verification - A script built the new `doc/observability.md` from line ranges of the old file and asserts the first line of each range. - A link check on all changed Markdown files found 0 missing files and 0 missing anchors. The remaining inbound anchors (`#enabling-tracing`, `#sentry-error-monitoring`) still exist. - No test reads either doc. - `node scripts/check-maps.mjs` passes. - `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail. - `pnpm verify` was not run. This worktree has no installed dependencies. The only code change is a comment. ## Risks - The privacy contract no longer lists each run-failure diagnostic context field. `server/src/sentry.ts` is now the list. A reviewer of a Sentry change must read that file. - No browsable list of span names or run-log event names remains. A search for the quoted name finds the producer. - `.greptile/files.json` still scopes `rules/data-paths.mdc` to both docs. Both files still exist, so it does not change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`), Claude Code desktop, with tool use. Earlier analysis in this session used Claude Fable 5.2. ## 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 - [ ] 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>
20 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Runs, harnesses, and model accounts
Operators choose an agent harness and model account, inspect execution history and transcripts, and distinguish a working configuration from a successful task result.
Feature ID: runs-adapters.
Implementation: adapter manager, run host, configuration.
Agent access: companion.
Sub-features
model-accounts:runs-adapters/model-accounts— configure AI accounts, login attempts, defaults, bindings, usage and pools through delegated connection APIs.availability:runs-adapters/availability— discover installed adapters and available models/accounts.validation:runs-adapters/validation— test an adapter in the selected execution environment and surface authentication failures.runs:runs-adapters/runs— inspect run status, events, output, costs, and the source task.session:runs-adapters/session— preserve or reset execution context through supported lifecycle actions.
How to get to it (user POV)
adapter-setup
Open an agent’s model/adapter configuration or the instance adapter settings page when permitted.
managed-account-setup
Ask an authorized agent to save or connect a managed AI account. Open its saved
aiLogin setup link as the responsible human when sign-in or a code is required.
The agent can inspect the saved attempt and manage authorized account/pool
bindings; human authentication and raw host administration retain their gates.
run-history
Open an agent run at /agents/:agentId/runs/:runId from the agent or task activity.
The agent header has one Run now action. Administrators can enable
Capture raw provider traces under the agent configuration’s Debugging section
for future runs. The header shows Raw tracing on while that setting is enabled.
For latency diagnosis with an operator OTLP endpoint, search the hashed run ID
without restricting the root span name. Compare workspace preparation with its
workspace_<step> intervals. Measure controller readiness separately through
controller.startup.<phase>. A recovery pause or deployment drain is not model
execution time. See the spans in
execution-preparation-timing.ts.
These source-level diagnostics do not establish a live response-time budget.
task.time_to_first_token measures accepted ingress through the first committed
text that the task transcript can show, including thinking and completed
responses. It includes preparation and startup, and excludes browser latency.
Inspect native.controller.<phase> for backend construction, assigned-tool
discovery and post-turn cleanup. Compare those intervals with the actual model
turn; do not count a nested discovery interval twice.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Record adapter, model, account, native/legacy runtime, and environment. Capabilities vary; one harness result is not a matrix-wide qualification.
managed-account-setup
Automated: actual-auth connection integration exercises account/pool persistence, responsible-user ownership, agent attribution, saved local-login access and native secret-response protection with provider fixtures. Saved handoff UI tests exercise setup routing with mocked APIs. Neither establishes live provider sign-in.
Manual: Start delegated managed-account setup, reload the exact saved human handoff, finish the required login, and inspect the saved account and original task continuation. Bind the account or pool only to authorized agents, reload their configuration, and verify the selected owner and account remain correct. Reject a different user's saved attempt, revoked management authority and Ask/Plan mutations. Qualify a useful model task separately from saving the account.
session
For runs-adapters/session, complete a task in a disposable warm sandbox and
retain its saved workspace file. Let the warm session close normally and verify
that the retained lease has a complete, lease-bound harness backup before
injecting sandbox loss. Removing a still-warm sandbox before that checkpoint
exercises the separate acquisition safety gate, which must remain blocked.
Use a board-authorized session reset, then remove only that fixture's inactive
provider sandbox. Send a follow-up that
reads the retained file and appends one new line. Verify a replacement sandbox,
a new provider session, the exact file contents, successful finalization and no
stranded task lock. Send another follow-up and verify ordinary session reuse.
Repeat without resetting the session: its replacement must restore verified history or remain blocked. Missing backup state must not silently start an existing session again. The executor controls cover the bootstrap identity, activity and atomic directory claim; those controls do not establish live provider acceptance.
adapter-setup
Cloud-managed instances load adapters from the release image. Installing, removing, or overriding adapters remains platform-managed.
Automated: adapter validation routes and model refresh cover server behavior.
Cursor Cloud keeps Legacy as its automatic default. Choose Paperclip Runner explicitly under Advanced for experimental native support on a local controller. Select an exact model, bind a Cursor API key, and configure the repository or named Cloud environment. Save/reopen and Test must retain those choices. Test requires a reachable HTTPS callback origin and checks account/model access without starting a paid prompt. Cursor owns native shell permissions and does not independently acknowledge the effective model. Use the qualification ledger to distinguish local controls from live task, continuation, Stop and artifact proof.
Claude native setup uses the existing Anthropic API-key or subscription connection flow. Record the selected account separately from successful execution; unavailable models/authentication and unsupported Legacy-only options must fail visibly.
Claude CLI tests and runs also prepare a compatible private executable when a managed sandbox image's default CLI is too old for the selected model. Verify the command used for the hello test and task, reuse of a compatible private installation, and a blocking failure when installation cannot establish a valid version. Local, SSH and explicit custom commands retain operator management. Cloud onboarding must not offer shell commands the customer cannot run.
Manual: Select the intended adapter and account, refresh model choices, and run its environment test. Save, reload, then execute a small task. Repeat with a deliberately unavailable account and verify the failure remains visible.
For Legacy Codex, assign a service secret such as SLACK_BOT_TOKEN through agent
configuration and run a task that checks its presence without printing its value.
Check both ACP and CLI execution. Remove the binding and repeat on the next run.
The assigned secret must reach shell tools; an unassigned host token and Codex's
own login keys must remain unavailable. Verify the same delivery without an
agent identity. Shell-policy metadata must contain names rather than values.
Choose Codex as the harness; the UI displays its name/icon for both runners. Setup selects the runner automatically, and edits preserve saved execution. The UI has no runner dropdown; Advanced appears only when other settings remain. New Codex agents default to the native runner on supported macOS or GNU/Linux targets; the shared selection contract and runtime prerequisites define the platform/libc boundary. Windows and Alpine/musl remain Legacy. Claude follows its qualified rollout described above. Disabled adapters, external overrides, and selected-target qualification also affect availability.
Choose OpenCode with the native-runner experimental flag off on a qualified
macOS or GNU/Linux x64 target. Linux ARM64 must retain Legacy because its pinned
OpenCode runtime is not qualified. Advanced should show Paperclip Runner as the
automatic default on qualified targets. Save an inactive draft without a model,
resume it, select an explicit provider/model,
test, finish setup, and reload. Verify the saved provider is opencode. Repeat
with explicit Legacy and an existing Legacy agent; neither should migrate on an
unrelated edit. Check that saved native permission/lifecycle choices survive
resuming setup. Custom commands, arguments, variants, and inherited permissions
must give Legacy remediation when native is selected. A live task with the
selected account is separate proof from these setup and persistence controls.
Repeat with Pi on macOS or GNU/Linux x64 after explicit operator setup of the
pinned runtime (paperclipai runtime setup pi). Linux ARM64 retains Legacy.
Resume an inactive model-free draft, connect an account, choose a provider/model,
and finish setup with the generic native flag off. Verify Pi branding and native
ACPX Pi execution by completing a simple assigned task. Preserve saved native
thinking/permission/lifecycle settings on resume and unrelated edits. Native
thinking supports off, low, high, max; legacy aliases must give remediation,
and returning to Legacy must reject settings it cannot honor.
On a fresh forced-Kubernetes instance without an environment row, inspect discovery
and create with automatic selection. Both must retain Legacy without provisioning;
an explicit Paperclip request must give target-qualification guidance. Begin the
ordinary task to exercise the existing lazy environment path. This live journey
remains separate from the resolver's source controls.
Managed Cloud images default to Paperclip Runner without a saved platform qualification. A platform snapshot update must not change that default or require a separate qualification request before Test. Disabled or overridden adapters still restrict availability, and actual runtime startup can still fail.
For other sandbox defaults, follow the environment probe recipe first. Discovery/creation read company-bound immutable-image evidence without allocating a target. A mutable image or snapshot name does not establish native compatibility. Then test the actual selected runtime with its selected account/model: a legacy CLI or authentication probe alone cannot establish native readiness. For an image-provided Codex harness, verify both final executables after concurrent artifact preparation on an eligible provider. Repeat with a failed runner probe and confirm the harness work has settled before failure returns. Providers without concurrent sync and explicit harness installs remain serial. The real-shell artifact controls cover these source contracts; they do not establish live reply latency. For remote native Codex with managed GitHub access, inspect the controller preparation spans for overlapping GitHub setup and assigned MCP discovery. Provider startup must wait for both. Force either preparation to fail while the other is pending; confirm that the pending operation settles and run-owned access is released before failure returns. Repeat a warm follow-up and retain its actual reply time. The executor controls cover ordering, failure drain and credential projection; they do not qualify a live response-time target. For native OpenCode with assigned connections, inspect the provider tool surface on both local and sandbox execution. It should contain bounded assigned-tool search/call schemas. Discover an allowed tool, call its returned alias, revoke its grant, and confirm discovery and execution enforce that revocation. Repeat in planning/ask mode with a write tool and confirm denial. The controller must retain the assigned gateway URL and token. An older direct-catalog OpenCode checkpoint must refresh without changing another provider's fingerprint. The assigned-tool and executor controls cover source behavior; live sandbox discovery and a real call remain separate acceptance evidence. Missing dependencies, failed authentication, invalid models and incompatible custom settings must remain actionable errors without silent runner switching. Saved unchanged execution can still be tested without applying new selection policy, but runtime/account validation must still run.
Verify an automatic Codex hire and an explicit Legacy control through a useful file artifact, follow-up and reload. Preserve Codex reasoning effort and account isolation; retain explicit Legacy permission choices, including false. Reopen an existing agent, make an unrelated edit, and confirm both its persisted runner and next run stay unchanged. Use hiring/import preservation for approval and portability controls.
Test native Codex with a saved subscription whose setup auth file is a managed
link, as well as a regular file and an API-key account. Setup must seed the
isolated probe from the checked account without exposing credentials or changing
its saved runner. With subscription authentication, an unbound configured
CODEX_HOME with linked credentials must fail setup with managed-account or explicit Legacy guidance; it must not claim
readiness when task isolation would omit the file. Dangling or incorrectly owned
credentials must also fail clearly. A selected CODEX_API_KEY or
OPENAI_API_KEY takes precedence over an unrelated subscription file. Test valid,
dangling and invalid subscription links with that selected key; setup must test
the key without reading or refreshing the unrelated account. The private probe copy must be removed after confirmed retirement following success,
failure or cancellation. Unconfirmed shutdown remains a cleanup failure.
Exercise an unavailable local daemon and a preparation failure before probe
handoff. No owned temporary credential copy may remain, and original account
files must be unchanged. A probe whose shutdown is unconfirmed must retain its
recovery state; do not treat it as a preparation-only failure.
Existing setup controls use fake credentials; real account execution remains
a separate acceptance requirement.
run-history
Automated: live run routes and run event sequencing cover run data contracts.
Manual: Start a disposable task, open its running transcript, and follow it to a terminal outcome. Reload and compare task/run IDs, status, output, and cost. Verify a failed run remains distinguishable from a completed run with useful output.
For Legacy OpenCode on a disposable Linux sandbox, run a Bash tool that reads
/proc/self/oom_score_adj and its parent's score. The tool should report 1000;
OpenCode should retain its original score. Repeat with an operator BASH_ENV
and confirm that it takes precedence. Repeat with a linked operator plugins
directory; it must remain unchanged, and the uploaded runtime must contain a
real plugins directory with the guard and existing plugins. Under controlled memory pressure, record
the cgroup OOM counters and verify that a killed tool can return an error while
the agent continues. Local and SSH execution must keep their original shell
environment. See the adapter contract.
These controls do not guarantee that every memory exhaustion preserves the agent.
An explicit runner change starts a configuration revision and invalidates the eligible session. Active runs, restart recovery and historical transcript parsing retain their recorded execution configuration; do not infer their runner from a later edit to the agent. Account/harness branding and execution identity are different observations, both required in the evidence.
For an onboarding child-completion callback, verify actual session/turn events
and the source-correlated reply. A succeeded row alone is insufficient: the
literal ea6c8eb5e16d61111968f633a66748b397b64a3e managed attempt was marked
successful during startup without a provider turn. The recovery correction
preserves the existing validated Done-parent handoff; process-death and ownership
checks remain active. Its PostgreSQL controls are separate from the required
revised-source live onboarding and follow-up proof.
Gotchas
-
Model accounts are managed in Apps and inline agent account controls.
/company/settings/connectionsconfigures decision/fast-response models, not the general model-account library. -
Structured run events stay in the instance database. Optional stdout/stderr and raw trace payload storage can use S3; see run evidence storage. Both are separate from first-party Telemetry and operator OpenTelemetry export.
-
Authentication/model discovery does not establish tool, image, steering, or resumption capability parity.
-
Use recovery for interrupted runs and execution environments for local/SSH/sandbox differences.
Native setup retirement joins owned startup before cleanup can be confirmed. Transport ownership controls hold preparation or registration without launching a provider, then check bounded close, rejected duplicate requests, no later launch and retention of unconfirmed state. Readiness observes shutdown; resumed startup cannot reactivate ingress after close. These are lifecycle controls, separate from installed provider proof. The real daemon readiness and recovery controls require their existing native fixtures in hosted CI; passing credential-free controls does not qualify them. A primary setup timeout remains a failure even when teardown also fails.
For remote setup shutdown, verify that each durable-state read respects the
remaining suspension deadline. A late result cannot establish suspension or
queue a replacement command after that deadline. An intentional ingress close
must observe physical socket closure before retiring its connection owner and
releasing the endpoint; an unresponsive peer must not extend the setup budget.
The existing transport and ingress suites exercise these conditions without a
provider. Repeat the actual managed setup and useful task journey separately;
the literal 651a3de64fc943216cc414b64b1443809f9499da Test attempt failed
cleanup before hire and retains its unconfirmed recovery state.
delegated-configuration
See the canonical delegated configuration guidance and acceptance evidence.
Kimi Code verification
The qualified native Kimi profile uses paperclipai runtime setup kimi on Mac
ARM64 or Linux x64, an exact typed model, and a KIMI_API_KEY company secret.
Ordinary setup, hiring and Runtime Test require no candidate grant. Runtime Test
queries the authenticated Code model catalog without inference. Existing legacy
Kimi agents keep their saved runtime. Future pending profiles retain protected
startup admission; saved agent configuration and public requests cannot grant it.
Use the explicit kimi-qualification Product E2E suite for local and Daytona
reply, semantic question/plan, file/download, Stop, and continuation cases.
Verify the actual task result, persisted state and process cleanup. Run the
ordinary New Agent draft → model/secret → Test → save/reopen → task journey
through ordinary released selection. Native filesystem/shell tools are denied in read-only
Kimi work; scoped Paperclip tools retain control-plane authorization. This recipe
is a test path, not a statement that live acceptance passed. Current evidence:
Kimi release ledger.