wave-agent-sdk 0.17.1 → 0.17.3

package/dist/workflow/workflowApis.js

@@ -0,0 +1,280 @@
+import * as fs from "fs";
+import * as path from "path";
+import { createStructuredOutputPrompt, createStructuredOutputTool, extractStructuredResult, } from "./structuredOutput.js";
+import { AGENT_TOOL_NAME, WORKFLOW_TOOL_NAME } from "../constants/tools.js";
+import { logger } from "../utils/globalLogger.js";
+/**
+ * Attempt to parse args if it was passed as a JSON string.
+ * LLMs may serialize array/object args as a string (e.g. "[3,8,15,42,7]")
+ * which would cause `for...of` to iterate character-by-character.
+ */
+function parseArgsIfNeeded(args) {
+    if (typeof args === "string") {
+        try {
+            const parsed = JSON.parse(args);
+            // Only accept parsed arrays/objects, not primitives like "42" → 42
+            if (typeof parsed === "object" && parsed !== null) {
+                return parsed;
+            }
+        }
+        catch {
+            // Not valid JSON — use as-is (string)
+        }
+    }
+    return args;
+}
+const MAX_TOTAL_AGENTS = 1000;
+const MAX_ITEMS_PER_CALL = 4096;
+export function createWorkflowApis(ctx) {
+    let agentCounter = ctx.initialAgentCount ?? 0;
+    const agent = async (prompt, opts) => {
+        const index = agentCounter++;
+        // Check agent limit
+        if (index >= MAX_TOTAL_AGENTS) {
+            throw new Error(`Workflow exceeded maximum agent count of ${MAX_TOTAL_AGENTS}`);
+        }
+        // Check abort
+        if (ctx.abortSignal.aborted) {
+            return null;
+        }
+        // Check budget
+        if (ctx.budgetTracker.isExceeded()) {
+            throw new Error("Workflow token budget exceeded");
+        }
+        // Check journal for cached result (resume)
+        const cached = ctx.journal.getCachedResult(index);
+        if (cached !== undefined) {
+            logger.debug(`[Workflow] agent(${index}): using cached result`);
+            return cached;
+        }
+        // Acquire concurrency slot
+        await ctx.concurrencyLimiter.acquire();
+        // Create per-agent abort controller linked to the run's signal
+        const agentController = new AbortController();
+        ctx.agentControllers.set(index, agentController);
+        // If the run is already aborted, abort this agent immediately
+        if (ctx.abortSignal.aborted) {
+            agentController.abort();
+        }
+        // Propagate run abort to agent abort
+        const onRunAbort = () => agentController.abort();
+        ctx.abortSignal.addEventListener("abort", onRunAbort);
+        try {
+            // Resolve subagent type
+            const subagentType = opts?.agentType || "general-purpose";
+            let configuration = await ctx.subagentManager.findSubagent(subagentType);
+            if (!configuration) {
+                logger.warn(`[Workflow] agent(${index}): subagent type "${subagentType}" not found, falling back to general-purpose`);
+                configuration =
+                    await ctx.subagentManager.findSubagent("general-purpose");
+                if (!configuration) {
+                    throw new Error(`No subagent type available for agent call`);
+                }
+            }
+            // Build the effective prompt
+            let effectivePrompt = prompt;
+            if (opts?.schema) {
+                effectivePrompt += createStructuredOutputPrompt(opts.schema);
+            }
+            // Set phase if specified
+            if (opts?.phase) {
+                ctx.progressReporter.setPhase(opts.phase);
+            }
+            ctx.progressReporter.agentStarted();
+            // Create subagent instance
+            const instance = await ctx.subagentManager.createInstance(configuration, {
+                description: opts?.label || `workflow-agent-${index}`,
+                prompt: effectivePrompt,
+                subagent_type: subagentType,
+                model: opts?.model,
+            });
+            // Capture subagent linkage info
+            const subagentId = instance.subagentId;
+            const transcriptPath = instance.messageManager.getTranscriptPath();
+            // If schema provided, register StructuredOutput tool on the subagent's tool manager
+            // and force the model to call it via tool_choice
+            if (opts?.schema) {
+                const structuredTool = createStructuredOutputTool(opts.schema);
+                instance.toolManager.register(structuredTool);
+                instance.aiManager.toolChoiceOverride = {
+                    type: "function",
+                    function: { name: "StructuredOutput" },
+                };
+            }
+            // Deny Agent and Workflow tools in workflow subagents
+            // (prevent infinite recursion)
+            instance.permissionManager.addTemporaryRules([
+                `${AGENT_TOOL_NAME}:deny`,
+                `${WORKFLOW_TOOL_NAME}:deny`,
+            ]);
+            // Execute agent
+            const result = await ctx.subagentManager.executeAgent(instance, effectivePrompt, agentController.signal, false);
+            // Track token usage — sum from assistant messages' usage field
+            // (getUsages() is empty because onUsageAdded targets the parent agent)
+            const messages = instance.messageManager.getMessages();
+            const tokens = messages.reduce((sum, msg) => {
+                if (msg.role !== "assistant" || !msg.usage)
+                    return sum;
+                const u = msg.usage;
+                return (sum +
+                    (u.total_tokens || 0) +
+                    (u.cache_read_input_tokens || 0) +
+                    (u.cache_creation_input_tokens || 0));
+            }, 0);
+            ctx.budgetTracker.addUsage(tokens);
+            ctx.progressReporter.agentCompleted(tokens);
+            // Extract structured result if schema was provided
+            let finalResult;
+            if (opts?.schema) {
+                const messages = instance.messageManager.getMessages();
+                // Build the format extractStructuredResult expects:
+                // Look for StructuredOutput tool calls in ToolBlocks
+                const structuredToolBlocks = messages
+                    .filter((m) => m.role === "assistant")
+                    .flatMap((m) => m.blocks)
+                    .filter((b) => b.type === "tool" &&
+                    b.name === "StructuredOutput" &&
+                    b.stage === "end");
+                if (structuredToolBlocks.length > 0) {
+                    // Parse the StructuredOutput tool call parameters
+                    const lastBlock = structuredToolBlocks[structuredToolBlocks.length - 1];
+                    try {
+                        const parsed = JSON.parse(lastBlock.parameters || "{}");
+                        finalResult = parsed;
+                    }
+                    catch {
+                        // Parameters parse failed, try result
+                        try {
+                            const parsed = JSON.parse(lastBlock.result || "null");
+                            finalResult = parsed;
+                        }
+                        catch {
+                            finalResult = result;
+                        }
+                    }
+                }
+                else {
+                    // Fallback: try extractStructuredResult with message content
+                    finalResult = extractStructuredResult(messages.map((m) => {
+                        const textBlock = m.blocks.find((b) => b.type === "text");
+                        return {
+                            role: m.role,
+                            content: textBlock?.content,
+                            tool_calls: m.tool_calls,
+                        };
+                    }), opts.schema);
+                    if (finalResult === null) {
+                        // Schema enforcement failed — return the raw text
+                        finalResult = result;
+                    }
+                }
+            }
+            else {
+                finalResult = result;
+            }
+            // Append to journal
+            ctx.journal.append({
+                agentIndex: index,
+                prompt,
+                opts: { ...opts },
+                result: finalResult,
+                tokens,
+                subagentId,
+                transcriptPath,
+            });
+            // Write agent metadata sidecar
+            try {
+                const agentMeta = {
+                    agentType: subagentType,
+                    subagentId,
+                    transcriptPath,
+                    label: opts?.label,
+                    phase: opts?.phase,
+                };
+                const metaPath = path.join(ctx.runDir, "agents", `${index}.meta.json`);
+                await fs.promises.writeFile(metaPath, JSON.stringify(agentMeta, null, 2), "utf-8");
+            }
+            catch (metaErr) {
+                logger.warn(`[Workflow] Failed to write agent meta for ${index}: ${metaErr instanceof Error ? metaErr.message : String(metaErr)}`);
+            }
+            // Cleanup
+            ctx.subagentManager.cleanupInstance(instance.subagentId);
+            return finalResult;
+        }
+        catch (error) {
+            // Agent errors are logged but don't crash the workflow
+            // Return null so the caller can filter with .filter(Boolean)
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            logger.warn(`[Workflow] agent(${index}) failed: ${errorMsg}`);
+            // Write agent_failed entry to journal for skip/retry tracking
+            ctx.journal.append({
+                type: "agent_failed",
+                agentIndex: index,
+                error: errorMsg,
+            });
+            // Emit progress event for agent failure
+            ctx.progressReporter.agentFailed(index);
+            return null;
+        }
+        finally {
+            ctx.agentControllers.delete(index);
+            ctx.abortSignal.removeEventListener("abort", onRunAbort);
+            ctx.concurrencyLimiter.release();
+        }
+    };
+    const parallel = async (thunks) => {
+        if (thunks.length > MAX_ITEMS_PER_CALL) {
+            throw new Error(`parallel() accepts at most ${MAX_ITEMS_PER_CALL} items, got ${thunks.length}`);
+        }
+        // Note: thunks typically call agent() which acquires its own slot,
+        // so parallel does NOT acquire a slot per thunk to avoid deadlock.
+        const results = await Promise.allSettled(thunks.map(async (thunk) => {
+            try {
+                return await thunk();
+            }
+            catch {
+                return null;
+            }
+        }));
+        // Convert rejected promises to null
+        return results.map((r) => (r.status === "fulfilled" ? r.value : null));
+    };
+    const pipeline = async (items, ...stages) => {
+        if (items.length > MAX_ITEMS_PER_CALL) {
+            throw new Error(`pipeline() accepts at most ${MAX_ITEMS_PER_CALL} items, got ${items.length}`);
+        }
+        // Run each item through all stages, items are independent.
+        // Note: agent() inside stages acquires its own concurrency slot,
+        // so pipeline does NOT acquire a slot per item to avoid deadlock.
+        const results = await Promise.allSettled(items.map(async (item, index) => {
+            try {
+                let result = undefined;
+                for (const stage of stages) {
+                    result = await stage(result, item, index);
+                }
+                return result;
+            }
+            catch (error) {
+                logger.warn(`[Workflow] pipeline item ${index} failed: ${error instanceof Error ? error.message : String(error)}`);
+                return null;
+            }
+        }));
+        return results.map((r) => (r.status === "fulfilled" ? r.value : null));
+    };
+    const phase = (title) => {
+        ctx.progressReporter.setPhase(title);
+    };
+    const log = (message) => {
+        ctx.journal.appendLog(message);
+        ctx.onLog?.(message);
+    };
+    return {
+        agent,
+        parallel,
+        pipeline,
+        phase,
+        log,
+        args: parseArgsIfNeeded(ctx.args),
+        budget: ctx.budgetTracker.toBudgetInfo(),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave-agent-sdk",
-  "version": "0.17.1",
+  "version": "0.17.3",
   "description": "SDK for building AI-powered development tools and agents",
   "keywords": [
     "ai",

package/src/agent.ts

@@ -8,6 +8,7 @@ import { McpManager } from "./managers/mcpManager.js";
 import { LspManager } from "./managers/lspManager.js";
 import { BangManager } from "./managers/bangManager.js";
 import { CronManager } from "./managers/cronManager.js";
+import { GoalManager } from "./managers/goalManager.js";
 import { BackgroundTaskManager } from "./managers/backgroundTaskManager.js";
 import { NotificationQueue } from "./managers/notificationQueue.js";
 import { MessageQueue, type QueuedMessage } from "./managers/messageQueue.js";
@@ -71,6 +72,7 @@ export class Agent {
   private pluginManager: PluginManager; // Add plugin manager instance
   private skillManager: SkillManager; // Add skill manager instance
   private cronManager: CronManager; // Add cron manager instance
+  private goalManager: GoalManager; // Add goal manager instance
   private hookManager: HookManager; // Add hooks manager instance
   private reversionManager: ReversionManager;
   private notificationQueue: NotificationQueue; // Add notification queue instance
@@ -202,6 +204,7 @@ export class Agent {
     this.pluginManager = this.container.get("PluginManager")!;
     this.bangManager = this.container.get("BangManager")!;
     this.cronManager = this.container.get("CronManager")!;
+    this.goalManager = this.container.get("GoalManager")!;
     this.notificationQueue = this.container.get("NotificationQueue")!;
     this.messageQueue = this.container.get("MessageQueue")!;
 
@@ -229,39 +232,33 @@ export class Agent {
     });
 
     // Wire up message queue to process when agent becomes idle
-    this.messageQueue.onMessageEnqueued = () => {
-      // If the AI is NOT loading and command is not running, trigger dequeue
-      if (!this.aiManager.isLoading && !this.isCommandRunning) {
-        this.processQueuedMessage().catch((error) => {
-          this.logger?.error("Failed to process queued message:", error);
-        });
-      }
-    };
+    this.messageQueue.onMessageEnqueued = () => this.tryDequeue();
 
     // Wire up AI loading changes to process queue when AI becomes idle
     this.aiManager.onLoadingChange = (loading: boolean) => {
-      if (!loading && !this.isCommandRunning) {
-        this.processQueuedMessage().catch((error) => {
-          this.logger?.error("Failed to process queued message:", error);
-        });
-      }
+      if (!loading) this.tryDequeue();
     };
 
     // Wire up bang manager callback for command running changes
     this.bangManager.onCommandRunningChange = (running: boolean) => {
       this.options.callbacks?.onCommandRunningChange?.(running);
-      // When command stops and AI is idle, process queue
-      if (!running && !this.aiManager.isLoading) {
-        this.processQueuedMessage().catch((error) => {
-          this.logger?.error("Failed to process queued message:", error);
-        });
-      }
+      if (!running) this.tryDequeue();
     };
 
     // Set initial permission mode if provided
     if (options.permissionMode) {
       this.setPermissionMode(options.permissionMode);
     }
+
+    // Wire up goal state change callback
+    this.goalManager.setOnGoalStateChange((active, condition, elapsed) => {
+      this.options.callbacks?.onGoalStateChange?.(active, condition, elapsed);
+    });
+
+    // Wire up goal evaluating callback
+    this.goalManager.setOnGoalEvaluating((evaluating) => {
+      this.options.callbacks?.onGoalEvaluating?.(evaluating);
+    });
   }
 
   // Public getter methods
@@ -343,6 +340,16 @@ export class Agent {
     return this.messageQueue.getQueue();
   }
 
+  /** Get goal status string */
+  public get goalStatus(): string {
+    return this.goalManager.getStatusString();
+  }
+
+  /** Check if a goal is active */
+  public get isGoalActive(): boolean {
+    return this.goalManager.isGoalActive();
+  }
+
   /**
    * Remove a queued message by index
    * @param index - The index of the message to remove
@@ -356,14 +363,60 @@ export class Agent {
     return removed;
   }
 
+  /**
+   * Recall the last editable queued message (for inline editing)
+   * @returns The recalled message, or null if no editable message exists
+   */
+  public recallQueuedMessage(): QueuedMessage | null {
+    const msg = this.messageQueue.popLastEditable();
+    if (msg) {
+      this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+    }
+    return msg;
+  }
+
+  /**
+   * Remove a queued message by its ID
+   * @param id - The ID of the message to remove
+   * @returns true if the message was removed, false if not found
+   */
+  public removeQueuedMessageById(id: string): boolean {
+    const removed = this.messageQueue.removeById(id);
+    if (removed) {
+      this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+    }
+    return removed;
+  }
+
+  /**
+   * Unified dequeue trigger — checks state machine before processing.
+   * Called from onMessageEnqueued, onLoadingChange(false), and
+   * onCommandRunningChange(false).
+   */
+  private tryDequeue(): void {
+    if (this.messageQueue.state !== "idle") return;
+    if (!this.messageQueue.hasPending()) return;
+    if (this.aiManager.isLoading || this.isCommandRunning) return;
+
+    this.messageQueue.transitionTo("dispatching");
+    this.processQueuedMessage()
+      .catch((error) => {
+        this.logger?.error("Failed to process queued message:", error);
+      })
+      .finally(() => {
+        this.messageQueue.transitionTo("idle");
+        this.tryDequeue(); // Re-check after processing
+      });
+  }
+
   /**
    * Process the next queued message when the agent becomes idle.
-   * Dequeues the next message and handles it based on type.
    */
   private async processQueuedMessage(): Promise<void> {
     const next = this.messageQueue.dequeue();
     if (!next) return;
 
+    this.messageQueue.transitionTo("running");
     this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
 
     if (next.type === "bang") {
@@ -414,6 +467,40 @@ export class Agent {
     return this.backgroundTaskManager.stopTask(id);
   }
 
+  /** Get all workflow runs */
+  public async getWorkflowRuns(): Promise<
+    import("./workflow/types.js").WorkflowRun[]
+  > {
+    if (!this.container.has("WorkflowManager")) return [];
+    return this.container
+      .get<
+        import("./managers/workflowManager.js").WorkflowManager
+      >("WorkflowManager")!
+      .listRuns();
+  }
+
+  /** Get a specific workflow run by ID */
+  public getWorkflowRun(
+    runId: string,
+  ): import("./workflow/types.js").WorkflowRun | undefined {
+    if (!this.container.has("WorkflowManager")) return undefined;
+    return this.container
+      .get<
+        import("./managers/workflowManager.js").WorkflowManager
+      >("WorkflowManager")!
+      .getRun(runId);
+  }
+
+  /** Stop a workflow run */
+  public stopWorkflowRun(runId: string): void {
+    if (!this.container.has("WorkflowManager")) return;
+    this.container
+      .get<
+        import("./managers/workflowManager.js").WorkflowManager
+      >("WorkflowManager")!
+      .stopRun(runId);
+  }
+
   /**
    * Static async factory method for creating Agent instances
    *
@@ -518,12 +605,18 @@ export class Agent {
     });
 
     // Log session_start event
-    const modelConfig = this.getModelConfig();
-    logOTelEvent("session_start", {
-      sessionId: this.messageManager.getSessionId(),
-      model: modelConfig.model,
-      workdir: this.workdir,
-    }).catch(() => {}); // Non-blocking
+    try {
+      const modelConfig = this.getModelConfig();
+      if (modelConfig.model) {
+        logOTelEvent("session_start", {
+          sessionId: this.messageManager.getSessionId(),
+          model: modelConfig.model,
+          workdir: this.workdir,
+        }).catch(() => {}); // Non-blocking
+      }
+    } catch {
+      // Model not configured yet - will be available after SSO login
+    }
   }
 
   /**
@@ -597,10 +690,13 @@ export class Agent {
 
   /** Unified interrupt method, interrupts both AI messages and command execution */
   public abortMessage(): void {
-    // Clear queue first to prevent processQueuedMessage from dequeuing
-    // when abortAIMessage triggers onLoadingChange(false)
-    this.messageQueue.clear();
-    this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+    if (this.aiManager.isLoading || this.isCommandRunning) {
+      // Clear queue first to prevent processQueuedMessage from dequeuing
+      // when abortAIMessage triggers onLoadingChange(false)
+      this.messageQueue.clear();
+      this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+    }
+    this.messageQueue.transitionTo("idle"); // Reset state on abort
     this.abortAIMessage(); // This will abort tools including Agent tool (subagents)
     this.abortBashCommand();
     this.abortSlashCommand();
@@ -796,11 +892,25 @@ export class Agent {
     content: string,
     images?: Array<{ path: string; mimeType: string }>,
   ): Promise<void> {
-    // If the agent is busy, enqueue the message
+    // If the agent is busy, enqueue the message — unless it's an immediate
+    // slash command (e.g., /goal clear, /clear, /compact) that should execute
+    // right away even while AI is processing
     if (this.aiManager.isLoading || this.isCommandRunning) {
-      this.messageQueue.enqueue({ content, images });
-      this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
-      return;
+      const trimmed = content.trim();
+      const isImmediate =
+        trimmed.startsWith("/") &&
+        trimmed !== "/" &&
+        this.slashCommandManager.isImmediateCommand(trimmed);
+
+      if (!isImmediate) {
+        this.messageQueue.enqueue({
+          content,
+          images,
+        });
+        this.options.callbacks?.onQueuedMessagesChange?.(this.queuedMessages);
+        return;
+      }
+      // Immediate slash command: fall through to InteractionService
     }
 
     await InteractionService.sendMessage(

package/src/constants/goalPrompts.ts

@@ -0,0 +1,10 @@
+export const GOAL_EVALUATION_SYSTEM_PROMPT = `You are a goal evaluator. Given a goal condition and a conversation, determine whether the goal has been achieved.
+
+Rules:
+- Judge ONLY based on what the conversation shows — tool outputs, test results, file contents, etc.
+- Do NOT assume work is done without evidence in the conversation.
+- Be strict and conservative: when uncertain, return met: false.
+- Be concise: your reason should be 1-2 sentences.
+
+Respond with JSON only, no other text:
+{"met": boolean, "reason": "short explanation"}`;

package/src/constants/tools.ts

@@ -21,3 +21,4 @@ export const CRON_LIST_TOOL_NAME = "CronList";
 export const WEB_FETCH_TOOL_NAME = "WebFetch";
 export const ENTER_WORKTREE_TOOL_NAME = "EnterWorktree";
 export const EXIT_WORKTREE_TOOL_NAME = "ExitWorktree";
+export const WORKFLOW_TOOL_NAME = "Workflow";