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.5 KiB
Companies and portability — agent access
Product map: Companies and portability.
Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b.
Native REST transport reconciled in this change; see the
shared transport contract.
This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.
selection
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}.GET /api/companies.POST /api/companies.
Agent access: partial — Agent reads its bound company; CLI context chooses it; board
lists/creates companies.
Policy: Same-company CEO or board for identity/import operations; list/create/archive convenience endpoint is board-gated.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: A worker cannot enumerate/create companies via its company agent key. Browser selection is local state.
identity
Review: baseline.
API: present — representative operation IDs:
PATCH /api/companies/{companyId}.PATCH /api/companies/{companyId}/branding.
Agent access: available — Same-company CEO REST / native call_api / CLI company.
Policy: Same-company CEO or board for identity/import operations; list/create/archive convenience endpoint is board-gated.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: The CEO restriction is a real policy, not a missing API; ordinary employees need denial evidence.
archive
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/archive.PATCH /api/companies/{companyId}.
Agent access: partial — Board archive endpoint; CEO company PATCH can express status
changes.
Policy: Same-company CEO or board for identity/import operations; list/create/archive convenience endpoint is board-gated.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Convenience archive and general company PATCH have different authorization. Review equivalence rather than declaring all archival human-only.
portability
Review: baseline.
API: present — representative operation IDs:
POST /api/companies/{companyId}/exports.POST /api/companies/{companyId}/imports/preview.POST /api/companies/{companyId}/imports/apply.
Agent access: partial — Same-company CEO REST / native call_api / CLI exports
and eligible same-company imports.
Policy: Same-company CEO or board for identity/import operations; list/create/archive convenience endpoint is board-gated.
Evidence: source-only — implementation
at the reviewed commit above.
Verification: not-run — exercise a listed permitted operation with actual agent
credentials/run context; inspect its result and applicable persistence/attribution.
Assert the relevant denied actor, owner, company or mode from Policy. Review the
remaining operations before qualifying the whole capability.
Gaps: Exports use inline credential delivery and encrypted mutation receipts. New-company/ZIP import flows retain their board and transport constraints.
decision-models
Review: baseline.
API: present — GET and PUT /api/companies/{companyId}/decision-model;
POST /api/companies/{companyId}/decision-model/test;
GET /api/companies/{companyId}/decision-model/availability;
GET /api/companies/{companyId}/decision-model/history.
Agent access: partial — same-company REST and admitted native call_api
availability/history reads where policy allows. Settings and the fixed Test
action require board identity. Native rollout/run gates follow the shared
transport contract.
Policy: Settings access requires board and company access; non-managers receive no settings or choices. Configuration and tests additionally require connection management authority (owner/admin, instance admin, or tools:manage_connections). History requires company_scope:read and redacts task/run links without issue:read. Background sponsorship and budget admission remain separate service checks.
Evidence: source-only — reviewed on 2026-10-13 at
60bc0d5fee9a6e48db08fc016521fee3d9f57d67:
routes,
service, and
connection authority.
Verification: not-run — read history with an allowed company actor and an actor
without task access; check link redaction. Reject agent configuration/tests and
board mutations without connection-management permission. Verify settings and
bounded test receipts with an owned simulated provider.
Gaps: No agent settings/test path; permitted history does not delegate management. Live native and agent-credential reads remain unverified.
fast-responses
Review: baseline.
API: present — GET and PUT /api/companies/{companyId}/fast-response;
GET /api/companies/{companyId}/fast-response/models;
GET /api/companies/{companyId}/fast-response/availability;
POST /api/companies/{companyId}/fast-response/test;
GET /api/companies/{companyId}/fast-response/history.
Agent access: partial — same-company REST and admitted native call_api history
reads where policy allows, subject to the shared
transport contract.
Settings, model selection, availability and test controls require board identity.
Policy: Board and company access gate configuration surfaces. Updates, models and tests additionally require connection-management authority. History requires company_scope:read; task/run links require issue:read. The experiment, provider account, sponsorship and budget controls still gate actual acknowledgements.
Evidence: source-only — reviewed on 2026-10-13 at
60bc0d5fee9a6e48db08fc016521fee3d9f57d67:
routes,
service, and
connection authority.
Verification: not-run — inspect history and redacted task links as an allowed
company actor. Reject agent settings/models/availability/tests and unauthorized
board mutations. Use a simulated provider to inspect a saved configuration,
success receipt, timeout and recorded usage.
Gaps: No agent configuration/test path. An acknowledgement is not completed task work. Live native, provider and agent access remain unverified.
agent-observability
Review: baseline.
API: present — representative operation IDs:
GET /api/companies/{companyId}/observability.PUT /api/companies/{companyId}/observability.DELETE /api/companies/{companyId}/observability.POST /api/companies/{companyId}/observability/test.
Agent access: operator-only — configuration and tests require board context.
Policy: Company access and Manage connections permission; non-managing board readers receive no settings. Credentials are write-only and stored through company secret bindings.
Evidence: source-only — routes.
Verification: not-run — exercise board management, restricted board, agent denial, and cross-company denial.
Gaps: Direct agent management and independent personal harness enrollment are outside v1.