The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
Implement generated client telemetry types (#8818)
Nicky Leach8a93a0de4cba
diff --git a/packages/shared/src/telemetry/client-types.test.ts b/packages/shared/src/telemetry/client-types.test.tsnew file mode 100644index 0000000000..3b630edda4--- /dev/null+++ b/packages/shared/src/telemetry/client-types.test.ts@@ -0,0 +1,25 @@+import { describe, expect, it } from "vitest";+import { TelemetryClient } from "./client.js";++describe("TelemetryClient event-name types", () => {+ it("keeps dynamic telemetry separate from registered events", () => {+ const client = new TelemetryClient(+ { enabled: false },+ () => ({+ installId: "test-install",+ salt: "test-salt",+ createdAt: "2026-01-01T00:00:00Z",+ firstSeenVersion: "0.0.0",+ }),+ "0.0.0-test",+ );++ client.track("install.started", {});+ client.trackDynamic("plugin.linear.sync_completed", {});++ // @ts-expect-error plugin events are intentionally not registered first-party events.+ client.track("plugin.linear.sync_completed", {});++ expect(client).toBeInstanceOf(TelemetryClient);+ });+});diff --git a/packages/shared/src/telemetry/client.ts b/packages/shared/src/telemetry/client.tsindex 9c4181cd3a..178e5f0556 100644--- a/packages/shared/src/telemetry/client.ts+++ b/packages/shared/src/telemetry/client.ts@@ -1,7 +1,9 @@import { createHash } from "node:crypto";import type {TelemetryConfig,+ TelemetryDimensions,TelemetryEvent,+ TelemetryEventDimensions,TelemetryEventName,TelemetryState,} from "./types.js";@@ -13,6 +15,11 @@ const DEFAULT_ENDPOINTS = [const BATCH_SIZE = 50;const SEND_TIMEOUT_MS = 5_000;+type TrackArgs<K extends TelemetryEventName> =+ keyof TelemetryEventDimensions<K> extends never+ ? [dimensions?: TelemetryEventDimensions<K>]+ : [dimensions: TelemetryEventDimensions<K>];+export class TelemetryClient {private queue: TelemetryEvent[] = [];private readonly config: TelemetryConfig;@@ -27,14 +34,32 @@ export class TelemetryClient {this.version = version;}- track(eventName: TelemetryEventName, dimensions?: Record<string, string | number | boolean>): void {+ /**+ * Tracks first-party Paperclip telemetry events registered in the generated+ * backend event schema.+ */+ track<K extends TelemetryEventName>(eventName: K, ...args: TrackArgs<K>): void {+ const [dimensions] = args;+ this.enqueue(eventName, dimensions);+ }++ /**+ * Tracks plugin telemetry bridge events whose names are built dynamically+ * from third-party plugin input. The backend accepts only explicitly+ * registered plugin events.+ */+ trackDynamic(eventName: string, dimensions?: TelemetryDimensions): void {+ this.enqueue(eventName, dimensions);+ }++ private enqueue(eventName: string, dimensions?: object): void {if (!this.config.enabled) return;this.getState(); // ensure state is initialised (side-effect: creates state file on first call)this.queue.push({name: eventName,occurredAt: new Date().toISOString(),- dimensions: dimensions ?? {},+ dimensions: { ...dimensions } as TelemetryDimensions,});if (this.queue.length >= BATCH_SIZE) {diff --git a/packages/shared/src/telemetry/events.ts b/packages/shared/src/telemetry/events.tsindex 1b347f3cd1..15315719b5 100644--- a/packages/shared/src/telemetry/events.ts+++ b/packages/shared/src/telemetry/events.ts@@ -1,91 +1,123 @@import type { TelemetryClient } from "./client.js";+import type { EventDimensionsMap } from "./generated/paperclip-telemetry.js";++type RawDimension<T extends string | undefined> = T | (string & {});++function asEventDimension<T extends string>(value: RawDimension<T>): T {+ return value as T;+}export function trackInstallStarted(client: TelemetryClient): void {- client.track("install.started");+ client.track("install.started", {});}export function trackInstallCompleted(client: TelemetryClient,- dims: { adapterType: string },+ dims: { adapterType: RawDimension<EventDimensionsMap["install.completed"]["adapter_type"]> },): void {- client.track("install.completed", { adapter_type: dims.adapterType });+ client.track("install.completed", {+ adapter_type: asEventDimension(dims.adapterType),+ });}export function trackCompanyImported(client: TelemetryClient,- dims: { sourceType: string; sourceRef: string; isPrivate: boolean },+ dims: {+ sourceType: RawDimension<EventDimensionsMap["company.imported"]["source_type"]>;+ sourceRef: string;+ isPrivate: boolean;+ },): void {const ref = dims.isPrivate ? client.hashPrivateRef(dims.sourceRef) : dims.sourceRef;client.track("company.imported", {- source_type: dims.sourceType,+ source_type: asEventDimension(dims.sourceType),source_ref: ref,source_ref_hashed: dims.isPrivate,});}export function trackProjectCreated(client: TelemetryClient): void {- client.track("project.created");+ client.track("project.created", {});}export function trackRoutineCreated(client: TelemetryClient): void {- client.track("routine.created");+ client.track("routine.created", {});}export function trackRoutineRun(client: TelemetryClient,- dims: { source: string; status: string },+ dims: {+ source: RawDimension<EventDimensionsMap["routine.run"]["source"]>;+ status: RawDimension<EventDimensionsMap["routine.run"]["status"]>;+ },): void {client.track("routine.run", {- source: dims.source,- status: dims.status,+ source: asEventDimension(dims.source),+ status: asEventDimension(dims.status),});}export function trackGoalCreated(client: TelemetryClient,- dims?: { goalLevel?: string | null },+ dims?: { goalLevel?: RawDimension<EventDimensionsMap["goal.created"]["goal_level"]> | null },): void {- client.track("goal.created", dims?.goalLevel ? { goal_level: dims.goalLevel } : undefined);+ client.track("goal.created", {+ goal_level: dims?.goalLevel ? asEventDimension(dims.goalLevel) : "other",+ });}export function trackAgentCreated(client: TelemetryClient,- dims: { agentRole: string; agentId?: string },+ dims: {+ agentRole: RawDimension<EventDimensionsMap["agent.created"]["agent_role"]>;+ agentId: string;+ },): void {client.track("agent.created", {- agent_role: dims.agentRole,- ...(dims.agentId ? { agent_id: dims.agentId } : {}),+ agent_role: asEventDimension(dims.agentRole),+ agent_id: dims.agentId,});}export function trackSkillImported(client: TelemetryClient,- dims: { sourceType: string; skillRef?: string | null },+ dims: {+ sourceType: RawDimension<EventDimensionsMap["skill.imported"]["source_type"]>;+ skillRef?: string | null;+ },): void {client.track("skill.imported", {- source_type: dims.sourceType,+ source_type: asEventDimension(dims.sourceType),...(dims.skillRef ? { skill_ref: dims.skillRef } : {}),});}export function trackAgentFirstHeartbeat(client: TelemetryClient,- dims: { agentRole: string; agentId?: string },+ dims: {+ agentRole: RawDimension<EventDimensionsMap["agent.first_heartbeat"]["agent_role"]>;+ agentId: string;+ },): void {client.track("agent.first_heartbeat", {- agent_role: dims.agentRole,- ...(dims.agentId ? { agent_id: dims.agentId } : {}),+ agent_role: asEventDimension(dims.agentRole),+ agent_id: dims.agentId,});}export function trackAgentTaskCompleted(client: TelemetryClient,- dims: { agentRole: string; agentId?: string; adapterType?: string; model?: string },+ dims: {+ agentRole: RawDimension<EventDimensionsMap["agent.task_completed"]["agent_role"]>;+ agentId: string;+ adapterType: RawDimension<EventDimensionsMap["agent.task_completed"]["adapter_type"]>;+ model?: string;+ },): void {client.track("agent.task_completed", {- agent_role: dims.agentRole,- ...(dims.agentId ? { agent_id: dims.agentId } : {}),- ...(dims.adapterType ? { adapter_type: dims.adapterType } : {}),+ agent_role: asEventDimension(dims.agentRole),+ agent_id: dims.agentId,+ adapter_type: asEventDimension(dims.adapterType),...(dims.model ? { model: dims.model } : {}),});}@@ -96,3 +128,38 @@ export function trackErrorHandlerCrash(): void {client.track("error.handler_crash", { error_code: dims.errorCode });}++export function trackInteractionResolved(+ client: TelemetryClient,+ dims: {+ interactionKind: RawDimension<EventDimensionsMap["interaction.resolved"]["interaction_kind"]>;+ status: RawDimension<EventDimensionsMap["interaction.resolved"]["status"]>;+ resolvedByKind: RawDimension<EventDimensionsMap["interaction.resolved"]["resolved_by_kind"]>;+ resolutionReason?: RawDimension<EventDimensionsMap["interaction.resolved"]["resolution_reason"]> | null;+ createdByKind?: RawDimension<EventDimensionsMap["interaction.resolved"]["created_by_kind"]> | null;+ creatorAgentRole?: RawDimension<EventDimensionsMap["interaction.resolved"]["creator_agent_role"]> | null;+ continuationPolicy?: RawDimension<EventDimensionsMap["interaction.resolved"]["continuation_policy"]> | null;+ targetType?: RawDimension<EventDimensionsMap["interaction.resolved"]["target_type"]> | null;+ optionCount?: number;+ selectedOptionCount?: number;+ questionCount?: number;+ answeredQuestionCount?: number;+ createdTaskCount?: number;+ },+): void {+ client.track("interaction.resolved", {+ interaction_kind: asEventDimension(dims.interactionKind),+ status: asEventDimension(dims.status),+ resolved_by_kind: asEventDimension(dims.resolvedByKind),+ ...(dims.resolutionReason ? { resolution_reason: asEventDimension(dims.resolutionReason) } : {}),+ ...(dims.createdByKind ? { created_by_kind: asEventDimension(dims.createdByKind) } : {}),+ ...(dims.creatorAgentRole ? { creator_agent_role: asEventDimension(dims.creatorAgentRole) } : {}),+ ...(dims.continuationPolicy ? { continuation_policy: asEventDimension(dims.continuationPolicy) } : {}),+ ...(dims.targetType ? { target_type: asEventDimension(dims.targetType) } : {}),+ ...(dims.optionCount === undefined ? {} : { option_count: dims.optionCount }),+ ...(dims.selectedOptionCount === undefined ? {} : { selected_option_count: dims.selectedOptionCount }),+ ...(dims.questionCount === undefined ? {} : { question_count: dims.questionCount }),+ ...(dims.answeredQuestionCount === undefined ? {} : { answered_question_count: dims.answeredQuestionCount }),+ ...(dims.createdTaskCount === undefined ? {} : { created_task_count: dims.createdTaskCount }),+ });+}diff --git a/packages/shared/src/telemetry/generated/paperclip-telemetry.ts b/packages/shared/src/telemetry/generated/paperclip-telemetry.tsnew file mode 100644index 0000000000..05ef53b9c4--- /dev/null+++ b/packages/shared/src/telemetry/generated/paperclip-telemetry.ts@@ -0,0 +1,371 @@+// GENERATED — DO NOT EDIT.++export interface PaperclipAgentCreatedDimensions {+agent_id: string+agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other")+}++export interface PaperclipAgentFirstHeartbeatDimensions {+agent_id: string+agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other")+}++export interface PaperclipAgentTaskCompletedDimensions {+adapter_type: ("process" | "http" | "acpx_local" | "claude_local" | "codex_local" | "cursor_cloud" | "gemini_local" | "hermes_gateway" | "hermes_local" | "opencode_local" | "pi_local" | "cursor" | "openclaw_gateway" | "grok_local" | "other")+agent_id: string+agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other")+model?: string+}++export interface PaperclipCompanyImportedDimensions {+source_type: ("local_path" | "github" | "url" | "catalog" | "skills_sh" | "unknown")+source_ref?: string+source_ref_hashed?: boolean+}++export interface PaperclipErrorHandlerCrashDimensions {+error_code: string+}++export interface PaperclipGoalCreatedDimensions {+goal_level: ("company" | "team" | "agent" | "task" | "other")+}++export interface PaperclipInstallCompletedDimensions {+adapter_type: ("process" | "http" | "acpx_local" | "claude_local" | "codex_local" | "cursor_cloud" | "gemini_local" | "hermes_gateway" | "hermes_local" | "opencode_local" | "pi_local" | "cursor" | "openclaw_gateway" | "grok_local" | "other")+}++export interface PaperclipInstallStartedDimensions {++}++export interface PaperclipInteractionResolvedDimensions {+interaction_kind: ("suggest_tasks" | "ask_user_questions" | "request_confirmation" | "request_checkbox_confirmation" | "other")+status: ("accepted" | "rejected" | "answered" | "cancelled" | "expired" | "failed" | "other")+resolution_reason?: ("accepted" | "rejected" | "stale_target" | "superseded_by_comment" | "expired" | "cancelled" | "other")+resolved_by_kind: ("user" | "agent" | "system" | "other")+created_by_kind?: ("agent" | "user" | "other")+creator_agent_role?: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other")+continuation_policy?: ("none" | "wake_assignee" | "wake_assignee_on_accept" | "other")+target_type?: ("issue_document" | "custom" | "none" | "other")+option_count?: number+selected_option_count?: number+question_count?: number+answered_question_count?: number+created_task_count?: number+skipped_task_count?: number+has_reason?: boolean+resolution_latency_seconds?: number+interaction_id?: string+created_by_agent_id?: string+source_run_id?: string+}++export interface PaperclipProjectCreatedDimensions {++}++export interface PaperclipRoutineCreatedDimensions {++}++export interface PaperclipRoutineRunDimensions {+source: ("schedule" | "manual" | "api" | "webhook" | "other")+status: ("received" | "coalesced" | "skipped" | "issue_created" | "completed" | "failed" | "other")+}++export interface PaperclipSkillImportedDimensions {+source_type: ("local_path" | "github" | "url" | "catalog" | "skills_sh" | "unknown")+skill_ref?: string+}++export type PaperclipEventName =+ | "agent.created"+ | "agent.first_heartbeat"+ | "agent.task_completed"+ | "company.imported"+ | "error.handler_crash"+ | "goal.created"+ | "install.completed"+ | "install.started"+ | "interaction.resolved"+ | "project.created"+ | "routine.created"+ | "routine.run"+ | "skill.imported";++export interface EventDimensionsMap {+ "agent.created": PaperclipAgentCreatedDimensions;+ "agent.first_heartbeat": PaperclipAgentFirstHeartbeatDimensions;+ "agent.task_completed": PaperclipAgentTaskCompletedDimensions;+ "company.imported": PaperclipCompanyImportedDimensions;+ "error.handler_crash": PaperclipErrorHandlerCrashDimensions;+ "goal.created": PaperclipGoalCreatedDimensions;+ "install.completed": PaperclipInstallCompletedDimensions;+ "install.started": PaperclipInstallStartedDimensions;+ "interaction.resolved": PaperclipInteractionResolvedDimensions;+ "project.created": PaperclipProjectCreatedDimensions;+ "routine.created": PaperclipRoutineCreatedDimensions;+ "routine.run": PaperclipRoutineRunDimensions;+ "skill.imported": PaperclipSkillImportedDimensions;+}++export const PAPERCLIP_EVENTS = {+ "agent.created": "agent.created",+ "agent.first_heartbeat": "agent.first_heartbeat",+ "agent.task_completed": "agent.task_completed",+ "company.imported": "company.imported",+ "error.handler_crash": "error.handler_crash",+ "goal.created": "goal.created",+ "install.completed": "install.completed",+ "install.started": "install.started",+ "interaction.resolved": "interaction.resolved",+ "project.created": "project.created",+ "routine.created": "routine.created",+ "routine.run": "routine.run",+ "skill.imported": "skill.imported",+} as const;++export const PAPERCLIP_ENUM_DESCRIPTIONS = {+ "agent.created": {+ "agent_role": {+ "ceo": "Agent configured for company leadership and board coordination work.",+ "cto": "Agent configured for technical leadership, architecture, and engineering coordination.",+ "cmo": "Agent configured for marketing leadership work.",+ "cfo": "Agent configured for finance leadership work.",+ "security": "Agent configured for security review, risk, or policy work.",+ "engineer": "Agent configured for general software engineering work.",+ "designer": "Agent configured for product, visual, or experience design work.",+ "pm": "Agent configured for product management or planning work.",+ "qa": "Agent configured for quality assurance, testing, or validation work.",+ "devops": "Agent configured for infrastructure, deployment, or operations work.",+ "researcher": "Agent configured for research and information-gathering work.",+ "general": "Agent configured as a general-purpose worker without a more specific role.",+ "other": "Fallback when the agent role is unknown or not represented by the tracked enum."+ }+ },+ "agent.first_heartbeat": {+ "agent_role": {+ "ceo": "Agent configured for company leadership and board coordination work.",+ "cto": "Agent configured for technical leadership, architecture, and engineering coordination.",+ "cmo": "Agent configured for marketing leadership work.",+ "cfo": "Agent configured for finance leadership work.",+ "security": "Agent configured for security review, risk, or policy work.",+ "engineer": "Agent configured for general software engineering work.",+ "designer": "Agent configured for product, visual, or experience design work.",+ "pm": "Agent configured for product management or planning work.",+ "qa": "Agent configured for quality assurance, testing, or validation work.",+ "devops": "Agent configured for infrastructure, deployment, or operations work.",+ "researcher": "Agent configured for research and information-gathering work.",+ "general": "Agent configured as a general-purpose worker without a more specific role.",+ "other": "Fallback when the agent role is unknown or not represented by the tracked enum."+ }+ },+ "agent.task_completed": {+ "adapter_type": {+ "process": "Agent runtime uses a local process adapter.",+ "http": "Agent runtime uses a generic HTTP adapter.",+ "acpx_local": "Agent runtime uses the local ACPX adapter.",+ "claude_local": "Agent runtime uses the local Claude adapter.",+ "codex_local": "Agent runtime uses the local Codex adapter.",+ "cursor_cloud": "Agent runtime uses the Cursor cloud adapter.",+ "gemini_local": "Agent runtime uses the local Gemini adapter.",+ "hermes_gateway": "Agent runtime uses the Hermes gateway adapter.",+ "hermes_local": "Agent runtime uses the local Hermes adapter.",+ "opencode_local": "Agent runtime uses the local OpenCode adapter.",+ "pi_local": "Agent runtime uses the local Pi adapter.",+ "cursor": "Agent runtime uses the Cursor adapter.",+ "openclaw_gateway": "Agent runtime uses the OpenClaw gateway adapter.",+ "grok_local": "Agent runtime uses the local Grok adapter.",+ "other": "Fallback when the adapter type is unknown or not represented by the tracked enum."+ },+ "agent_role": {+ "ceo": "Agent configured for company leadership and board coordination work.",+ "cto": "Agent configured for technical leadership, architecture, and engineering coordination.",+ "cmo": "Agent configured for marketing leadership work.",+ "cfo": "Agent configured for finance leadership work.",+ "security": "Agent configured for security review, risk, or policy work.",+ "engineer": "Agent configured for general software engineering work.",+ "designer": "Agent configured for product, visual, or experience design work.",+ "pm": "Agent configured for product management or planning work.",+ "qa": "Agent configured for quality assurance, testing, or validation work.",+ "devops": "Agent configured for infrastructure, deployment, or operations work.",+ "researcher": "Agent configured for research and information-gathering work.",+ "general": "Agent configured as a general-purpose worker without a more specific role.",+ "other": "Fallback when the agent role is unknown or not represented by the tracked enum."+ }+ },+ "company.imported": {+ "source_type": {+ "local_path": "Import source came from a filesystem path on the operator's machine.",+ "github": "Import source came from a GitHub repository or GitHub-backed reference.",+ "url": "Import source came from a direct URL.",+ "catalog": "Import source came from a Paperclip catalog entry.",+ "skills_sh": "Import source came from a Skills.sh-compatible source.",+ "unknown": "Source type could not be classified."+ }+ },+ "goal.created": {+ "goal_level": {+ "company": "Goal applies at company scope.",+ "team": "Goal applies at team or group scope.",+ "agent": "Goal applies to a specific agent.",+ "task": "Goal applies to task-level work.",+ "other": "Fallback when the goal level is unknown or not represented by the tracked enum."+ }+ },+ "install.completed": {+ "adapter_type": {+ "process": "Agent runtime uses a local process adapter.",+ "http": "Agent runtime uses a generic HTTP adapter.",+ "acpx_local": "Agent runtime uses the local ACPX adapter.",+ "claude_local": "Agent runtime uses the local Claude adapter.",+ "codex_local": "Agent runtime uses the local Codex adapter.",+ "cursor_cloud": "Agent runtime uses the Cursor cloud adapter.",+ "gemini_local": "Agent runtime uses the local Gemini adapter.",+ "hermes_gateway": "Agent runtime uses the Hermes gateway adapter.",+ "hermes_local": "Agent runtime uses the local Hermes adapter.",+ "opencode_local": "Agent runtime uses the local OpenCode adapter.",+ "pi_local": "Agent runtime uses the local Pi adapter.",+ "cursor": "Agent runtime uses the Cursor adapter.",+ "openclaw_gateway": "Agent runtime uses the OpenClaw gateway adapter.",+ "grok_local": "Agent runtime uses the local Grok adapter.",+ "other": "Fallback when the adapter type is unknown or not represented by the tracked enum."+ }+ },+ "interaction.resolved": {+ "interaction_kind": {+ "suggest_tasks": "Board-facing interaction that proposes concrete subtasks for acceptance.",+ "ask_user_questions": "Board-facing interaction that asks structured questions and stores answers.",+ "request_confirmation": "Board-facing interaction that asks for a single accept or reject decision.",+ "request_checkbox_confirmation": "Board-facing interaction that asks the board to select options and confirm.",+ "other": "Fallback when the interaction kind is unknown or not represented by the tracked enum."+ },+ "status": {+ "accepted": "Interaction was accepted.",+ "rejected": "Interaction was rejected.",+ "answered": "Ask-user-questions interaction was answered.",+ "cancelled": "Interaction was cancelled before acceptance or answer.",+ "expired": "Interaction expired because the bound target became stale or was superseded.",+ "failed": "Interaction resolution attempted but failed.",+ "other": "Fallback when the terminal status is unknown or not represented by the tracked enum."+ },+ "resolution_reason": {+ "accepted": "Stored result outcome says the interaction was accepted.",+ "rejected": "Stored result outcome says the interaction was rejected.",+ "stale_target": "Bound target, such as an issue document revision, was no longer current.",+ "superseded_by_comment": "A later user or board comment superseded the pending confirmation.",+ "expired": "Interaction expired for a generic expiration reason.",+ "cancelled": "Interaction was explicitly cancelled.",+ "other": "Fallback when the resolution reason is unknown or not represented by the tracked enum."+ },+ "resolved_by_kind": {+ "user": "A board or human user resolved the interaction.",+ "agent": "An agent resolved the interaction.",+ "system": "Paperclip resolved the interaction automatically.",+ "other": "Fallback when the resolver kind is unknown or not represented by the tracked enum."+ },+ "created_by_kind": {+ "agent": "Interaction was created by an agent.",+ "user": "Interaction was created by a board or human user.",+ "other": "Fallback when the creator kind is unknown or not represented by the tracked enum."+ },+ "creator_agent_role": {+ "ceo": "Agent configured for company leadership and board coordination work.",+ "cto": "Agent configured for technical leadership, architecture, and engineering coordination.",+ "cmo": "Agent configured for marketing leadership work.",+ "cfo": "Agent configured for finance leadership work.",+ "security": "Agent configured for security review, risk, or policy work.",+ "engineer": "Agent configured for general software engineering work.",+ "designer": "Agent configured for product, visual, or experience design work.",+ "pm": "Agent configured for product management or planning work.",+ "qa": "Agent configured for quality assurance, testing, or validation work.",+ "devops": "Agent configured for infrastructure, deployment, or operations work.",+ "researcher": "Agent configured for research and information-gathering work.",+ "general": "Agent configured as a general-purpose worker without a more specific role.",+ "other": "Fallback when the agent role is unknown or not represented by the tracked enum."+ },+ "continuation_policy": {+ "none": "Resolving the interaction does not automatically wake the issue assignee.",+ "wake_assignee": "Resolving the interaction wakes or returns the issue to the assignee.",+ "wake_assignee_on_accept": "Accepting the interaction wakes or returns the issue to the assignee.",+ "other": "Fallback when the continuation policy is unknown or not represented by the tracked enum."+ },+ "target_type": {+ "issue_document": "Interaction is bound to a specific issue document revision.",+ "custom": "Interaction is bound to a custom target.",+ "none": "Interaction has no bound target.",+ "other": "Fallback when the target type is unknown or not represented by the tracked enum."+ }+ },+ "routine.run": {+ "source": {+ "schedule": "Routine was triggered by a scheduled trigger.",+ "manual": "Routine was triggered manually by a user or agent action.",+ "api": "Routine was triggered through an API request.",+ "webhook": "Routine was triggered by a webhook.",+ "other": "Fallback when the source is unknown or not represented by the tracked enum."+ },+ "status": {+ "received": "Routine run was accepted for processing.",+ "coalesced": "A live execution already existed and the run was coalesced into it.",+ "skipped": "A live execution already existed and concurrency policy skipped the run.",+ "issue_created": "Routine dispatch created a new issue and queued the agent wakeup.",+ "completed": "Routine run completed without needing a new issue.",+ "failed": "Routine dispatch failed and the run was finalized as failed.",+ "other": "Fallback when the status is unknown or not represented by the tracked enum."+ }+ },+ "skill.imported": {+ "source_type": {+ "local_path": "Import source came from a filesystem path on the operator's machine.",+ "github": "Import source came from a GitHub repository or GitHub-backed reference.",+ "url": "Import source came from a direct URL.",+ "catalog": "Import source came from a Paperclip catalog entry.",+ "skills_sh": "Import source came from a Skills.sh-compatible source.",+ "unknown": "Source type could not be classified."+ }+ }+} as const;++export const SCHEMA_VERSION = "1" as const;++export interface PaperclipTelemetryEvent<K extends PaperclipEventName = PaperclipEventName> {+name: K+occurredAt: string+dimensions: EventDimensionsMap[K]+}++export type AnyPaperclipTelemetryEvent = {+ [K in PaperclipEventName]: PaperclipTelemetryEvent<K>+}[PaperclipEventName];++export interface PaperclipTelemetryBatch {+app: "paperclip"+schemaVersion: typeof SCHEMA_VERSION+installId: string+version?: string+events: AnyPaperclipTelemetryEvent[]+}++export function makeEvent<K extends PaperclipEventName>(+ name: K,+ dimensions: EventDimensionsMap[K],+ occurredAt: string+): PaperclipTelemetryEvent<K> {+ return { name, occurredAt, dimensions };+}++export function makeBatch(+ installId: string,+ events: readonly AnyPaperclipTelemetryEvent[],+ version?: string+): PaperclipTelemetryBatch {+ return {+ app: "paperclip",+ schemaVersion: SCHEMA_VERSION,+ installId,+ ...(version === undefined ? {} : { version }),+ events: [...events]+ };+}diff --git a/packages/shared/src/telemetry/index.ts b/packages/shared/src/telemetry/index.tsindex f80de29c3b..16b5d8de5d 100644--- a/packages/shared/src/telemetry/index.ts+++ b/packages/shared/src/telemetry/index.ts@@ -14,11 +14,21 @@ export {trackAgentFirstHeartbeat,trackAgentTaskCompleted,trackErrorHandlerCrash,+ trackInteractionResolved,} from "./events.js";export type {TelemetryConfig,TelemetryState,TelemetryEvent,TelemetryEventEnvelope,+ TelemetryDimensions,+ TelemetryDimensionValue,+ TelemetryEventDimensions,TelemetryEventName,+ RegisteredPluginEventName,} from "./types.js";+export type {+ AnyPaperclipTelemetryEvent,+ EventDimensionsMap,+ PaperclipEventName,+} from "./generated/paperclip-telemetry.js";diff --git a/packages/shared/src/telemetry/types.ts b/packages/shared/src/telemetry/types.tsindex d3552d0d21..b5c2aef21b 100644--- a/packages/shared/src/telemetry/types.ts+++ b/packages/shared/src/telemetry/types.ts@@ -1,3 +1,8 @@+import type {+ EventDimensionsMap,+ PaperclipEventName,+} from "./generated/paperclip-telemetry.js";+export interface TelemetryState {installId: string;salt: string;@@ -12,11 +17,14 @@ export interface TelemetryConfig {schemaVersion?: string;}+export type TelemetryDimensionValue = string | number | boolean;+export type TelemetryDimensions = Record<string, TelemetryDimensionValue>;+/** Per-event object inside the backend envelope */export interface TelemetryEvent {name: string;occurredAt: string;- dimensions: Record<string, string | number | boolean>;+ dimensions: TelemetryDimensions;}/** Full payload sent to the backend ingest endpoint */@@ -28,17 +36,8 @@ export interface TelemetryEventEnvelope {events: TelemetryEvent[];}-export type TelemetryEventName =- | "install.started"- | "install.completed"- | "company.imported"- | "project.created"- | "routine.created"- | "routine.run"- | "goal.created"- | "agent.created"- | "skill.imported"- | "agent.first_heartbeat"- | "agent.task_completed"- | "error.handler_crash"- | `plugin.${string}`;+export type RegisteredPluginEventName = never;+export type TelemetryEventName = PaperclipEventName | RegisteredPluginEventName;++export type TelemetryEventDimensions<K extends TelemetryEventName> =+ K extends keyof EventDimensionsMap ? EventDimensionsMap[K] : never;diff --git a/server/src/__tests__/plugin-telemetry-bridge.test.ts b/server/src/__tests__/plugin-telemetry-bridge.test.tsindex 367663d9bb..2b3b483627 100644--- a/server/src/__tests__/plugin-telemetry-bridge.test.ts+++ b/server/src/__tests__/plugin-telemetry-bridge.test.ts@@ -26,8 +26,8 @@ describe("plugin telemetry bridge", () => {});it("prefixes plugin telemetry events before forwarding them to the telemetry client", async () => {- const track = vi.fn();- mockGetTelemetryClient.mockReturnValue({ track });+ const trackDynamic = vi.fn();+ mockGetTelemetryClient.mockReturnValue({ trackDynamic });const services = buildHostServices({} as never,@@ -46,14 +46,14 @@ describe("plugin telemetry bridge", () => {dimensions: { attempts: 2, success: true },});- expect(track).toHaveBeenCalledWith("plugin.linear.sync_completed", {+ expect(trackDynamic).toHaveBeenCalledWith("plugin.linear.sync_completed", {attempts: 2,success: true,});});it("rejects invalid bare telemetry event names before prefixing", async () => {- mockGetTelemetryClient.mockReturnValue({ track: vi.fn() });+ mockGetTelemetryClient.mockReturnValue({ trackDynamic: vi.fn() });const services = buildHostServices({} as never,@@ -92,6 +92,9 @@ describe("plugin telemetry bridge", () => {});it("passes telemetry requests through when the plugin declares the capability", async () => {+ const trackDynamic = vi.fn();+ mockGetTelemetryClient.mockReturnValue({ trackDynamic });+const services = buildHostServices({} as never,"plugin-record-id",@@ -110,5 +113,8 @@ describe("plugin telemetry bridge", () => {});expect(mockGetTelemetryClient).toHaveBeenCalledTimes(1);+ expect(trackDynamic).toHaveBeenCalledWith("plugin.linear.sync_completed", {+ source: "manual",+ });});});diff --git a/server/src/__tests__/project-goal-telemetry-routes.test.ts b/server/src/__tests__/project-goal-telemetry-routes.test.tsindex 7b5b97bc1b..a0c12d799c 100644--- a/server/src/__tests__/project-goal-telemetry-routes.test.ts+++ b/server/src/__tests__/project-goal-telemetry-routes.test.ts@@ -150,7 +150,7 @@ describe("project and goal telemetry routes", () => {.send({ name: "Telemetry project" });expect([200, 201], JSON.stringify(res.body)).toContain(res.status);- expect(mockTelemetryTrack).toHaveBeenCalledWith("project.created");+ expect(mockTelemetryTrack).toHaveBeenCalledWith("project.created", {});});it("emits telemetry when a goal is created", async () => {diff --git a/server/src/__tests__/shared-telemetry-events.test.ts b/server/src/__tests__/shared-telemetry-events.test.tsindex 1d6483d2e8..8150910ae9 100644--- a/server/src/__tests__/shared-telemetry-events.test.ts+++ b/server/src/__tests__/shared-telemetry-events.test.ts@@ -3,9 +3,10 @@ import {trackAgentCreated,trackAgentFirstHeartbeat,trackAgentTaskCompleted,+ trackInteractionResolved,trackInstallCompleted,} from "@paperclipai/shared/telemetry";-import type { TelemetryClient } from "@paperclipai/shared/telemetry";+import type { EventDimensionsMap, TelemetryClient } from "@paperclipai/shared/telemetry";function createClient(): TelemetryClient {return {@@ -14,6 +15,10 @@ function createClient(): TelemetryClient {} as unknown as TelemetryClient;}+function runtimeValue<T>(value: string): T {+ return value as T;+}+describe("shared telemetry agent events", () => {it("includes agent_id for agent.created", () => {const client = createClient();@@ -29,16 +34,30 @@ describe("shared telemetry agent events", () => {});});+ it("passes an unrecognized agent role through for backend normalization", () => {+ const client = createClient();++ trackAgentCreated(client, {+ agentRole: runtimeValue<EventDimensionsMap["agent.created"]["agent_role"]>("coder"),+ agentId: "44444444-4444-4444-8444-444444444444",+ });++ expect(client.track).toHaveBeenCalledWith("agent.created", {+ agent_role: "coder",+ agent_id: "44444444-4444-4444-8444-444444444444",+ });+ });+it("includes agent_id for agent.first_heartbeat", () => {const client = createClient();trackAgentFirstHeartbeat(client, {- agentRole: "coder",+ agentRole: "engineer",agentId: "22222222-2222-4222-8222-222222222222",});expect(client.track).toHaveBeenCalledWith("agent.first_heartbeat", {- agent_role: "coder",+ agent_role: "engineer",agent_id: "22222222-2222-4222-8222-222222222222",});});@@ -49,11 +68,13 @@ describe("shared telemetry agent events", () => {trackAgentTaskCompleted(client, {agentRole: "qa",agentId: "33333333-3333-4333-8333-333333333333",+ adapterType: "codex_local",});expect(client.track).toHaveBeenCalledWith("agent.task_completed", {agent_role: "qa",agent_id: "33333333-3333-4333-8333-333333333333",+ adapter_type: "codex_local",});});@@ -70,4 +91,38 @@ describe("shared telemetry agent events", () => {expect.objectContaining({ agent_id: expect.any(String) }),);});++ it("passes interaction.resolved enum dimensions through for backend normalization", () => {+ const client = createClient();++ trackInteractionResolved(client, {+ interactionKind: runtimeValue<EventDimensionsMap["interaction.resolved"]["interaction_kind"]>(+ "single_confirmation",+ ),+ status: "accepted",+ resolvedByKind: runtimeValue<EventDimensionsMap["interaction.resolved"]["resolved_by_kind"]>("operator"),+ resolutionReason: "accepted",+ createdByKind: "agent",+ creatorAgentRole: runtimeValue<EventDimensionsMap["interaction.resolved"]["creator_agent_role"]>("coder"),+ continuationPolicy: runtimeValue<EventDimensionsMap["interaction.resolved"]["continuation_policy"]>(+ "wake_everyone",+ ),+ targetType: "issue_document",+ optionCount: 2,+ selectedOptionCount: 1,+ });++ expect(client.track).toHaveBeenCalledWith("interaction.resolved", {+ interaction_kind: "single_confirmation",+ status: "accepted",+ resolved_by_kind: "operator",+ resolution_reason: "accepted",+ created_by_kind: "agent",+ creator_agent_role: "coder",+ continuation_policy: "wake_everyone",+ target_type: "issue_document",+ option_count: 2,+ selected_option_count: 1,+ });+ });});diff --git a/server/src/services/plugin-host-services.ts b/server/src/services/plugin-host-services.tsindex 4309e1e3c0..5284af6ee6 100644--- a/server/src/services/plugin-host-services.ts+++ b/server/src/services/plugin-host-services.ts@@ -1294,7 +1294,7 @@ export function buildHostServices(}const telemetryClient = getTelemetryClient();if (!telemetryClient) return;- telemetryClient.track(`plugin.${pluginKey}.${eventName}`, params.dimensions);+ telemetryClient.trackDynamic(`plugin.${pluginKey}.${eventName}`, params.dimensions);},},