@funkai/agents 0.1.0

package/src/core/agents/flow/messages.ts

@@ -0,0 +1,141 @@
+import type { Message } from "@/core/agents/base/types.js";
+import { safeStringify } from "@/utils/error.js";
+
+/**
+ * Build the `toolCallId` for a step.
+ *
+ * Combines the step id with the global step index to produce a unique
+ * identifier that correlates tool-call and tool-result messages.
+ *
+ * @param stepId - The step's user-provided id.
+ * @param index - The step's global index within the flow.
+ * @returns A unique tool call identifier.
+ */
+export function buildToolCallId(stepId: string, index: number): string {
+  return `${stepId}-${index}`;
+}
+
+/**
+ * Create an assistant message containing a synthetic tool-call part.
+ *
+ * Emitted when a `$` step starts execution. The `input` field captures
+ * the step's input snapshot (or `{}` when no input is available).
+ *
+ * @param toolCallId - Unique tool call identifier.
+ * @param toolName - The step id used as the tool name.
+ * @param args - The step's input snapshot.
+ * @returns A `Message` with role `assistant` and a `tool-call` content part.
+ */
+export function createToolCallMessage(
+  toolCallId: string,
+  toolName: string,
+  args: unknown,
+): Message {
+  return {
+    role: "assistant",
+    content: [
+      {
+        type: "tool-call",
+        toolCallId,
+        toolName,
+        input: args ?? {},
+      },
+    ],
+  };
+}
+
+/**
+ * Create a tool message containing a synthetic tool-result part.
+ *
+ * Emitted when a `$` step finishes execution. The `result` field captures
+ * the step's output. When `isError` is true, the result represents an
+ * error message.
+ *
+ * @param toolCallId - Unique tool call identifier (must match the paired tool-call).
+ * @param toolName - The step id used as the tool name.
+ * @param result - The step's output snapshot.
+ * @param isError - Whether this result represents an error.
+ * @returns A `Message` with role `tool` and a `tool-result` content part.
+ */
+export function createToolResultMessage(
+  toolCallId: string,
+  toolName: string,
+  result: unknown,
+  isError?: boolean,
+): Message {
+  // Synthetic tool-result for flow step tracking — not consumed by the AI SDK
+  return {
+    role: "tool",
+    content: [
+      {
+        type: "tool-result",
+        toolCallId,
+        toolName,
+        output: result ?? {},
+        ...(isError ? { isError: true } : {}),
+      },
+    ],
+  } as Message;
+}
+
+/**
+ * Safely serialize a value to a string for message content.
+ *
+ * Returns the value as-is when it's already a string. Otherwise
+ * delegates to {@link safeStringify} which handles circular refs,
+ * Maps, Sets, bigints, and other non-JSON-serializable types.
+ *
+ * @param value - The value to serialize.
+ * @returns A string representation of the value.
+ */
+function serializeMessageContent(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  return safeStringify(value ?? null);
+}
+
+/**
+ * Create a user message from flow agent input.
+ *
+ * This is the first message in the flow's message array, representing
+ * the input passed to `flowAgent.generate()` or `flowAgent.stream()`.
+ *
+ * @param input - The flow agent input.
+ * @returns A `Message` with role `user`.
+ */
+export function createUserMessage(input: unknown): Message {
+  return { role: "user", content: serializeMessageContent(input) };
+}
+
+/**
+ * Create a final assistant message from flow agent output.
+ *
+ * This is the last message in the flow's message array, representing
+ * the validated output returned by the handler.
+ *
+ * @param output - The flow agent output.
+ * @returns A `Message` with role `assistant`.
+ */
+export function createAssistantMessage(output: unknown): Message {
+  return { role: "assistant", content: serializeMessageContent(output) };
+}
+
+/**
+ * Collect text content from assistant messages in the message array.
+ *
+ * Used for flow agents without an output schema — the output is
+ * the concatenated text from sub-agent responses. Only considers
+ * messages with string content (tool-call messages have array content
+ * and are skipped).
+ *
+ * @param messages - The flow's message array.
+ * @returns The concatenated assistant text, trimmed.
+ */
+export function collectTextFromMessages(messages: readonly Message[]): string {
+  return messages
+    .filter((m) => m.role === "assistant" && typeof m.content === "string")
+    .map((m) => m.content as string)
+    .join("\n")
+    .trim();
+}

package/src/core/agents/flow/steps/agent.test.ts

@@ -0,0 +1,280 @@
+import { match } from "ts-pattern";
+import { describe, expect, it, vi } from "vitest";
+
+import type { Agent, GenerateResult } from "@/core/agents/base/types.js";
+import { createStepBuilder } from "@/core/agents/flow/steps/factory.js";
+import { createMockCtx } from "@/testing/index.js";
+import type { Result } from "@/utils/result.js";
+
+const MOCK_USAGE = {
+  inputTokens: 100,
+  outputTokens: 50,
+  totalTokens: 150,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  reasoningTokens: 0,
+};
+
+function mockAgent(result: Result<Pick<GenerateResult, "output" | "messages">>): Agent<string> {
+  const resolved: Result<GenerateResult> = match(result)
+    .with({ ok: true }, (r) => ({ ...r, usage: MOCK_USAGE, finishReason: "stop" as const }))
+    .otherwise((r) => r);
+  return {
+    generate: vi.fn(async () => resolved),
+    stream: vi.fn(),
+    fn: vi.fn(),
+  } as unknown as Agent<string>;
+}
+
+describe("agent()", () => {
+  it("unwraps successful agent result into StepResult", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({
+      ok: true,
+      output: "hello",
+      messages: [],
+    });
+
+    const result = await $.agent({ id: "ag", agent, input: "test" });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value.output).toBe("hello");
+    expect(result.value.messages).toEqual([]);
+    expect(result.value.usage).toEqual(MOCK_USAGE);
+    expect(result.value.finishReason).toBe("stop");
+    expect(result.step.type).toBe("agent");
+  });
+
+  it("converts agent error result into StepError", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({
+      ok: false,
+      error: { code: "AGENT_ERROR", message: "agent failed", cause: new Error("root") },
+    });
+
+    const result = await $.agent({ id: "ag-err", agent, input: "test" });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.code).toBe("STEP_ERROR");
+    expect(result.error.stepId).toBe("ag-err");
+  });
+
+  it("throws the cause error from agent error result", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const rootCause = new Error("root cause");
+    const agent = mockAgent({
+      ok: false,
+      error: { code: "AGENT_ERROR", message: "agent failed", cause: rootCause },
+    });
+
+    const result = await $.agent({ id: "ag-cause", agent, input: "test" });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.cause).toBe(rootCause);
+  });
+
+  it("creates new Error from message when no cause is provided", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({
+      ok: false,
+      error: { code: "AGENT_ERROR", message: "no cause" },
+    });
+
+    const result = await $.agent({ id: "ag-no-cause", agent, input: "test" });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect(result.error.message).toBe("no cause");
+  });
+
+  it("calls agent.generate with input and config", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "hi", messages: [] });
+    const config = { signal: new AbortController().signal };
+
+    await $.agent({ id: "ag-cfg", agent, input: "hello", config });
+
+    expect(agent.generate).toHaveBeenCalledWith(
+      "hello",
+      expect.objectContaining({ signal: config.signal, logger: expect.any(Object) }),
+    );
+  });
+
+  it("propagates ctx.signal to agent when no user signal is provided", async () => {
+    const controller = new AbortController();
+    const ctx = createMockCtx({ signal: controller.signal });
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "hi", messages: [] });
+
+    await $.agent({ id: "ag-ctx-signal", agent, input: "test" });
+
+    expect(agent.generate).toHaveBeenCalledWith(
+      "test",
+      expect.objectContaining({ signal: controller.signal }),
+    );
+  });
+
+  it("user-provided config.signal takes precedence over ctx.signal", async () => {
+    const ctxController = new AbortController();
+    const userController = new AbortController();
+    const ctx = createMockCtx({ signal: ctxController.signal });
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "hi", messages: [] });
+
+    await $.agent({
+      id: "ag-user-signal",
+      agent,
+      input: "test",
+      config: { signal: userController.signal },
+    });
+
+    expect(agent.generate).toHaveBeenCalledWith(
+      "test",
+      expect.objectContaining({ signal: userController.signal }),
+    );
+  });
+
+  it("records input in trace", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "hi", messages: [] });
+
+    await $.agent({ id: "ag-trace", agent, input: "my-input" });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.input).toBe("my-input");
+    expect(traceEntry.type).toBe("agent");
+  });
+
+  it("fires onStart and onFinish hooks", async () => {
+    const order: string[] = [];
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "done", messages: [] });
+
+    await $.agent({
+      id: "ag-hooks",
+      agent,
+      input: "test",
+      onStart: () => {
+        order.push("onStart");
+      },
+      onFinish: () => {
+        order.push("onFinish");
+      },
+    });
+
+    expect(order).toEqual(["onStart", "onFinish"]);
+  });
+
+  it("fires onError hook on failure", async () => {
+    const onError = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({
+      ok: false,
+      error: { code: "AGENT_ERROR", message: "failed" },
+    });
+
+    await $.agent({
+      id: "ag-onerror",
+      agent,
+      input: "test",
+      onError,
+    });
+
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "ag-onerror",
+        error: expect.any(Error),
+      }),
+    );
+  });
+
+  it("onFinish receives the GenerateResult", async () => {
+    const onFinish = vi.fn();
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "result-text", messages: [] });
+
+    await $.agent({
+      id: "ag-finish-result",
+      agent,
+      input: "test",
+      onFinish,
+    });
+
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "ag-finish-result",
+        result: expect.objectContaining({
+          output: "result-text",
+          messages: [],
+        }),
+        duration: expect.any(Number),
+      }),
+    );
+  });
+
+  it("passes scoped logger to agent.generate", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "hi", messages: [] });
+
+    await $.agent({ id: "ag-logger", agent, input: "test" });
+
+    expect(agent.generate).toHaveBeenCalledWith(
+      "test",
+      expect.objectContaining({ logger: expect.any(Object) }),
+    );
+    expect(ctx.log.child).toHaveBeenCalledWith({ stepId: "ag-logger" });
+  });
+
+  it("handles agent returning empty messages array", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "text", messages: [] });
+
+    const result = await $.agent({ id: "ag-empty-msgs", agent, input: "test" });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.value.messages).toEqual([]);
+  });
+
+  it("records usage on trace entry", async () => {
+    const ctx = createMockCtx();
+    const $ = createStepBuilder({ ctx });
+    const agent = mockAgent({ ok: true, output: "hi", messages: [] });
+
+    await $.agent({ id: "ag-trace-usage", agent, input: "test" });
+
+    const traceEntry = ctx.trace[0];
+    if (traceEntry === undefined) {
+      throw new Error("Expected trace entry");
+    }
+    expect(traceEntry.usage).toEqual(MOCK_USAGE);
+  });
+});

package/src/core/agents/flow/steps/agent.ts

@@ -0,0 +1,87 @@
+import type { AgentOverrides, GenerateResult } from "@/core/agents/base/types.js";
+import type { Runnable } from "@/core/types.js";
+
+/**
+ * Configuration for `$.agent()` — execute an agent call as a tracked operation.
+ *
+ * The `input` field matches whatever the agent accepts — typed `TInput`
+ * if the agent has a schema, or `string | Message[]` for simple agents.
+ *
+ * @typeParam TInput - The agent's input type.
+ */
+export interface AgentStepConfig<TInput> {
+  /**
+   * Unique step identifier.
+   *
+   * Appears in the execution trace, hook events, and error messages.
+   */
+  id: string;
+
+  /**
+   * The agent to invoke.
+   *
+   * The framework calls `agent.generate()` internally with the
+   * provided `input` and optional `config` overrides.
+   */
+  agent: Runnable<TInput>;
+
+  /**
+   * Input to pass to the agent.
+   *
+   * Same as what you'd pass to `agent.generate()` — typed `TInput`
+   * for agents with an input schema, or `string | Message[]` for
+   * simple agents.
+   */
+  input: TInput;
+
+  /**
+   * Optional inline overrides for this agent call.
+   *
+   * Accepts the same fields as `AgentOverrides` — model, output,
+   * tools, hooks, etc.
+   */
+  config?: AgentOverrides;
+
+  /**
+   * When `true`, call `agent.stream()` instead of `agent.generate()`
+   * and pipe the agent's text output through the parent flow's stream.
+   *
+   * Only has an effect when the flow agent is streaming (i.e., when
+   * a stream writer is available). Falls back to `agent.generate()`
+   * when the flow agent is not streaming.
+   *
+   * @default false
+   */
+  stream?: boolean;
+
+  /**
+   * Hook: fires when this agent step starts.
+   *
+   * @param event - Event containing the step id.
+   * @param event.id - The step's unique identifier.
+   */
+  onStart?: (event: { id: string }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when this agent step finishes.
+   *
+   * @param event - Event containing the step id, result, and duration.
+   * @param event.id - The step's unique identifier.
+   * @param event.result - The agent's `GenerateResult`.
+   * @param event.duration - Wall-clock time in milliseconds.
+   */
+  onFinish?: (event: {
+    id: string;
+    result: GenerateResult;
+    duration: number;
+  }) => void | Promise<void>;
+
+  /**
+   * Hook: fires when this agent step encounters an error.
+   *
+   * @param event - Event containing the step id and error.
+   * @param event.id - The step's unique identifier.
+   * @param event.error - The error that occurred.
+   */
+  onError?: (event: { id: string; error: Error }) => void | Promise<void>;
+}