wave-agent-sdk 1.0.4 → 1.0.6

package/src/telemetry/sessionTracing.ts

@@ -1,348 +0,0 @@
-/**
- * Session Tracing -- OpenTelemetry Span Management
- *
- * Provides span creation/ending APIs for interactions, LLM requests, and tool
- * executions. Uses two independent AsyncLocalStorage contexts:
- * - interactionContext: holds the interaction span for the entire turn
- * - toolContext: holds the current tool span (cleared on end)
- *
- * LLM request spans do not enter any ALS; they are passed explicitly to
- * endLLMRequestSpan, aligning with Claude Code's approach.
- */
-
-import { AsyncLocalStorage } from "node:async_hooks";
-import { createHash } from "node:crypto";
-import type { Span } from "@opentelemetry/api";
-import {
-  getOTELApi,
-  isInitialized,
-  getCurrentConfig,
-} from "./instrumentation.js";
-import { logOTelEvent } from "./events.js";
-import type {
-  LLMRequestMetadata,
-  LLMRequestInput,
-  ToolMetadata,
-} from "../types/telemetry.js";
-
-// -- Constants --
-
-/** Max content length for span attributes (60KB, aligning with Claude Code) */
-const MAX_CONTENT_LENGTH = 60000;
-
-// -- AsyncLocalStorage for context propagation --
-
-const interactionContext = new AsyncLocalStorage<Span | undefined>();
-const toolContext = new AsyncLocalStorage<Span | undefined>();
-
-// -- Incremental tracking state (module-level, per session) --
-
-/** Number of messages already reported in new_context; only deltas are sent */
-let lastReportedMessageCount = 0;
-/** Set of system prompt hashes already emitted via logOTelEvent */
-const seenSystemPromptHashes = new Set<string>();
-/** Set of tool schema hashes already emitted via logOTelEvent */
-const seenToolSchemaHashes = new Set<string>();
-
-// -- Helpers --
-
-/** Computes SHA-256 hash of content, returns first 12 hex characters */
-function hashContent(content: string): string {
-  return createHash("sha256").update(content).digest("hex").substring(0, 12);
-}
-
-/** Truncates content to MAX_CONTENT_LENGTH, returns [truncated, originalLength] */
-function truncateContent(content: string): [string, number] {
-  const originalLength = content.length;
-  if (originalLength > MAX_CONTENT_LENGTH) {
-    return [content.substring(0, MAX_CONTENT_LENGTH), originalLength];
-  }
-  return [content, originalLength];
-}
-
-// -- Tracer accessor --
-
-function getTracer() {
-  if (!isInitialized()) return undefined;
-  const otelApi = getOTELApi();
-  if (!otelApi) return undefined;
-  return otelApi.trace.getTracer("wave");
-}
-
-// -- Public API --
-
-/**
- * Creates an interaction span for a user turn.
- * The span is stored in interactionContext for the duration of the turn.
- */
-export function startInteractionSpan(
-  userPrompt: string,
-  sequence: number,
-): Span | undefined {
-  const tracer = getTracer();
-  if (!tracer) return undefined;
-
-  const config = getCurrentConfig();
-  const attributes: Record<string, string | number> = {
-    "span.type": "interaction",
-    user_prompt_length: userPrompt.length,
-    "interaction.sequence": sequence,
-  };
-  if (config?.logUserPrompts) {
-    attributes.user_prompt = userPrompt;
-  }
-
-  const span = tracer.startSpan("interaction", { attributes });
-  interactionContext.enterWith(span);
-  return span;
-}
-
-/**
- * Ends the current interaction span and clears the context.
- */
-export function endInteractionSpan(): void {
-  const span = interactionContext.getStore();
-  if (!span) return;
-  span.end();
-  interactionContext.enterWith(undefined);
-}
-
-/**
- * Resets incremental tracing state. Should be called after compaction to
- * prevent incorrect delta calculations.
- */
-export function resetTracingState(): void {
-  lastReportedMessageCount = 0;
-  seenSystemPromptHashes.clear();
-  seenToolSchemaHashes.clear();
-}
-
-/**
- * Creates an LLM request span as a child of the interaction span.
- * Does NOT enter any ALS — the span must be passed explicitly to endLLMRequestSpan.
- *
- * When logToolContent is enabled, captures:
- * - system_prompt_hash / system_prompt_preview / system_prompt_length
- * - new_context (incremental messages delta)
- * - tools (JSON array of {name, hash}) / tools_count
- */
-export function startLLMRequestSpan(
-  model: string,
-  options?: LLMRequestInput,
-): Span | undefined {
-  const tracer = getTracer();
-  if (!tracer) return undefined;
-
-  const attributes: Record<string, string | number | boolean> = {
-    "span.type": "llm_request",
-    model,
-  };
-  if (options?.context) {
-    attributes["llm_request.context"] = options.context;
-  }
-
-  const config = getCurrentConfig();
-
-  // Content capture gated by logToolContent
-  if (config?.logToolContent) {
-    // System prompt: hash + preview + length
-    if (options?.systemPrompt) {
-      const hash = hashContent(options.systemPrompt);
-      attributes.system_prompt_hash = hash;
-      attributes.system_prompt_length = options.systemPrompt.length;
-      const preview =
-        options.systemPrompt.length > 500
-          ? options.systemPrompt.substring(0, 500)
-          : options.systemPrompt;
-      attributes.system_prompt_preview = preview;
-
-      // Emit full system prompt via event only once per hash
-      if (!seenSystemPromptHashes.has(hash)) {
-        seenSystemPromptHashes.add(hash);
-        logOTelEvent("system_prompt", {
-          system_prompt_hash: hash,
-          system_prompt: options.systemPrompt,
-        }).catch(() => {});
-      }
-    }
-
-    // Incremental input messages: only send new messages since last report
-    if (options?.inputMessages && options.inputMessages.length > 0) {
-      const totalCount = options.inputMessages.length;
-      const deltaCount = totalCount - lastReportedMessageCount;
-      if (deltaCount > 0) {
-        const newMessages = options.inputMessages.slice(
-          lastReportedMessageCount,
-        );
-        const newContextStr = JSON.stringify(newMessages);
-        const [truncated, originalLength] = truncateContent(newContextStr);
-        attributes.new_context = truncated;
-        attributes.new_context_message_count = deltaCount;
-        if (originalLength > MAX_CONTENT_LENGTH) {
-          attributes.new_context_truncated = true;
-          attributes.new_context_original_length = originalLength;
-        }
-      }
-      lastReportedMessageCount = totalCount;
-    }
-
-    // Tool schemas: hash per tool + count
-    if (options?.toolsSchema) {
-      try {
-        const tools = JSON.parse(options.toolsSchema);
-        if (Array.isArray(tools)) {
-          const toolHashes = tools.map(
-            (tool: { function?: { name?: string } }) => {
-              const name = tool.function?.name || "unknown";
-              const toolStr = JSON.stringify(tool);
-              const hash = hashContent(toolStr);
-              return { name, hash };
-            },
-          );
-          attributes.tools = JSON.stringify(toolHashes);
-          attributes.tools_count = toolHashes.length;
-
-          // Emit full tool schema via event only once per hash
-          for (const { name, hash } of toolHashes) {
-            if (!seenToolSchemaHashes.has(hash)) {
-              seenToolSchemaHashes.add(hash);
-              const fullTool = tools.find(
-                (t: { function?: { name?: string } }) =>
-                  t.function?.name === name,
-              );
-              if (fullTool) {
-                logOTelEvent("tool_schema", {
-                  tool_name: name,
-                  tool_hash: hash,
-                  tool_schema: JSON.stringify(fullTool),
-                }).catch(() => {});
-              }
-            }
-          }
-        }
-      } catch {
-        // toolsSchema is not valid JSON — skip
-      }
-    }
-  }
-
-  const parent = interactionContext.getStore();
-  let span: Span;
-  if (parent) {
-    const otelApi = getOTELApi()!;
-    const ctx = otelApi.trace.setSpan(otelApi.context.active(), parent);
-    span = tracer.startSpan("llm.request", { attributes }, ctx);
-  } else {
-    span = tracer.startSpan("llm.request", { attributes });
-  }
-  return span;
-}
-
-/**
- * Ends an LLM request span with response metadata.
- * The span is passed explicitly — no ALS is read or modified.
- *
- * When logToolContent is enabled, captures response.model_output.
- */
-export function endLLMRequestSpan(
-  span: Span | undefined,
-  metadata: LLMRequestMetadata,
-): void {
-  if (!span) return;
-
-  if (metadata.inputTokens != null)
-    span.setAttribute("input_tokens", metadata.inputTokens);
-  if (metadata.outputTokens != null)
-    span.setAttribute("output_tokens", metadata.outputTokens);
-  if (metadata.cacheReadTokens != null)
-    span.setAttribute("cache_read_tokens", metadata.cacheReadTokens);
-  if (metadata.cacheCreationTokens != null)
-    span.setAttribute("cache_creation_tokens", metadata.cacheCreationTokens);
-  if (metadata.ttftMs != null) span.setAttribute("ttft_ms", metadata.ttftMs);
-  if (metadata.ttltMs != null) span.setAttribute("ttlt_ms", metadata.ttltMs);
-  span.setAttribute("success", metadata.success);
-  if (metadata.error) span.setAttribute("error", metadata.error);
-  if (metadata.hasToolCall != null)
-    span.setAttribute("has_tool_call", metadata.hasToolCall);
-
-  // Content capture gated by logToolContent
-  const config = getCurrentConfig();
-  if (config?.logToolContent && metadata.modelOutput) {
-    const [truncated, originalLength] = truncateContent(metadata.modelOutput);
-    span.setAttribute("response.model_output", truncated);
-    if (originalLength > MAX_CONTENT_LENGTH) {
-      span.setAttribute("response.model_output_truncated", true);
-      span.setAttribute(
-        "response.model_output_original_length",
-        originalLength,
-      );
-    }
-  }
-
-  span.end();
-}
-
-/**
- * Creates a tool execution span as a child of the interaction span.
- * Enters toolContext with the new span.
- */
-export function startToolSpan(
-  toolName: string,
-  input?: unknown,
-): Span | undefined {
-  const tracer = getTracer();
-  if (!tracer) return undefined;
-
-  const config = getCurrentConfig();
-  const attributes: Record<string, string | number | boolean> = {
-    "span.type": "tool",
-    tool_name: toolName,
-  };
-  if (config?.logToolContent && input !== undefined) {
-    const inputStr = typeof input === "string" ? input : JSON.stringify(input);
-    const [truncated, originalLength] = truncateContent(inputStr);
-    attributes.tool_input = truncated;
-    if (originalLength > MAX_CONTENT_LENGTH) {
-      attributes.tool_input_truncated = true;
-      attributes.tool_input_original_length = originalLength;
-    }
-  }
-
-  const parent = interactionContext.getStore();
-  let span: Span;
-  if (parent) {
-    const otelApi = getOTELApi()!;
-    const ctx = otelApi.trace.setSpan(otelApi.context.active(), parent);
-    span = tracer.startSpan(`tool.${toolName}`, { attributes }, ctx);
-  } else {
-    span = tracer.startSpan(`tool.${toolName}`, { attributes });
-  }
-  toolContext.enterWith(span);
-  return span;
-}
-
-/**
- * Ends the current tool span with execution metadata.
- * Reads the span from toolContext, then clears it.
- */
-export function endToolSpan(metadata: ToolMetadata): void {
-  const span = toolContext.getStore();
-  if (!span) return;
-
-  span.setAttribute("success", metadata.success);
-  if (metadata.error) span.setAttribute("error", metadata.error);
-  span.setAttribute("duration_ms", metadata.durationMs);
-
-  const config = getCurrentConfig();
-  if (config?.logToolContent && metadata.output) {
-    const [truncated, originalLength] = truncateContent(metadata.output);
-    span.setAttribute("tool_output", truncated);
-    if (originalLength > MAX_CONTENT_LENGTH) {
-      span.setAttribute("tool_output_truncated", true);
-      span.setAttribute("tool_output_original_length", originalLength);
-    }
-  }
-
-  span.end();
-  toolContext.enterWith(undefined);
-}

package/src/tools/agentTool.ts

@@ -1,322 +0,0 @@
-import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
-import { EXPLORE_SUBAGENT_TYPE } from "../constants/subagents.js";
-import { AGENT_TOOL_NAME } from "../constants/tools.js";
-import type { SubagentConfiguration } from "../utils/subagentParser.js";
-import {
-  countToolBlocks,
-  formatToolTokenSummary,
-} from "../utils/messageOperations.js";
-
-/**
- * Agent tool plugin for launching specialized agents to handle complex tasks
- */
-export const agentTool: ToolPlugin = {
-  name: AGENT_TOOL_NAME,
-  config: {
-    type: "function" as const,
-    function: {
-      name: AGENT_TOOL_NAME,
-      description:
-        "Launch a new agent to handle complex, multi-step tasks autonomously.",
-      parameters: {
-        type: "object",
-        properties: {
-          description: {
-            type: "string",
-            description: "A short (3-5 word) description of the task",
-          },
-          prompt: {
-            type: "string",
-            description: "The task for the agent to perform",
-          },
-          subagent_type: {
-            type: "string",
-            description: "The type of specialized agent to use for this task",
-          },
-          run_in_background: {
-            type: "boolean",
-            description:
-              "Set to true to run this command in the background. Use Read to read the output later.",
-          },
-        },
-        required: ["description", "prompt", "subagent_type"],
-      },
-    },
-  },
-
-  prompt: (args?: { availableSubagents?: SubagentConfiguration[] }) => {
-    const subagentList = args?.availableSubagents
-      ? args.availableSubagents
-          .map((config) => {
-            let toolsStr = "";
-            if (config.tools && config.tools.length > 0) {
-              toolsStr = ` (Tools: ${config.tools.join(", ")})`;
-            } else {
-              toolsStr = " (Tools: *)";
-            }
-
-            return `- ${config.name}: ${config.description}${toolsStr}`;
-          })
-          .join("\n")
-      : "";
-
-    return `Launch a new agent to handle complex, multi-step tasks autonomously.
-
-The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
-
-Available agent types and the tools they have access to:
-${subagentList || "No agents configured"}
-
-When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use from the list above. Choose the agent whose description best matches the task you want to delegate.
-
-- When doing file search, prefer to use the ${AGENT_TOOL_NAME} tool in order to reduce context usage.
-- You should proactively use the ${AGENT_TOOL_NAME} tool with specialized agents when the task at hand matches the agent's description.
-- VERY IMPORTANT: When exploring the codebase to gather context or to answer a question that is not a needle query for a specific file/class/function, it is CRITICAL that you use the ${AGENT_TOOL_NAME} tool with subagent_type=${EXPLORE_SUBAGENT_TYPE} instead of running search commands directly.
-- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
-- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
-- **Don't peek.** The tool result includes an output file path — do not Read or tail it unless the user explicitly asks for a progress check. You get a completion notification; trust it. Reading the transcript mid-flight pulls the agent's tool noise into your context, which defeats the point of backgrounding.
-- **Don't race.** After launching, you know nothing about what the agent found. Never fabricate or predict agent results in any format — not as prose, summary, or structured output. The notification arrives as a user-role message in a later turn; it is never something you write yourself. If the user asks a follow-up before the notification lands, tell them the agent is still running — give status, not a guess.`;
-  },
-
-  execute: async (
-    args: Record<string, unknown>,
-    context: ToolContext,
-  ): Promise<ToolResult> => {
-    const subagentManager = context.subagentManager;
-    if (!subagentManager) {
-      return {
-        success: false,
-        content: "",
-        error: "Subagent manager not available in tool context",
-        shortResult: "Agent delegation failed",
-      };
-    }
-
-    // Input validation
-    const description = args.description as string;
-    const prompt = args.prompt as string;
-    const subagent_type = args.subagent_type as string;
-    const run_in_background = args.run_in_background as boolean;
-
-    if (!description || typeof description !== "string") {
-      return {
-        success: false,
-        content: "",
-        error: "description parameter is required and must be a string",
-        shortResult: "Agent delegation failed",
-      };
-    }
-
-    if (!prompt || typeof prompt !== "string") {
-      return {
-        success: false,
-        content: "",
-        error: "prompt parameter is required and must be a string",
-        shortResult: "Agent delegation failed",
-      };
-    }
-
-    if (!subagent_type || typeof subagent_type !== "string") {
-      return {
-        success: false,
-        content: "",
-        error: "subagent_type parameter is required and must be a string",
-        shortResult: "Agent delegation failed",
-      };
-    }
-
-    try {
-      // Subagent selection logic with explicit name matching only
-      const configuration = await subagentManager.findSubagent(subagent_type);
-
-      if (!configuration) {
-        // Error handling for nonexistent subagents with available subagents listing
-        const allConfigs = subagentManager.getConfigurations();
-        const availableNames = allConfigs.map((c) => c.name).join(", ");
-
-        return {
-          success: false,
-          content: "",
-          error: `No agent found matching "${subagent_type}". Available agents: ${availableNames || "none"}`,
-          shortResult: "Agent not found",
-        };
-      }
-
-      let isBackgrounded = false;
-
-      // Create subagent instance and execute agent
-      const instance = await subagentManager.createInstance(
-        configuration,
-        {
-          description,
-          prompt,
-          subagent_type,
-        },
-        run_in_background,
-        () => {
-          // Do not update shortResult if it is running in background
-          if (run_in_background || isBackgrounded) return;
-
-          const messages = instance.messageManager.getMessages();
-          const tokens = instance.messageManager.getLatestTotalTokens();
-          const usedTools = instance.usedTools;
-
-          const toolCount = countToolBlocks(messages);
-          const summary = formatToolTokenSummary(toolCount, tokens);
-
-          const getDisplayParam = (t: {
-            name: string;
-            parameters: string;
-            compactParams?: string;
-            stage?: string;
-          }) => {
-            if (
-              (t.stage === "end" || t.stage === "running") &&
-              t.compactParams
-            ) {
-              return t.compactParams;
-            }
-            const flat = t.parameters.replace(/\n/g, "\\n");
-            return flat.length > 30 ? `…${flat.slice(-30)}` : flat;
-          };
-
-          let shortResult = "";
-          if (toolCount > 2) {
-            shortResult += "... ";
-          }
-          shortResult += summary;
-          if (usedTools.length > 0) {
-            shortResult +=
-              "\n" +
-              usedTools
-                .map((t) => `${t.name} ${getDisplayParam(t)}`)
-                .join("\n");
-          }
-
-          context.onShortResultUpdate?.(shortResult);
-        },
-      );
-
-      return new Promise<ToolResult>((resolve) => {
-        (async () => {
-          // Register for backgrounding if not already in background
-          if (!run_in_background && context.foregroundTaskManager) {
-            context.foregroundTaskManager.registerForegroundTask({
-              id: instance.subagentId,
-              backgroundHandler: async () => {
-                isBackgrounded = true;
-                const taskId = await subagentManager.backgroundInstance(
-                  instance.subagentId,
-                );
-                const task = context.backgroundTaskManager?.getTask(taskId);
-                const outputPath = task?.outputPath;
-                resolve({
-                  success: true,
-                  content: `Agent backgrounded with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
-                  shortResult: "Agent backgrounded",
-                  isManuallyBackgrounded: true,
-                });
-              },
-            });
-          }
-
-          try {
-            const result = await subagentManager.executeAgent(
-              instance,
-              prompt,
-              context.abortSignal,
-              run_in_background,
-            );
-
-            if (isBackgrounded) {
-              return;
-            }
-
-            if (run_in_background) {
-              const task = context.backgroundTaskManager?.getTask(result);
-              const outputPath = task?.outputPath;
-              const backgroundMsg = [
-                `Agent started in background with ID: ${result}.`,
-                `The agent is working in the background. You will be notified automatically when it completes.`,
-                `Do not duplicate this agent's work — avoid working with the same files or topics it is using.`,
-                outputPath
-                  ? `output_file: ${outputPath}`
-                  : `Briefly tell the user what you launched and end your response.`,
-              ].join("\n");
-              resolve({
-                success: true,
-                content: backgroundMsg,
-                shortResult: `Agent started in background: ${result}${outputPath ? ` → ${outputPath}` : ""}`,
-              });
-              return;
-            }
-
-            // Cleanup subagent instance after agent completion
-            subagentManager.cleanupInstance(instance.subagentId);
-
-            const messages = instance.messageManager.getMessages();
-            const tokens = instance.messageManager.getLatestTotalTokens();
-            const toolCount = countToolBlocks(messages);
-            const summary = formatToolTokenSummary(toolCount, tokens);
-
-            resolve({
-              success: true,
-              content: result,
-              shortResult: `Agent completed${summary ? ` ${summary}` : ""}`,
-            });
-          } catch (error) {
-            if (!isBackgrounded) {
-              // Extract content from the subagent's last assistant message.
-              // aiManager.sendAIMessage() catch block already added an error
-              // block via addErrorBlock(), so the error info is in the message
-              // history — just return it directly.
-              let content = "";
-              try {
-                const messages = instance.messageManager.getMessages();
-                const lastAssistant = messages
-                  .filter((m) => m.role === "assistant")
-                  .pop();
-                if (lastAssistant) {
-                  content = lastAssistant.blocks
-                    .filter((b) => b.type === "text" || b.type === "error")
-                    .map((b) => (b as { content: string }).content)
-                    .join("\n")
-                    .trim();
-                }
-              } catch {
-                // Ignore errors when extracting messages
-              }
-
-              const errorMsg = `Agent delegation failed: ${error instanceof Error ? error.message : String(error)}`;
-              resolve({
-                success: false,
-                content: content || errorMsg,
-                error: errorMsg,
-                shortResult: "Delegation error",
-              });
-            }
-          } finally {
-            if (!run_in_background && context.foregroundTaskManager) {
-              context.foregroundTaskManager.unregisterForegroundTask(
-                instance.subagentId,
-              );
-            }
-          }
-        })();
-      });
-    } catch (error) {
-      return {
-        success: false,
-        content: "",
-        error: `Agent delegation failed: ${error instanceof Error ? error.message : String(error)}`,
-        shortResult: "Delegation error",
-      };
-    }
-  },
-
-  formatCompactParams: (params: Record<string, unknown>) => {
-    const subagent_type = params.subagent_type as string;
-    const description = params.description as string;
-    return `${subagent_type || "unknown"}: ${description || "no description"}`;
-  },
-};