@volcengine/tls-observer-cursor 0.0.4

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,80 @@
+# TLS Observer for Cursor
+
+采集 Cursor 本地 hooks 和 `agent-transcripts/*.jsonl`，转换为 GenAI Trace，并通过 Volcengine TLS Producer 写入 Trace Topic。
+
+## 数据源
+
+- Cursor 原生 hooks：`beforeSubmitPrompt`、`preToolUse`、`postToolUse`、`postToolUseFailure`、`stop`、`sessionEnd`、`subagentStart`、`subagentStop`、`preCompact`。主 `tool.call` 链路只使用 Cursor generic tool hooks。
+- Cursor transcript：`~/.cursor/projects/<workspace>/agent-transcripts/<conversation-id>/<conversation-id>.jsonl`。
+
+## Span
+
+- `agent.turn`：一个用户 turn 的根 span。
+- `llm.request`：从 assistant transcript entry 还原的模型请求。
+- `tool.call`：从 `tool_use` block 与 tool hook observation 还原的工具调用，挂在产出该 `tool_use` 的 `llm.request` 下。
+- `agent.subagent` / `agent.compact`：Cursor subagent 和 compact hook 事件。
+
+所有 span 都包含 `tls.app.type=cursor`。Cursor 专属字段使用 `cursor.*` attribute，例如 `cursor.version`、`cursor.workspace.roots`、`cursor.transcript_path`。
+
+## 本地接入
+
+构建：
+
+```bash
+pnpm --dir packages/cursor build
+```
+
+准备 env：
+
+```bash
+cat > ~/.cursor/tls-observer-cursor.env <<'EOF'
+CURSOR_TLS_ENDPOINT=https://tls-cn-beijing.volces.com
+CURSOR_TLS_REGION=cn-beijing
+CURSOR_TLS_TRACE_TOPIC_ID=<trace-topic-id>
+CURSOR_TLS_API_KEY=<api-key>
+CURSOR_TLS_CAPTURE_CONTENT=1
+EOF
+```
+
+在 Cursor hooks 中引用构建产物。用户级示例：
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "beforeSubmitPrompt": [
+      {
+        "command": "node \"/Users/bytedance/TLSProjects/storage-tls-observer/packages/cursor/dist/index.js\""
+      }
+    ],
+    "stop": [
+      {
+        "command": "node \"/Users/bytedance/TLSProjects/storage-tls-observer/packages/cursor/dist/index.js\"",
+        "timeout": 120
+      }
+    ]
+  }
+}
+```
+
+完整 hook 模板见 `hooks/hooks.json`。
+
+## 配置
+
+| 环境变量 | 说明 |
+| --- | --- |
+| `CURSOR_TLS_EXPORT` | 设为 `0` 可关闭上报 |
+| `CURSOR_TLS_CAPTURE_CONTENT` | 设为 `0` 时不写 prompt/response/tool body |
+| `CURSOR_TLS_DEBUG_ARTIFACTS` | 设为 `1` 输出本地 trace/OTLP 调试文件 |
+| `CURSOR_TLS_DATA_ROOT` | 默认 `~/.cursor/plugins/data/tls-observer-cursor` |
+| `CURSOR_TLS_ENDPOINT` / `CURSOR_TLS_OTEL_ENDPOINT` | TLS endpoint |
+| `CURSOR_TLS_REGION` | TLS region |
+| `CURSOR_TLS_TRACE_TOPIC_ID` | Trace Topic ID |
+| `CURSOR_TLS_API_KEY` | TLS API key |
+| `CURSOR_TLS_AK` / `CURSOR_TLS_SK` | AK/SK 鉴权 |
+
+最近一次发送结果：
+
+```bash
+cat ~/.cursor/plugins/data/tls-observer-cursor/logs/send/latest.send-log.json
+```

package/dist/config.d.ts

@@ -0,0 +1,26 @@
+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;
+    transcriptLookbehindBytes: 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,3 @@
+import type { Config } from '../config';
+import type { CompactHookInput } from '../types';
+export declare function handlePreCompact(input: CompactHookInput, 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 { handlePreCompact } from './compact';
+export { handleSessionEnd, handleStop } from './stop';
+export { handleSubagentStart, 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,4 @@
+import type { Config } from '../config';
+import type { StopHookInput } from '../types';
+export declare function handleStop(input: StopHookInput, config: Config): Promise<void>;
+export declare function handleSessionEnd(input: StopHookInput, config: Config): Promise<void>;

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

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

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

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

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

@@ -0,0 +1,34 @@
+import type { Config } from '../config';
+import type { HookInput, SessionState, StopHookInput, TraceModel } from '../types';
+export declare function expandHome(filePath: string | undefined): string | undefined;
+export declare function sessionIdForInput(input: HookInput, transcriptPath?: string): 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;
+    turnEndTimeMs?: number;
+    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;
+    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 {};