ronds_ai 0.1.21 → 0.1.23

package/lib/analyze_langfuse.js

@@ -0,0 +1,736 @@
+/*
+ * 此实现基于 Langfuse Claude Observability Plugin（MIT）进行等价迁移：
+ * https://github.com/langfuse/Claude-Observability-Plugin
+ */
+
+const path = require('path');
+const {
+  buildTurns,
+  extractTextFromContent,
+  getContentFromRow,
+  getModel,
+  getToolUseBlocks,
+  getUsageDetailsFromRow,
+  parseTimestamp,
+  readSubagentJsonl,
+  truncateText,
+} = require('./analyze_transcript');
+
+/**
+ * 返回多个时间中的最晚值。
+ */
+function latestTimestamp(...timestamps) {
+  const values = timestamps.filter((value) => value instanceof Date);
+  return values.length > 0
+    ? new Date(Math.max(...values.map((value) => value.getTime())))
+    : null;
+}
+
+/**
+ * 创建具有历史时间和明确父级的 Langfuse Observation。
+ */
+function startHistoricalObservation(api, parent, name, attributes, asType, startTime) {
+  const options = { asType };
+  if (startTime instanceof Date) {
+    options.startTime = startTime;
+  }
+  if (parent && parent.otelSpan) {
+    options.parentSpanContext = parent.otelSpan.spanContext();
+  }
+  return api.startObservation(name, attributes, options);
+}
+
+/**
+ * 使用历史时间结束 Observation。
+ */
+function endObservation(observation, endTime) {
+  observation.end(endTime instanceof Date ? endTime : undefined);
+}
+
+/**
+ * 获取用于 Langfuse 显示的短会话标识。
+ */
+function shortSessionLabel(sessionId, maxLength = 12) {
+  const normalized = String(sessionId || '').trim();
+  if (!normalized) {
+    return 'unknown';
+  }
+  const parts = normalized.split('-');
+  if (parts.length === 5 && parts[0].length === 8) {
+    return parts[0];
+  }
+  return normalized.length <= maxLength
+    ? normalized
+    : normalized.slice(0, maxLength).replace(/-+$/, '');
+}
+
+/**
+ * 构造每个 Turn 的 Trace 名称。
+ */
+function traceDisplayName(sessionId, turnNumber) {
+  return `Claude Code - Turn ${turnNumber} (${shortSessionLabel(sessionId)})`;
+}
+
+/**
+ * 收集当前 Turn 调用的 Skill 标签。
+ */
+function collectSkillTags(turn) {
+  const tags = [];
+  for (const assistantMessage of turn.assistantMsgs) {
+    for (const toolUse of getToolUseBlocks(getContentFromRow(assistantMessage))) {
+      const skill = toolUse.name === 'Skill'
+        && toolUse.input
+        && typeof toolUse.input.skill === 'string'
+        ? toolUse.input.skill
+        : '';
+      if (skill && !tags.includes(`skill:${skill}`)) {
+        tags.push(`skill:${skill}`);
+      }
+    }
+  }
+  return tags;
+}
+
+/**
+ * 构造与原插件一致的 Trace 标签。
+ */
+function getTraceTags(turn, config) {
+  return config.skillTags
+    ? ['claude-code', ...collectSkillTags(turn)]
+    : ['claude-code'];
+}
+
+/**
+ * 构造 LLM Generation 的输入。
+ */
+function buildGenerationInput(
+  assistantIndex,
+  userText,
+  previousToolResults,
+  readyAsyncToolResults,
+) {
+  if (assistantIndex === 0) {
+    return { role: 'user', content: userText };
+  }
+  const toolResults = previousToolResults.concat(
+    readyAsyncToolResults.map((entry) => entry.toolResult),
+  );
+  return toolResults.length > 0
+    ? { role: 'tool', tool_results: toolResults }
+    : null;
+}
+
+/**
+ * 构造 LLM Generation 的输出。
+ */
+function buildGenerationOutput(assistantText, toolUses) {
+  const output = { role: 'assistant' };
+  if (assistantText) {
+    output.content = assistantText;
+  }
+  if (toolUses.length > 0) {
+    output.tool_calls = toolUses.map((toolUse) => ({
+      id: toolUse.id,
+      name: toolUse.name,
+    }));
+  }
+  return output;
+}
+
+/**
+ * 规范化工具输入，并对字符串执行截断。
+ */
+function getToolInputForObservation(toolUse, config) {
+  const input = toolUse && toolUse.input;
+  if (typeof input === 'string') {
+    const truncated = truncateText(input, config.maxChars);
+    return { input: truncated.text, inputMetadata: truncated.metadata };
+  }
+  const supported = input == null
+    || typeof input === 'string'
+    || typeof input === 'number'
+    || typeof input === 'boolean'
+    || Array.isArray(input)
+    || typeof input === 'object';
+  return { input: supported ? input : {}, inputMetadata: null };
+}
+
+/**
+ * 规范化工具返回，并保留异步 Agent 的初始和最终结果。
+ */
+function getToolResultForObservation(entry, config) {
+  if (!entry || typeof entry !== 'object') {
+    return {
+      output: null,
+      outputMetadata: null,
+      resultTimestamp: null,
+      finalOutput: null,
+      finalResultTimestamp: null,
+    };
+  }
+  const rawOutput = typeof entry.content === 'string'
+    ? entry.content
+    : JSON.stringify(entry.content);
+  const output = truncateText(rawOutput, config.maxChars);
+  let finalOutput = null;
+  if (entry.finalContent != null) {
+    const rawFinal = typeof entry.finalContent === 'string'
+      ? entry.finalContent
+      : JSON.stringify(entry.finalContent);
+    finalOutput = truncateText(rawFinal, config.maxChars).text;
+  }
+  return {
+    output: output.text,
+    outputMetadata: output.metadata,
+    resultTimestamp: parseTimestamp(entry.timestamp),
+    finalOutput,
+    finalResultTimestamp: parseTimestamp(entry.finalTimestamp),
+  };
+}
+
+/**
+ * 读取 metadata 中使用的短 transcript 文件名。
+ */
+function shortTranscriptPath(filePath) {
+  return typeof filePath === 'string' && filePath ? path.basename(filePath) : null;
+}
+
+/**
+ * 构造 Tool Observation metadata。
+ */
+function buildToolMetadata(toolName, toolUseId, inputMetadata, toolResult, subagent) {
+  const metadata = {
+    tool_name: toolName,
+    tool_id: toolUseId,
+    input_meta: inputMetadata,
+    output_meta: toolResult.outputMetadata,
+  };
+  if (subagent) {
+    metadata.subagent_type = subagent.agentType;
+    metadata.subagent_description = subagent.description;
+    metadata.subagent_transcript_path = shortTranscriptPath(subagent.path);
+  }
+  return metadata;
+}
+
+/**
+ * 读取 Turn 的结束时间。
+ */
+function getTurnEndTimestamp(turn) {
+  const timestamps = [];
+  if (turn.assistantMsgs.length > 0) {
+    timestamps.push(parseTimestamp(turn.assistantMsgs[turn.assistantMsgs.length - 1]));
+  }
+  for (const result of Object.values(turn.toolResultsById)) {
+    timestamps.push(parseTimestamp(result));
+  }
+  return latestTimestamp(...timestamps);
+}
+
+/**
+ * 从等待队列中取出当前 Generation 前已完成的子 Agent。
+ */
+function takeReadySubagents(pendingSubagents, assistantTimestamp) {
+  const ready = [];
+  const pending = [];
+  for (const entry of pendingSubagents) {
+    if (entry.readyTimestamp instanceof Date
+      && (!(assistantTimestamp instanceof Date)
+        || entry.readyTimestamp.getTime() <= assistantTimestamp.getTime())) {
+      ready.push(entry);
+    } else {
+      pending.push(entry);
+    }
+  }
+  return { ready, pending };
+}
+
+/**
+ * 从等待队列中取出当前 Generation 前已完成的异步工具结果。
+ */
+function takeReadyAsyncToolResults(pendingResults, assistantTimestamp) {
+  const ready = [];
+  const pending = [];
+  for (const entry of pendingResults) {
+    if (entry.timestamp instanceof Date
+      && (!(assistantTimestamp instanceof Date)
+        || entry.timestamp.getTime() <= assistantTimestamp.getTime())) {
+      ready.push(entry);
+    } else {
+      pending.push(entry);
+    }
+  }
+  return {
+    ready,
+    pending,
+    latestReadyTimestamp: latestTimestamp(...ready.map((entry) => entry.timestamp)),
+  };
+}
+
+/**
+ * 在启动响应被下一次 Generation 消费后微调子 Agent 的展示起点。
+ */
+function updatePendingSubagentDisplayStart(
+  pendingSubagents,
+  generationInputToolResults,
+  generationStartTimestamp,
+) {
+  if (!(generationStartTimestamp instanceof Date)) {
+    return;
+  }
+  const toolUseIds = new Set(
+    generationInputToolResults
+      .map((entry) => entry && entry.tool_use_id)
+      .filter(Boolean)
+      .map(String),
+  );
+  for (const entry of pendingSubagents) {
+    if (!entry.displayStartTimestamp && toolUseIds.has(entry.toolUseId)) {
+      entry.displayStartTimestamp = new Date(generationStartTimestamp.getTime() + 1);
+    }
+  }
+}
+
+/**
+ * 导出完整的子 Agent Span 及其内部 Generation 和 Tool。
+ */
+function emitSubagentObservations(api, parent, subagent, startTimestamp, config) {
+  if (!subagent || typeof subagent.path !== 'string') {
+    return startTimestamp;
+  }
+  let rows;
+  try {
+    rows = readSubagentJsonl(subagent.path);
+  } catch {
+    return startTimestamp;
+  }
+  const turns = buildTurns(rows);
+  if (turns.length === 0) {
+    return startTimestamp;
+  }
+
+  const firstTurn = turns[0];
+  const subagentStart = startTimestamp || parseTimestamp(firstTurn.userMsg);
+  const input = truncateText(
+    extractTextFromContent(getContentFromRow(firstTurn.userMsg)),
+    config.maxChars,
+  );
+  const lastTurn = turns[turns.length - 1];
+  const lastAssistant = lastTurn.assistantMsgs[lastTurn.assistantMsgs.length - 1];
+  const output = truncateText(
+    extractTextFromContent(getContentFromRow(lastAssistant)),
+    config.maxChars,
+  );
+  const name = subagent.description
+    ? `Subagent: ${subagent.description}`
+    : 'Subagent';
+  const span = startHistoricalObservation(api, parent, name, {
+    input: { role: 'user', content: input.text },
+    metadata: {
+      agent_type: subagent.agentType,
+      description: subagent.description,
+      transcript_path: shortTranscriptPath(subagent.path),
+      user_text: input.metadata,
+    },
+  }, 'span', subagentStart);
+
+  let latestEnd = subagentStart;
+  let previousStart = subagentStart;
+  for (const turn of turns) {
+    const turnEnd = emitTurnObservations(
+      api,
+      span,
+      turn,
+      previousStart,
+      config,
+      'Subagent LLM Call',
+      null,
+    );
+    latestEnd = latestTimestamp(latestEnd, turnEnd);
+    if (turnEnd) {
+      previousStart = turnEnd;
+    }
+  }
+  span.update({ output: { role: 'assistant', content: output.text } });
+  endObservation(span, latestTimestamp(latestEnd, subagentStart));
+  return latestEnd;
+}
+
+/**
+ * 导出单个 Tool Observation，并调度关联的异步结果和子 Agent。
+ */
+function emitSingleToolObservation(
+  api,
+  parent,
+  turn,
+  assistantTimestamp,
+  toolUse,
+  subagents,
+  pendingSubagents,
+  pendingAsyncToolResults,
+  config,
+) {
+  const toolUseId = String(toolUse.id || '');
+  const toolName = toolUse.name || 'unknown';
+  const toolInput = getToolInputForObservation(toolUse, config);
+  const resultEntry = toolUseId ? turn.toolResultsById[toolUseId] : null;
+  const toolResult = getToolResultForObservation(resultEntry, config);
+  const subagent = subagents && toolUseId ? subagents[toolUseId] : null;
+
+  let toolOutput = toolResult.output;
+  if (config.captureSkillContent && turn.injectedByToolId[toolUseId]) {
+    toolOutput = {
+      result: toolResult.output,
+      injected_instructions: truncateText(
+        turn.injectedByToolId[toolUseId],
+        config.maxChars,
+      ).text,
+    };
+  }
+
+  const toolStart = parseTimestamp(turn.toolUseTimestampsById[toolUseId])
+    || assistantTimestamp;
+  const toolSpan = startHistoricalObservation(api, parent, `Tool: ${toolName}`, {
+    input: toolInput.input,
+    metadata: buildToolMetadata(
+      toolName,
+      toolUseId,
+      toolInput.inputMetadata,
+      toolResult,
+      subagent,
+    ),
+  }, 'tool', toolStart);
+  toolSpan.update({ output: toolOutput });
+
+  let subagentEnd = null;
+  if (subagent) {
+    if (toolResult.finalResultTimestamp) {
+      pendingSubagents.push({
+        toolUseId,
+        subagent,
+        startTimestamp: toolStart,
+        readyTimestamp: toolResult.finalResultTimestamp,
+      });
+    } else {
+      subagentEnd = emitSubagentObservations(api, parent, subagent, toolStart, config);
+    }
+  }
+
+  const toolEnd = latestTimestamp(toolResult.resultTimestamp, toolStart);
+  const handoffTimestamp = toolResult.resultTimestamp
+    || toolResult.finalResultTimestamp
+    || subagentEnd
+    || assistantTimestamp;
+  endObservation(toolSpan, toolEnd);
+
+  if (toolResult.finalResultTimestamp && toolResult.finalOutput != null) {
+    pendingAsyncToolResults.push({
+      timestamp: toolResult.finalResultTimestamp,
+      toolResult: {
+        tool_use_id: toolUseId,
+        tool_name: toolName,
+        output: toolResult.finalOutput,
+      },
+    });
+  }
+  return {
+    handoffTimestamp,
+    toolResult: {
+      tool_use_id: toolUseId,
+      tool_name: toolName,
+      output: toolResult.output,
+    },
+    latestEndTimestamp: latestTimestamp(toolEnd, subagentEnd),
+  };
+}
+
+/**
+ * 导出某次 Assistant 消息中的全部工具调用。
+ */
+function emitToolObservationBatch(
+  api,
+  parent,
+  turn,
+  assistantMessage,
+  toolUses,
+  subagents,
+  pendingSubagents,
+  pendingAsyncToolResults,
+  config,
+) {
+  const assistantTimestamp = parseTimestamp(assistantMessage);
+  const resultTimestamps = [];
+  const toolResults = [];
+  let latestEndTimestamp = null;
+  for (const toolUse of toolUses) {
+    const emitted = emitSingleToolObservation(
+      api,
+      parent,
+      turn,
+      assistantTimestamp,
+      toolUse,
+      subagents,
+      pendingSubagents,
+      pendingAsyncToolResults,
+      config,
+    );
+    if (emitted.handoffTimestamp) {
+      resultTimestamps.push(emitted.handoffTimestamp);
+    }
+    toolResults.push(emitted.toolResult);
+    latestEndTimestamp = latestTimestamp(
+      latestEndTimestamp,
+      emitted.latestEndTimestamp,
+    );
+  }
+  return { resultTimestamps, toolResults, latestEndTimestamp };
+}
+
+/**
+ * 构造单个 Assistant Generation 的 Langfuse 属性。
+ */
+function buildGenerationAttributes(
+  assistantIndex,
+  assistantMessage,
+  userText,
+  previousToolResults,
+  readyAsyncToolResults,
+  config,
+) {
+  const assistantText = truncateText(
+    extractTextFromContent(getContentFromRow(assistantMessage)),
+    config.maxChars,
+  );
+  const toolUses = getToolUseBlocks(getContentFromRow(assistantMessage));
+  const attributes = {
+    model: getModel(assistantMessage),
+    input: buildGenerationInput(
+      assistantIndex,
+      userText,
+      previousToolResults,
+      readyAsyncToolResults,
+    ),
+    output: buildGenerationOutput(assistantText.text, toolUses),
+    metadata: {
+      assistant_index: assistantIndex,
+      assistant_text: assistantText.metadata,
+      tool_count: toolUses.length,
+    },
+  };
+  const usageDetails = getUsageDetailsFromRow(assistantMessage);
+  if (usageDetails) {
+    attributes.usageDetails = usageDetails;
+  }
+  return { attributes, toolUses };
+}
+
+/**
+ * 导出一个 Turn 内的 Generation、Tool 和 Subagent Observations。
+ */
+function emitTurnObservations(
+  api,
+  parent,
+  turn,
+  startTimestamp,
+  config,
+  generationPrefix = 'LLM Call',
+  subagents = null,
+) {
+  const userText = truncateText(
+    extractTextFromContent(getContentFromRow(turn.userMsg)),
+    config.maxChars,
+  ).text;
+  let previousTimestamp = startTimestamp;
+  let previousToolResults = [];
+  let pendingAsyncToolResults = [];
+  let pendingSubagents = [];
+  let latestEndTimestamp = startTimestamp;
+
+  for (let index = 0; index < turn.assistantMsgs.length; index += 1) {
+    const assistantMessage = turn.assistantMsgs[index];
+    const assistantTimestamp = parseTimestamp(assistantMessage);
+
+    if (index > 0 && pendingSubagents.length > 0) {
+      const subagentBatch = takeReadySubagents(pendingSubagents, assistantTimestamp);
+      pendingSubagents = subagentBatch.pending;
+      for (const entry of subagentBatch.ready) {
+        const subagentEnd = emitSubagentObservations(
+          api,
+          parent,
+          entry.subagent,
+          entry.displayStartTimestamp || entry.startTimestamp,
+          config,
+        );
+        latestEndTimestamp = latestTimestamp(latestEndTimestamp, subagentEnd);
+      }
+    }
+
+    let readyAsyncToolResults = [];
+    if (index > 0 && pendingAsyncToolResults.length > 0) {
+      const resultBatch = takeReadyAsyncToolResults(
+        pendingAsyncToolResults,
+        assistantTimestamp,
+      );
+      readyAsyncToolResults = resultBatch.ready;
+      pendingAsyncToolResults = resultBatch.pending;
+      previousTimestamp = latestTimestamp(
+        previousTimestamp,
+        resultBatch.latestReadyTimestamp,
+      );
+    }
+
+    const generationData = buildGenerationAttributes(
+      index,
+      assistantMessage,
+      userText,
+      previousToolResults,
+      readyAsyncToolResults,
+      config,
+    );
+    const generationStart = previousTimestamp || assistantTimestamp;
+    const generation = startHistoricalObservation(
+      api,
+      parent,
+      `${generationPrefix} ${index + 1}`,
+      generationData.attributes,
+      'generation',
+      generationStart,
+    );
+    updatePendingSubagentDisplayStart(
+      pendingSubagents,
+      previousToolResults,
+      generationStart,
+    );
+
+    const tools = emitToolObservationBatch(
+      api,
+      parent,
+      turn,
+      assistantMessage,
+      generationData.toolUses,
+      subagents,
+      pendingSubagents,
+      pendingAsyncToolResults,
+      config,
+    );
+    latestEndTimestamp = latestTimestamp(
+      latestEndTimestamp,
+      tools.latestEndTimestamp,
+    );
+    const generationEnd = tools.resultTimestamps.length > 0
+      ? latestTimestamp(...tools.resultTimestamps)
+      : assistantTimestamp;
+    endObservation(
+      generation,
+      generationEnd || assistantTimestamp || previousTimestamp,
+    );
+    latestEndTimestamp = latestTimestamp(latestEndTimestamp, generationEnd);
+    previousToolResults = tools.toolResults;
+    previousTimestamp = tools.resultTimestamps.length > 0
+      ? latestTimestamp(...tools.resultTimestamps)
+      : assistantTimestamp || previousTimestamp;
+  }
+
+  for (const entry of pendingSubagents) {
+    const subagentEnd = emitSubagentObservations(
+      api,
+      parent,
+      entry.subagent,
+      entry.displayStartTimestamp || entry.startTimestamp,
+      config,
+    );
+    latestEndTimestamp = latestTimestamp(latestEndTimestamp, subagentEnd);
+  }
+  return latestEndTimestamp;
+}
+
+/**
+ * 构造根 Trace metadata。
+ */
+function buildTraceMetadata(sessionId, turnNumber, turn, transcriptPath, userTextMetadata) {
+  const metadata = {
+    source: 'claude-code',
+    session_id: sessionId,
+    turn_number: turnNumber,
+    transcript_path: shortTranscriptPath(transcriptPath),
+    user_text: userTextMetadata,
+    assistant_message_count: turn.assistantMsgs.length,
+  };
+  if (typeof turn.userMsg.cwd === 'string' && turn.userMsg.cwd) {
+    metadata.cwd = turn.userMsg.cwd;
+  }
+  if (typeof turn.userMsg.gitBranch === 'string' && turn.userMsg.gitBranch) {
+    metadata.git_branch = turn.userMsg.gitBranch;
+  }
+  return metadata;
+}
+
+/**
+ * 导出单个 Claude Code Turn。
+ */
+function emitTurn(api, sessionId, turnNumber, turn, transcriptPath, subagents, config) {
+  const userText = truncateText(
+    extractTextFromContent(getContentFromRow(turn.userMsg)),
+    config.maxChars,
+  );
+  const lastAssistant = turn.assistantMsgs[turn.assistantMsgs.length - 1];
+  const assistantText = truncateText(
+    extractTextFromContent(getContentFromRow(lastAssistant)),
+    config.maxChars,
+  );
+  const userTimestamp = parseTimestamp(turn.userMsg);
+  const assistantTimestamp = parseTimestamp(lastAssistant);
+  const tags = getTraceTags(turn, config);
+
+  api.propagateAttributes({
+    sessionId,
+    userId: config.userId,
+    traceName: traceDisplayName(sessionId, turnNumber),
+    tags,
+  }, () => {
+    const root = startHistoricalObservation(api, null, 'Conversational Turn', {
+      input: { role: 'user', content: userText.text },
+      metadata: buildTraceMetadata(
+        sessionId,
+        turnNumber,
+        turn,
+        transcriptPath,
+        userText.metadata,
+      ),
+    }, 'span', userTimestamp);
+    const observationEnd = emitTurnObservations(
+      api,
+      root,
+      turn,
+      userTimestamp,
+      config,
+      'LLM Call',
+      subagents,
+    );
+    root.update({
+      output: { role: 'assistant', content: assistantText.text },
+    });
+    endObservation(
+      root,
+      latestTimestamp(
+        getTurnEndTimestamp(turn),
+        assistantTimestamp,
+        observationEnd,
+        userTimestamp,
+      ),
+    );
+  });
+}
+
+module.exports = {
+  buildGenerationInput,
+  buildGenerationOutput,
+  buildTraceMetadata,
+  collectSkillTags,
+  emitTurn,
+  emitTurnObservations,
+  getToolResultForObservation,
+  latestTimestamp,
+  shortSessionLabel,
+  traceDisplayName,
+};