@volcengine/tls-observer-claude-code 0.0.1

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,23 @@
+import type { Config } from './config';
+import type { SessionState, PostCompactHookInput, StopFailureHookInput, StopHookInput, TraceModel, 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;
+    source?: string;
+    traceSeedSuffix?: string;
+    extraAttributes?: Record<string, unknown>;
+}): TraceModel;
+export declare function buildCompactTrace(options: {
+    input: PostCompactHookInput;
+    sessionState: SessionState;
+    config: Config;
+}): TraceModel;
+export declare function buildStopFailureTrace(options: {
+    input: StopFailureHookInput;
+    config: Config;
+}): TraceModel;

package/dist/transcript.d.ts

@@ -0,0 +1,15 @@
+import type { AssistantMessage, ToolResultMessage, TranscriptMessage, Turn, UserMessage } from './types';
+export declare function readTranscript(filePath: string, afterLine?: number, afterOffset?: number): {
+    messages: TranscriptMessage[];
+    lastLine: number;
+    lastOffset: number;
+};
+export declare function getTranscriptEndPosition(filePath: string): {
+    lastLine: number;
+    lastOffset: number;
+};
+export declare function isHumanMessage(msg: TranscriptMessage): msg is UserMessage;
+export declare function isToolResult(msg: TranscriptMessage): msg is ToolResultMessage;
+export declare function isAssistantMessage(msg: TranscriptMessage): msg is AssistantMessage;
+export declare function stripModelDateSuffix(model: string): string;
+export declare function groupIntoTurns(messages: TranscriptMessage[]): Turn[];

package/dist/types.d.ts

@@ -0,0 +1,223 @@
+export interface HookInputBase {
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    permission_mode?: string;
+    hook_event_name?: string;
+    agent_id?: string;
+    agent_type?: string;
+}
+export interface UserPromptSubmitHookInput extends HookInputBase {
+    hook_event_name: 'UserPromptSubmit';
+    prompt?: string;
+}
+export interface PreToolUseHookInput extends HookInputBase {
+    hook_event_name: 'PreToolUse';
+    tool_use_id?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+}
+export interface PostToolUseHookInput extends HookInputBase {
+    hook_event_name: 'PostToolUse' | 'PostToolUseFailure';
+    tool_use_id?: string;
+    tool_name?: string;
+    tool_input?: Record<string, unknown>;
+    tool_response?: unknown;
+}
+export interface StopHookInput extends HookInputBase {
+    hook_event_name: 'Stop';
+    stop_hook_active?: boolean;
+    last_assistant_message?: string;
+}
+export interface StopFailureHookInput extends HookInputBase {
+    hook_event_name: 'StopFailure';
+    error?: string;
+    error_type?: string;
+}
+export interface SubagentStopHookInput extends HookInputBase {
+    hook_event_name: 'SubagentStop';
+    agent_id?: string;
+    agent_type?: string;
+    agent_transcript_path?: string;
+}
+export interface PreCompactHookInput extends HookInputBase {
+    hook_event_name: 'PreCompact';
+    trigger?: 'manual' | 'auto' | string;
+    custom_instructions?: string;
+}
+export interface PostCompactHookInput extends HookInputBase {
+    hook_event_name: 'PostCompact';
+    trigger?: 'manual' | 'auto' | string;
+    compact_summary?: string;
+}
+export interface SessionEndHookInput extends HookInputBase {
+    hook_event_name: 'SessionEnd';
+    reason?: string;
+}
+export type HookInput = UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | StopHookInput | StopFailureHookInput | SubagentStopHookInput | PreCompactHookInput | PostCompactHookInput | SessionEndHookInput | HookInputBase;
+export interface TextBlock {
+    type: 'text';
+    text: string;
+}
+export interface ThinkingBlock {
+    type: 'thinking';
+    thinking: 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: string | Array<{
+        type: string;
+        text?: string;
+    }>;
+    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 UserMessage {
+    type: 'user';
+    message: {
+        role: 'user';
+        content: string | Array<Record<string, unknown>>;
+    };
+    timestamp?: string;
+    promptId?: string;
+}
+export interface ToolResultMessage {
+    type: 'user';
+    message: {
+        role: 'user';
+        content: ToolResultBlock[];
+    };
+    timestamp?: string;
+    promptId?: string;
+    toolUseResult?: {
+        agentId?: string;
+    };
+}
+export interface AssistantMessage {
+    type: 'assistant';
+    message: {
+        id?: string;
+        role: 'assistant';
+        model?: string;
+        content?: ContentBlock[];
+        usage?: Usage;
+        stop_reason?: string | null;
+    };
+    timestamp?: string;
+    promptId?: string;
+}
+export type TranscriptMessage = UserMessage | ToolResultMessage | AssistantMessage;
+export interface ToolCall {
+    tool_use: ToolUseBlock;
+    result?: {
+        content: string;
+        timestamp: string;
+        is_error?: boolean;
+    };
+    agentId?: string;
+}
+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;
+}
+export interface ToolObservation {
+    tool_use_id: string;
+    tool_name?: string;
+    tool_input?: unknown;
+    tool_response?: unknown;
+    start_time_ms?: number;
+    end_time_ms?: number;
+    status?: 'ok' | 'error';
+}
+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>;
+    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' | 'skipped' | 'failed';
+    reason?: string;
+    message?: string;
+    status_code?: number;
+    trace_id?: string;
+    span_count?: number;
+    payload_bytes?: number;
+    endpoint_host?: string;
+    endpoint_path?: string;
+    attempts?: number;
+    duration_ms?: number;
+}

package/hooks/hooks.json

@@ -0,0 +1,121 @@
+{
+  "description": "TLS Observer hooks for Claude Code traces.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 30,
+            "statusMessage": "Recording Claude Code turn"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 30,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 30,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 120,
+            "statusMessage": "Exporting Claude Code trace to TLS"
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 60,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 30,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/index.js\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@volcengine/tls-observer-claude-code",
+  "version": "0.0.1",
+  "description": "Export Claude Code hook telemetry 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",
+  "files": [
+    "dist",
+    "hooks",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "jest --runInBand",
+    "test:coverage": "jest --runInBand --coverage"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude-code",
+    "hooks",
+    "observability",
+    "opentelemetry",
+    "tls"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "@volcengine/openapi": "^1.36.1"
+  },
+  "devDependencies": {
+    "@rslib/core": "^0.21.5",
+    "@swc/core": "1.15.41",
+    "@swc/jest": "0.2.39",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.10.9",
+    "@volcengine/tls-observer-shared": "workspace:*",
+    "jest": "30.4.2",
+    "typescript": "^6.0.3"
+  }
+}