mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-19 16:29:42 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Paperclip Cloud sends server telemetry straight to PostHog (`server/src/services/posthog-direct/`) > - Request events get `company_id` from the request context. Background events have no request. > - So `agent.task_run`, `routine.run`, `connection.invoked`, and other background events arrive with `stack_id` but without `company_id`. On staging, 66 of 66 `agent.task_run` events had a null `company_id`. > - Without `company_id`, product analytics cannot split agent and routine activity by company. > - This pull request lets each background emit site name the company of the entity that it reports on. Only the direct PostHog transport reads that company. > - The benefit is that Cloud background events carry `company_id`, and the self-hosted collector output does not change. ## Linked Issues or Issue Description Refs #22006 **Subsystem affected** Server telemetry: Cloud direct delivery to PostHog (`server/src/services/posthog-direct/`) and the server emit sites for background events. **Problem or motivation** Cloud direct events from background work have no `company_id`. Heartbeat runs, scheduled routines, connection invocations, and interaction updates do not run inside an HTTP request, so the request context gives no company. On paperclip.staging, all 66 sampled `agent.task_run` events had `company_id` null. **Proposed solution** Add a small AsyncLocalStorage scope, `withTelemetryCompany(companyId, fn)`, in `server/src/telemetry-company-scope.ts`. Each background emit site wraps its typed `track*` call with the company id of the row that it already has. The direct transport reads the scope at track time, through the existing `captureEventContext()` seam. A live request company still wins. The collector path never reads the scope. **Alternatives considered** 1. An optional context argument on the shared `track*` helpers. This changes the public helpers in `@paperclipai/shared` for a Cloud-only value, so I did not use it. 2. A scope around each whole work unit (heartbeat run, routine run, invocation). The emit calls are fire-and-forget and are spread across many modules, so it is easy to miss one or to leak a company into other work. A scope at the emit site is narrow and explicit. 3. Let the transport look up the company in the database. The transport must not query the database. **Roadmap alignment** This completes the Cloud direct PostHog work from #22006. It does not change the telemetry contract. ## What Changed - Add `server/src/telemetry-company-scope.ts`. It has `withTelemetryCompany(companyId, fn)` and `scopedTelemetryCompanyId()`. With no company id, it calls `fn` directly. - `capturePostHogEventContext()` uses the scoped company when no live request gives a company. The request company, user, and session behave as before. - Wrap these emit sites with the company of their entity: - `agent.task_run` (`emitAgentTaskRun`, `emitAgentTaskRunById`; `companyId` is now part of the run that the function reads). This covers heartbeat, native runtime, recovery, run-dispatch, and watchdog callers. - `routine.run` (`routineService` dispatch, which covers scheduler, webhook, and manual runs) - `agent.first_heartbeat` (heartbeat agent status) - `connection.created`, `connection.updated`, `connection.invoked` - `interaction.created`, `interaction.resolved` - `agent.task_completed` (issue route; the issue company is the fallback when the request gives no company) - Request-only events (`project.created`, `goal.created`, `agent.created`, `routine.created`, `skill.imported`) keep the request context. `server.started` and `error_handler.crash` are not company-scoped. Dynamic plugin and `question_response.delivery` events are not in the contract, so the direct path drops them. - Update the "Cloud Direct Delivery" section of `packages/shared/src/telemetry/README.md`. Design note on module boundaries: the scope lives beside `server/src/telemetry.ts`, not inside `posthog-direct/`. Emit sites do not import the transport, and the transport does not know which services exist. The shared telemetry package does not change. ## Verification - Red/green: with the source changes removed, these 4 new tests fail. With the changes, they pass. - `agent-task-run-telemetry.test.ts`: `emitAgentTaskRun` and `emitAgentTaskRunById` track in the run company scope. - `routine-run-telemetry.test.ts`: a routine run tracks in the routine company scope. - `posthog-direct-telemetry.test.ts`: on Cloud, background `agent.task_run` and `routine.run` (also after an `await`) carry `company_id`, and an unscoped event does not. - `posthog-direct-telemetry.test.ts`: a live request company wins over the scope, and the scope fills the gap when the request has no company. - Red/green per emit family: the tests for `connection.created`, `connection.updated`, `connection.invoked`, `interaction.created`, `interaction.resolved`, `agent.first_heartbeat`, and `agent.task_completed` assert the company scope at track time. With the emit-site wrappers removed, all 7 assertions fail. - New guard test: on self-hosted, a scoped `agent.task_run` and `routine.run` produce a byte-identical collector envelope with no `company` text. - `cd server && npx vitest run` on 16 telemetry, PostHog, routine, heartbeat status, interaction, and connector test files: 408 passed. - `pnpm --filter @paperclipai/server typecheck`: passed. - Local check with a real `posthog-node` client sent to a local capture server (never real PostHog), embedded Postgres, and a real `routineService.tickScheduledTriggers()` tick plus `emitAgentTaskRun`: - Cloud mode: the captured `routine.run` (`source: schedule`) and `agent.task_run` both had the seeded `company_id`, plus `stack_id` and `environment`. `server.started` had no `company_id`. - Self-hosted mode: the collector body from this branch and from `origin/master` are identical after I normalize random ids and timestamps. - I did not boot a full Cloud-managed server, because it needs S3 and an external Postgres. The check above uses the same server modules and the real PostHog client. ## Risks - Privacy review: this is a Telemetry change under `rules/data-paths.mdc`, so I request a privacy review. Background Cloud events now send the real Paperclip `company_id` to PostHog. #22006 already approved `company_id` as a Cloud direct property for request events. This PR only fills it for background events. It adds no new property, dimension, or event, so the generated contract does not change. `packages/shared/src/telemetry/README.md` is updated in this PR. - Low runtime risk. The self-hosted collector path does not read the scope, and a test proves its output does not change. - On Cloud, more events now have `company_id`. No event loses a field. - If a request with a company tracks an event for an entity in a different company, the request company wins. This is the same as before this change. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, and 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 - [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 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>