wave-agent-sdk 1.0.4 → 1.0.6

package/src/workflow/structuredOutput.ts

@@ -1,123 +0,0 @@
-import type { ToolPlugin, ToolResult } from "../tools/types.js";
-
-const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
-
-/**
- * Creates a system prompt addition that instructs the agent to use structured output
- */
-export function createStructuredOutputPrompt(schema: object): string {
-  return `\n\nIMPORTANT: You MUST call the ${STRUCTURED_OUTPUT_TOOL_NAME} tool with your final answer. Do not just write the answer as text — call the tool with a JSON object matching this schema:\n${JSON.stringify(schema, null, 2)}\n\nCall this tool exactly once with your complete answer.`;
-}
-
-/**
- * Creates a StructuredOutput ToolPlugin that enforces the given schema
- */
-export function createStructuredOutputTool(schema: object): ToolPlugin {
-  return {
-    name: STRUCTURED_OUTPUT_TOOL_NAME,
-    config: {
-      type: "function" as const,
-      function: {
-        name: STRUCTURED_OUTPUT_TOOL_NAME,
-        description:
-          "Output structured data matching the required schema. Call this with your final answer.",
-        parameters: schema as Record<string, unknown>,
-      },
-    },
-    execute: async (args: Record<string, unknown>): Promise<ToolResult> => {
-      // The tool just returns the args as-is — the real validation happens
-      // in extractStructuredResult after the agent completes
-      return {
-        success: true,
-        content: JSON.stringify(args),
-      };
-    },
-  };
-}
-
-/**
- * Extract structured result from a completed subagent's messages.
- * Looks for StructuredOutput tool calls in the messages.
- * Falls back to JSON.parse on the last assistant message text.
- */
-export function extractStructuredResult(
-  messages: Array<{
-    role: string;
-    content?: string;
-    tool_calls?: Array<{ function: { name: string; arguments: string } }>;
-  }>,
-  schema: object,
-): unknown | null {
-  // Search messages in reverse for a StructuredOutput tool call
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (msg.tool_calls) {
-      for (const tc of msg.tool_calls) {
-        if (tc.function.name === STRUCTURED_OUTPUT_TOOL_NAME) {
-          try {
-            const parsed = JSON.parse(tc.function.arguments);
-            if (validateAgainstSchema(parsed, schema)) {
-              return parsed;
-            }
-          } catch {
-            // Parse error — continue searching
-          }
-        }
-      }
-    }
-  }
-
-  // Fallback: try to extract JSON from the last assistant message
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (msg.role === "assistant" && msg.content) {
-      // Try to find JSON in the content
-      const jsonMatch = msg.content.match(/```json\n([\s\S]*?)\n```/);
-      if (jsonMatch) {
-        try {
-          const parsed = JSON.parse(jsonMatch[1]);
-          if (validateAgainstSchema(parsed, schema)) {
-            return parsed;
-          }
-        } catch {
-          // Parse error — continue
-        }
-      }
-
-      // Try parsing the entire content as JSON
-      try {
-        const parsed = JSON.parse(msg.content);
-        if (validateAgainstSchema(parsed, schema)) {
-          return parsed;
-        }
-      } catch {
-        // Not JSON — continue
-      }
-    }
-  }
-
-  return null;
-}
-
-/**
- * Basic schema validation — checks that required fields exist.
- * This is intentionally lightweight; full JSON Schema validation
- * would require a dependency like ajv.
- */
-function validateAgainstSchema(data: unknown, schema: object): boolean {
-  if (!data || typeof data !== "object") return false;
-  const schemaObj = schema as {
-    properties?: Record<string, unknown>;
-    required?: string[];
-  };
-  if (schemaObj.required && Array.isArray(schemaObj.required)) {
-    for (const field of schemaObj.required) {
-      if (!(field in (data as Record<string, unknown>))) {
-        return false;
-      }
-    }
-  }
-  return true;
-}
-
-export { STRUCTURED_OUTPUT_TOOL_NAME };

package/src/workflow/types.ts

@@ -1,101 +0,0 @@
-export interface WorkflowMetaPhase {
-  title: string;
-  detail?: string;
-  model?: string;
-}
-
-export interface WorkflowMeta {
-  name: string;
-  description: string;
-  whenToUse?: string;
-  phases?: WorkflowMetaPhase[];
-}
-
-export interface WorkflowPhaseState {
-  title: string;
-  agentCount: number;
-  tokens: number;
-  elapsed: number;
-  startTime: number;
-}
-
-export interface WorkflowRun {
-  runId: string;
-  meta: WorkflowMeta;
-  status: "running" | "paused" | "completed" | "failed" | "aborted";
-  scriptPath: string;
-  args?: unknown;
-  startTime: number;
-  endTime?: number;
-  phases: WorkflowPhaseState[];
-  totalAgents: number;
-  totalTokens: number;
-  result?: unknown;
-  error?: string;
-  /** Resolves when the background execution finishes (completed/failed/aborted) */
-  completionPromise?: Promise<void>;
-  /** If set, this run resumes from a previous run's journal */
-  resumeFromRunId?: string;
-  /** Index of the agent that caused the workflow to fail */
-  failedAgentIndex?: number;
-  /** Error message from the failed agent */
-  failedAgentError?: string;
-}
-
-/**
- * Serializable workflow run for stdio transport, with the non-serializable
- * `completionPromise` stripped. Returned by the `getWorkflowRuns` RPC.
- */
-export type SerializableWorkflowRun = Omit<WorkflowRun, "completionPromise">;
-
-export interface JournalEntry {
-  agentIndex: number;
-  prompt: string;
-  opts: Record<string, unknown>;
-  result: unknown;
-  tokens: number;
-  /** Subagent instance ID for linking to the full conversation transcript */
-  subagentId?: string;
-  /** Path to the subagent's transcript JSONL file */
-  transcriptPath?: string;
-}
-
-export interface AgentMeta {
-  agentType: string;
-  subagentId: string;
-  transcriptPath: string;
-  label?: string;
-  phase?: string;
-}
-
-export interface LogEntry {
-  type: "log";
-  message: string;
-}
-
-export interface AgentFailedEntry {
-  type: "agent_failed";
-  agentIndex: number;
-  error: string;
-}
-
-export type JournalLine = JournalEntry | LogEntry | AgentFailedEntry;
-
-export interface BudgetInfo {
-  total: number | null;
-  spent: () => number;
-  remaining: () => number;
-}
-
-export interface WorkflowProgressEvent {
-  type:
-    | "phase_started"
-    | "phase_completed"
-    | "agent_started"
-    | "agent_completed"
-    | "agent_failed";
-  runId: string;
-  phaseIndex: number;
-  agentIndex?: number;
-  timestamp: number;
-}

package/src/workflow/workflowApis.ts

@@ -1,410 +0,0 @@
-import type { SubagentManager } from "../managers/subagentManager.js";
-import * as fs from "fs";
-import * as path from "path";
-import { ConcurrencyLimiter } from "./concurrencyLimiter.js";
-import { BudgetTracker } from "./budgetTracker.js";
-import { ProgressReporter } from "./progressReporter.js";
-import { Journal } from "./journal.js";
-import type { BudgetInfo, AgentMeta } from "./types.js";
-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: unknown): unknown {
-  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;
-
-interface WorkflowApiContext {
-  subagentManager: SubagentManager;
-  concurrencyLimiter: ConcurrencyLimiter;
-  budgetTracker: BudgetTracker;
-  progressReporter: ProgressReporter;
-  journal: Journal;
-  abortSignal: AbortSignal;
-  args: unknown;
-  onLog?: (message: string) => void;
-  /** When resuming, offset the agent counter by this many existing entries */
-  initialAgentCount?: number;
-  /** Session directory for computing transcript paths */
-  sessionDir: string;
-  /** Per-run directory for writing agent metadata sidecars */
-  runDir: string;
-  /** Per-agent abort controllers for kill/skip support */
-  agentControllers: Map<number, AbortController>;
-}
-
-interface AgentOpts {
-  label?: string;
-  phase?: string;
-  schema?: object;
-  model?: string;
-  isolation?: string;
-  agentType?: string;
-}
-
-export interface WorkflowApis {
-  agent: (prompt: string, opts?: AgentOpts) => Promise<unknown>;
-  parallel: (thunks: Array<() => Promise<unknown>>) => Promise<unknown[]>;
-  pipeline: (
-    items: unknown[],
-    ...stages: Array<
-      (prev: unknown, item: unknown, index: number) => Promise<unknown>
-    >
-  ) => Promise<unknown[]>;
-  phase: (title: string) => void;
-  log: (message: string) => void;
-  args: unknown;
-  budget: BudgetInfo;
-}
-
-export function createWorkflowApis(ctx: WorkflowApiContext): WorkflowApis {
-  let agentCounter = ctx.initialAgentCount ?? 0;
-
-  const agent = async (prompt: string, opts?: AgentOpts): Promise<unknown> => {
-    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: unknown;
-      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 is import("../types/messaging.js").ToolBlock =>
-              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 is import("../types/messaging.js").TextBlock =>
-                  b.type === "text",
-              );
-              return {
-                role: m.role,
-                content: textBlock?.content,
-                tool_calls: (
-                  m as unknown as {
-                    tool_calls?: Array<{
-                      function: { name: string; arguments: string };
-                    }>;
-                  }
-                ).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 } as Record<string, unknown>,
-        result: finalResult,
-        tokens,
-        subagentId,
-        transcriptPath,
-      });
-
-      // Write agent metadata sidecar
-      try {
-        const agentMeta: 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: Array<() => Promise<unknown>>,
-  ): Promise<unknown[]> => {
-    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: unknown[],
-    ...stages: Array<
-      (prev: unknown, item: unknown, index: number) => Promise<unknown>
-    >
-  ): Promise<unknown[]> => {
-    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: unknown = 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: string): void => {
-    ctx.progressReporter.setPhase(title);
-  };
-
-  const log = (message: string): void => {
-    ctx.journal.appendLog(message);
-    ctx.onLog?.(message);
-  };
-
-  return {
-    agent,
-    parallel,
-    pipeline,
-    phase,
-    log,
-    args: parseArgsIfNeeded(ctx.args),
-    budget: ctx.budgetTracker.toBudgetInfo(),
-  };
-}