@volcengine/tls-observer-claude-code 0.0.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "tls-observer-claude-code",
+  "description": "Export Claude Code prompts, assistant responses, tool calls, and token usage to Volcengine TLS as OTLP traces.",
+  "version": "0.0.1",
+  "author": {
+    "name": "Volcengine"
+  },
+  "homepage": "https://code.byted.org",
+  "hooks": "./hooks/hooks.json",
+  "defaultEnabled": true
+}

package/LICENCE

@@ -0,0 +1,13 @@
+# Copyright 2023 Beijing Volcano Engine Technology Ltd. 
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

package/README.md

@@ -0,0 +1,91 @@
+# TLS Observer for Claude Code
+
+将 Claude Code 的 prompt、assistant response、tool call、token usage、subagent 和 compact 事件转换为 GenAI Trace，并通过 Volcengine TLS Producer 写入 Trace Topic。
+
+## 安装
+
+推荐使用安装器：
+
+```bash
+npm exec -y \
+  --package=@volcengine/tls-observer-claude-code-install -- \
+  tls-observer-claude-code-install
+```
+
+安装器会：
+
+1. 从 registry 下载插件包。
+2. 安装到 `~/.claude/skills/tls-observer-claude-code`。
+3. 在 `~/.claude/settings.json` 启用 `tls-observer-claude-code@skills-dir`。
+4. 将 TLS 配置写入 `~/.claude/tls-observer-claude-code.env`。
+
+## 采集事件
+
+- `UserPromptSubmit`
+- `PreToolUse`
+- `PostToolUse` / `PostToolUseFailure`
+- `Stop` / `StopFailure`
+- `SubagentStop`
+- `PreCompact` / `PostCompact`
+- `SessionEnd`
+
+`Stop` 和 `SessionEnd` 从 transcript 增量读取当前 turn。工具 hooks 补充工具开始时间、结果和错误状态；Subagent transcript 在主 turn 结束时导出。
+
+## Trace
+
+```text
+agent.turn (server)
+  llm.request (client)
+  tool.call (client)
+```
+
+根 span 包含最终模型、prompt、最终 assistant output 和所有模型调用 token 汇总。工具 span 包含：
+
+- `gen_ai.tool.name`
+- `gen_ai.tool.call.id`
+- `gen_ai.tool.call.arguments`
+- `gen_ai.tool.call.result`
+- `tool.error`
+- `error.message`
+
+所有 span 都包含 `session.id` 和 `tls.app.type=claude-code`。对象和数组类 attribute 会 JSON stringify 后写入。
+
+## 内容采集
+
+插件默认采集完整 prompt、assistant output、tool input/output：
+
+```bash
+CLAUDE_CODE_TLS_CAPTURE_CONTENT=1
+```
+
+设置为 `0` 可关闭正文，只保留结构、模型、token 和工具元数据。
+
+## 本地诊断
+
+默认 data root：
+
+```text
+~/.claude/plugins/data/tls-observer-claude-code
+```
+
+最近一次导出结果：
+
+```bash
+cat ~/.claude/plugins/data/tls-observer-claude-code/logs/send/latest.send-log.json
+```
+
+设置 `CLAUDE_CODE_TLS_DEBUG_ARTIFACTS=1` 后还会生成：
+
+```text
+artifacts/otel-traces/
+artifacts/otlp-payloads/
+artifacts/schema-aligned/
+```
+
+## 开发
+
+```bash
+emo run test --filter @volcengine/tls-observer-claude-code --skip-cache
+```
+
+Rslib 会把 shared OTEL、storage 和 utils 源码内联进 `dist/index.js`。发布包只携带 `dist`、`hooks`、`.claude-plugin` 和 README。

package/dist/config.d.ts

@@ -0,0 +1,25 @@
+export interface Config {
+    enabled: boolean;
+    dataRoot: string;
+    stateFilePath: string;
+    sendLogsDir: string;
+    artifactsDir: string;
+    diagnosticLogMaxBytes: number;
+    captureContent: boolean;
+    debugArtifacts: boolean;
+    serviceName: string;
+    serviceInstanceId: string;
+    tlsEndpoint?: string;
+    otelEndpoint?: string;
+    region?: string;
+    traceTopicId?: string;
+    apiKey?: string;
+    ak?: string;
+    sk?: string;
+    authMode: 'header' | 'resource';
+    exportTimeoutMs: number;
+    exportTimeoutRetries: number;
+}
+export declare function loadEnvFile(filePath?: string): boolean;
+export declare function loadConfig(): Config;
+export declare function localIdentityMetadata(): Record<string, unknown>;

package/dist/exporter.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from './config';
+import { closeTraceLogProducers } from './tls-producer';
+import type { ExportResult, TraceModel, TraceSpan } from './types';
+export declare const SCHEMA_FIELD_ORDER: string[];
+export declare function buildOtlpPayload(trace: TraceModel, config: Config): Record<string, unknown>;
+export declare function exportTraceToTls(trace: TraceModel, config: Config): Promise<ExportResult>;
+export { closeTraceLogProducers };
+export declare function buildSchemaAlignedRecord(trace: TraceModel, span: TraceSpan, observedTimeUnixMs?: number): Record<string, unknown>;
+export declare function buildSchemaAlignedRecords(trace: TraceModel, observedTimeUnixMs?: number): Array<Record<string, unknown>>;
+export declare function exportSummary(trace: TraceModel, result: ExportResult): Record<string, unknown>;

package/dist/hooks/compact.d.ts

@@ -0,0 +1,4 @@
+import type { Config } from '../config';
+import type { PostCompactHookInput, PreCompactHookInput } from '../types';
+export declare function handlePreCompact(input: PreCompactHookInput, config: Config): Promise<void>;
+export declare function handlePostCompact(input: PostCompactHookInput, config: Config): Promise<void>;

package/dist/hooks/dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from '../config';
+import type { HookInput } from '../types';
+export declare function dispatchHook(input: HookInput, config: Config): Promise<void>;

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { dispatchHook } from './dispatch';
+export { handlePostCompact, handlePreCompact } from './compact';
+export { handleSessionEnd, handleStop, handleStopFailure } from './stop';
+export { handleSubagentStop } from './subagent-stop';
+export { handlePostToolUse, handlePreToolUse } from './tool-use';
+export { handleUserPromptSubmit } from './user-prompt-submit';

package/dist/hooks/stop.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from '../config';
+import type { SessionEndHookInput, StopFailureHookInput, StopHookInput } from '../types';
+export declare function handleStop(input: StopHookInput, config: Config): Promise<void>;
+export declare function handleStopFailure(input: StopFailureHookInput, config: Config): Promise<void>;
+export declare function handleSessionEnd(input: SessionEndHookInput, config: Config): Promise<void>;

package/dist/hooks/subagent-stop.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from '../config';
+import type { SubagentStopHookInput } from '../types';
+export declare function handleSubagentStop(input: SubagentStopHookInput, config: Config): Promise<void>;

package/dist/hooks/tool-use.d.ts

@@ -0,0 +1,4 @@
+import type { Config } from '../config';
+import type { PostToolUseHookInput, PreToolUseHookInput } from '../types';
+export declare function handlePreToolUse(input: PreToolUseHookInput, config: Config): Promise<void>;
+export declare function handlePostToolUse(input: PostToolUseHookInput, config: Config): Promise<void>;

package/dist/hooks/trace-flow.d.ts

@@ -0,0 +1,32 @@
+import type { Config } from '../config';
+import type { SessionEndHookInput, SessionState, StopHookInput, TraceModel } from '../types';
+export declare function expandHome(filePath: string | undefined): string | undefined;
+export declare function writeSendLog(config: Config, record: Record<string, unknown>): Promise<void>;
+export declare function exportTraceAndLog(options: {
+    config: Config;
+    trace: TraceModel;
+    hookEventName: string;
+}): Promise<void>;
+export declare function exportTranscriptTurns(options: {
+    input: StopHookInput;
+    config: Config;
+    transcriptPath: string;
+    afterLine: number;
+    afterOffset?: number;
+    session: SessionState;
+    hookEventName: string;
+    source?: string;
+    traceSeedSuffix?: string;
+    extraAttributes?: Record<string, unknown>;
+    turnIndexBase?: number;
+    synthesizeFinalAssistant?: boolean;
+}): Promise<{
+    lastLine: number;
+    lastOffset: number;
+    tracedTurns: number;
+}>;
+export declare function exportPendingSubagents(options: {
+    input: StopHookInput | SessionEndHookInput;
+    config: Config;
+    session: SessionState;
+}): Promise<number>;

package/dist/hooks/user-prompt-submit.d.ts

@@ -0,0 +1,3 @@
+import type { Config } from '../config';
+import type { UserPromptSubmitHookInput } from '../types';
+export declare function handleUserPromptSubmit(input: UserPromptSubmitHookInput, config: Config): Promise<void>;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};