diff --git a/packages/shared/src/telemetry/README.md b/packages/shared/src/telemetry/README.md index 36b4a57d187..41b9c614005 100644 --- a/packages/shared/src/telemetry/README.md +++ b/packages/shared/src/telemetry/README.md @@ -53,6 +53,13 @@ to a stable reporting shape. Do not add client-side lowercasing, alias mapping, or fallback mapping unless the generated telemetry contract specifically requires that emitted value. +The `adapter_type` dimension on `agent.task_run` and `agent.task_completed` is +not an alias map. For a Paperclip runner agent, the server sends the harness +that `agentHarnessType()` resolves from the agent configuration. The receiving +layer does not get that configuration, so it cannot derive the harness from +`paperclip_runner`. The emitter sends the resolved value raw. It does not fall +back to `other`. + If a dimension is privacy-protected before emission, emit only the protected value and its matching public marker as defined by the typed helper or generated contract. Do not emit private source material in telemetry dimensions. @@ -130,6 +137,17 @@ category decides the code only for the generic `adapter_failed` and run failure code sets in `server/src/services/continuation-cause.ts`, and a test fails when a code in those sets has no telemetry code. +The `adapter_type` dimension on `agent.task_run` and `agent.task_completed` +reports the harness the agent runs, as `agentHarnessType()` resolves it. A +Paperclip runner agent therefore reports its underlying harness (for example +`claude_local` or `codex_local`), not `paperclip_runner`. Some runner harnesses +are not in the generated `adapter_type` enum yet: `acpx:copilot`, +`antigravity_runtime`, `aws_agentcore`, `claude_managed`, `grok_bot`, `muse`, +and `openai_dot`. The receiving layer reports them as `other` until the +contract lists them. A test in +`server/src/__tests__/agent-task-run-telemetry.test.ts` fails when a runner +harness that is not in this list is missing from the contract. + ## Product Lifecycle Events `model.connected`, `task.created`, `task.completed`, `task.blocked`, diff --git a/server/src/__tests__/agent-task-run-telemetry.test.ts b/server/src/__tests__/agent-task-run-telemetry.test.ts index cbce97e41f8..fa762527e9e 100644 --- a/server/src/__tests__/agent-task-run-telemetry.test.ts +++ b/server/src/__tests__/agent-task-run-telemetry.test.ts @@ -8,6 +8,8 @@ import { } from "./helpers/embedded-postgres.js"; import { scopedTelemetryCompanyId, scopedTelemetryPerson } from "../telemetry-company-scope.js"; import { EXECUTION_RECONCILIATION_CAUSES } from "@paperclipai/shared"; +import { PAPERCLIP_ENUM_DESCRIPTIONS } from "@paperclipai/shared/telemetry"; +import { PAPERCLIP_RUNNER_ACPX_PROFILES, PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES } from "@paperclipai/adapter-utils"; import { PERMANENT_FAILURE_CODES, PERSON_OWNED_FAILURE_CODES, RESTART_CLASS_FAILURE_CODES, SETUP_FAILURE_CODES } from "../services/continuation-cause.ts"; const mockTelemetryClient = vi.hoisted(() => ({ track: vi.fn() })); @@ -27,7 +29,7 @@ vi.mock("@paperclipai/shared/telemetry", async () => { }; }); -import { agentRunFailureCause, emitAgentTaskRun, emitAgentTaskRunById } from "../services/agent-task-run-telemetry.ts"; +import { agentRunFailureCause, emitAgentTaskRun, emitAgentTaskRunById, telemetryAdapterType } from "../services/agent-task-run-telemetry.ts"; const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport(); const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip; @@ -376,6 +378,19 @@ describeEmbeddedPostgres("emitAgentTaskRun", () => { await expect(emitAgentTaskRun(db, run)).resolves.toBeUndefined(); }); + it.each([ + { adapterConfig: {}, adapterType: "codex_local" }, + { adapterConfig: { provider: "acpx", acpxAgent: "claude" }, adapterType: "claude_local" }, + { adapterConfig: { provider: "opencode" }, adapterType: "opencode_local" }, + ])("reports a Paperclip runner agent's underlying harness $adapterType as adapterType", async ({ adapterConfig, adapterType }) => { + await seedCompanyAndAgent({ adapterType: "paperclip_runner", adapterConfig }); + const [run] = await db.insert(heartbeatRuns).values({ companyId, agentId, status: "succeeded" }).returning(); + + await emitAgentTaskRun(db, run); + + expect(mockTrackAgentTaskRun.mock.calls[0][1].adapterType).toBe(adapterType); + }); + it("omits adapterType and agentRole when the agent row is absent", async () => { await seedCompanyAndAgent(); const run = { @@ -454,3 +469,25 @@ describe("agentRunFailureCause", () => { expect(unclassified).toEqual([]); }); }); + +describe("Paperclip runner adapter_type coverage", () => { + it.each(["agent.task_run", "agent.task_completed"] as const)("lists every runner harness in the %s adapter_type contract except the known gaps", (event) => { + const contract = Object.keys(PAPERCLIP_ENUM_DESCRIPTIONS[event].adapter_type); + const harnesses = [ + ...Object.keys(PAPERCLIP_RUNNER_PERMISSION_CAPABILITIES) + .filter((provider) => provider !== "acpx") + .map((provider) => telemetryAdapterType({ adapterType: "paperclip_runner", adapterConfig: { provider } })), + ...PAPERCLIP_RUNNER_ACPX_PROFILES.map(({ value }) => telemetryAdapterType({ adapterType: "paperclip_runner", adapterConfig: { provider: "acpx", acpxAgent: value } })), + ]; + + expect(harnesses.filter((harness) => !contract.includes(harness)).sort()).toEqual([ + "acpx:copilot", + "antigravity_runtime", + "aws_agentcore", + "claude_managed", + "grok_bot", + "muse", + "openai_dot", + ]); + }); +}); diff --git a/server/src/__tests__/issue-telemetry-routes.test.ts b/server/src/__tests__/issue-telemetry-routes.test.ts index 04e75132724..a8888f54054 100644 --- a/server/src/__tests__/issue-telemetry-routes.test.ts +++ b/server/src/__tests__/issue-telemetry-routes.test.ts @@ -253,6 +253,34 @@ describe("issue telemetry routes", () => { await vi.waitFor(() => expect(people).toEqual([expected])); }, 10_000); + it("emits a Paperclip runner agent's underlying harness as the adapter type", async () => { + mockAgentService.getById.mockResolvedValue({ + id: "agent-1", + companyId: "company-1", + role: "engineer", + adapterType: "paperclip_runner", + adapterConfig: { provider: "acpx", acpxAgent: "claude", model: "claude-sonnet-4-6" }, + }); + + const app = await createApp({ + type: "agent", + agentId: "agent-1", + companyId: "company-1", + runId: "22222222-2222-4222-8222-222222222222", + }); + const res = await request(app) + .patch("/api/issues/11111111-1111-4111-8111-111111111111") + .send({ status: "done" }); + + expect(res.status).toBe(200); + await vi.waitFor(() => { + expect(mockTrackAgentTaskCompleted).toHaveBeenCalledWith( + expect.anything(), + expect.objectContaining({ adapterType: "claude_local", model: "claude-sonnet-4-6" }), + ); + }); + }, 10_000); + it("does not emit agent task-completed telemetry for board-driven completions", async () => { const app = await createApp({ type: "board", diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.ts index 8f1092dacc0..0da962ebb8e 100644 --- a/server/src/routes/issues.ts +++ b/server/src/routes/issues.ts @@ -249,7 +249,7 @@ import { ContextCompactionError, contextCompactionService } from "../services/co import { issueContextUsage } from "../services/issue-context-usage.js"; import { queueLiveRunnerPrpCommand } from "../realtime/runner-prp-ws.js"; import { questionResponseDeliveryService } from "../services/question-response-delivery.js"; -import { emitAgentTaskRunById } from "../services/agent-task-run-telemetry.js"; +import { emitAgentTaskRunById, telemetryAdapterType } from "../services/agent-task-run-telemetry.js"; import { createAutomaticGoalCommentSteering, createQueuedCommentQueue, @@ -16328,7 +16328,7 @@ export function issueRoutes( withTelemetryActor({ companyId: issue.companyId, person }, () => trackAgentTaskCompleted(tc, { agentRole: actorAgent.role, agentId: actorAgent.id, - adapterType: actorAgent.adapterType, + adapterType: telemetryAdapterType(actorAgent), model, taskId: issue.id, })); diff --git a/server/src/services/agent-task-run-telemetry.ts b/server/src/services/agent-task-run-telemetry.ts index c05b7dd1111..ceab7157111 100644 --- a/server/src/services/agent-task-run-telemetry.ts +++ b/server/src/services/agent-task-run-telemetry.ts @@ -1,6 +1,6 @@ import { and, eq, sql } from "drizzle-orm"; import { agents, heartbeatRuns, issues, type Db } from "@paperclipai/db"; -import { requiresExecutionReconciliation } from "@paperclipai/shared"; +import { agentHarnessType, requiresExecutionReconciliation } from "@paperclipai/shared"; import { PERMANENT_FAILURE_CODES, RESTART_CLASS_FAILURE_CODES, SETUP_FAILURE_CODES } from "./continuation-cause.js"; import { trackAgentTaskRun } from "@paperclipai/shared/telemetry"; import { parseObject } from "../adapters/utils.js"; @@ -143,6 +143,10 @@ export function agentRunFailureCause(input: { return PLATFORM_FAILURE_CODES.has(code) ? "platform_error" : "unknown"; } +export function telemetryAdapterType(agent: { adapterType: string; adapterConfig: unknown }): string { + return agentHarnessType(agent.adapterType, parseObject(agent.adapterConfig)); +} + function providerFailureCategory(resultJson: unknown): string | null { const providerFailure = parseObject(parseObject(resultJson).providerFailure); return typeof providerFailure.category === "string" ? providerFailure.category : null; @@ -243,7 +247,7 @@ export async function emitAgentTaskRun(db: Db, run: TelemetryRun): Promise agentId: run.agentId, state: run.status, ...(agent - ? { adapterType: agent.adapterType, agentRole: agent.role } + ? { adapterType: telemetryAdapterType(agent), agentRole: agent.role } : {}), ...(model ? { model } : {}), ...(() => { diff --git a/tests/runner-e2e/source-sdk-public-inputs.json b/tests/runner-e2e/source-sdk-public-inputs.json index ba5e145aece..51c7cdf0aea 100644 --- a/tests/runner-e2e/source-sdk-public-inputs.json +++ b/tests/runner-e2e/source-sdk-public-inputs.json @@ -371,7 +371,7 @@ "packages/shared/src/standing-checks.ts": "7ab71e4b6984e41e1c1dfd1bddf0116041d5abf1", "packages/shared/src/subscriptions.ts": "ef70e63395ca967bbc30776b71560e96eb354a75", "packages/shared/src/summary-slot.test.ts": "5f8e222dea425f0d5bff0adb5c683087bd7cf7fb", - "packages/shared/src/telemetry/README.md": "36b4a57d187218ec141256d7f093c96c793ff901", + "packages/shared/src/telemetry/README.md": "41b9c614005d53b74b6a4c9c9a55c715e9144653", "packages/shared/src/telemetry/client-types.test.ts": "3b630edda4972b929ba4decd7457f226eb9cfc5b", "packages/shared/src/telemetry/client.test.ts": "5a95f2305a393c5b2e7750b10e0ed65da0f30cf8", "packages/shared/src/telemetry/client.ts": "d6534ce8aaa6f69fb2dd03e12487db024e250a96",