@volcengine/tls-observer-cursor 0.0.4

package/dist/state.d.ts

@@ -0,0 +1,6 @@
+import type { SessionState, ToolObservation, TracingState } from './types';
+export declare function loadState(stateFilePath: string): TracingState;
+export declare function getSessionState(state: TracingState, sessionId: string): SessionState;
+export declare function atomicUpdateState(stateFilePath: string, fn: (state: TracingState) => TracingState): Promise<void>;
+export declare function pruneOldSessions(state: TracingState, now?: number): TracingState;
+export declare function putToolObservation(session: SessionState, observation: ToolObservation): SessionState;

package/dist/stdin.d.ts

@@ -0,0 +1 @@
+export declare function readStdinJson<T>(): Promise<T>;

package/dist/tls-producer.d.ts

@@ -0,0 +1,12 @@
+export interface TlsProducerConfig {
+    endpoint: string;
+    region: string;
+    traceTopicId: string;
+    apiKey?: string;
+    ak?: string;
+    sk?: string;
+    timeoutMs?: number;
+}
+export declare function normalizeProducerEndpoint(endpoint: string): string;
+export declare function sendTlsLogRecords(config: TlsProducerConfig, records: Array<Record<string, string>>, fileName: string): Promise<void>;
+export declare function closeTraceLogProducers(): Promise<void>;

package/dist/trace.d.ts

@@ -0,0 +1,42 @@
+import type { Config } from './config';
+import type { CompactHookInput, HookInput, SessionState, StopHookInput, TraceModel, TraceSpan, Turn } from './types';
+export declare function toTraceId(value: string): string;
+export declare function toSpanId(...parts: unknown[]): string;
+export declare function buildTraceFromTurn(options: {
+    input: StopHookInput;
+    turn: Turn;
+    turnIndex: number;
+    sessionState: SessionState;
+    config: Config;
+    turnEndTimeMs?: number;
+    source?: string;
+    traceSeedSuffix?: string;
+    extraAttributes?: Record<string, unknown>;
+}): TraceModel;
+export declare function buildTraceFromHookState(options: {
+    input: StopHookInput;
+    sessionState: SessionState;
+    config: Config;
+    turnIndex: number;
+    stopTimeMs?: number;
+    source?: string;
+    traceSeedSuffix?: string;
+    extraAttributes?: Record<string, unknown>;
+}): TraceModel | undefined;
+export declare function buildEventTrace(options: {
+    input: HookInput;
+    config: Config;
+    eventName: string;
+    spanName?: string;
+    startMs?: number;
+    endMs?: number;
+    attributes?: Record<string, unknown>;
+    inputPayload?: unknown;
+    outputPayload?: unknown;
+    status?: TraceSpan['status'];
+}): TraceModel;
+export declare function buildCompactTrace(options: {
+    input: CompactHookInput;
+    sessionState: SessionState;
+    config: Config;
+}): TraceModel;

package/dist/transcript.d.ts

@@ -0,0 +1,17 @@
+import type { CursorTranscriptEntry, Turn } from './types';
+export declare function readTranscript(filePath: string, afterLine?: number, afterOffset?: number, options?: {
+    lookBehindBytes?: number;
+}): {
+    messages: CursorTranscriptEntry[];
+    lastLine: number;
+    lastOffset: number;
+};
+export declare function getTranscriptEndPosition(filePath: string): {
+    lastLine: number;
+    lastOffset: number;
+};
+export declare function groupIntoTurns(messages: CursorTranscriptEntry[], options?: {
+    fallbackStartMs?: number;
+    fallbackModel?: string;
+}): Turn[];
+export declare function toolObservationMatchKey(toolName?: string, toolInput?: unknown): string | undefined;

package/dist/types.d.ts

@@ -0,0 +1,228 @@
+export interface HookInputBase {
+    hook_event_name?: string;
+    event_name?: string;
+    session_id?: string;
+    conversation_id?: string;
+    generation_id?: string;
+    session_name?: string;
+    transcript_path?: string | null;
+    cwd?: string;
+    cursor_version?: string;
+    version?: string;
+    user_email?: string;
+    workspace_roots?: string[];
+    workspace?: {
+        current_dir?: string;
+        project_dir?: string;
+        added_dirs?: string[];
+    };
+    model?: string | {
+        id?: string;
+        display_name?: string;
+        [key: string]: unknown;
+    };
+    model_id?: string;
+    model_params?: Array<{
+        id?: string;
+        value?: string;
+    }>;
+    [key: string]: unknown;
+}
+export interface UserPromptSubmitHookInput extends HookInputBase {
+    hook_event_name: 'beforeSubmitPrompt' | 'UserPromptSubmit';
+    prompt?: string;
+    user_prompt?: string;
+    query?: string;
+}
+export interface ToolHookInput extends HookInputBase {
+    hook_event_name: 'preToolUse' | 'postToolUse' | 'postToolUseFailure' | 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure';
+    tool_use_id?: string;
+    tool_call_id?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_output?: unknown;
+    error_message?: string;
+    failure_type?: string;
+    duration?: number | string;
+    is_interrupt?: boolean;
+    agent_message?: string;
+    tool_response?: unknown;
+    output?: unknown;
+    result?: unknown;
+    error?: unknown;
+}
+export interface StopHookInput extends HookInputBase {
+    hook_event_name: 'stop' | 'Stop' | 'sessionEnd' | 'SessionEnd';
+    stop_hook_active?: boolean;
+    last_assistant_message?: string;
+    reason?: string;
+}
+export interface SubagentHookInput extends HookInputBase {
+    hook_event_name: 'subagentStart' | 'subagentStop' | 'SubagentStart' | 'SubagentStop';
+    agent_id?: string;
+    agent_type?: string;
+    subagent_id?: string;
+    subagent_type?: string;
+    agent_transcript_path?: string;
+    transcript_path?: string | null;
+}
+export interface CompactHookInput extends HookInputBase {
+    hook_event_name: 'preCompact' | 'PreCompact';
+    trigger?: 'manual' | 'auto' | string;
+    custom_instructions?: string;
+}
+export type HookInput = UserPromptSubmitHookInput | ToolHookInput | StopHookInput | SubagentHookInput | CompactHookInput | HookInputBase;
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export interface ThinkingBlock {
+    type: 'thinking' | 'reasoning';
+    thinking?: string;
+    text?: string;
+}
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id?: string;
+    content?: unknown;
+    is_error?: boolean;
+}
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock;
+export interface Usage {
+    input_tokens?: number;
+    output_tokens?: number;
+    reasoning_output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+}
+export interface CursorTranscriptEntry {
+    role?: 'user' | 'assistant' | string;
+    type?: string;
+    status?: string;
+    timestamp?: string;
+    message?: {
+        id?: string;
+        role?: string;
+        model?: string;
+        content?: unknown;
+        usage?: Usage;
+        stop_reason?: string | null;
+    };
+    promptId?: string;
+    __line?: number;
+    __startOffset?: number;
+    __endOffset?: number;
+}
+export interface ToolCall {
+    tool_use: ToolUseBlock;
+    result?: {
+        content: string;
+        timestamp: string;
+        is_error?: boolean;
+    };
+}
+export interface LlmCall {
+    content: ContentBlock[];
+    model: string;
+    usage: Usage;
+    startTime: string;
+    endTime: string;
+    toolCalls: ToolCall[];
+    stopReason?: string | null;
+    synthetic?: boolean;
+}
+export interface Turn {
+    userContent: string | Array<Record<string, unknown>>;
+    userTimestamp: string;
+    promptId?: string;
+    llmCalls: LlmCall[];
+    isComplete: boolean;
+    startOffset?: number;
+    endOffset?: number;
+}
+export interface ToolObservation {
+    tool_use_id: string;
+    tool_call_id?: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_response?: unknown;
+    error_type?: string;
+    is_interrupt?: boolean;
+    start_time_ms?: number;
+    end_time_ms?: number;
+    status?: 'ok' | 'error';
+    match_key?: string;
+    event_name?: string;
+    sequence?: number;
+}
+export interface PendingSubagentTrace {
+    agent_id?: string;
+    agent_type?: string;
+    agent_transcript_path: string;
+    session_id?: string;
+}
+export interface SessionState {
+    last_line: number;
+    last_offset?: number;
+    turn_count: number;
+    updated: string;
+    current_turn_id?: string;
+    current_turn_start_ms?: number;
+    current_prompt?: string;
+    tool_start_times?: Record<string, number>;
+    tool_observations?: Record<string, ToolObservation>;
+    tool_observation_order?: string[];
+    pending_subagent_traces?: PendingSubagentTrace[];
+    subagent_turn_count?: number;
+    compaction_start_time_ms?: number;
+    compaction_trigger?: string;
+    compaction_custom_instructions?: string;
+}
+export interface TracingState {
+    [sessionId: string]: SessionState;
+}
+export interface TraceSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string | null;
+    name: string;
+    type: 'entry' | 'model' | 'tool' | 'event';
+    span_kind: 'SERVER' | 'CLIENT' | 'INTERNAL';
+    start_time: string;
+    end_time: string;
+    start_time_unix_ms: number;
+    end_time_unix_ms: number;
+    duration_ms: number;
+    attributes: Record<string, unknown>;
+    input?: unknown;
+    output?: unknown;
+    status?: {
+        code?: 'UNSET' | 'OK' | 'ERROR';
+        message?: string;
+    };
+}
+export interface TraceModel {
+    schema_url: string;
+    source: string;
+    trace_id: string;
+    resource: Record<string, unknown>;
+    spans: TraceSpan[];
+}
+export interface ExportResult {
+    status: 'success' | 'failed' | 'skipped';
+    reason?: string;
+    message?: string;
+    trace_id?: string;
+    span_count?: number;
+    payload_bytes?: number;
+    attempts?: number;
+    duration_ms?: number;
+    endpoint_host?: string;
+    endpoint_path?: string;
+}

package/hooks/hooks.json

@@ -0,0 +1,24 @@
+{
+  "version": 1,
+  "description": "TLS Observer hooks for Cursor agent traces.",
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "node \"${CURSOR_TLS_OBSERVER_ROOT}/dist/index.js\"",
+        "timeout": 30
+      }
+    ],
+    "stop": [
+      {
+        "command": "node \"${CURSOR_TLS_OBSERVER_ROOT}/dist/index.js\"",
+        "timeout": 120
+      }
+    ],
+    "sessionEnd": [
+      {
+        "command": "node \"${CURSOR_TLS_OBSERVER_ROOT}/dist/index.js\"",
+        "timeout": 30
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@volcengine/tls-observer-cursor",
+  "version": "0.0.4",
+  "description": "Export Cursor hook telemetry and agent transcripts to Volcengine TLS with OTLP traces.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "cursor",
+    "hooks",
+    "observability",
+    "opentelemetry",
+    "tls"
+  ],
+  "dependencies": {
+    "@volcengine/openapi": "^1.36.1"
+  }
+}