DottaandPaperclip
b81b870732
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Product E2E journeys verify saved application behavior across deployments. > - Task creation and questions need reusable smoke selections and exact run attribution. > - Operators also need to inspect the OpenCode execution behind a measured question. > - Company observability does not currently support native OpenCode. > - This change adds the journeys and a bounded projection of normalized OpenCode run events. > - The projection follows the configured capture policy and retains the current run identity across warm reuse. ## Linked Issues or Issue Description Related foundation: #17262. Related alternative: #17989 exports metadata from OpenCode's native OTLP stream. This change uses normalized run events to support the existing content switches and per-run linkage. It does not forward the native stream. The two PRs overlap in launch registration and must be reconciled before both land. **What existing behavior does this improve?** Reusable Product E2E smoke selections and company observability for native OpenCode. **Current behavior** The journey catalog lacks reusable task creation and attached-agent question checks. Native OpenCode is marked unsupported for company observability, so a successful destination connection test does not prove that agent traces will appear. **Proposed behavior** Add explicit task-create and ask-question selections. Verify saved state and exact company, issue, agent, model, environment and successful run attribution. Export normalized OpenCode turns, tools and usage to the configured OTLP destination. Honor each capture switch and redact known secrets. **Reason and benefit** CI can run a small measured smoke selection, retain its screenshots and checks, and link results to traces belonging to the same run. **Breaking changes** Existing selectors remain unchanged. OpenCode export is opt-in through existing company settings. Legacy OpenCode stays unsupported. ## What Changed - Add reusable task creation and question journeys, configured-agent capability, owned-fixture checkpoints and strict evidence validation. - Add an OpenCode-owned projection of normalized run events. No provider SDK or raw payload schema enters heartbeat coordination. - Extend the private launch union and reserved environment allowlist for native OpenCode. With export disabled, no receiver request runs. - Keep destination headers in the parent wrapper and out of the actual provider child environment and configuration. - Bound each turn to 64 tool and 64 usage entries, 8 KiB per text field and a 1 MiB request. Use a three-second request deadline, four concurrent exports, and no retries or idle worker. - Pass the rotated runner authority to each proxy turn. A retained process no longer attributes later turns to its original launch run. - Update settings copy, observability documentation and capability maps. ## Verification - `pnpm -r typecheck` and `pnpm build` passed after the implementation changes. - Adapter launch/redaction: 9 tests passed. Projection and actual proxy: 12 tests passed before the review fix; the expanded projection suite passed all 12 cases after the fix. The proxy test exercises two runs in one process against a real local HTTP receiver and a fake provider. - Full OpenCode driver/projection suite: 72 passed, one existing response_wake test timed out at five seconds. A focused check then passed both existing omitted-continuation cases and the new trace export case. The timeout cause remains unconfirmed. - Runner package TypeScript and Rust `cargo check` passed. Map and UI token checks passed. - Prior journey validation: 273 tests across 12 files and the journey TypeScript check passed. - Broad local `pnpm test:run` encountered native-runtime integration failures with repeated embedded PostgreSQL initialization failures and was stopped. All 16 failing cases passed in an isolated run outside the filesystem sandbox (961 unrelated cases unselected). The broad local run is not a clean acceptance result. A later focused database-backed chat/heartbeat run passed all six selected observability cases, including native OpenCode launch and successful allocation (1,809 unrelated cases were unselected). - All CI gates passed for `21085f880d8babc9efeb22d0623db99613d33093`, including packaged-runner, clean-install, browser and build checks: https://github.com/paperclipai/paperclip/actions/runs/40884658995 . Greptile reviewed the same commit at 5/5 with no unresolved findings. - Verified OTLP JSON acceptance and indexing with an explicitly synthetic transport marker. No live OpenCode model trace or deployed smoke acceptance is claimed yet. ## Risks Export is best effort. Abrupt termination, recovered in-flight turns without a new submitted event, limits or receiver failure can lose traces. Export failure does not change task success. The projection represents observed normalized events, not raw native model spans or hidden reasoning. Known-secret redaction is not an OS isolation boundary. UI changes can break journey locators. Deployment adapters retain credential, ownership and cleanup responsibility. Both the controller and native runner bundle must be updated before live qualification. ## Model Used OpenAI Codex, GPT-6, with reasoning, code execution and browser tools. The exact serving model ID and context size are not exposed to 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 (targeted suites; broad local limitation documented above) - [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>
9.9 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.
Feature ID: companies.
Implementation: companies, settings, import, export.
Agent access: companion.
Sub-features
selection:companies/selection— create/select a company and keep navigation in its scope.identity:companies/identity— update company identity and configured settings.decision-models:companies/decision-models— configure and test the company's decision model, then inspect invocation history and recorded usage.prompt-injection-prevention:companies/prompt-injection-prevention— opt into a shared OpenRouter classifier for existing tool-result guards, test fixed samples, and recover unavailable selections.fast-responses:companies/fast-responses— configure and test the experimental fast-response service, then inspect acknowledgement history, failures, and recorded usage.agent-observability:companies/agent-observability— configure one company OTLP destination for Codex, Claude Code and native OpenCode, test synthetic delivery, and disable export.archive:companies/archive— archive and restore through the available controls without confusing archival with deletion.portability:companies/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) for Decision model
and Prompt Injection Prevention, independent of experimental flags. Fast response
appears there only when its experiment is enabled.
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
Capability ID: companies/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
Capability ID: companies/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
Capability ID: companies/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, Claude Code and native OpenCode 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.
prompt-injection-prevention
Capability ID: companies/prompt-injection-prevention.
Scope: ui, api, runtime
Storybook: Production PromptInjectionPreventionSettingsView states under Companies
and portability → Prompt Injection Prevention. Provider data is simulated.
Automated: settings,
service,
gateway,
guards including redaction
that hides content still delivered under the existing return contract.
Manual: Open Connections with Fast Responses off, save a shared OpenRouter
connection/default model, reload, run both fixed samples, and inspect charges.
Verify benign code reaches a gateway caller, malicious instructions are blocked,
provider failure records regex fallback, and disabling makes no model call.
Root results with concealed instruction text use input_redaction_mismatch
fallback without model dispatch.