wave-agent-sdk 0.18.6 → 0.18.7

package/src/telemetry/sessionTracing.ts

@@ -2,7 +2,12 @@
  * 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";
@@ -16,12 +21,8 @@ import type { LLMRequestMetadata, ToolMetadata } from "../types/telemetry.js";
 
 // -- AsyncLocalStorage for context propagation --
 
-const spanContext = new AsyncLocalStorage<Span>();
-
-// -- LIFO stacks for nested span tracking --
-
-const llmSpans: Span[] = [];
-const toolSpans: Span[] = [];
+const interactionContext = new AsyncLocalStorage<Span | undefined>();
+const toolContext = new AsyncLocalStorage<Span | undefined>();
 
 // -- Tracer accessor --
 
@@ -32,37 +33,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,25 +55,33 @@ 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);
 }
 
 /**
- * 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.
  */
 export function startLLMRequestSpan(
   model: string,
   options?: { context?: string },
 ): Span | undefined {
+  const tracer = getTracer();
+  if (!tracer) return undefined;
+
   const attributes: Record<string, string> = {
     "span.type": "llm_request",
     model,
@@ -99,18 +90,26 @@ export function startLLMRequestSpan(
     attributes["llm_request.context"] = options.context;
   }
 
-  const span = startChildSpan("llm.request", attributes);
-  if (span) {
-    llmSpans.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("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.
  */
-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)
@@ -129,19 +128,19 @@ export function endLLMRequestSpan(metadata: LLMRequestMetadata): void {
     span.setAttribute("has_tool_call", metadata.hasToolCall);
 
   span.end();
-
-  if (llmSpans.length > 0) {
-    spanContext.enterWith(llmSpans[llmSpans.length - 1]);
-  }
 }
 
 /**
- * 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> = {
     "span.type": "tool",
@@ -155,42 +154,40 @@ export function startToolSpan(
     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) {
+    let outputStr = metadata.output;
+    if (outputStr.length > 1000) {
+      outputStr = outputStr.substring(0, 1000);
+    }
+    span.setAttribute("tool_output", outputStr);
   }
-}
 
-/**
- * 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/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/telemetry.ts

@@ -68,6 +68,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 */

package/src/utils/fileUtils.ts

@@ -1,8 +1,6 @@
 import fs from "node:fs/promises";
 import { createReadStream } from "node:fs";
 import path from "node:path";
-import { execSync } from "node:child_process";
-import { homedir } from "node:os";
 import { glob } from "glob";
 
 /**
@@ -156,50 +154,6 @@ export async function getLastLine(
   }
 }
 
-/**
- * Ensures that a pattern is present in the global git ignore file.
- *
- * @param {string} pattern - The pattern to add to global git ignore.
- */
-export async function ensureGlobalGitIgnore(pattern: string): Promise<void> {
-  try {
-    let globalIgnorePath: string;
-    try {
-      globalIgnorePath = execSync("git config --get core.excludesfile", {
-        encoding: "utf8",
-      }).trim();
-    } catch {
-      // If not set, use default paths
-      const xdgConfigHome =
-        process.env.XDG_CONFIG_HOME || path.join(homedir(), ".config");
-      globalIgnorePath = path.join(xdgConfigHome, "git", "ignore");
-    }
-
-    if (!globalIgnorePath) return;
-
-    // Ensure directory exists
-    await fs.mkdir(path.dirname(globalIgnorePath), { recursive: true });
-
-    let content = "";
-    try {
-      content = await fs.readFile(globalIgnorePath, "utf8");
-    } catch {
-      // File doesn't exist
-    }
-
-    const lines = content.split("\n").map((line) => line.trim());
-    if (!lines.includes(pattern)) {
-      const newContent =
-        content.endsWith("\n") || content === ""
-          ? `${content}${pattern}\n`
-          : `${content}\n${pattern}\n`;
-      await fs.writeFile(globalIgnorePath, newContent, "utf8");
-    }
-  } catch {
-    // Ignore errors
-  }
-}
-
 /**
  * Simple Levenshtein distance implementation
  */

package/src/utils/gitUtils.ts

@@ -222,6 +222,60 @@ export function getDefaultRemoteBranch(cwd: string): string {
   return "main";
 }
 
+/**
+ * Module-level set tracking git dirs already processed in this process,
+ * to avoid redundant I/O.
+ */
+const excludedGitDirs = new Set<string>();
+
+/**
+ * Ensure that Wave runtime files are excluded from git status by writing
+ * patterns to `.git/info/exclude` (per-repo, not global).
+ *
+ * Idempotent: if the marker `# wave-runtime` is already present in the
+ * exclude file, it skips writing. A module-level Set provides additional
+ * per-process dedup to avoid redundant file reads.
+ *
+ * @param cwd Working directory to start searching from
+ */
+export function ensureWaveRuntimeFilesExcluded(cwd: string): void {
+  try {
+    const gitDir = resolveGitDir(cwd);
+    if (!gitDir) return;
+
+    if (excludedGitDirs.has(gitDir)) return;
+
+    const excludePath = path.join(gitDir, "info", "exclude");
+    let content = "";
+    try {
+      content = fsSync.readFileSync(excludePath, "utf8");
+    } catch {
+      // File doesn't exist yet
+    }
+
+    const marker = "# wave-runtime";
+    if (content.includes(marker)) {
+      excludedGitDirs.add(gitDir);
+      return;
+    }
+
+    const block = [
+      marker,
+      "**/.wave/scheduled_tasks.lock",
+      "**/.wave/scheduled_tasks.json",
+      "**/.wave/worktrees/",
+      "**/.wave/settings.local.json",
+      "",
+    ].join("\n");
+
+    fsSync.mkdirSync(path.join(gitDir, "info"), { recursive: true });
+    fsSync.appendFileSync(excludePath, block);
+    excludedGitDirs.add(gitDir);
+  } catch {
+    // Best-effort: ignore all errors
+  }
+}
+
 /**
  * Check if there are uncommitted changes in the working directory
  * @param cwd Working directory

package/src/utils/groupMessagesByApiRound.ts

@@ -1,4 +1,5 @@
 import type { Message } from "../types/index.js";
+import { estimateTokens as estimateStrTokens } from "./tokenEstimate.js";
 
 export interface ApiRound {
   messages: Message[];
@@ -95,26 +96,26 @@ export function getLastApiRounds(
 }
 
 /**
- * Roughly estimate token count from character count (~4 chars per token).
+ * Estimate token count from message blocks using CJK-aware estimation.
  */
 function estimateTokens(messages: Message[]): number {
-  let chars = 0;
+  let combined = "";
   for (const msg of messages) {
     for (const block of msg.blocks) {
       if ("content" in block && typeof block.content === "string") {
-        chars += block.content.length;
+        combined += block.content;
       }
       if (
         block.type === "tool" &&
         block.parameters &&
         typeof block.parameters === "string"
       ) {
-        chars += block.parameters.length;
+        combined += block.parameters;
       }
       if (block.type === "tool" && block.result) {
-        chars += block.result.length;
+        combined += block.result;
       }
     }
   }
-  return Math.ceil(chars / 4);
+  return estimateStrTokens(combined);
 }

package/src/utils/tokenEstimate.ts

@@ -0,0 +1,34 @@
+/**
+ * CJK-aware token estimation without external dependencies.
+ *
+ * The naive `length / 4` heuristic under-estimates CJK text by ~4x because
+ * each Chinese/Japanese/Korean character is typically 1-2 tokens, not 0.25.
+ * This function separates CJK characters from other text and applies
+ * different ratios:
+ *
+ * - CJK characters: 1 char ≈ 1 token
+ * - Other characters: 4 chars ≈ 1 token (2 for JSON/JSONL/JSONC)
+ *
+ * The estimate intentionally leans high for CJK (safe direction for limit
+ * checks — better to reject than to let oversized content through).
+ */
+
+// CJK Unified Ideographs + Extension A + Hiragana + Katakana + Hangul Syllables
+const CJK_REGEX =
+  /[\u4e00-\u9fff\u3400-\u4dbf\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g;
+
+/**
+ * Estimate token count for a string, with CJK-awareness.
+ *
+ * @param content - The text content to estimate
+ * @param ext - File extension (without dot), e.g. "ts", "json". JSON/JSONL/JSONC
+ *              files use a tighter ratio (2 chars/token) for non-CJK text.
+ * @returns Estimated token count
+ */
+export function estimateTokens(content: string, ext?: string): number {
+  const cjkCount = (content.match(CJK_REGEX) || []).length;
+  const otherCount = content.length - cjkCount;
+  const bytesPerToken =
+    ext === "json" || ext === "jsonl" || ext === "jsonc" ? 2 : 4;
+  return Math.ceil(cjkCount + otherCount / bytesPerToken);
+}

package/src/utils/worktreeUtils.ts

@@ -6,7 +6,11 @@
 import { execFileSync } from "node:child_process";
 import * as path from "node:path";
 import * as fs from "node:fs";
-import { getGitMainRepoRoot, getDefaultRemoteBranch } from "./gitUtils.js";
+import {
+  getGitMainRepoRoot,
+  getDefaultRemoteBranch,
+  ensureWaveRuntimeFilesExcluded,
+} from "./gitUtils.js";
 import { logger } from "./globalLogger.js";
 
 export interface WorktreeInfo {
@@ -105,6 +109,9 @@ export function createWorktree(name: string, cwd: string): WorktreeInfo {
   const branchName = `worktree-${name}`;
   const baseBranch = getDefaultRemoteBranch(cwd);
 
+  // Ensure Wave runtime files are git-excluded in this repo
+  ensureWaveRuntimeFilesExcluded(cwd);
+
   // Ensure parent directory exists
   const parentDir = path.dirname(worktreePath);
   if (!fs.existsSync(parentDir)) {