deepseek-agent-acp 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -11,3 +11,7 @@
  * - Full Model Context Protocol (MCP) tool execution.
  */
 export declare function loadSecretKey(secretsPath?: string): string;
+/**
+ * Extract clean prompt text from ACP params supporting string, ContentBlock[], or nested structures.
+ */
+export declare function extractPromptText(params?: Record<string, unknown>): string;

package/dist/index.js

@@ -15,6 +15,7 @@ import readline from 'node:readline';
 import { format } from 'node:util';
 import { StreamAccumulator, parseSSEStream } from './sse-parser.js';
 import { McpClient } from './mcp-client.js';
+import { initTelemetry, registerSecret, parseNostrContext } from './telemetry.js';
 // ============================================================================
 // 1. STDIO HYGIENE
 // Redirect all console output to process.stderr so process.stdout is 100%
@@ -80,6 +81,11 @@ const DEEPSEEK_API_KEY = loadSecretKey();
 if (!DEEPSEEK_API_KEY) {
     console.warn('DEEPSEEK_API_KEY is not set. Ensure secrets are provided in environment or secrets file.');
 }
+registerSecret(DEEPSEEK_API_KEY);
+// OpenTelemetry & Arize Phoenix Telemetry Service
+const telemetryService = initTelemetry({
+    secrets: DEEPSEEK_API_KEY ? [DEEPSEEK_API_KEY] : []
+});
 // Configuration
 const BASE_URL = (process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/+$/, '');
 const MODEL = process.env.DEEPSEEK_MODEL ?? 'deepseek-chat';
@@ -261,12 +267,54 @@ async function handleRpcMessage(rpc) {
         }
     }
 }
+/**
+ * Extract clean prompt text from ACP params supporting string, ContentBlock[], or nested structures.
+ */
+export function extractPromptText(params) {
+    if (!params) {
+        return '';
+    }
+    const prompt = params.prompt ?? params.message ?? params.text;
+    if (typeof prompt === 'string') {
+        return prompt;
+    }
+    if (Array.isArray(prompt)) {
+        return prompt
+            .map((block) => {
+            if (typeof block === 'string') {
+                return block;
+            }
+            if (block && typeof block === 'object') {
+                const rec = block;
+                if (typeof rec.text === 'string') {
+                    return rec.text;
+                }
+                if (typeof rec.content === 'string') {
+                    return rec.content;
+                }
+            }
+            return '';
+        })
+            .filter(Boolean)
+            .join('\n');
+    }
+    if (prompt && typeof prompt === 'object') {
+        const rec = prompt;
+        if (typeof rec.text === 'string') {
+            return rec.text;
+        }
+        if (typeof rec.content === 'string') {
+            return rec.content;
+        }
+    }
+    return '';
+}
 /**
  * Handle ACP session/prompt execution with multi-turn tool loops.
  */
 async function handleSessionPrompt(id, params) {
     const sessionId = params?.sessionId || `session-${Date.now().toString()}`;
-    const promptText = params?.prompt || params?.message || params?.text || '';
+    const promptText = extractPromptText(params);
     let session = sessions.get(sessionId);
     if (!session) {
         session = new Session(sessionId);
@@ -285,6 +333,8 @@ async function handleSessionPrompt(id, params) {
     session.abortController = new AbortController();
     session.activePromptId = id ?? null;
     session.messages.push({ role: 'user', content: promptText });
+    const nostrMeta = parseNostrContext(promptText);
+    const turnHandle = telemetryService?.startTurnSpan(sessionId, promptText, MODEL, nostrMeta);
     const maxIterations = getIterationLimit(MODEL);
     let iteration = 0;
     let lastToolError = null;
@@ -298,6 +348,7 @@ async function handleSessionPrompt(id, params) {
             }
             iteration++;
             console.info(`Turn iteration ${iteration.toString()}/${maxIterations.toString()} for session ${sessionId}`);
+            const llmSpan = turnHandle?.startLlmSpan(MODEL, iteration);
             // Prepare messages for DeepSeek API: preserve reasoning_content (CoT Invariant)
             const messagesPayload = session.messages.map((m) => {
                 const msg = {
@@ -335,18 +386,21 @@ async function handleSessionPrompt(id, params) {
                     messages: messagesPayload,
                     tools: tools && tools.length > 0 ? tools : undefined,
                     temperature: TEMPERATURE,
-                    stream: true
+                    stream: true,
+                    stream_options: { include_usage: true }
                 }),
                 signal: combinedSignal
             });
             if (!response.ok) {
                 const errorText = await response.text();
+                llmSpan?.end(undefined, `DeepSeek API error (HTTP ${response.status.toString()}): ${errorText}`);
                 throw new Error(`DeepSeek API error (HTTP ${response.status.toString()}): ${errorText}`);
             }
             // Stream accumulator for 3-phase events
             let accumulator = null;
             for await (const event of parseSSEStream(response.body, requestTimeoutMs)) {
                 if (session.abortController?.signal?.aborted || !session.abortController) {
+                    llmSpan?.end(undefined, 'Stream aborted by client cancellation.');
                     throw new Error('Stream aborted by client cancellation.');
                 }
                 if (event.type === 'delta') {
@@ -376,6 +430,10 @@ async function handleSessionPrompt(id, params) {
             if (!accumulator) {
                 accumulator = new StreamAccumulator();
             }
+            if (accumulator.usage) {
+                llmSpan?.recordUsage(accumulator.usage);
+                turnHandle?.recordUsage(accumulator.usage);
+            }
             // Build assistant message
             const assistantMsg = {
                 role: 'assistant',
@@ -387,6 +445,7 @@ async function handleSessionPrompt(id, params) {
             // Truncated Stream / Synthetic Tool Error
             if (accumulator.isTruncated() && accumulator.toolCalls.length > 0) {
                 console.warn(`[SAFE STREAM] finish_reason === 'length' on tool call. Injecting synthetic tool error.`);
+                llmSpan?.end(undefined, 'Tool execution truncated due to token limits.');
                 assistantMsg.tool_calls = accumulator.toolCalls.map((tc) => ({
                     id: tc.id,
                     type: 'function',
@@ -418,9 +477,12 @@ async function handleSessionPrompt(id, params) {
             const validToolCalls = accumulator.getValidToolCalls();
             // No tool calls means the model produced its final response text
             if (validToolCalls.length === 0) {
+                llmSpan?.end(accumulator.content || undefined);
                 session.messages.push(assistantMsg);
                 session.commit();
                 turnCompleted = true;
+                turnHandle?.end('OK', accumulator.content || '');
+                void telemetryService?.backgroundFlush();
                 sendResponse(id, {
                     sessionId,
                     message: {
@@ -432,7 +494,8 @@ async function handleSessionPrompt(id, params) {
                 sendNotification('session/turnComplete', { sessionId });
                 return;
             }
-            // Tool calls were produced
+            // Tool calls were produced: close current iteration's LLM span before executing tools
+            llmSpan?.end(accumulator.content || undefined);
             assistantMsg.tool_calls = validToolCalls;
             session.messages.push(assistantMsg);
             let loopAborted = false;
@@ -447,6 +510,8 @@ async function handleSessionPrompt(id, params) {
                     const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
                     console.warn(`JSON parse error on tool arguments for ${tc.function.name}: ${msg}`);
                     const errorMsg = `Tool execution truncated due to token limits: malformed JSON arguments (${msg})`;
+                    turnHandle?.startToolSpan(tc.id, tc.function.name, tc.function.arguments);
+                    turnHandle?.endToolSpan(tc.id, JSON.stringify({ error: errorMsg }), true, tc.function.name);
                     session.messages.push({
                         role: 'tool',
                         tool_call_id: tc.id,
@@ -476,6 +541,7 @@ async function handleSessionPrompt(id, params) {
                 }
                 const argsPreview = JSON.stringify(parsedArgs).slice(0, 150);
                 console.info(`Executing tool via MCP: ${tc.function.name} args: ${argsPreview}`);
+                turnHandle?.startToolSpan(tc.id, tc.function.name, parsedArgs);
                 const toolResult = await mcpClient.callTool(tc.function.name, parsedArgs);
                 console.info(`Tool ${tc.function.name} output: ${toolResult.slice(0, 150).replace(/\n/g, ' ')}`);
                 session.messages.push({
@@ -495,6 +561,7 @@ async function handleSessionPrompt(id, params) {
                 catch {
                     // Ignored
                 }
+                turnHandle?.endToolSpan(tc.id, toolResult, Boolean(errorString), tc.function.name);
                 if (errorString) {
                     if (lastToolError === errorString) {
                         consecutiveErrorCount++;
@@ -545,6 +612,8 @@ async function handleSessionPrompt(id, params) {
             const finalContent = iteration >= maxIterations
                 ? (session.messages[session.messages.length - 1]?.content ?? 'Turn reached maximum iteration limit.')
                 : 'Turn execution stopped because repetitive tool errors occurred.';
+            turnHandle?.end('OK', finalContent);
+            void telemetryService?.backgroundFlush();
             sendResponse(id, {
                 sessionId,
                 message: {
@@ -561,6 +630,15 @@ async function handleSessionPrompt(id, params) {
         console.error(`Turn execution error in session ${sessionId}: ${msg}`);
         // Rollback session state on error
         session.rollback();
+        const isCancelled = session.abortController?.signal?.aborted ||
+            (err instanceof Error && (err.name === 'AbortError' || err.message.includes('cancellation')));
+        if (isCancelled) {
+            turnHandle?.end('CANCELLED');
+        }
+        else {
+            turnHandle?.end('ERROR', undefined, 'turn_failed', msg);
+        }
+        void telemetryService?.backgroundFlush();
         sendNotification('session/update', {
             sessionId,
             delta: {
@@ -604,29 +682,36 @@ rl.on('line', (line) => {
         console.error(`Invalid JSON-RPC frame: ${msg}`);
     }
 });
-const shutdown = (signal) => {
+const shutdown = async (signal) => {
     if (signal) {
         console.info(`Received ${signal}, closing...`);
     }
     else {
         console.info('Stdin closed. Shutting down adapter...');
     }
-    mcpClient
-        .close()
-        .catch((err) => {
-        console.error('Error during shutdown:', err);
-    })
-        .finally(() => {
-        process.exit(0);
-    });
+    try {
+        await mcpClient.close();
+    }
+    catch (err) {
+        console.error('Error during MCP client close:', err);
+    }
+    try {
+        if (telemetryService) {
+            await telemetryService.shutdown();
+        }
+    }
+    catch (err) {
+        console.error('Error during telemetry shutdown:', err);
+    }
+    process.exit(0);
 };
 rl.on('close', () => {
-    shutdown();
+    void shutdown();
 });
 // Handle graceful termination signals
 process.on('SIGTERM', () => {
-    shutdown('SIGTERM');
+    void shutdown('SIGTERM');
 });
 process.on('SIGINT', () => {
-    shutdown('SIGINT');
+    void shutdown('SIGINT');
 });

package/dist/sse-parser.d.ts

@@ -5,7 +5,7 @@
  *   2. content (response text tokens)
  *   3. tool_calls (function name and argument chunks)
  */
-import type { SSEEvent, SSEChunkData, ProcessedChunkResult, ToolCall, StreamYieldEvent } from './types.js';
+import type { SSEEvent, SSEChunkData, ProcessedChunkResult, ToolCall, StreamYieldEvent, DeepSeekUsage } from './types.js';
 export declare class SSEParser {
     private buffer;
     /**
@@ -20,6 +20,7 @@ export declare class StreamAccumulator {
     content: string;
     toolCalls: ToolCall[];
     finishReason: string | null;
+    usage: DeepSeekUsage | null;
     /**
      * Process a parsed SSE chunk data object.
      */

package/dist/sse-parser.js

@@ -52,10 +52,14 @@ export class StreamAccumulator {
     content = '';
     toolCalls = [];
     finishReason = null;
+    usage = null;
     /**
      * Process a parsed SSE chunk data object.
      */
     processChunk(chunkData) {
+        if (chunkData?.usage) {
+            this.usage = chunkData.usage;
+        }
         if (!chunkData?.choices || !Array.isArray(chunkData.choices) || chunkData.choices.length === 0) {
             return {
                 reasoningDelta: null,

package/dist/telemetry.d.ts

@@ -0,0 +1,73 @@
+/**
+ * telemetry.ts — OpenTelemetry and Arize Phoenix tracing for deepseek-agent-acp.
+ * Implements OpenInference GenAI semantic conventions:
+ * - AGENT root span (agent_turn) representing complete ACP turn.
+ * - LLM child spans (llm:<model>) per iteration tracking streaming deltas & token usage.
+ * - TOOL child spans (tool:<name>) for MCP tool execution with duration, output bytes, and status.
+ * - Special extraction of `nostr.posted_event_id` for buzz-trace topological thread linking.
+ * - Two-tier secret redaction (32KB pre-truncation, exact-match, bounded regexes) and fail-open design.
+ * - Strict stdio hygiene: zero writes to stdout (all diagnostics redirected to stderr).
+ */
+import type { DeepSeekUsage } from './types.js';
+export declare function _resetProcessSecretsCache(): void;
+/**
+ * Register a secret string for exact-match redaction (e.g. DEEPSEEK_API_KEY before env deletion).
+ */
+export declare function registerSecret(secret: string | undefined | null): void;
+/**
+ * Truncate a payload to maximum character length.
+ */
+export declare function truncatePayload(text: string, maxLen?: number): string;
+/**
+ * Redact sensitive secrets from text or object payloads.
+ * Pre-truncates to 32KB to protect against regex catastrophic backtracking.
+ */
+export declare function redactSecrets(input: unknown): string;
+/**
+ * Computes byte length of output safely without throwing TypeError
+ * when output is an Array, Object, Buffer, or String.
+ */
+export declare function computeOutputBytes(output: unknown): number;
+export interface NostrMetadata {
+    threadRootId?: string;
+    eventId?: string;
+    channelId?: string;
+    channelName?: string;
+    replyToId?: string;
+    senderName?: string;
+    senderPubkey?: string;
+}
+/**
+ * Parse Nostr context envelope injected by buzz-acp into prompt text.
+ * Isolates the active envelope using lastIndexOf('Event ID:') to prevent
+ * capturing cancelled or steered predecessor messages.
+ */
+export declare function parseNostrContext(rawText: unknown): NostrMetadata;
+/**
+ * Extract the posted Buzz event ID from a reply tool result.
+ * buzz-thread reply tools return `posted (N characters) · event_id <64 hex>`.
+ */
+export declare function extractPostedEventId(output: unknown): string | undefined;
+export interface LlmSpanHandle {
+    recordUsage(usage: DeepSeekUsage): void;
+    end(outputValue?: string, errorMessage?: string): void;
+}
+export interface TurnSpanHandle {
+    startLlmSpan(modelName: string, iteration?: number): LlmSpanHandle;
+    startToolSpan(toolCallId: string, toolName: string, toolParams: unknown): void;
+    endToolSpan(toolCallId: string, output?: unknown, isError?: boolean, toolName?: string): void;
+    recordUsage(usage: DeepSeekUsage): void;
+    end(status: 'OK' | 'ERROR' | 'CANCELLED', outputOrError?: string, failureKind?: string, errorMessage?: string): void;
+}
+export interface TelemetryService {
+    startTurnSpan(sessionId: string, promptText: string, modelName?: string, nostrMeta?: NostrMetadata): TurnSpanHandle;
+    backgroundFlush(timeoutMs?: number): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare function backgroundFlush(provider: {
+    forceFlush(): Promise<void>;
+}, timeoutMs?: number): Promise<void>;
+export declare function getPackageVersion(): string;
+export declare function initTelemetry(options?: {
+    secrets?: string[];
+}): TelemetryService | null;

package/dist/telemetry.js

@@ -0,0 +1,549 @@
+/**
+ * telemetry.ts — OpenTelemetry and Arize Phoenix tracing for deepseek-agent-acp.
+ * Implements OpenInference GenAI semantic conventions:
+ * - AGENT root span (agent_turn) representing complete ACP turn.
+ * - LLM child spans (llm:<model>) per iteration tracking streaming deltas & token usage.
+ * - TOOL child spans (tool:<name>) for MCP tool execution with duration, output bytes, and status.
+ * - Special extraction of `nostr.posted_event_id` for buzz-trace topological thread linking.
+ * - Two-tier secret redaction (32KB pre-truncation, exact-match, bounded regexes) and fail-open design.
+ * - Strict stdio hygiene: zero writes to stdout (all diagnostics redirected to stderr).
+ */
+import { trace, context, SpanStatusCode } from '@opentelemetry/api';
+import { NodeTracerProvider, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+// ============================================================================
+// 1. SECRET HYGIENE & REDACTION
+// ============================================================================
+const PREFIXED_PATTERNS = [
+    /nsec1[0-9a-z]{58}/gi,
+    /sk-[a-zA-Z0-9_\-.]{20,64}/g,
+    /sk-ant-[a-zA-Z0-9_.-]+/g,
+    /\bgl(pat|rt|dt|ptt|cbt|oas)-[0-9a-zA-Z_-]+/g,
+    /\bgh[pousr]_[0-9a-zA-Z]{36}\b/g,
+    /ya29\.[0-9a-zA-Z_-]+/g,
+    /1\/\/[0-9a-zA-Z_-]+/g,
+    /\beyJ[a-zA-Z0-9_-]{10,}\.eyJ[a-zA-Z0-9_-]{10,}\.[a-zA-Z0-9_-]+/g
+];
+const explicitSecrets = new Set();
+let cachedProcessSecrets = null;
+export function _resetProcessSecretsCache() {
+    cachedProcessSecrets = null;
+    explicitSecrets.clear();
+}
+/**
+ * Register a secret string for exact-match redaction (e.g. DEEPSEEK_API_KEY before env deletion).
+ */
+export function registerSecret(secret) {
+    if (!secret || typeof secret !== 'string' || secret.length < 8) {
+        return;
+    }
+    explicitSecrets.add(secret);
+    try {
+        const b64 = Buffer.from(secret).toString('base64');
+        if (b64.length >= 8) {
+            explicitSecrets.add(b64);
+        }
+    }
+    catch {
+        // Ignore base64 conversion errors
+    }
+    cachedProcessSecrets = null;
+}
+function getProcessSecrets() {
+    if (cachedProcessSecrets !== null) {
+        return cachedProcessSecrets;
+    }
+    const secrets = new Set(explicitSecrets);
+    const sensitiveKeys = [
+        'DEEPSEEK_API_KEY',
+        'BUZZ_PRIVATE_KEY',
+        'GITLAB_TOKEN',
+        'PHOENIX_API_KEY',
+        'AGY_OAUTH_TOKEN_B64',
+        'CLAUDE_CODE_OAUTH_TOKEN',
+        'ANTHROPIC_API_KEY'
+    ];
+    for (const key of sensitiveKeys) {
+        const val = process.env[key];
+        if (val && typeof val === 'string' && val.length >= 8) {
+            secrets.add(val);
+            try {
+                const b64 = Buffer.from(val).toString('base64');
+                if (b64.length >= 8) {
+                    secrets.add(b64);
+                }
+            }
+            catch {
+                // Ignore base64 conversion errors
+            }
+        }
+    }
+    // Deduplicate and sort descending by length to replace longer strings first
+    cachedProcessSecrets = Array.from(secrets).sort((a, b) => b.length - a.length);
+    return cachedProcessSecrets;
+}
+/**
+ * Truncate a payload to maximum character length.
+ */
+export function truncatePayload(text, maxLen = 8192) {
+    if (!text) {
+        return '';
+    }
+    if (text.length <= maxLen) {
+        return text;
+    }
+    return `${text.slice(0, maxLen)}... [TRUNCATED]`;
+}
+/**
+ * Redact sensitive secrets from text or object payloads.
+ * Pre-truncates to 32KB to protect against regex catastrophic backtracking.
+ */
+export function redactSecrets(input) {
+    if (input === null || input === undefined) {
+        return '';
+    }
+    let text = typeof input === 'string' ? input : JSON.stringify(input);
+    // Pre-truncate to 32KB to avoid ReDoS on massive tool payloads
+    if (text.length > 32768) {
+        text = `${text.slice(0, 32768)}... [PRE_TRUNCATED]`;
+    }
+    // 1. Exact match against known process secrets
+    const secrets = getProcessSecrets();
+    for (const secret of secrets) {
+        if (text.includes(secret)) {
+            text = text.split(secret).join('[REDACTED]');
+        }
+    }
+    // 2. Prefixed patterns (Nostr, DeepSeek, Anthropic, GitLab, GitHub, Google OAuth, JWT)
+    for (const pattern of PREFIXED_PATTERNS) {
+        text = text.replace(pattern, '[REDACTED]');
+    }
+    return text;
+}
+/**
+ * Computes byte length of output safely without throwing TypeError
+ * when output is an Array, Object, Buffer, or String.
+ */
+export function computeOutputBytes(output) {
+    if (output === null || output === undefined) {
+        return 0;
+    }
+    if (typeof output === 'string') {
+        return Buffer.byteLength(output, 'utf8');
+    }
+    if (Buffer.isBuffer(output)) {
+        return output.length;
+    }
+    try {
+        return Buffer.byteLength(JSON.stringify(output), 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Parse Nostr context envelope injected by buzz-acp into prompt text.
+ * Isolates the active envelope using lastIndexOf('Event ID:') to prevent
+ * capturing cancelled or steered predecessor messages.
+ */
+export function parseNostrContext(rawText) {
+    const result = {};
+    if (typeof rawText !== 'string' || !rawText) {
+        return result;
+    }
+    const lastEventIdx = rawText.lastIndexOf('Event ID:');
+    const contextSnippet = lastEventIdx !== -1 ? rawText.slice(Math.max(0, lastEventIdx - 200)) : rawText;
+    // 1. Thread Root ID: "Thread root: <64-hex>" or "root=<64-hex>"
+    const rootMatch = contextSnippet.match(/Thread root:\s*([a-f0-9]{64})/i) ?? contextSnippet.match(/\broot=([a-f0-9]{64})\b/i);
+    if (rootMatch?.[1]) {
+        result.threadRootId = rootMatch[1].toLowerCase();
+    }
+    // 2. Event ID: "Event ID: <64-hex>"
+    const eventMatch = contextSnippet.match(/Event ID:\s*([a-f0-9]{64})/i);
+    if (eventMatch?.[1]) {
+        result.eventId = eventMatch[1].toLowerCase();
+        if (!result.threadRootId) {
+            result.threadRootId = result.eventId;
+        }
+    }
+    // 3. Channel ID: "(#<UUID>)"
+    const channelMatch = contextSnippet.match(/#([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})/i);
+    if (channelMatch?.[1]) {
+        result.channelId = channelMatch[1].toLowerCase();
+    }
+    // 4. Channel Name: "Channel: <name> (#...)"
+    const channelNameMatch = contextSnippet.match(/Channel:\s*([a-zA-Z0-9_\-]+)\s*\(/i);
+    if (channelNameMatch?.[1]) {
+        result.channelName = channelNameMatch[1];
+    }
+    // 5. Parent / Reply-To ID: "parent=<64-hex>"
+    const parentMatch = contextSnippet.match(/\bparent=([a-f0-9]{64})\b/i);
+    if (parentMatch?.[1]) {
+        result.replyToId = parentMatch[1].toLowerCase();
+    }
+    // 6. Sender info: "From: Name (npub: ..., hex: <64-hex>)"
+    const fromMatch = contextSnippet.match(/From:\s*([^(]+?)\s*\(.*?hex:\s*([a-f0-9]{64})\)/i);
+    if (fromMatch?.[1] && fromMatch[2]) {
+        result.senderName = fromMatch[1].trim();
+        result.senderPubkey = fromMatch[2].toLowerCase();
+    }
+    return result;
+}
+/**
+ * Extract the posted Buzz event ID from a reply tool result.
+ * buzz-thread reply tools return `posted (N characters) · event_id <64 hex>`.
+ */
+export function extractPostedEventId(output) {
+    let text = '';
+    if (typeof output === 'string') {
+        text = output;
+    }
+    else if (output && typeof output === 'object') {
+        text = JSON.stringify(output);
+    }
+    if (!text) {
+        return undefined;
+    }
+    const match = /\bevent_id\s+([0-9a-f]{64})\b/i.exec(text.slice(0, 4096));
+    return match?.[1] ? match[1].toLowerCase() : undefined;
+}
+function isReplyTool(toolName) {
+    return toolName === 'mcp__buzz-thread__reply' || toolName === 'reply' || toolName.endsWith('reply');
+}
+// ============================================================================
+// 4. FLUSH COALESCING & ERROR THROTTLING
+// ============================================================================
+let inFlightFlush = null;
+let exportErrorCount = 0;
+function logExportError(err) {
+    exportErrorCount++;
+    if (exportErrorCount === 1 || exportErrorCount % 100 === 0) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[deepseek-acp:TELEMETRY] Trace export failed (#${exportErrorCount.toString()}): ${msg}`);
+    }
+}
+export function backgroundFlush(provider, timeoutMs = 1500) {
+    if (inFlightFlush) {
+        return inFlightFlush;
+    }
+    let timer;
+    const timeoutPromise = new Promise((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+        timer.unref(); // Prevent timer from pinning event loop
+    });
+    inFlightFlush = Promise.race([
+        provider.forceFlush().catch((err) => {
+            logExportError(err);
+        }),
+        timeoutPromise
+    ]).finally(() => {
+        if (timer) {
+            clearTimeout(timer);
+        }
+        inFlightFlush = null;
+    });
+    return inFlightFlush;
+}
+export function getPackageVersion() {
+    try {
+        const dir = dirname(fileURLToPath(import.meta.url));
+        const pkgPath = join(dir, '../package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return pkg.version ?? '0.2.0';
+    }
+    catch {
+        return '0.2.0';
+    }
+}
+// ============================================================================
+// 5. INITIALIZATION & ENGINE IMPLEMENTATION
+// ============================================================================
+export function initTelemetry(options) {
+    if (options?.secrets) {
+        for (const s of options.secrets) {
+            registerSecret(s);
+        }
+    }
+    const tracesEndpoint = process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+    if (!tracesEndpoint) {
+        return null;
+    }
+    try {
+        const serviceName = process.env.OTEL_SERVICE_NAME ?? 'deepseek-agent';
+        const projectName = process.env.PHOENIX_PROJECT_NAME ?? 'default';
+        const apiKey = process.env.PHOENIX_API_KEY;
+        const headers = {
+            'x-project-name': projectName
+        };
+        if (apiKey) {
+            headers['Authorization'] = `Bearer ${apiKey}`;
+        }
+        const exporter = new OTLPTraceExporter({
+            url: tracesEndpoint,
+            headers,
+            timeoutMillis: 1500
+        });
+        const batchProcessor = new BatchSpanProcessor(exporter, {
+            maxQueueSize: 2048,
+            maxExportBatchSize: 128,
+            scheduledDelayMillis: 5000,
+            exportTimeoutMillis: 1500
+        });
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: serviceName,
+            'openinference.project.name': projectName
+        });
+        const provider = new NodeTracerProvider({
+            resource,
+            spanProcessors: [batchProcessor],
+            spanLimits: {
+                attributeValueLengthLimit: 8192
+            }
+        });
+        provider.register();
+        const tracer = trace.getTracer('deepseek-agent-acp', getPackageVersion());
+        return {
+            startTurnSpan(sessionId, promptText, modelName, nostrMeta) {
+                const sanitizedPrompt = truncatePayload(redactSecrets(promptText), 8192);
+                const resolvedSessionId = nostrMeta?.threadRootId ?? sessionId;
+                const rootSpan = tracer.startSpan('agent_turn', {
+                    attributes: {
+                        'openinference.span.kind': 'AGENT',
+                        'session.id': resolvedSessionId,
+                        'user.id': nostrMeta?.senderPubkey ?? 'anonymous',
+                        'agent.name': serviceName,
+                        'input.value': sanitizedPrompt,
+                        'input.mime_type': 'text/plain',
+                        ...(nostrMeta?.threadRootId ? { 'nostr.thread_root_id': nostrMeta.threadRootId } : {}),
+                        ...(nostrMeta?.eventId ? { 'nostr.event_id': nostrMeta.eventId } : {}),
+                        ...(nostrMeta?.channelId ? { 'nostr.channel_id': nostrMeta.channelId } : {}),
+                        ...(nostrMeta?.channelName ? { 'nostr.channel_name': nostrMeta.channelName } : {}),
+                        ...(nostrMeta?.replyToId ? { 'nostr.reply_to_id': nostrMeta.replyToId, 'nostr.reply_to': nostrMeta.replyToId } : {}),
+                        ...(nostrMeta?.senderName ? { 'nostr.sender_name': nostrMeta.senderName } : {}),
+                        ...(nostrMeta?.senderPubkey ? { 'nostr.sender_pubkey': nostrMeta.senderPubkey } : {}),
+                        ...(process.env.AGENT_ID ? { 'agent.id': process.env.AGENT_ID } : {}),
+                        ...(process.env.AGENT_COMMUNITY ? { 'agent.community': process.env.AGENT_COMMUNITY } : {})
+                    }
+                });
+                const rootContext = trace.setSpan(context.active(), rootSpan);
+                const activeToolSpans = new Map();
+                const activeLlmSpans = new Set();
+                let hasEnded = false;
+                // Cumulative token counters across iterations for rootSpan
+                let totalPromptTokens = 0;
+                let totalCompletionTokens = 0;
+                let totalReasoningTokens = 0;
+                let totalCacheHitTokens = 0;
+                return {
+                    startLlmSpan(llmModel, iteration = 1) {
+                        const effectiveModel = llmModel || modelName || process.env.DEEPSEEK_MODEL || 'deepseek-chat';
+                        const llmSpan = tracer.startSpan(`llm:${effectiveModel}`, {
+                            attributes: {
+                                'openinference.span.kind': 'LLM',
+                                'session.id': resolvedSessionId,
+                                'llm.model_name': effectiveModel,
+                                'llm.provider': 'deepseek',
+                                'llm.iteration': iteration,
+                                'input.value': sanitizedPrompt,
+                                'input.mime_type': 'text/plain'
+                            }
+                        }, rootContext);
+                        activeLlmSpans.add(llmSpan);
+                        return {
+                            recordUsage(usage) {
+                                const promptTokens = usage.prompt_tokens || 0;
+                                // In DeepSeek-R1, completion_tokens already includes reasoning_tokens
+                                const completionTokens = usage.completion_tokens || 0;
+                                const totalTokens = usage.total_tokens || (promptTokens + completionTokens);
+                                const cacheHit = usage.prompt_cache_hit_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? 0;
+                                const reasoning = usage.completion_tokens_details?.reasoning_tokens ?? 0;
+                                totalPromptTokens += promptTokens;
+                                totalCompletionTokens += completionTokens;
+                                totalReasoningTokens += reasoning;
+                                totalCacheHitTokens += cacheHit;
+                                llmSpan.setAttributes({
+                                    'llm.token_count.prompt': promptTokens,
+                                    'llm.token_count.completion': completionTokens,
+                                    'llm.token_count.total': totalTokens,
+                                    ...(cacheHit > 0 ? { 'llm.token_count.prompt_details.cache_read': cacheHit } : {}),
+                                    ...(reasoning > 0 ? { 'llm.token_count.completion_details.reasoning': reasoning } : {})
+                                });
+                                // Update root cumulative counts
+                                rootSpan.setAttributes({
+                                    'llm.token_count.prompt': totalPromptTokens,
+                                    'llm.token_count.completion': totalCompletionTokens,
+                                    'llm.token_count.total': totalPromptTokens + totalCompletionTokens,
+                                    ...(totalCacheHitTokens > 0 ? { 'llm.token_count.prompt_details.cache_read': totalCacheHitTokens } : {}),
+                                    ...(totalReasoningTokens > 0 ? { 'llm.token_count.completion_details.reasoning': totalReasoningTokens } : {})
+                                });
+                            },
+                            end(outputValue, errorMessage) {
+                                activeLlmSpans.delete(llmSpan);
+                                if (outputValue) {
+                                    const sanitizedOut = truncatePayload(redactSecrets(outputValue), 8192);
+                                    llmSpan.setAttribute('output.value', sanitizedOut);
+                                    llmSpan.setAttribute('output.mime_type', 'text/plain');
+                                }
+                                if (errorMessage) {
+                                    llmSpan.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage });
+                                    llmSpan.setAttribute('error.message', errorMessage);
+                                }
+                                else {
+                                    llmSpan.setStatus({ code: SpanStatusCode.OK });
+                                }
+                                llmSpan.end();
+                            }
+                        };
+                    },
+                    startToolSpan(toolCallId, toolName, toolParams) {
+                        if (activeToolSpans.has(toolCallId)) {
+                            return;
+                        }
+                        const sanitizedParams = truncatePayload(redactSecrets(toolParams), 8192);
+                        const toolSpan = tracer.startSpan(`tool:${toolName}`, {
+                            attributes: {
+                                'openinference.span.kind': 'TOOL',
+                                'session.id': resolvedSessionId,
+                                'tool.name': toolName,
+                                'tool.call_id': toolCallId,
+                                'tool.parameters': sanitizedParams,
+                                'input.value': sanitizedParams,
+                                'input.mime_type': 'application/json'
+                            }
+                        }, rootContext);
+                        activeToolSpans.set(toolCallId, { span: toolSpan, toolName });
+                    },
+                    endToolSpan(toolCallId, output, isError, toolName) {
+                        const entry = activeToolSpans.get(toolCallId);
+                        if (!entry) {
+                            if (toolName) {
+                                rootSpan.addEvent('unmapped_tool_result', {
+                                    'tool.call_id': toolCallId,
+                                    'tool.name': toolName
+                                });
+                            }
+                            return;
+                        }
+                        const { span: toolSpan, toolName: resolvedToolName } = entry;
+                        const outputBytes = computeOutputBytes(output);
+                        toolSpan.setAttribute('tool.output_bytes', outputBytes);
+                        // Extract posted_event_id for reply tools
+                        if (!isError && isReplyTool(resolvedToolName)) {
+                            const postedId = extractPostedEventId(output);
+                            if (postedId) {
+                                toolSpan.setAttribute('nostr.posted_event_id', postedId);
+                                rootSpan.setAttribute('nostr.posted_event_id', postedId);
+                            }
+                        }
+                        if (process.env.OTEL_CAPTURE_TOOL_OUTPUT === 'true' && output !== undefined) {
+                            const sanitizedOut = truncatePayload(redactSecrets(output), 8192);
+                            toolSpan.setAttribute('output.value', sanitizedOut);
+                            toolSpan.setAttribute('output.mime_type', 'text/plain');
+                        }
+                        toolSpan.setAttribute('tool.is_error', Boolean(isError));
+                        if (isError) {
+                            toolSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: 'tool_execution_failed'
+                            });
+                        }
+                        else {
+                            toolSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        toolSpan.end();
+                        activeToolSpans.delete(toolCallId);
+                    },
+                    recordUsage(usage) {
+                        const promptTokens = usage.prompt_tokens || 0;
+                        const completionTokens = usage.completion_tokens || 0;
+                        const cacheHit = usage.prompt_cache_hit_tokens ?? usage.prompt_tokens_details?.cached_tokens ?? 0;
+                        const reasoning = usage.completion_tokens_details?.reasoning_tokens ?? 0;
+                        totalPromptTokens = Math.max(totalPromptTokens, promptTokens);
+                        totalCompletionTokens = Math.max(totalCompletionTokens, completionTokens);
+                        totalReasoningTokens = Math.max(totalReasoningTokens, reasoning);
+                        totalCacheHitTokens = Math.max(totalCacheHitTokens, cacheHit);
+                        rootSpan.setAttributes({
+                            'llm.token_count.prompt': totalPromptTokens,
+                            'llm.token_count.completion': totalCompletionTokens,
+                            'llm.token_count.total': totalPromptTokens + totalCompletionTokens,
+                            ...(totalCacheHitTokens > 0 ? { 'llm.token_count.prompt_details.cache_read': totalCacheHitTokens } : {}),
+                            ...(totalReasoningTokens > 0 ? { 'llm.token_count.completion_details.reasoning': totalReasoningTokens } : {})
+                        });
+                    },
+                    end(status, outputOrError, failureKind, errorMessage) {
+                        if (hasEnded) {
+                            return;
+                        }
+                        hasEnded = true;
+                        // Turn boundary sweep: close any orphaned tool spans safely
+                        for (const { span: orphanSpan } of activeToolSpans.values()) {
+                            orphanSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: 'orphaned_at_turn_end'
+                            });
+                            orphanSpan.setAttribute('error.message', 'orphaned_at_turn_end');
+                            orphanSpan.setAttribute('tool.is_error', true);
+                            orphanSpan.end();
+                        }
+                        activeToolSpans.clear();
+                        // Sweep any lingering LLM spans
+                        for (const orphanLlm of activeLlmSpans) {
+                            orphanLlm.setStatus({ code: SpanStatusCode.ERROR, message: 'orphaned_at_turn_end' });
+                            orphanLlm.end();
+                        }
+                        activeLlmSpans.clear();
+                        const outputValue = status === 'OK' ? outputOrError : undefined;
+                        if (outputValue) {
+                            const sanitizedOut = truncatePayload(redactSecrets(outputValue), 8192);
+                            rootSpan.setAttribute('output.value', sanitizedOut);
+                            rootSpan.setAttribute('output.mime_type', 'text/plain');
+                        }
+                        if (status === 'CANCELLED') {
+                            // Leave status UNSET to preserve SLO Error Budget; record stop_reason
+                            rootSpan.setAttribute('deepseek.stop_reason', 'cancelled');
+                        }
+                        else if (status === 'ERROR') {
+                            const errDesc = errorMessage ?? failureKind ?? outputOrError ?? 'turn_failed';
+                            rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: errDesc });
+                            if (failureKind) {
+                                rootSpan.setAttribute('error.kind', failureKind);
+                            }
+                            rootSpan.setAttribute('error.message', truncatePayload(errDesc, 1024));
+                        }
+                        else {
+                            rootSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
+                        rootSpan.end();
+                    }
+                };
+            },
+            backgroundFlush(timeoutMs = 1500) {
+                return backgroundFlush(provider, timeoutMs);
+            },
+            async shutdown() {
+                try {
+                    await Promise.race([
+                        provider.shutdown(),
+                        new Promise((resolve) => {
+                            const t = setTimeout(resolve, 1500);
+                            t.unref();
+                        })
+                    ]);
+                }
+                catch (err) {
+                    logExportError(err);
+                }
+            }
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[deepseek-acp:TELEMETRY] Failed to initialize OpenTelemetry SDK (running fail-open): ${msg}`);
+        return null;
+    }
+}

package/dist/types.d.ts

@@ -36,12 +36,26 @@ export interface SSEChoice {
     delta?: SSEChoiceDelta;
     finish_reason?: 'stop' | 'tool_calls' | 'length' | null;
 }
+export interface DeepSeekUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    prompt_cache_hit_tokens?: number;
+    prompt_cache_miss_tokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
+    completion_tokens_details?: {
+        reasoning_tokens?: number;
+    };
+}
 export interface SSEChunkData {
     id?: string;
     object?: string;
     created?: number;
     model?: string;
     choices: SSEChoice[];
+    usage?: DeepSeekUsage;
 }
 export interface SSEEvent {
     done: boolean;
@@ -72,6 +86,7 @@ export interface StreamYieldEvent {
         content: string;
         toolCalls: ToolCall[];
         finishReason: string | null;
+        usage: DeepSeekUsage | null;
         isTruncated: () => boolean;
         getValidToolCalls: () => ToolCall[];
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepseek-agent-acp",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Agent Client Protocol (ACP) adapter for DeepSeek reasoning and chat models with Model Context Protocol (MCP) tool execution",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,7 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src tests",
     "lint:fix": "eslint src tests --fix",
-    "test": "node --test tests/test_sse_parser.test.mjs tests/test_deepseek_acp.test.mjs",
+    "test": "node --test tests/test_sse_parser.test.mjs tests/test_deepseek_acp.test.mjs tests/test_telemetry.test.mjs",
     "start": "node dist/index.js",
     "prepare": "husky",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
@@ -59,7 +59,12 @@
   },
   "homepage": "https://github.com/dongitran/deepseek-agent-acp#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.2"
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.223.0",
+    "@opentelemetry/resources": "^2.12.0",
+    "@opentelemetry/sdk-trace-node": "^2.12.0",
+    "@opentelemetry/semantic-conventions": "^1.45.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",