@stigmer/runner 3.0.1

package/src/workflow-engine/__tests__/task-status-accumulator.test.ts

@@ -0,0 +1,373 @@
+import { describe, it, expect } from "vitest";
+import {
+  TaskStatusAccumulator,
+  truncatePayload,
+} from "../task-status-accumulator.js";
+
+describe("TaskStatusAccumulator", () => {
+  describe("taskStarted", () => {
+    it("records task name, kind, status, startedAt, and taskId", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("myTask", "call:http");
+      const [entry] = acc.toArray();
+      expect(entry.taskName).toBe("myTask");
+      expect(entry.taskKind).toBe("call:http");
+      expect(entry.status).toBe("started");
+      expect(entry.startedAt).toBeDefined();
+      expect(entry.taskId).toBe("myTask:1");
+    });
+  });
+
+  describe("taskStartedWithInput", () => {
+    it("records input alongside start fields", () => {
+      const acc = new TaskStatusAccumulator();
+      const input = { url: "https://example.com", method: "GET" };
+      acc.taskStartedWithInput("httpTask", "call:http", input);
+      const [entry] = acc.toArray();
+      expect(entry.taskName).toBe("httpTask");
+      expect(entry.status).toBe("started");
+      expect(entry.input).toEqual(input);
+    });
+
+    it("truncates large inputs", () => {
+      const acc = new TaskStatusAccumulator();
+      const largeInput = { data: "x".repeat(100_000) };
+      acc.taskStartedWithInput("bigTask", "call:agent", largeInput);
+      const [entry] = acc.toArray();
+      expect((entry.input as Record<string, unknown>)._truncated).toBe(true);
+    });
+  });
+
+  describe("taskCompleted", () => {
+    it("preserves startedAt from taskStarted and records completedAt", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "set");
+      const startedAt = acc.toArray()[0].startedAt;
+      acc.taskCompleted("t1", 150);
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("completed");
+      expect(entry.startedAt).toBe(startedAt);
+      expect(entry.completedAt).toBeDefined();
+      expect(entry.durationMs).toBe(150);
+    });
+  });
+
+  describe("taskCompletedWithResult", () => {
+    it("stores output and cost info", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("llmTask", "call:function:llm");
+      const output = { result: "hello", input_tokens: 50, output_tokens: 20 };
+      acc.taskCompletedWithResult("llmTask", 200, output, {
+        costMicros: 1500,
+        inputTokens: 50,
+        outputTokens: 20,
+      });
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("completed");
+      expect(entry.output).toEqual(output);
+      expect(entry.costMicros).toBe(1500);
+      expect(entry.inputTokens).toBe(50);
+      expect(entry.outputTokens).toBe(20);
+      expect(entry.durationMs).toBe(200);
+    });
+
+    it("preserves input from taskStartedWithInput", () => {
+      const acc = new TaskStatusAccumulator();
+      const input = { prompt: "test" };
+      acc.taskStartedWithInput("t1", "call:function:llm", input);
+      acc.taskCompletedWithResult("t1", 100, { result: "ok" }, {
+        costMicros: 0,
+        inputTokens: 10,
+        outputTokens: 5,
+      });
+      const [entry] = acc.toArray();
+      expect(entry.input).toEqual(input);
+      expect(entry.output).toEqual({ result: "ok" });
+    });
+
+    it("handles undefined cost gracefully", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "set");
+      acc.taskCompletedWithResult("t1", 50, { greeting: "hi" });
+      const [entry] = acc.toArray();
+      expect(entry.costMicros).toBeUndefined();
+      expect(entry.inputTokens).toBeUndefined();
+      expect(entry.outputTokens).toBeUndefined();
+      expect(entry.output).toEqual({ greeting: "hi" });
+    });
+  });
+
+  describe("taskFailed", () => {
+    it("records error and preserves startedAt", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStartedWithInput("t1", "call:http", { url: "bad" });
+      acc.taskFailed("t1", "connection timeout");
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("failed");
+      expect(entry.error).toBe("connection timeout");
+      expect(entry.input).toEqual({ url: "bad" });
+    });
+  });
+
+  describe("setTaskMetadata", () => {
+    it("adds metadata to an existing entry", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("agentTask", "call:agent");
+      acc.setTaskMetadata("agentTask", { agent_execution_id: "exec-123" });
+      const [entry] = acc.toArray();
+      expect(entry.metadata).toEqual({ agent_execution_id: "exec-123" });
+    });
+
+    it("merges with existing metadata", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "call:agent");
+      acc.setTaskMetadata("t1", { agent_execution_id: "e1" });
+      acc.setTaskMetadata("t1", { tool_call_count: 3 });
+      const [entry] = acc.toArray();
+      expect(entry.metadata).toEqual({
+        agent_execution_id: "e1",
+        tool_call_count: 3,
+      });
+    });
+
+    it("is a no-op for unknown task names", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.setTaskMetadata("nonexistent", { key: "val" });
+      expect(acc.toArray()).toHaveLength(0);
+    });
+  });
+
+  describe("toArray", () => {
+    it("returns entries in insertion order", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("a", "set");
+      acc.taskStarted("b", "call:http");
+      acc.taskStarted("c", "switch");
+      const names = acc.toArray().map(e => e.taskName);
+      expect(names).toEqual(["a", "b", "c"]);
+    });
+  });
+
+  describe("taskId generation", () => {
+    it("generates taskId as taskName:attemptNumber for first attempt", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("validate", "call:http");
+      expect(acc.toArray()[0].taskId).toBe("validate:1");
+    });
+
+    it("increments attempt on repeated taskStarted calls for the same task", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("flaky", "call:http");
+      expect(acc.toArray()[0].taskId).toBe("flaky:1");
+
+      acc.taskStarted("flaky", "call:http");
+      expect(acc.toArray()[0].taskId).toBe("flaky:2");
+    });
+
+    it("preserves taskId from taskStarted through taskStartedWithInput", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "call:http");
+      acc.taskStartedWithInput("t1", "call:http", { url: "http://example.com" });
+      expect(acc.toArray()[0].taskId).toBe("t1:1");
+    });
+
+    it("preserves taskId through taskCompletedWithResult", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "set");
+      acc.taskCompletedWithResult("t1", 100, { greeting: "hi" });
+      expect(acc.toArray()[0].taskId).toBe("t1:1");
+    });
+
+    it("preserves taskId through taskFailed", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "call:http");
+      acc.taskFailed("t1", "timeout");
+      expect(acc.toArray()[0].taskId).toBe("t1:1");
+    });
+
+    it("assigns unique taskIds across different tasks", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("a", "set");
+      acc.taskStarted("b", "call:http");
+      acc.taskStarted("c", "switch");
+      const ids = acc.toArray().map(e => e.taskId);
+      expect(ids).toEqual(["a:1", "b:1", "c:1"]);
+      expect(new Set(ids).size).toBe(3);
+    });
+
+    it("assigns taskId for skipped tasks", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskSkipped("conditional", "condition false");
+      expect(acc.toArray()[0].taskId).toBe("conditional:1");
+    });
+  });
+
+  describe("taskWaitingApproval", () => {
+    it("transitions a started task to waiting_approval", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("approval_gate", "human_input");
+      acc.taskWaitingApproval("approval_gate");
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("waiting_approval");
+      expect(entry.taskKind).toBe("human_input");
+      expect(entry.startedAt).toBeDefined();
+    });
+
+    it("preserves existing fields when transitioning", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStartedWithInput("gate", "human_input", { prompt: "Approve?" });
+      acc.taskWaitingApproval("gate");
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("waiting_approval");
+      expect(entry.input).toEqual({ prompt: "Approve?" });
+    });
+  });
+
+  describe("taskSkipped", () => {
+    it("records skip reason and completedAt", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskSkipped("optional_step", "condition evaluated to false");
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("skipped");
+      expect(entry.error).toBe("condition evaluated to false");
+      expect(entry.completedAt).toBeDefined();
+      expect(entry.startedAt).toBeUndefined();
+    });
+  });
+
+  describe("taskFailed with structuredError", () => {
+    it("stores structured error fields in metadata", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("http_task", "call:http");
+      acc.taskFailed("http_task", "connection timeout", {
+        category: "NETWORK",
+        detail: "ECONNREFUSED 127.0.0.1:8080",
+        retryable: true,
+      });
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("failed");
+      expect(entry.error).toBe("connection timeout");
+      expect(entry.metadata).toEqual({
+        error_category: "NETWORK",
+        error_detail: "ECONNREFUSED 127.0.0.1:8080",
+        error_retryable: true,
+      });
+    });
+
+    it("merges structured error with existing metadata", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("agent_task", "call:agent");
+      acc.setTaskMetadata("agent_task", { agent_execution_id: "exec-1" });
+      acc.taskFailed("agent_task", "agent crashed", {
+        category: "RUNTIME",
+        detail: "OOM killed",
+        retryable: false,
+      });
+      const [entry] = acc.toArray();
+      expect(entry.metadata).toEqual({
+        agent_execution_id: "exec-1",
+        error_category: "RUNTIME",
+        error_detail: "OOM killed",
+        error_retryable: false,
+      });
+    });
+  });
+
+  describe("taskFailed with durationMs", () => {
+    it("records duration on failed tasks", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("slow_task", "call:http");
+      acc.taskFailed("slow_task", "timeout", undefined, 5000);
+      const [entry] = acc.toArray();
+      expect(entry.status).toBe("failed");
+      expect(entry.durationMs).toBe(5000);
+    });
+
+    it("leaves durationMs undefined when not provided", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "call:http");
+      acc.taskFailed("t1", "error");
+      const [entry] = acc.toArray();
+      expect(entry.durationMs).toBeUndefined();
+    });
+  });
+
+  describe("getAttempt", () => {
+    it("returns 1 for tasks that haven't started", () => {
+      const acc = new TaskStatusAccumulator();
+      expect(acc.getAttempt("nonexistent")).toBe(1);
+    });
+
+    it("returns 1 after the first taskStarted call", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("t1", "call:http");
+      expect(acc.getAttempt("t1")).toBe(1);
+    });
+
+    it("increments on repeated taskStarted calls", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("flaky", "call:http");
+      expect(acc.getAttempt("flaky")).toBe(1);
+      acc.taskStarted("flaky", "call:http");
+      expect(acc.getAttempt("flaky")).toBe(2);
+      acc.taskStarted("flaky", "call:http");
+      expect(acc.getAttempt("flaky")).toBe(3);
+    });
+
+    it("tracks attempts independently per task", () => {
+      const acc = new TaskStatusAccumulator();
+      acc.taskStarted("a", "set");
+      acc.taskStarted("b", "set");
+      acc.taskStarted("a", "set");
+      expect(acc.getAttempt("a")).toBe(2);
+      expect(acc.getAttempt("b")).toBe(1);
+    });
+  });
+});
+
+describe("truncatePayload", () => {
+  it("returns small objects unchanged", () => {
+    const obj = { name: "test", value: 42 };
+    expect(truncatePayload(obj)).toEqual(obj);
+  });
+
+  it("returns null/undefined unchanged", () => {
+    expect(truncatePayload(null)).toBeNull();
+    expect(truncatePayload(undefined)).toBeUndefined();
+  });
+
+  it("returns strings unchanged if small", () => {
+    expect(truncatePayload("hello")).toBe("hello");
+  });
+
+  it("truncates objects larger than maxBytes", () => {
+    const large = { data: "x".repeat(100_000) };
+    const result = truncatePayload(large, 1000) as Record<string, unknown>;
+    expect(result._truncated).toBe(true);
+    expect(result._original_bytes).toBeGreaterThan(1000);
+    expect(typeof result._preview).toBe("string");
+    expect((result._preview as string).length).toBeLessThanOrEqual(2048);
+  });
+
+  it("uses default 64KB limit", () => {
+    const justUnder = { data: "x".repeat(60_000) };
+    expect(truncatePayload(justUnder)).toEqual(justUnder);
+
+    const justOver = { data: "x".repeat(70_000) };
+    const result = truncatePayload(justOver) as Record<string, unknown>;
+    expect(result._truncated).toBe(true);
+  });
+
+  it("handles circular references gracefully", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    const result = truncatePayload(circular) as Record<string, unknown>;
+    expect(result._truncated).toBe(true);
+    expect(result._reason).toBe("unserializable");
+  });
+
+  it("handles arrays", () => {
+    const arr = [1, 2, 3, 4, 5];
+    expect(truncatePayload(arr)).toEqual(arr);
+  });
+});

package/src/workflow-engine/__tests__/tasks/call-agent-output.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import { validateAgentCallOutput } from "../../tasks/call-agent-output.js";
+import type { AgentCallResult } from "../../types.js";
+
+describe("validateAgentCallOutput", () => {
+  const objectSchema = {
+    type: "object",
+    required: ["severity", "category"],
+    properties: {
+      severity: { type: "string", enum: ["low", "medium", "high", "critical"] },
+      category: { type: "string" },
+      rationale: { type: "string" },
+    },
+  };
+
+  describe("valid results", () => {
+    it("validates structured output against schema", () => {
+      const result: AgentCallResult = {
+        structured: { severity: "high", category: "security", rationale: "SQL injection" },
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(true);
+      expect(validation.errors).toHaveLength(0);
+    });
+
+    it("returns invalid when only final_text is present (no fallback parsing)", () => {
+      const result: AgentCallResult = {
+        final_text: '{"severity": "low", "category": "style"}',
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+      expect(validation.errors[0]).toContain("did not return structured output");
+    });
+  });
+
+  describe("invalid results", () => {
+    it("fails when required fields are missing", () => {
+      const result: AgentCallResult = {
+        structured: { severity: "high" },
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+      expect(validation.errors).toContain("Missing required field 'category'");
+    });
+
+    it("fails when enum value is invalid", () => {
+      const result: AgentCallResult = {
+        structured: { severity: "extreme", category: "perf" },
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+      expect(validation.errors[0]).toContain("must be one of");
+    });
+
+    it("fails when type is wrong", () => {
+      const result: AgentCallResult = {
+        structured: { severity: 42, category: "bugs" },
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+      expect(validation.errors[0]).toContain("expected type 'string'");
+    });
+
+    it("fails when structured is not an object", () => {
+      const result: AgentCallResult = {
+        structured: "just a string",
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+      expect(validation.errors[0]).toContain("Expected object");
+    });
+
+    it("fails when no structured output and final_text is not JSON", () => {
+      const result: AgentCallResult = {
+        final_text: "This is plain text, not JSON",
+      };
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+      expect(validation.errors[0]).toContain("did not return structured output");
+    });
+
+    it("fails when both structured and final_text are absent", () => {
+      const result: AgentCallResult = {};
+      const validation = validateAgentCallOutput(result, objectSchema);
+      expect(validation.valid).toBe(false);
+    });
+  });
+
+  describe("type validation", () => {
+    it("validates array type", () => {
+      const schema = { type: "array" };
+      const result: AgentCallResult = { structured: [1, 2, 3] };
+      expect(validateAgentCallOutput(result, schema).valid).toBe(true);
+    });
+
+    it("rejects non-array for array schema", () => {
+      const schema = { type: "array" };
+      const result: AgentCallResult = { structured: "not array" };
+      expect(validateAgentCallOutput(result, schema).valid).toBe(false);
+    });
+
+    it("validates string type", () => {
+      const schema = { type: "string" };
+      const result: AgentCallResult = { structured: "hello" };
+      expect(validateAgentCallOutput(result, schema).valid).toBe(true);
+    });
+
+    it("validates boolean type", () => {
+      const schema = { type: "boolean" };
+      const result: AgentCallResult = { structured: true };
+      expect(validateAgentCallOutput(result, schema).valid).toBe(true);
+    });
+
+    it("validates number type", () => {
+      const schema = { type: "number" };
+      const result: AgentCallResult = { structured: 42 };
+      expect(validateAgentCallOutput(result, schema).valid).toBe(true);
+    });
+  });
+});