DottaandPaperclip
ac9459bae3
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Companies use several agent harnesses and execution environments. > - Operators need one place to select where native agent logs and traces go. > - An inference proxy would add a dependency to the agent request path. > - This pull request supplies native OpenTelemetry settings to managed Codex and Claude Code processes. > - Company secrets protect destination credentials. Export failure does not change the task result. ## Linked Issues or Issue Description **Subsystem affected** Company settings, shared contracts, database, server, adapters, and runner. **Problem or motivation** An operator cannot configure a company destination for native agent logs and traces. Manual harness configuration is hard to apply across local and remote execution. **Proposed solution** Add one company destination: Braintrust or a custom OTLP HTTP/protobuf endpoint. Apply a transient snapshot when execution preparation starts. Keep credentials out of API reads, task environment manifests, recovery files, and command arguments. Replace a warm process when its export settings change and preserve its conversation. **Alternatives considered** Multiple destinations can use a user-operated collector for fan-out. This change does not add a collector, an inference proxy, or transcript scraping. **Roadmap alignment** This extends company settings, secret management, and support for multiple harnesses. The maintainer requested this implementation. Searches for observability and Braintrust found no duplicate company destination feature. Related infrastructure tracing work in #16236 has a separate content-free contract. ## What Changed - Add strict schemas, revision checks, encrypted secret storage, activity records, and board-only settings routes. - Add explicit synthetic logs and traces tests with a bounded HTTP request and sanitized results. - Supply native Codex configuration and Claude Code environment values through local and remote launch paths. - Preserve Codex login refresh through the existing managed credential link. Retain unsaved drafts across background reads. Require complete custom header re-entry when the endpoint origin changes. - Separate process export compatibility from conversation identity. Isolate generated Codex configuration and preserve resumable sessions, including remote home refresh after export changes. - Advance the immutable Pi/Copilot source attestations for shared environment and sidecar code changes. Keep their provider payloads unchanged and retain prior identities for decoding. - Redact destination credentials throughout launch diagnostics and HTTP logs. - Add the production settings form, Storybook states and journey, documentation, and feature/access map entries. ## Verification - Real managed local Codex 0.160.0 and Claude Code 2.1.286 tasks exported to Braintrust. API readback and the Braintrust UI showed the test records. A real remote Daytona Codex task exported through the legacy `exec` path. - Live tests exercised content capture off, export disabled, warm conversation reuse, and a destination that accepted connections but never replied. Agent work succeeded and export requests stopped at the configured three-second timeout. The UI connection test returned “Test payload accepted”; the saved API key stayed masked after reload. - All current-head CI test lanes, typechecks, packaging/build checks, and required aggregates passed on `71e994b2be9c8fb6d6e938a4ad7cf4c95fdafe31` ([CI run](https://github.com/paperclipai/paperclip/actions/runs/39319194318)). Greptile completed on that exact commit at 5/5, with zero unresolved review threads. The additional optional Paperclip Review check remains queued waiting for its assigned agent. - Local workspace typecheck and build passed. Focused verification included 239 combined runner tests, 789 API/native-session tests, 107 Codex home/ACP/sandbox-site tests, 204 feature/privacy tests, and the affected Rust suites. Migration, token, map, Storybook catalog, and Storybook build checks passed during acceptance. These checks ran at the relevant implementation or merge boundary; the current-head CI is the complete final gate. - Managed AI credential projections now receive enabled and disabled company export settings; genuine caller-owned Codex homes remain untouched. Two regressions reproduced the skip before the repair. All 276 engine/lifecycle tests and adapter-utils typecheck pass afterward. The launched TOML retains provider/MCP settings, credential continuity, and redaction. - Settings saves, removal, and the real company-deletion owner acquire secret mutation ownership before database locks. PostgreSQL NOWAIT probes cover all three paths; concurrent save/rotation/removal/deletion requests settle correctly. The affected suites passed 137 tests, followed by all 32 service/connection cases after expanded deletion coverage. Server and Codex adapter typechecks pass. - Codex source profiles use the effective CLI argument list. A spawned fixture CLI reproduced both ignored-argument failures; all three precedence/fallback cases now pass. - Real tar staging reproduced remote conversation loss in both API-key and subscription modes before the repair. Both now pass: changing managed settings preserves sessions, archives, native indexes, and refreshed subscription credentials. A corrupt upload preserves the prior config and conversation. - Preserved failure evidence: initial CI caught stale Pi/Copilot source attestations, a missing test-harness helper, and packaging fixture/probe mismatches; those were corrected and covered by focused checks. Superseded heads had intermittent attachment-composer timeouts despite successful uploads; [the original trace and screenshot remain available](https://github.com/paperclipai/paperclip/actions/runs/39309701089/artifacts/12215109203). The same attachment case passed on the final head: [25/25 tests in shard 3](https://github.com/paperclipai/paperclip/actions/runs/39319194318/job/118288637051). - A connection-fault fixture also exposed a stale pooled socket after its hang case; closing fixture responses isolated scenarios and the full affected suite passed. - The broad local test run was not clean: database resource failures, timeouts, an older cached module graph, and a stale optional-resource manifest assumption were recorded. Focused checks passed after the documented fixes. This does not establish a clean full local pass. - Native remote Codex, remote Claude, and the full ACPX Codex bridge remain unqualified. The direct Codex resume test does not establish full bridge acceptance. ## Risks - Native exporters perform network requests from each execution environment. A server connection test does not prove remote reachability. - Prompts, assistant responses, and tool content are enabled by default when supported. Native caps and harness-specific controls still apply. - Caller-owned Codex homes are unsupported for automatic configuration and remain untouched. - Native harnesses and their tool processes can inspect export credentials. The settings form and documentation advise using ingestion-scoped credentials. Retained headers remain bound to their saved scheme, host, and port; changing origin requires fresh values or removal. - Migration 0357 adds a company-scoped row and secret reference. It is safe to reapply. Secret removal and company deletion use the existing secret lifecycle. - Slow or unavailable destinations must not block task settlement. Export settings take effect at the next execution preparation boundary. ## Model Used OpenAI Codex, GPT-6, with reasoning, tool use, code execution, and browser verification. The exact serving model ID and context window size are not exposed in this session. ## 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 - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
8.2 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Companies and portability
An operator can switch between companies, change their identity and settings, archive them, and preview an import or export. Each company remains a separate scope for work and agents.
Implementation: companies, settings, import, export.
Agent access: companion.
Sub-features
selection: create/select a company and keep navigation in its scope.identity: update company identity and configured settings.decision-models: configure and test the company's decision model, then inspect invocation history and recorded usage.fast-responses: configure and test the experimental fast-response service, then inspect acknowledgement history, failures, and recorded usage.agent-observability: configure one company OTLP destination for Codex and Claude Code, test synthetic delivery, and disable export.archive: archive and restore through the available controls without confusing archival with deletion.portability: preview a company package and inspect imported agents, projects, skills, and conflicts.
How to get to it (user POV)
company-switcher
Use the company switcher or /companies, then enter company Settings.
package-transfer
Use /company/export and /company/import where enabled, or the corresponding CLI company commands.
company-ai-services
Use Settings → Connections (/company/settings/connections) when fast responses
are enabled. Otherwise decision-model settings remain in Company Settings.
Open the Decisions and Fast responses tabs in Costs to inspect invocation history.
Driving it with Playwright and the Paperclip CLI
Preconditions: follow the baseline. Use two disposable companies and a small package fixture. Record cloud-managed restrictions and visible settings gates.
company-switcher
Automated: company list and archive UI cover UI behavior with mocks.
Manual: Create or select a company, rename it, and reload. Switch to the second company and back; verify tasks, agents, and settings follow the selection. Archive the disposable company and verify its visibility and offered restoration path.
package-transfer
Automated: portability routes and CLI import/export cover package and command behavior, not every external Git host.
Manual: Export a small company, inspect the package preview, and import into a disposable target. Verify counts, references, conflict choices, and agent configuration. Run one imported task after supplying its required local credentials. Confirm source company data is unchanged.
company-ai-services
Automated: decision settings, decision history, fast-response settings, decision service, and fast-response service cover component and service contracts with simulated providers.
Manual: As an authorized connection manager, select a disposable shared AI connection, save the provider/model and sponsorship options, reload, and run the bounded Test action. Inspect success and failure receipts and their history in Costs. Verify disabled or revoked connections remain clear and that a user without connection-management permission cannot configure or test the service. Use an owned provider fixture for failure states; record any actual provider usage.
Gotchas
-
Restore an archived company through
/companies→ its menu → Unarchive. Archiving pauses eligible agents and cancels active runs; restoration handles agents paused specifically for company archival. -
Package presence does not prove a runnable imported company; credentials and environment bindings need separate verification.
-
Company deletion is a distinct gated operation; do not use it as the archive test.
-
Settings hidden in a managed deployment should be recorded as unavailable, not bypassed.
-
Decision tests and fast responses have different request and execution contracts. A fast-response receipt is an acknowledgement, not completed agent work. History visibility and connection-management authority are separate; task links in history also require access to the underlying task.
Storybook verification
selection
Scope: ui Storybook: Company list/create/switcher; empty, loading, error, unavailable company and switched navigation. Production: Switch and reload between companies; verify tasks/agents/cache/routes remain scoped and unauthorized company requests fail. Sources: Source: Companies.tsx, CompanySwitcher.tsx, CompanyContext.tsx. Tests: Companies.test.tsx, CompanyContext.test.tsx, companies-route-cross-company-authz.test.ts
archive
Scope: ui Storybook: Archive confirmation, pending/error and departure navigation; archived list entry and Unarchive action. Production: Archive eligible agents/runs without deleting history; restoration handles archival-specific pause and navigates to correct company. Sources: Source: CompanySettings.tsx, Companies.tsx, companies.ts. Tests: CompanySettingsArchive.test.tsx, Companies.test.tsx, companies-service.test.ts
portability
Scope: ui Storybook: Import/export preview, conflict choice, warnings, async progress/failure/success and restricted managed deployment. Production: Apply real small package to disposable target; inspect counts/references/conflicts, source immutability and credential exclusions; imported task requires separate runnable-account proof. Sources: Source: CompanyImport.tsx, CompanyExport.tsx, companies.ts. Tests: CompanyImport.test.tsx, CompanyExport.test.tsx, company-portability-routes.test.ts, company-import-export-e2e.test.ts
Documentation scope: Company and instance administration
Core administration/import/export/operator workflows are mapped; cloud/self-hosted differences, migration/restore compatibility, and platform-specific service variants need deeper recipes.
agent-observability
Use Company Settings → General → Agent observability. Select Braintrust or Custom OTLP, save credentials and capture settings, then test the saved destination. Saving is offline; the test originates at the control plane and does not prove remote runner reachability.
Automated: shared validation, encrypted configuration service, receiver tests, runtime projection, and production settings stories cover their respective boundaries. Provider delivery requires a real run.
Manual: configure a disposable company, reload, test, run Codex and Claude Code locally and remotely, inspect their unique markers at the destination, then disable and verify a new marker is absent.
Storybook verification: agent-observability-01-settings, agent-observability-02-states,
and agent-observability-03-journey mount production subjects with simulated APIs/providers.