export interface PaperclipAgentCreatedDimensions { /** Per-installation salted hash; never the raw database agent ID. */ agent_id: string; agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other"); } export interface PaperclipAgentFirstHeartbeatDimensions { /** Per-installation salted hash; never the raw database agent ID. */ 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" | "kimi_local" | "other"); /** Per-installation salted hash; never the raw database agent ID. */ agent_id: string; agent_role: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other"); model?: string; task_id?: string; } export interface PaperclipAgentTaskRunDimensions { 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" | "kimi_local" | "other"); /** Per-installation salted hash; never the raw database agent ID. */ agent_id: string; agent_role?: ("ceo" | "cto" | "cmo" | "cfo" | "security" | "engineer" | "designer" | "pm" | "qa" | "devops" | "researcher" | "general" | "other"); model?: string; state: ("succeeded" | "interrupted" | "failed" | "cancelled" | "timed_out"); duration_seconds?: number; input_tokens?: number; output_tokens?: number; cached_tokens?: number; task_id?: string; } export interface PaperclipCompanyImportedDimensions { source_type: ("local_path" | "github" | "url" | "catalog" | "skills_sh" | "unknown"); /** Hash private or unverified sources; raw refs are reserved for verified public catalog entries. Never include URL userinfo. */ 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" | "kimi_local" | "other"); } export interface PaperclipInstallStartedDimensions { } export interface PaperclipInteractionCreatedDimensions { interaction_kind: ("suggest_tasks" | "ask_user_questions" | "request_confirmation" | "request_checkbox_confirmation" | "request_item_verdicts" | "other"); used_deprecated_resolver_policy_alias: boolean; } /** Emit only after the complete resolution transaction commits, including response provenance. */ export interface PaperclipInteractionResolvedDimensions { interaction_kind: ("suggest_tasks" | "ask_user_questions" | "request_confirmation" | "request_checkbox_confirmation" | "request_item_verdicts" | "other"); status: ("accepted" | "rejected" | "answered" | "cancelled" | "expired" | "failed" | "other"); resolution_reason?: ("accepted" | "rejected" | "stale_target" | "superseded_by_comment" | "superseded_by_newer_request" | "expired" | "cancelled" | "skipped" | "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; legacy_inherited_restriction: boolean; } 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 { /** skill_ref may identify a known public catalog source only. Omit it for * GitHub-synced sources, which may be private; never emit repository paths or names. */ source_type: ("local_path" | "github" | "url" | "catalog" | "skills_sh" | "unknown"); skill_ref?: string; } export type PaperclipEventName = "agent.created" | "agent.first_heartbeat" | "agent.task_completed" | "agent.task_run" | "company.imported" | "error.handler_crash" | "goal.created" | "install.completed" | "install.started" | "interaction.created" | "interaction.resolved" | "project.created" | "routine.created" | "routine.run" | "skill.imported"; export interface EventDimensionsMap { "agent.created": PaperclipAgentCreatedDimensions; "agent.first_heartbeat": PaperclipAgentFirstHeartbeatDimensions; "agent.task_completed": PaperclipAgentTaskCompletedDimensions; "agent.task_run": PaperclipAgentTaskRunDimensions; "company.imported": PaperclipCompanyImportedDimensions; "error.handler_crash": PaperclipErrorHandlerCrashDimensions; "goal.created": PaperclipGoalCreatedDimensions; "install.completed": PaperclipInstallCompletedDimensions; "install.started": PaperclipInstallStartedDimensions; "interaction.created": PaperclipInteractionCreatedDimensions; "interaction.resolved": PaperclipInteractionResolvedDimensions; "project.created": PaperclipProjectCreatedDimensions; "routine.created": PaperclipRoutineCreatedDimensions; "routine.run": PaperclipRoutineRunDimensions; "skill.imported": PaperclipSkillImportedDimensions; } export declare const PAPERCLIP_EVENTS: { readonly "agent.created": "agent.created"; readonly "agent.first_heartbeat": "agent.first_heartbeat"; readonly "agent.task_completed": "agent.task_completed"; readonly "agent.task_run": "agent.task_run"; readonly "company.imported": "company.imported"; readonly "error.handler_crash": "error.handler_crash"; readonly "goal.created": "goal.created"; readonly "install.completed": "install.completed"; readonly "install.started": "install.started"; readonly "interaction.created": "interaction.created"; readonly "interaction.resolved": "interaction.resolved"; readonly "project.created": "project.created"; readonly "routine.created": "routine.created"; readonly "routine.run": "routine.run"; readonly "skill.imported": "skill.imported"; }; export declare const PAPERCLIP_ENUM_DESCRIPTIONS: { readonly "agent.created": { readonly agent_role: { readonly ceo: "Agent configured for company leadership and board coordination work."; readonly cto: "Agent configured for technical leadership, architecture, and engineering coordination."; readonly cmo: "Agent configured for marketing leadership work."; readonly cfo: "Agent configured for finance leadership work."; readonly security: "Agent configured for security review, risk, or policy work."; readonly engineer: "Agent configured for general software engineering work."; readonly designer: "Agent configured for product, visual, or experience design work."; readonly pm: "Agent configured for product management or planning work."; readonly qa: "Agent configured for quality assurance, testing, or validation work."; readonly devops: "Agent configured for infrastructure, deployment, or operations work."; readonly researcher: "Agent configured for research and information-gathering work."; readonly general: "Agent configured as a general-purpose worker without a more specific role."; readonly other: "Fallback when the agent role is unknown or not represented by the tracked enum."; }; }; readonly "agent.first_heartbeat": { readonly agent_role: { readonly ceo: "Agent configured for company leadership and board coordination work."; readonly cto: "Agent configured for technical leadership, architecture, and engineering coordination."; readonly cmo: "Agent configured for marketing leadership work."; readonly cfo: "Agent configured for finance leadership work."; readonly security: "Agent configured for security review, risk, or policy work."; readonly engineer: "Agent configured for general software engineering work."; readonly designer: "Agent configured for product, visual, or experience design work."; readonly pm: "Agent configured for product management or planning work."; readonly qa: "Agent configured for quality assurance, testing, or validation work."; readonly devops: "Agent configured for infrastructure, deployment, or operations work."; readonly researcher: "Agent configured for research and information-gathering work."; readonly general: "Agent configured as a general-purpose worker without a more specific role."; readonly other: "Fallback when the agent role is unknown or not represented by the tracked enum."; }; }; readonly "agent.task_completed": { readonly adapter_type: { readonly process: "Agent runtime uses a local process adapter."; readonly http: "Agent runtime uses a generic HTTP adapter."; readonly acpx_local: "Agent runtime uses the local ACPX adapter."; readonly claude_local: "Agent runtime uses the local Claude adapter."; readonly codex_local: "Agent runtime uses the local Codex adapter."; readonly cursor_cloud: "Agent runtime uses the Cursor cloud adapter."; readonly gemini_local: "Agent runtime uses the local Gemini adapter."; readonly hermes_gateway: "Agent runtime uses the Hermes gateway adapter."; readonly hermes_local: "Agent runtime uses the local Hermes adapter."; readonly opencode_local: "Agent runtime uses the local OpenCode adapter."; readonly pi_local: "Agent runtime uses the local Pi adapter."; readonly cursor: "Agent runtime uses the Cursor adapter."; readonly openclaw_gateway: "Agent runtime uses the OpenClaw gateway adapter."; readonly grok_local: "Agent runtime uses the local Grok adapter."; readonly kimi_local: "Agent runtime uses the local Kimi adapter."; readonly other: "Fallback when the adapter type is unknown or not represented by the tracked enum."; }; readonly agent_role: { readonly ceo: "Agent configured for company leadership and board coordination work."; readonly cto: "Agent configured for technical leadership, architecture, and engineering coordination."; readonly cmo: "Agent configured for marketing leadership work."; readonly cfo: "Agent configured for finance leadership work."; readonly security: "Agent configured for security review, risk, or policy work."; readonly engineer: "Agent configured for general software engineering work."; readonly designer: "Agent configured for product, visual, or experience design work."; readonly pm: "Agent configured for product management or planning work."; readonly qa: "Agent configured for quality assurance, testing, or validation work."; readonly devops: "Agent configured for infrastructure, deployment, or operations work."; readonly researcher: "Agent configured for research and information-gathering work."; readonly general: "Agent configured as a general-purpose worker without a more specific role."; readonly other: "Fallback when the agent role is unknown or not represented by the tracked enum."; }; }; readonly "agent.task_run": { readonly adapter_type: { readonly process: "Agent runtime uses a local process adapter."; readonly http: "Agent runtime uses a generic HTTP adapter."; readonly acpx_local: "Agent runtime uses the local ACPX adapter."; readonly claude_local: "Agent runtime uses the local Claude adapter."; readonly codex_local: "Agent runtime uses the local Codex adapter."; readonly cursor_cloud: "Agent runtime uses the Cursor cloud adapter."; readonly gemini_local: "Agent runtime uses the local Gemini adapter."; readonly hermes_gateway: "Agent runtime uses the Hermes gateway adapter."; readonly hermes_local: "Agent runtime uses the local Hermes adapter."; readonly opencode_local: "Agent runtime uses the local OpenCode adapter."; readonly pi_local: "Agent runtime uses the local Pi adapter."; readonly cursor: "Agent runtime uses the Cursor adapter."; readonly openclaw_gateway: "Agent runtime uses the OpenClaw gateway adapter."; readonly grok_local: "Agent runtime uses the local Grok adapter."; readonly kimi_local: "Agent runtime uses the local Kimi adapter."; readonly other: "Fallback when the adapter type is unknown or not represented by the tracked enum."; }; readonly agent_role: { readonly ceo: "Agent configured for company leadership and board coordination work."; readonly cto: "Agent configured for technical leadership, architecture, and engineering coordination."; readonly cmo: "Agent configured for marketing leadership work."; readonly cfo: "Agent configured for finance leadership work."; readonly security: "Agent configured for security review, risk, or policy work."; readonly engineer: "Agent configured for general software engineering work."; readonly designer: "Agent configured for product, visual, or experience design work."; readonly pm: "Agent configured for product management or planning work."; readonly qa: "Agent configured for quality assurance, testing, or validation work."; readonly devops: "Agent configured for infrastructure, deployment, or operations work."; readonly researcher: "Agent configured for research and information-gathering work."; readonly general: "Agent configured as a general-purpose worker without a more specific role."; readonly other: "Fallback when the agent role is unknown or not represented by the tracked enum."; }; readonly state: { readonly succeeded: "The agent run finished its task and reached a successful terminal state."; readonly interrupted: "A user or the board interrupted the agent run before it finished."; readonly failed: "The agent run reached a terminal state because of an unrecoverable error."; readonly cancelled: "The agent run was cancelled before it reached a successful terminal state."; readonly timed_out: "The agent run reached its time limit before it finished."; }; }; readonly "company.imported": { readonly source_type: { readonly local_path: "Import source came from a filesystem path on the operator's machine."; readonly github: "Import source came from a GitHub repository or GitHub-backed reference."; readonly url: "Import source came from a direct URL."; readonly catalog: "Import source came from a Paperclip catalog entry."; readonly skills_sh: "Import source came from a Skills.sh-compatible source."; readonly unknown: "Source type could not be classified."; }; }; readonly "goal.created": { readonly goal_level: { readonly company: "Goal applies at company scope."; readonly team: "Goal applies at team or group scope."; readonly agent: "Goal applies to a specific agent."; readonly task: "Goal applies to task-level work."; readonly other: "Fallback when the goal level is unknown or not represented by the tracked enum."; }; }; readonly "install.completed": { readonly adapter_type: { readonly process: "Agent runtime uses a local process adapter."; readonly http: "Agent runtime uses a generic HTTP adapter."; readonly acpx_local: "Agent runtime uses the local ACPX adapter."; readonly claude_local: "Agent runtime uses the local Claude adapter."; readonly codex_local: "Agent runtime uses the local Codex adapter."; readonly cursor_cloud: "Agent runtime uses the Cursor cloud adapter."; readonly gemini_local: "Agent runtime uses the local Gemini adapter."; readonly hermes_gateway: "Agent runtime uses the Hermes gateway adapter."; readonly hermes_local: "Agent runtime uses the local Hermes adapter."; readonly opencode_local: "Agent runtime uses the local OpenCode adapter."; readonly pi_local: "Agent runtime uses the local Pi adapter."; readonly cursor: "Agent runtime uses the Cursor adapter."; readonly openclaw_gateway: "Agent runtime uses the OpenClaw gateway adapter."; readonly grok_local: "Agent runtime uses the local Grok adapter."; readonly kimi_local: "Agent runtime uses the local Kimi adapter."; readonly other: "Fallback when the adapter type is unknown or not represented by the tracked enum."; }; }; readonly "interaction.created": { readonly interaction_kind: { readonly suggest_tasks: "Board-facing interaction that proposes concrete subtasks for acceptance."; readonly ask_user_questions: "Board-facing interaction that asks structured questions and stores answers."; readonly request_confirmation: "Board-facing interaction that asks for a single accept or reject decision."; readonly request_checkbox_confirmation: "Board-facing interaction that asks the board to select options and confirm."; readonly request_item_verdicts: "Board-facing interaction that collects a verdict for each known item."; readonly other: "Fallback when the interaction kind is unknown or not represented by the tracked enum."; }; }; readonly "interaction.resolved": { readonly interaction_kind: { readonly suggest_tasks: "Board-facing interaction that proposes concrete subtasks for acceptance."; readonly ask_user_questions: "Board-facing interaction that asks structured questions and stores answers."; readonly request_confirmation: "Board-facing interaction that asks for a single accept or reject decision."; readonly request_checkbox_confirmation: "Board-facing interaction that asks the board to select options and confirm."; readonly request_item_verdicts: "Board-facing interaction that collects a verdict for each known item."; readonly other: "Fallback when the interaction kind is unknown or not represented by the tracked enum."; }; readonly status: { readonly accepted: "Interaction was accepted."; readonly rejected: "Interaction was rejected."; readonly answered: "Ask-user-questions interaction was answered."; readonly cancelled: "Interaction was cancelled before acceptance or answer."; readonly expired: "Interaction expired because the bound target became stale or was superseded."; readonly failed: "Interaction resolution attempted but failed."; readonly other: "Fallback when the terminal status is unknown or not represented by the tracked enum."; }; readonly resolution_reason: { readonly accepted: "Stored result outcome says the interaction was accepted."; readonly rejected: "Stored result outcome says the interaction was rejected."; readonly stale_target: "Bound target, such as an issue document revision, was no longer current."; readonly superseded_by_comment: "A later user or board comment superseded the pending confirmation."; readonly superseded_by_newer_request: "A newer confirmation from the same agent superseded the pending confirmation."; readonly expired: "Interaction expired for a generic expiration reason."; readonly cancelled: "Interaction was explicitly cancelled."; readonly skipped: "The board skipped the interaction and returned to ordinary task input."; readonly other: "Fallback when the resolution reason is unknown or not represented by the tracked enum."; }; readonly resolved_by_kind: { readonly user: "A board or human user resolved the interaction."; readonly agent: "An agent resolved the interaction."; readonly system: "Paperclip resolved the interaction automatically."; readonly other: "Fallback when the resolver kind is unknown or not represented by the tracked enum."; }; readonly created_by_kind: { readonly agent: "Interaction was created by an agent."; readonly user: "Interaction was created by a board or human user."; readonly other: "Fallback when the creator kind is unknown or not represented by the tracked enum."; }; readonly creator_agent_role: { readonly ceo: "Agent configured for company leadership and board coordination work."; readonly cto: "Agent configured for technical leadership, architecture, and engineering coordination."; readonly cmo: "Agent configured for marketing leadership work."; readonly cfo: "Agent configured for finance leadership work."; readonly security: "Agent configured for security review, risk, or policy work."; readonly engineer: "Agent configured for general software engineering work."; readonly designer: "Agent configured for product, visual, or experience design work."; readonly pm: "Agent configured for product management or planning work."; readonly qa: "Agent configured for quality assurance, testing, or validation work."; readonly devops: "Agent configured for infrastructure, deployment, or operations work."; readonly researcher: "Agent configured for research and information-gathering work."; readonly general: "Agent configured as a general-purpose worker without a more specific role."; readonly other: "Fallback when the agent role is unknown or not represented by the tracked enum."; }; readonly continuation_policy: { readonly none: "Resolving the interaction does not automatically wake the issue assignee."; readonly wake_assignee: "Resolving the interaction wakes or returns the issue to the assignee."; readonly wake_assignee_on_accept: "Accepting the interaction wakes or returns the issue to the assignee."; readonly other: "Fallback when the continuation policy is unknown or not represented by the tracked enum."; }; readonly target_type: { readonly issue_document: "Interaction is bound to a specific issue document revision."; readonly custom: "Interaction is bound to a custom target."; readonly none: "Interaction has no bound target."; readonly other: "Fallback when the target type is unknown or not represented by the tracked enum."; }; }; readonly "routine.run": { readonly source: { readonly schedule: "Routine was triggered by a scheduled trigger."; readonly manual: "Routine was triggered manually by a user or agent action."; readonly api: "Routine was triggered through an API request."; readonly webhook: "Routine was triggered by a webhook."; readonly other: "Fallback when the source is unknown or not represented by the tracked enum."; }; readonly status: { readonly received: "Routine run was accepted for processing."; readonly coalesced: "A live execution already existed and the run was coalesced into it."; readonly skipped: "A live execution already existed and concurrency policy skipped the run."; readonly issue_created: "Routine dispatch created a new issue and queued the agent wakeup."; readonly completed: "Routine run completed without needing a new issue."; readonly failed: "Routine dispatch failed and the run was finalized as failed."; readonly other: "Fallback when the status is unknown or not represented by the tracked enum."; }; }; readonly "skill.imported": { readonly source_type: { readonly local_path: "Import source came from a filesystem path on the operator's machine."; readonly github: "Import source came from a GitHub repository or GitHub-backed reference."; readonly url: "Import source came from a direct URL."; readonly catalog: "Import source came from a Paperclip catalog entry."; readonly skills_sh: "Import source came from a Skills.sh-compatible source."; readonly unknown: "Source type could not be classified."; }; }; }; export declare const SCHEMA_VERSION: "1"; export interface PaperclipTelemetryEvent { name: K; occurredAt: string; dimensions: EventDimensionsMap[K]; } export type AnyPaperclipTelemetryEvent = { [K in PaperclipEventName]: PaperclipTelemetryEvent; }[PaperclipEventName]; export interface PaperclipTelemetryBatch { app: "paperclip"; schemaVersion: typeof SCHEMA_VERSION; installId: string; /** * Optional client application build version. Paperclip clients report PEP 440 * local versions such as +.git.; * nearest tags are usually CalVer, but legacy SemVer tags such as 0.3.1 can * appear. Ingest documents this shape but does not strictly enforce PEP 440. */ version?: string; events: AnyPaperclipTelemetryEvent[]; } export declare function makeEvent(name: K, dimensions: EventDimensionsMap[K], occurredAt: string): PaperclipTelemetryEvent; export declare function makeBatch(installId: string, events: readonly AnyPaperclipTelemetryEvent[], /** * Optional client application build version. Paperclip clients report PEP 440 * local versions such as +.git.; * nearest tags are usually CalVer, but legacy SemVer tags such as 0.3.1 can * appear. Ingest documents this shape but does not strictly enforce PEP 440. */ version?: string): PaperclipTelemetryBatch; //# sourceMappingURL=paperclip-telemetry.d.ts.map