wave-agent-sdk 0.17.1 → 0.17.2

package/src/prompts/index.ts

@@ -236,6 +236,7 @@ export function buildSystemPrompt(
   tools: ToolPlugin[],
   options: {
     workdir?: string;
+    originalWorkdir?: string;
     memory?: string;
     language?: string;
     isSubagent?: boolean;
@@ -283,7 +284,7 @@ export function buildSystemPrompt(
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${options.workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
+Primary working directory: ${options.originalWorkdir ?? options.workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}
@@ -310,6 +311,7 @@ Today's date: ${today}
 export function enhanceSystemPromptWithEnvDetails(
   existingSystemPrompt: string,
   workdir: string,
+  originalWorkdir?: string,
 ): string {
   const isGitRepo = isGitRepository(workdir);
   const platform = os.platform();
@@ -336,7 +338,7 @@ ${notes}
 
 Here is useful information about the environment you are running in:
 <env>
-Working directory: ${workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
+Primary working directory: ${originalWorkdir ?? workdir}${worktreeSession ? `\nThis is a git worktree — an isolated copy of the repository. Run all commands from this directory. Do NOT \`cd\` to the original repository root at ${worktreeSession.originalCwd}.` : ""}
 Is directory a git repo: ${isGitRepo}
 Platform: ${platform}
 Shell: ${shellName}

package/src/services/aiService.ts

@@ -10,6 +10,7 @@ import { OpenAIClient } from "../utils/openaiClient.js";
 import { logger } from "../utils/globalLogger.js";
 import { addOnceAbortListener } from "../utils/abortUtils.js";
 import type { GatewayConfig, ModelConfig } from "../types/index.js";
+import { ConfigurationError, CONFIG_ERRORS } from "../types/index.js";
 import {
   transformMessagesForClaudeCache,
   addCacheControlToLastTool,
@@ -27,6 +28,7 @@ import {
   WEB_CONTENT_SYSTEM_PROMPT,
   BTW_SYSTEM_PROMPT,
 } from "../prompts/index.js";
+import { GOAL_EVALUATION_SYSTEM_PROMPT } from "../constants/goalPrompts.js";
 
 /**
  * Interface for debug data saved during 400 errors
@@ -160,6 +162,11 @@ export interface CallAgentOptions {
   model?: string; // Custom model
   systemPrompt?: string; // Custom system prompt
   maxTokens?: number; // Maximum output tokens
+  toolChoice?:
+    | "auto"
+    | "none"
+    | "required"
+    | { type: "function"; function: { name: string } }; // Force tool selection
 
   // NEW: Streaming callbacks
   onContentUpdate?: (content: string) => void;
@@ -189,6 +196,27 @@ export interface CallAgentResult {
   additionalFields?: Record<string, unknown>;
 }
 
+function validateModelConfig(
+  modelConfig: ModelConfig,
+): asserts modelConfig is ModelConfig & { model: string; fastModel: string } {
+  if (!modelConfig.model) {
+    throw new ConfigurationError(CONFIG_ERRORS.MISSING_MODEL, "model", {
+      constructor: undefined,
+      environment: process.env.WAVE_MODEL,
+    });
+  }
+  if (!modelConfig.fastModel) {
+    throw new ConfigurationError(
+      CONFIG_ERRORS.MISSING_FAST_MODEL,
+      "fastModel",
+      {
+        constructor: undefined,
+        environment: process.env.WAVE_FAST_MODEL,
+      },
+    );
+  }
+}
+
 export async function callAgent(
   options: CallAgentOptions,
 ): Promise<CallAgentResult> {
@@ -206,6 +234,9 @@ export async function callAgent(
     onReasoningUpdate,
   } = options;
 
+  // Validate model config at call time
+  validateModelConfig(modelConfig);
+
   // Apply global 1 QPS rate limit
   if (
     process.env.NODE_ENV !== "test" ||
@@ -301,6 +332,11 @@ export async function callAgent(
       createParams.tools = processedTools;
     }
 
+    // Add tool_choice if specified
+    if (options.toolChoice) {
+      createParams.tool_choice = options.toolChoice;
+    }
+
     if (isStreaming) {
       // Handle streaming response
       const { data: stream, response } = await openai.chat.completions
@@ -322,7 +358,6 @@ export async function callAgent(
         onReasoningUpdate,
         abortSignal,
         responseHeaders,
-        currentModel,
       );
     } else {
       // Handle non-streaming response
@@ -350,8 +385,8 @@ export async function callAgent(
           }
         : undefined;
 
-      // Extend usage with cache metrics for Claude models
-      if (totalUsage && supportsPromptCaching(currentModel) && response.usage) {
+      // Extend usage with cache metrics (Claude top-level + OpenAI prompt_tokens_details)
+      if (totalUsage && response.usage) {
         totalUsage = extendUsageWithCacheMetrics(
           totalUsage,
           response.usage as Partial<ClaudeUsage>,
@@ -521,7 +556,6 @@ export async function callAgent(
  * @param onToolUpdate Callback for tool updates
  * @param abortSignal Optional abort signal
  * @param responseHeaders Response headers from the initial request
- * @param modelName Model name for cache control processing
  * @returns Final result with accumulated content and tool calls
  */
 async function processStreamingResponse(
@@ -537,7 +571,6 @@ async function processStreamingResponse(
   onReasoningUpdate?: (content: string) => void,
   abortSignal?: AbortSignal,
   responseHeaders?: Record<string, string>,
-  modelName?: string,
 ): Promise<CallAgentResult> {
   let accumulatedContent = "";
   let accumulatedReasoningContent = "";
@@ -569,13 +602,11 @@ async function processStreamingResponse(
           total_tokens: chunk.usage.total_tokens,
         };
 
-        // Extend usage with cache metrics for Claude models
-        if (modelName && supportsPromptCaching(modelName)) {
-          chunkUsage = extendUsageWithCacheMetrics(
-            chunkUsage,
-            chunk.usage as Partial<ClaudeUsage>,
-          );
-        }
+        // Extend usage with cache metrics (Claude top-level + OpenAI prompt_tokens_details)
+        chunkUsage = extendUsageWithCacheMetrics(
+          chunkUsage,
+          chunk.usage as Partial<ClaudeUsage>,
+        );
 
         usage = chunkUsage;
       }
@@ -775,6 +806,9 @@ export async function compactMessages(
 ): Promise<CompactMessagesResult> {
   const { gatewayConfig, modelConfig, messages, abortSignal } = options;
 
+  // Validate model config at call time
+  validateModelConfig(modelConfig);
+
   // Apply global 1 QPS rate limit
   if (
     process.env.NODE_ENV !== "test" ||
@@ -901,6 +935,9 @@ export async function processWebContent(
 ): Promise<ProcessWebContentResult> {
   const { gatewayConfig, modelConfig, content, prompt, abortSignal } = options;
 
+  // Validate model config at call time
+  validateModelConfig(modelConfig);
+
   // Apply global 1 QPS rate limit
   if (
     process.env.NODE_ENV !== "test" ||
@@ -1008,6 +1045,9 @@ export async function btw(options: BtwOptions): Promise<BtwResult> {
   const { gatewayConfig, modelConfig, messages, question, abortSignal } =
     options;
 
+  // Validate model config at call time
+  validateModelConfig(modelConfig);
+
   // Apply global 1 QPS rate limit
   if (
     process.env.NODE_ENV !== "test" ||
@@ -1092,3 +1132,117 @@ export async function btw(options: BtwOptions): Promise<BtwResult> {
     throw error;
   }
 }
+
+export interface EvaluateGoalOptions {
+  gatewayConfig: GatewayConfig;
+  modelConfig: ModelConfig;
+  model: string;
+  goalCondition: string;
+  messages: ChatCompletionMessageParam[];
+  abortSignal?: AbortSignal;
+}
+
+export interface EvaluateGoalResult {
+  content: string;
+  usage?: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+export async function evaluateGoal(
+  options: EvaluateGoalOptions,
+): Promise<EvaluateGoalResult> {
+  const {
+    gatewayConfig,
+    modelConfig,
+    model,
+    goalCondition,
+    messages,
+    abortSignal,
+  } = options;
+
+  // Create OpenAI client with injected configuration (no rate limiter — bypasses 1 QPS)
+  const openai = new OpenAIClient({
+    apiKey: gatewayConfig.apiKey,
+    baseURL: gatewayConfig.baseURL,
+    defaultHeaders: gatewayConfig.defaultHeaders,
+    fetchOptions: gatewayConfig.fetchOptions,
+    fetch: gatewayConfig.fetch,
+  });
+
+  const {
+    model: _model,
+    fastModel: _fastModel,
+    maxTokens: _maxTokens,
+    permissionMode: _permissionMode,
+    ...extraParams
+  } = modelConfig;
+  void _model;
+  void _fastModel;
+  void _maxTokens;
+  void _permissionMode;
+
+  const openaiModelConfig = getModelConfig(model, {
+    temperature: 0,
+    max_tokens: 200,
+    ...extraParams,
+  });
+
+  // Strip images from messages to reduce token usage (same as compact)
+  const cleanedMessages = messages.map((msg) => {
+    if (Array.isArray(msg.content)) {
+      const textParts = msg.content.filter(
+        (part) => part.type === "text",
+      ) as import("openai/resources.js").ChatCompletionContentPartText[];
+      const text = textParts.map((p) => p.text).join("\n");
+      return { ...msg, content: text || "(empty message)" };
+    }
+    return msg;
+  });
+
+  try {
+    const response = await openai.chat.completions.create(
+      {
+        ...openaiModelConfig,
+        messages: [
+          {
+            role: "system",
+            content: GOAL_EVALUATION_SYSTEM_PROMPT,
+          },
+          ...cleanedMessages,
+          {
+            role: "user",
+            content: `Goal condition: ${goalCondition}\n\nHas this goal been achieved based on the conversation above?`,
+          },
+        ],
+      },
+      {
+        signal: abortSignal,
+      },
+    );
+
+    const result = response.choices[0]?.message?.content?.trim();
+    if (!result) {
+      throw new Error("Goal evaluation returned empty response");
+    }
+
+    const usage = response.usage
+      ? {
+          prompt_tokens: response.usage.prompt_tokens,
+          completion_tokens: response.usage.completion_tokens,
+          total_tokens: response.usage.total_tokens,
+        }
+      : undefined;
+
+    return { content: result, usage };
+  } catch (error) {
+    if ((error as Error).name === "AbortError") {
+      logger.info("Goal evaluation was aborted");
+      throw new Error("Goal evaluation was aborted");
+    }
+    logger.error("Goal evaluation failed:", error);
+    throw error;
+  }
+}

package/src/services/configurationService.ts

@@ -33,8 +33,6 @@ import {
 import {
   GatewayConfig,
   ModelConfig,
-  ConfigurationError,
-  CONFIG_ERRORS,
   PermissionMode,
   AgentOptions,
 } from "../types/index.js";
@@ -410,7 +408,7 @@ export class ConfigurationService {
    * @param fetchOptions - Fetch options override (optional)
    * @param fetch - Custom fetch implementation override (optional)
    * @returns Resolved gateway configuration
-   * @throws ConfigurationError if required configuration is missing after fallbacks
+   * @returns Resolved model configuration (model/fastModel may be undefined if not yet configured)
    */
   resolveGatewayConfig(
     apiKey?: string,
@@ -524,25 +522,6 @@ export class ConfigurationService {
     const resolvedFastModel =
       fastModel || this.options.fastModel || process.env.WAVE_FAST_MODEL;
 
-    // Validate required fields
-    if (!resolvedAgentModel) {
-      throw new ConfigurationError(CONFIG_ERRORS.MISSING_MODEL, "model", {
-        constructor: model,
-        environment: process.env.WAVE_MODEL,
-      });
-    }
-
-    if (!resolvedFastModel) {
-      throw new ConfigurationError(
-        CONFIG_ERRORS.MISSING_FAST_MODEL,
-        "fastModel",
-        {
-          constructor: fastModel,
-          environment: process.env.WAVE_FAST_MODEL,
-        },
-      );
-    }
-
     // Resolve max output tokens
     const resolvedMaxTokens = this.resolveMaxOutputTokens(maxTokens);
 
@@ -555,6 +534,7 @@ export class ConfigurationService {
 
     // Merge model-specific settings from configuration
     const modelSpecificConfig =
+      resolvedAgentModel &&
       this.currentConfiguration?.models?.[resolvedAgentModel];
 
     if (modelSpecificConfig) {

package/src/services/hook.ts

@@ -72,6 +72,11 @@ async function buildHookJsonInput(
     jsonInput.user_prompt = context.userPrompt;
   }
 
+  // Add plan_file_path if present
+  if (context.planFilePath !== undefined) {
+    jsonInput.plan_file_path = context.planFilePath;
+  }
+
   // Add subagent_type if present
   if (context.subagentType !== undefined) {
     jsonInput.subagent_type = context.subagentType;

package/src/services/session.ts

@@ -45,6 +45,7 @@ export interface SessionMetadata {
   sessionType: "main" | "subagent";
   subagentType?: string;
   workdir: string;
+  createdAt: Date;
   lastActiveAt: Date;
   latestTotalTokens: number;
   firstMessage?: string;
@@ -53,7 +54,10 @@ export interface SessionMetadata {
 export interface SessionIndex {
   sessions: Record<
     string,
-    Omit<SessionMetadata, "id" | "lastActiveAt"> & { lastActiveAt: string }
+    Omit<SessionMetadata, "id" | "lastActiveAt" | "createdAt"> & {
+      lastActiveAt: string;
+      createdAt: string;
+    }
   >;
   lastUpdated: string;
 }
@@ -77,6 +81,27 @@ export function generateSessionId(): string {
   return `${ts}-${shortId}`;
 }
 
+/**
+ * Parse the timestamp prefix from a session ID back into a Date
+ * Format: {YYYYMMDDHHmmss}-{8hex} (e.g. 20260527143025-a1b2c3d4)
+ * @returns Date from the session ID timestamp prefix
+ */
+export function parseSessionIdTimestamp(sessionId: string): Date {
+  const match = sessionId.match(/^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/);
+  if (!match) {
+    return new Date(); // Fallback to now for legacy UUID-format session IDs
+  }
+  const [, year, month, day, hour, minute, second] = match;
+  return new Date(
+    Number(year),
+    Number(month) - 1,
+    Number(day),
+    Number(hour),
+    Number(minute),
+    Number(second),
+  );
+}
+
 /**
  * Generate filename for subagent sessions
  * @param sessionId - UUID session identifier
@@ -114,6 +139,7 @@ async function updateSessionIndex(
   const { id, ...rest } = metadata;
   index.sessions[id] = {
     ...rest,
+    createdAt: metadata.createdAt.toISOString(),
     lastActiveAt: metadata.lastActiveAt.toISOString(),
     firstMessage: metadata.firstMessage || index.sessions[id]?.firstMessage,
     parentSessionId: metadata.parentSessionId,
@@ -247,8 +273,9 @@ export async function appendMessages(
   const projectDir = await encoder.getProjectDirectory(workdir, SESSION_DIR);
   const lastMessage = newMessages[newMessages.length - 1];
 
-  // Get first message content if it's a new session or we don't have it
+  // Get first message content and createdAt from existing index
   let firstMessage: string | undefined;
+  let createdAt: Date | undefined;
   try {
     const indexPath = join(projectDir.encodedPath, SESSION_INDEX_FILENAME);
     const content = await fs.readFile(indexPath, "utf8");
@@ -257,18 +284,27 @@ export async function appendMessages(
       firstMessage =
         (await getFirstMessageContent(sessionId, workdir)) || undefined;
     }
+    if (index.sessions[sessionId]?.createdAt) {
+      createdAt = new Date(index.sessions[sessionId].createdAt);
+    }
   } catch {
     // If index doesn't exist, this might be the first message
     firstMessage =
       (await getFirstMessageContent(sessionId, workdir)) || undefined;
   }
 
+  // Derive createdAt from session ID timestamp if not in index
+  if (!createdAt) {
+    createdAt = new Date(parseSessionIdTimestamp(sessionId));
+  }
+
   await updateSessionIndex(projectDir.encodedPath, {
     id: sessionId,
     rootSessionId,
     parentSessionId,
     sessionType,
     workdir,
+    createdAt,
     lastActiveAt: new Date(lastMessage.timestamp),
     latestTotalTokens: lastMessage.usage
       ? extractLatestTotalTokens([lastMessage])
@@ -447,6 +483,7 @@ export async function listSessionsFromJsonl(
         .map(([id, meta]) => ({
           id,
           ...meta,
+          createdAt: new Date(meta.createdAt),
           lastActiveAt: new Date(meta.lastActiveAt),
         }));
 
@@ -520,6 +557,7 @@ export async function listSessionsFromJsonl(
           sessionType: "main",
           subagentType: undefined, // No longer stored in metadata
           workdir: projectDir.originalPath,
+          createdAt: new Date(parseSessionIdTimestamp(sessionId)),
           lastActiveAt,
           latestTotalTokens: lastMessage?.usage
             ? extractLatestTotalTokens([lastMessage])
@@ -558,6 +596,7 @@ export async function listSessionsFromJsonl(
         const { id, ...rest } = session;
         index.sessions[id] = {
           ...rest,
+          createdAt: session.createdAt.toISOString(),
           lastActiveAt: session.lastActiveAt.toISOString(),
         };
       }
@@ -613,6 +652,7 @@ export async function listAllSessions(): Promise<SessionMetadata[]> {
               allSessions.push({
                 id,
                 ...meta,
+                createdAt: new Date(meta.createdAt),
                 lastActiveAt,
               });
             }

package/src/tools/bashTool.ts

@@ -18,6 +18,17 @@ import {
 
 const BASH_DEFAULT_TIMEOUT_MS = 120000;
 
+// Commands that should not be auto-backgrounded on timeout (e.g. sleep should just be killed)
+const DISALLOWED_AUTO_BACKGROUND_COMMANDS = ["sleep"];
+
+function isAutobackgroundingAllowed(command: string): boolean {
+  const trimmed = command.trim();
+  // Get the first word of the command
+  const baseCommand = trimmed.split(/\s+/)[0];
+  if (!baseCommand) return true;
+  return !DISALLOWED_AUTO_BACKGROUND_COMMANDS.includes(baseCommand);
+}
+
 /**
  * Bash command execution tool - supports both foreground and background execution
  */
@@ -125,9 +136,12 @@ The working directory persists between commands. Try to maintain your current wo
     const runInBackground = args.run_in_background as boolean | undefined;
     const description = args.description as string | undefined;
     // Set default timeout: BASH_DEFAULT_TIMEOUT_MS for foreground, no timeout for background
-    const timeout =
-      (args.timeout as number | undefined) ??
-      (runInBackground ? undefined : BASH_DEFAULT_TIMEOUT_MS);
+    // When run_in_background is explicitly set, cancel any timeout — the intent is to
+    // let the process run to completion (matching Claude Code behavior where background()
+    // clears the timeout via cleanupListeners).
+    const timeout = runInBackground
+      ? undefined
+      : ((args.timeout as number | undefined) ?? BASH_DEFAULT_TIMEOUT_MS);
 
     if (!command || typeof command !== "string") {
       return {
@@ -195,7 +209,7 @@ The working directory persists between commands. Try to maintain your current wo
         };
       }
 
-      const { id: taskId } = backgroundTaskManager.startShell(command, timeout);
+      const { id: taskId } = backgroundTaskManager.startShell(command);
       const task = backgroundTaskManager.getTask(taskId);
       const outputPath = task?.outputPath;
       const backgroundMsg = [
@@ -300,12 +314,47 @@ The working directory persists between commands. Try to maintain your current wo
         });
       }
 
-      // Set up timeout
+      // Set up timeout — auto-background if allowed, otherwise kill
       let timeoutHandle: NodeJS.Timeout | undefined;
+      const shouldAutoBackground =
+        !!context.backgroundTaskManager && isAutobackgroundingAllowed(command);
       if (timeout && timeout > 0) {
         timeoutHandle = setTimeout(() => {
-          if (!isAborted) {
-            handleAbort("Command timed out");
+          if (!isAborted && !isBackgrounded) {
+            if (shouldAutoBackground) {
+              // Auto-background: move the process to background task manager instead of killing it
+              isBackgrounded = true;
+              if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+              }
+
+              // Unregister foreground task since it's now backgrounded
+              if (context.foregroundTaskManager) {
+                context.foregroundTaskManager.unregisterForegroundTask(
+                  foregroundTaskId,
+                );
+              }
+
+              const backgroundTaskManager = context.backgroundTaskManager!;
+              const taskId = backgroundTaskManager.adoptProcess(
+                child,
+                command,
+                outputBuffer,
+                errorBuffer,
+              );
+              const task = backgroundTaskManager.getTask(taskId);
+              const outputPath = task?.outputPath;
+              logger.info(
+                `[Bash] Command timed out after ${timeout}ms, auto-backgrounded as ${taskId}`,
+              );
+              resolve({
+                success: true,
+                content: `Command timed out after ${timeout / 1000} seconds and was moved to background with ID: ${taskId}.${outputPath ? ` Real-time output: ${outputPath}` : ""}`,
+                shortResult: `Process ${taskId} auto-backgrounded (timeout)`,
+              });
+            } else {
+              handleAbort("Command timed out");
+            }
           }
         }, timeout);
       }
@@ -330,8 +379,14 @@ The working directory persists between commands. Try to maintain your current wo
                 if (child.pid && !child.killed) {
                   try {
                     process.kill(-child.pid, "SIGKILL");
-                  } catch (killError) {
-                    logger.error("Failed to force kill process:", killError);
+                  } catch (killError: unknown) {
+                    // ESRCH means the process already exited — not an error
+                    if (
+                      !(killError instanceof Error) ||
+                      (killError as NodeJS.ErrnoException).code !== "ESRCH"
+                    ) {
+                      logger.error("Failed to force kill process:", killError);
+                    }
                   }
                 }
               }, 1000);

package/src/tools/readTool.ts

@@ -295,8 +295,7 @@ Usage:
         logger.warn(`File ${filePath} exists but has empty contents`);
         return {
           success: true,
-          content:
-            "⚠️ System reminder: This file exists but has empty contents.",
+          content: "System reminder: This file exists but has empty contents.",
           shortResult: "Empty file",
           metadata: {
             type: "text",