@caplets/core 0.27.0 → 0.28.0

package/dist/telemetry/context.d.ts

@@ -0,0 +1,13 @@
+import type { CapletsConfig } from "../config";
+import { type TelemetryExecutionContext, type TelemetryState, type TelemetryStateOptions, type TelemetrySurface, type TelemetryVisibility } from "./state";
+export type ResolveTelemetryStateOptions = TelemetryStateOptions & {
+    config?: Pick<CapletsConfig, "telemetry"> | undefined;
+    env?: NodeJS.ProcessEnv | undefined;
+    surface: TelemetrySurface;
+    visibility: TelemetryVisibility;
+    debug?: boolean | undefined;
+    allowWithoutNotice?: boolean | undefined;
+    createIdentity?: boolean | undefined;
+};
+export declare function resolveTelemetryState(options: ResolveTelemetryStateOptions): TelemetryState;
+export declare function classifyExecutionContext(env?: NodeJS.ProcessEnv): TelemetryExecutionContext;

package/dist/telemetry/debug.d.ts

@@ -0,0 +1,10 @@
+import type { TelemetryEvent } from "./events";
+export type TelemetryDebugRecord = {
+    state: "debug" | "enabled" | "disabled" | "suppressed";
+    event: TelemetryEvent;
+};
+export declare class TelemetryDebugSink {
+    readonly records: TelemetryDebugRecord[];
+    capture(state: TelemetryDebugRecord["state"], event: TelemetryEvent): void;
+    toJSON(): TelemetryDebugRecord[];
+}

package/dist/telemetry/delivery.d.ts

@@ -0,0 +1 @@
+export { readTelemetryDeliveryHealth, recordTelemetryDrop, type TelemetryDeliveryHealth, } from "./state";

package/dist/telemetry/events.d.ts

@@ -0,0 +1,70 @@
+import type { TelemetryExecutionContext, TelemetrySurface } from "./state";
+export type RuntimeMode = "local" | "remote" | "cloud" | "unknown";
+export type CommandFamily = "init" | "setup" | "add" | "install" | "auth" | "remote" | "doctor" | "serve" | "attach" | "daemon" | "inspect" | "check" | "tools" | "resources" | "prompts" | "complete" | "code_mode" | "native" | "telemetry" | "unknown";
+export type Outcome = "success" | "failure" | "cancelled" | "timeout" | "suppressed";
+export type DurationBucket = "lt_100ms" | "lt_1s" | "lt_5s" | "lt_30s" | "gte_30s";
+export type TimeoutBucket = "none" | "lt_1s" | "lt_10s" | "lt_60s" | "gte_60s";
+export type DiagnosticCategory = "config" | "auth" | "network" | "runtime" | "validation" | "code_mode" | "provider" | "unknown";
+export type TelemetryProductEventName = "caplets_cli_command" | "caplets_tool_activation" | "caplets_code_mode_outcome";
+export type TelemetryReliabilityEventName = "caplets_reliability_error";
+export type TelemetryPropertyValue = string | number | boolean;
+export type TelemetryProperties = Partial<{
+    package: string;
+    version: string;
+    surface: TelemetrySurface;
+    runtime_mode: RuntimeMode;
+    execution_context: TelemetryExecutionContext;
+    command_family: CommandFamily;
+    operation_family: CommandFamily;
+    outcome: Outcome;
+    duration_bucket: DurationBucket;
+    timeout_bucket: TimeoutBucket;
+    integration: "opencode" | "pi" | "native" | "unknown";
+    exposure_mode: "direct" | "progressive" | "code_mode" | "mixed" | "unknown";
+    backend_mcp_count: number;
+    backend_openapi_count: number;
+    backend_google_discovery_count: number;
+    backend_graphql_count: number;
+    backend_http_count: number;
+    backend_cli_count: number;
+    backend_caplets_count: number;
+    direct_count: number;
+    progressive_count: number;
+    code_mode_count: number;
+    session_category: "created" | "reused" | "none" | "unknown";
+    any_caplet_invoked: boolean;
+    provider: "posthog" | "sentry";
+    reason: string;
+    count_bucket: string;
+    error_code: string;
+    diagnostic_category: DiagnosticCategory;
+    os_family: NodeJS.Platform | "unknown";
+    arch: NodeJS.Architecture | "unknown";
+    node_major: number;
+}>;
+export type ProductTelemetryEvent = {
+    provider: "posthog";
+    name: TelemetryProductEventName;
+    distinctId: string;
+    properties: TelemetryProperties & {
+        $process_person_profile: false;
+    };
+};
+export type ReliabilityTelemetryEvent = {
+    provider: "sentry";
+    name: TelemetryReliabilityEventName;
+    tags: Record<string, string>;
+    fingerprint: string[];
+};
+export type TelemetryEvent = ProductTelemetryEvent | ReliabilityTelemetryEvent;
+export declare function buildProductTelemetryEvent(input: {
+    name: TelemetryProductEventName;
+    distinctId: string;
+    properties: TelemetryProperties;
+}): ProductTelemetryEvent;
+export declare function buildReliabilityTelemetryEvent(input: {
+    name: TelemetryReliabilityEventName;
+    properties: TelemetryProperties;
+}): ReliabilityTelemetryEvent;
+export declare function durationBucket(ms: number): DurationBucket;
+export declare function timeoutBucket(ms: number | undefined): TimeoutBucket;

package/dist/telemetry/identity.d.ts

@@ -0,0 +1 @@
+export { deleteTelemetryIdentity, readTelemetryIdentity, rotateTelemetryIdentity, type TelemetryIdentity, } from "./state";

package/dist/telemetry/index.d.ts

@@ -0,0 +1,8 @@
+export { classifyExecutionContext, resolveTelemetryState, type ResolveTelemetryStateOptions, } from "./context";
+export { deleteTelemetryIdentity, readTelemetryDeliveryHealth, readTelemetryIdentity, readTelemetryNotice, recordTelemetryDrop, recordTelemetryNoticeShown, rotateTelemetryIdentity, telemetryDeliveryHealthPath, telemetryIdentityPath, telemetryNoticePath, telemetryStateDir, type TelemetryDeliveryHealth, type TelemetryExecutionContext, type TelemetryIdentity, type TelemetryNoticeState, type TelemetryState, type TelemetryStateDecider, type TelemetryStateOptions, type TelemetryStateStatus, type TelemetrySurface, type TelemetryVisibility, } from "./state";
+export { maybePrintTelemetryNotice, TELEMETRY_NOTICE } from "./notice";
+export { buildProductTelemetryEvent, buildReliabilityTelemetryEvent, durationBucket, timeoutBucket, type CommandFamily, type DiagnosticCategory, type RuntimeMode, type ProductTelemetryEvent, type ReliabilityTelemetryEvent, type TelemetryEvent, type TelemetryProductEventName, type TelemetryProperties, type TelemetryReliabilityEventName, } from "./events";
+export { assertTelemetrySafeProperties, stripSentryEvent } from "./privacy";
+export { TelemetryDebugSink, type TelemetryDebugRecord } from "./debug";
+export { createTelemetryDispatcher, type TelemetryDispatcher, type TelemetryDispatcherOptions, type TelemetryProviderFactories, } from "./providers";
+export { backendFamilyCounts, captureRuntimeReliabilityEvent, captureRuntimeTelemetryEvent, codeModeTelemetryProperties, createRuntimeTelemetryContext, exposureModeCounts, operationFamilyFromOperation, outcomeFromResult, runtimeFailureTelemetryProperties, toolActivationProperties, type RuntimeTelemetryContext, type RuntimeTelemetryOptions, } from "./runtime";

package/dist/telemetry/intake.generated.d.ts

@@ -0,0 +1,2 @@
+export declare const BUNDLED_POSTHOG_TOKEN: string | undefined;
+export declare const BUNDLED_SENTRY_DSN: string | undefined;

package/dist/telemetry/notice.d.ts

@@ -0,0 +1,8 @@
+import { type TelemetrySurface, type TelemetryStateOptions } from "./state";
+export declare const TELEMETRY_NOTICE = "Caplets collects anonymous telemetry for product usage and reliability. Disable it with CAPLETS_DISABLE_TELEMETRY=1 or `caplets telemetry disable`.\n";
+export type TelemetryNoticeOptions = TelemetryStateOptions & {
+    surface: TelemetrySurface;
+    stderrIsTTY?: boolean | undefined;
+    writeErr: (text: string) => void;
+};
+export declare function maybePrintTelemetryNotice(options: TelemetryNoticeOptions): boolean;

package/dist/telemetry/privacy.d.ts

@@ -0,0 +1,3 @@
+import type { TelemetryProperties } from "./events";
+export declare function assertTelemetrySafeProperties(properties: TelemetryProperties & Record<string, unknown>): void;
+export declare function stripSentryEvent(event: Record<string, unknown>): Record<string, unknown>;

package/dist/telemetry/providers.d.ts

@@ -0,0 +1,21 @@
+import type { NodeClient } from "@sentry/node";
+import type { PostHog } from "posthog-node";
+import type { TelemetryEvent } from "./events";
+import { type TelemetryState } from "./state";
+export type PostHogClient = Pick<PostHog, "capture" | "shutdown">;
+export type SentryClient = Pick<NodeClient, "captureEvent" | "flush">;
+export type TelemetryProviderFactories = {
+    createPostHog?: ((token: string) => Promise<PostHogClient> | PostHogClient) | undefined;
+    createSentry?: ((dsn: string) => Promise<SentryClient> | SentryClient) | undefined;
+};
+export type TelemetryDispatcherOptions = {
+    posthogToken?: string | undefined;
+    sentryDsn?: string | undefined;
+    stateDir?: string | undefined;
+    factories?: TelemetryProviderFactories | undefined;
+};
+export type TelemetryDispatcher = {
+    capture(state: TelemetryState, event: TelemetryEvent): Promise<void>;
+    shutdown(): Promise<void>;
+};
+export declare function createTelemetryDispatcher(options?: TelemetryDispatcherOptions): TelemetryDispatcher;

package/dist/telemetry/runtime.d.ts

@@ -0,0 +1,40 @@
+import type { CapletConfig, CapletsConfig } from "../config";
+import { type CommandFamily, type Outcome, type RuntimeMode, type TelemetryProductEventName, type TelemetryProperties } from "./events";
+import { TelemetryDebugSink } from "./debug";
+import { type TelemetryDispatcher } from "./providers";
+import { type TelemetrySurface, type TelemetryVisibility } from "./state";
+export type RuntimeTelemetryOptions = {
+    config: CapletsConfig;
+    env?: NodeJS.ProcessEnv | undefined;
+    stateDir?: string | undefined;
+    surface: TelemetrySurface;
+    visibility: TelemetryVisibility;
+    runtimeMode?: RuntimeMode | undefined;
+    integration?: "opencode" | "pi" | "native" | "unknown" | undefined;
+    debugSink?: TelemetryDebugSink | undefined;
+    dispatcher?: TelemetryDispatcher | undefined;
+};
+export type RuntimeTelemetryContext = RuntimeTelemetryOptions & {
+    dispatcher: TelemetryDispatcher;
+};
+export declare function createRuntimeTelemetryContext(options: RuntimeTelemetryOptions): RuntimeTelemetryContext;
+export declare function captureRuntimeTelemetryEvent(context: RuntimeTelemetryContext, name: TelemetryProductEventName, properties: TelemetryProperties): Promise<void>;
+export declare function captureRuntimeReliabilityEvent(context: RuntimeTelemetryContext, properties: TelemetryProperties): Promise<void>;
+export declare function backendFamilyCounts(config: CapletsConfig): TelemetryProperties;
+export declare function exposureModeCounts(config: CapletsConfig): TelemetryProperties;
+export declare function operationFamilyFromOperation(operation: unknown): CommandFamily;
+export declare function outcomeFromResult(result: unknown): Outcome;
+export declare function codeModeTelemetryProperties(envelope: unknown, durationMs: number, timeoutMs: number | undefined): TelemetryProperties;
+export declare function toolActivationProperties(input: {
+    config: CapletsConfig;
+    caplet: CapletConfig | undefined;
+    operation: unknown;
+    exposureMode: "direct" | "progressive" | "code_mode" | "mixed" | "unknown";
+    result: unknown;
+    durationMs: number;
+}): TelemetryProperties;
+export declare function runtimeFailureTelemetryProperties(input: {
+    operation: unknown;
+    exposureMode: "direct" | "progressive" | "code_mode" | "mixed" | "unknown";
+    result: unknown;
+}): TelemetryProperties;

package/dist/telemetry/state.d.ts

@@ -0,0 +1,53 @@
+export type TelemetrySurface = "cli" | "serve" | "attach" | "daemon" | "native" | "code_mode";
+export type TelemetryVisibility = "visible" | "hidden" | "unknown";
+export type TelemetryExecutionContext = "interactive" | "noninteractive" | "ci";
+export type TelemetryStateStatus = "enabled" | "disabled" | "suppressed" | "debug";
+export type TelemetryStateDecider = "debug" | "env" | "config" | "test" | "notice" | "default";
+export type TelemetryIdentity = {
+    kind: "stable";
+    id: string;
+} | {
+    kind: "ephemeral";
+    id: string;
+    reason: "state-unavailable";
+};
+export type TelemetryNoticeState = {
+    shown: false;
+} | {
+    shown: true;
+    shownAt: string;
+    surface: TelemetrySurface;
+};
+export type TelemetryDeliveryHealth = Record<string, Record<string, number>>;
+export type TelemetryState = {
+    status: TelemetryStateStatus;
+    decider: TelemetryStateDecider;
+    surface: TelemetrySurface;
+    visibility: TelemetryVisibility;
+    executionContext: TelemetryExecutionContext;
+    notice: TelemetryNoticeState;
+    stateDir?: string | undefined;
+    identity?: TelemetryIdentity | undefined;
+};
+export type TelemetryStateOptions = {
+    stateDir?: string | undefined;
+};
+export declare function telemetryStateDir(options?: TelemetryStateOptions): string;
+export declare function telemetryIdentityPath(options?: TelemetryStateOptions): string;
+export declare function telemetryNoticePath(options?: TelemetryStateOptions): string;
+export declare function telemetryDeliveryHealthPath(options?: TelemetryStateOptions): string;
+export declare function readTelemetryIdentity(options?: TelemetryStateOptions & {
+    create?: boolean | undefined;
+}): TelemetryIdentity;
+export declare function rotateTelemetryIdentity(options?: TelemetryStateOptions): TelemetryIdentity;
+export declare function deleteTelemetryIdentity(options?: TelemetryStateOptions): void;
+export declare function readTelemetryNotice(options?: TelemetryStateOptions): TelemetryNoticeState;
+export declare function recordTelemetryNoticeShown(options: TelemetryStateOptions & {
+    surface: TelemetrySurface;
+}): TelemetryNoticeState;
+export declare function readTelemetryDeliveryHealth(options?: TelemetryStateOptions): TelemetryDeliveryHealth;
+export declare function recordTelemetryDrop(options: TelemetryStateOptions & {
+    provider: string;
+    reason: string;
+}): void;
+export declare function writePrivateJson(path: string, value: unknown): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caplets/core",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Core runtime library for Caplets Code Mode and progressive disclosure gateways.",
   "keywords": [
     "caplets",
@@ -90,6 +90,7 @@
     "@hono/mcp": "^0.3.0",
     "@hono/node-server": "^2.0.4",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@sentry/node": "^10.60.0",
     "@ungap/structured-clone": "^1.3.1",
     "ajv": "^8.20.0",
     "commander": "^15.0.0",
@@ -97,6 +98,7 @@
     "graphql": "^16.14.2",
     "headers-polyfill": "^5.0.1",
     "hono": "^4.12.25",
+    "posthog-node": "^4.18.0",
     "quickjs-emscripten": "^0.32.0",
     "typescript": "^6.0.3",
     "vfile": "^6.0.3",