wave-agent-sdk 0.18.6 → 0.19.0

package/src/telemetry/sessionTracing.ts

@@ -2,26 +2,63 @@
  * Session Tracing -- OpenTelemetry Span Management
  *
  * Provides span creation/ending APIs for interactions, LLM requests, and tool
- * executions with AsyncLocalStorage context propagation and stale span cleanup.
+ * 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 type { LLMRequestMetadata, ToolMetadata } from "../types/telemetry.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 spanContext = new AsyncLocalStorage<Span>();
+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>();
 
-// -- LIFO stacks for nested span tracking --
+// -- Helpers --
 
-const llmSpans: Span[] = [];
-const toolSpans: Span[] = [];
+/** 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 --
 
@@ -32,37 +69,19 @@ function getTracer() {
   return otelApi.trace.getTracer("wave");
 }
 
-// -- Helper: create child span with parent context --
-
-function startChildSpan(
-  name: string,
-  attributes: Record<string, string | number>,
-): Span | undefined {
-  const tracer = getTracer();
-  if (!tracer) return undefined;
-
-  const parent = spanContext.getStore();
-  let span: Span;
-  if (parent) {
-    const otelApi = getOTELApi()!;
-    const ctx = otelApi.trace.setSpan(otelApi.context.active(), parent);
-    span = tracer.startSpan(name, { attributes }, ctx);
-  } else {
-    span = tracer.startSpan(name, { attributes });
-  }
-  spanContext.enterWith(span);
-  return span;
-}
-
 // -- 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",
@@ -72,26 +91,49 @@ export function startInteractionSpan(
   if (config?.logUserPrompts) {
     attributes.user_prompt = userPrompt;
   }
-  return startChildSpan("interaction", attributes);
+
+  const span = tracer.startSpan("interaction", { attributes });
+  interactionContext.enterWith(span);
+  return span;
 }
 
 /**
- * Ends the current active interaction span.
+ * Ends the current interaction span and clears the context.
  */
 export function endInteractionSpan(): void {
-  const span = spanContext.getStore();
+  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 current active span.
+ * 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?: { context?: string },
+  options?: LLMRequestInput,
 ): Span | undefined {
-  const attributes: Record<string, string> = {
+  const tracer = getTracer();
+  if (!tracer) return undefined;
+
+  const attributes: Record<string, string | number | boolean> = {
     "span.type": "llm_request",
     model,
   };
@@ -99,18 +141,113 @@ export function startLLMRequestSpan(
     attributes["llm_request.context"] = options.context;
   }
 
-  const span = startChildSpan("llm.request", attributes);
-  if (span) {
-    llmSpans.push(span);
+  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 the most recent LLM request span with response metadata.
+ * 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(metadata: LLMRequestMetadata): void {
-  const span = llmSpans.pop();
+export function endLLMRequestSpan(
+  span: Span | undefined,
+  metadata: LLMRequestMetadata,
+): void {
   if (!span) return;
 
   if (metadata.inputTokens != null)
@@ -128,69 +265,84 @@ export function endLLMRequestSpan(metadata: LLMRequestMetadata): void {
   if (metadata.hasToolCall != null)
     span.setAttribute("has_tool_call", metadata.hasToolCall);
 
-  span.end();
-
-  if (llmSpans.length > 0) {
-    spanContext.enterWith(llmSpans[llmSpans.length - 1]);
+  // 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 current active span.
+ * 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> = {
+  const attributes: Record<string, string | number | boolean> = {
     "span.type": "tool",
     tool_name: toolName,
   };
   if (config?.logToolContent && input !== undefined) {
-    let inputStr = typeof input === "string" ? input : JSON.stringify(input);
-    if (inputStr.length > 1000) {
-      inputStr = inputStr.substring(0, 1000);
+    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;
     }
-    attributes.tool_input = inputStr;
   }
 
-  const span = startChildSpan(`tool.${toolName}`, attributes);
-  if (span) {
-    toolSpans.push(span);
+  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 a tool span with execution metadata.
+ * Ends the current tool span with execution metadata.
+ * Reads the span from toolContext, then clears it.
  */
 export function endToolSpan(metadata: ToolMetadata): void {
-  const span = toolSpans.pop();
+  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);
 
-  span.end();
-
-  if (toolSpans.length > 0) {
-    spanContext.enterWith(toolSpans[toolSpans.length - 1]);
+  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);
+    }
   }
-}
-
-/**
- * Returns the current active span from ALS context.
- */
-export function getActiveInteractionSpan(): Span | undefined {
-  return spanContext.getStore();
-}
 
-/**
- * Executes `fn` with `span` as the active context via ALS.
- * Useful for parallel tool calls that each need their own span context.
- */
-export function withSpanContext<T>(span: Span, fn: () => T): T {
-  return spanContext.run(span, fn);
+  span.end();
+  toolContext.enterWith(undefined);
 }

package/src/tools/bashTool.ts

@@ -20,6 +20,25 @@ import {
 
 const BASH_DEFAULT_TIMEOUT_MS = 120000;
 
+/**
+ * Wrap a user command so we can append CWD tracking (`&& pwd -P`) without the
+ * appended part being affected by trailing here-docs, unbalanced quotes, or
+ * multi-line syntax in the user command.
+ *
+ * The command is single-quoted (with embedded single quotes escaped via the
+ * classic `'"'"'` sequence) and run through `eval`. Because the entire user
+ * command becomes a single literal argument to `eval`, any here-doc inside it
+ * only opens/closes during eval's own second parse pass and cannot leak out to
+ * clobber the trailing `&& pwd -P`. Works on sh/dash/bash and Git Bash.
+ */
+function wrapCommandForCwdTracking(
+  command: string,
+  cwdFileForBash: string,
+): string {
+  const escaped = command.replace(/'/g, `'"'"'`);
+  return `eval '${escaped}' && pwd -P >| ${cwdFileForBash}`;
+}
+
 // Commands that should not be auto-backgrounded on timeout (e.g. sleep should just be killed)
 const DISALLOWED_AUTO_BACKGROUND_COMMANDS = ["sleep"];
 
@@ -248,7 +267,10 @@ The working directory persists between commands. Try to maintain your current wo
         `wave_cwd_${Date.now()}_${Math.random().toString(36).substring(2, 11)}.tmp`,
       );
       const tempCwdFileForBash = toPosixPath(tempCwdFile);
-      const wrappedCommand = `${command} && pwd -P >| ${tempCwdFileForBash}`;
+      const wrappedCommand = wrapCommandForCwdTracking(
+        command,
+        tempCwdFileForBash,
+      );
 
       const child: ChildProcess = spawn(wrappedCommand, {
         shell: shellPath || true,

package/src/tools/readTool.ts

@@ -5,6 +5,7 @@ import { logger } from "../utils/globalLogger.js";
 import type { ToolPlugin, ToolResult, ToolContext } from "./types.js";
 import { resolvePath, getDisplayPath } from "../utils/path.js";
 import { formatLineNumberPrefix } from "../utils/stringUtils.js";
+import { estimateTokens } from "../utils/tokenEstimate.js";
 import {
   isBinaryDocument,
   getBinaryDocumentError,
@@ -267,14 +268,11 @@ Usage:
         }
       }
 
-      // Resource Limits
+      // Resource Limits — align with Claude Code: 256KB default, bypassed only
+      // when the caller provides an explicit line limit (not offset alone).
       const maxSizeBytes =
-        context.fileReadingLimits?.maxSizeBytes ?? 1024 * 1024; // Default 1MB
-      if (
-        stats.size > maxSizeBytes &&
-        typeof offset !== "number" &&
-        typeof limit !== "number"
-      ) {
+        context.fileReadingLimits?.maxSizeBytes ?? 0.25 * 1024 * 1024; // Default 256KB
+      if (stats.size > maxSizeBytes && typeof limit !== "number") {
         return {
           success: false,
           content: "",
@@ -357,11 +355,7 @@ Usage:
       // Token-level validation: estimate tokens and reject if over limit
       const maxTokens = context.fileReadingLimits?.maxTokens ?? 25000; // Default 25000 tokens
       const ext = extname(actualFilePath).toLowerCase().slice(1);
-      const bytesPerToken =
-        ext === "json" || ext === "jsonl" || ext === "jsonc" ? 2 : 4;
-      const estimatedTokens = Math.ceil(
-        formattedContent.length / bytesPerToken,
-      );
+      const estimatedTokens = estimateTokens(formattedContent, ext);
       if (estimatedTokens > maxTokens) {
         return {
           success: false,

package/src/types/config.ts

@@ -14,11 +14,19 @@ export interface GatewayConfig {
   fetch?: OpenAI["fetch"];
 }
 
+export interface ModelCapabilities {
+  /** Whether the model supports image/vision input. Default: true. */
+  vision?: boolean;
+  /** Whether the model supports prompt caching (ephemeral cache_control markers). Default: false. */
+  promptCaching?: boolean;
+}
+
 export interface ModelConfig {
   model?: string;
   fastModel?: string;
   maxTokens?: number;
   permissionMode?: PermissionMode;
   fastModelConfig?: Record<string, unknown>;
+  capabilities?: ModelCapabilities;
   [key: string]: unknown;
 }

package/src/types/hooks.ts

@@ -188,6 +188,7 @@ export interface HookJsonInput {
   user_prompt?: string; // Present for UserPromptSubmit only
   subagent_type?: string; // Present when hook is executed by a subagent
   name?: string; // Present for WorktreeCreate events
+  worktree_path?: string; // Present for WorktreeRemove events
   old_cwd?: string; // Present for CwdChanged events
   new_cwd?: string; // Present for CwdChanged events
   source?: SessionStartSource; // Present for SessionStart events

package/src/types/messaging.ts

@@ -89,7 +89,6 @@ export interface BangBlock {
 export interface CompactBlock {
   type: "compact";
   content: string;
-  sessionId: string;
 }
 
 export interface ReasoningBlock {

package/src/types/skills.ts

@@ -74,6 +74,7 @@ export interface SkillToolArgs {
 export interface SkillManagerOptions {
   personalSkillsPath?: string;
   personalClaudeSkillsPath?: string;
+  personalAgentsSkillsPath?: string;
   scanTimeout?: number;
   workdir?: string;
   watch?: boolean;

package/src/types/telemetry.ts

@@ -58,6 +58,20 @@ export interface LLMRequestMetadata {
   error?: string;
   /** Response included tool calls */
   hasToolCall?: boolean;
+  /** Model text output (recorded when logToolContent is true) */
+  modelOutput?: string;
+}
+
+/** Input context for an LLM request span (content capture gated by logToolContent) */
+export interface LLMRequestInput {
+  /** Scope context */
+  context?: "interaction" | "standalone";
+  /** System prompt string (when available) */
+  systemPrompt?: string;
+  /** Messages array sent to the API */
+  inputMessages?: unknown[];
+  /** Tool schemas JSON string */
+  toolsSchema?: string;
 }
 
 /** Metadata for tool execution spans */
@@ -68,6 +82,8 @@ export interface ToolMetadata {
   error?: string;
   /** Execution time (ms) */
   durationMs: number;
+  /** Tool output content (recorded when logToolContent is true) */
+  output?: string;
 }
 
 /** Event names for OTel structured logging */
@@ -77,4 +93,6 @@ export type OTelEventName =
   | "user_prompt"
   | "tool_decision"
   | "compaction"
-  | "error";
+  | "error"
+  | "system_prompt"
+  | "tool_schema";

package/src/utils/atomicWrite.ts

@@ -0,0 +1,61 @@
+/**
+ * Atomic file write utilities.
+ *
+ * Writes data to a temporary file first, then renames it to the target path.
+ * This prevents readers from observing a partially-written (truncated) file,
+ * which is critical for config files that may be read concurrently.
+ *
+ * Temp file naming: `${targetPath}.tmp.${process.pid}.${randomUUID()}`
+ * — avoids collisions when multiple processes write the same file.
+ */
+import { writeFileSync, renameSync, unlinkSync, promises as fsp } from "fs";
+import { randomUUID } from "crypto";
+
+function tmpPathFor(targetPath: string): string {
+  return `${targetPath}.tmp.${process.pid}.${randomUUID()}`;
+}
+
+/**
+ * Atomically write `data` to `filePath` (async).
+ *
+ * Writes to a temp file then renames it into place. On any failure the temp
+ * file is removed and the error is re-thrown so callers can handle it.
+ */
+export async function atomicWriteFile(
+  filePath: string,
+  data: string,
+): Promise<void> {
+  const tmpPath = tmpPathFor(filePath);
+  try {
+    await fsp.writeFile(tmpPath, data, "utf-8");
+    await fsp.rename(tmpPath, filePath);
+  } catch (error) {
+    try {
+      await fsp.unlink(tmpPath);
+    } catch {
+      // Ignore cleanup errors — the original error is more important
+    }
+    throw error;
+  }
+}
+
+/**
+ * Atomically write `data` to `filePath` (sync).
+ *
+ * Sync variant for callers that cannot await. Same temp-file-then-rename
+ * strategy as {@link atomicWriteFile}.
+ */
+export function atomicWriteFileSync(filePath: string, data: string): void {
+  const tmpPath = tmpPathFor(filePath);
+  try {
+    writeFileSync(tmpPath, data, "utf-8");
+    renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // Ignore cleanup errors — the original error is more important
+    }
+    throw error;
+  }
+}