@funkai/agents 0.1.0

package/src/utils/error.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from "vitest";
+
+import { toError, safeStringify, safeStringifyJSON } from "@/utils/error.js";
+
+describe("toError", () => {
+  it("returns Error instances as-is", () => {
+    const original = new Error("boom");
+    const result = toError(original);
+    expect(result).toBe(original);
+  });
+
+  it("preserves Error subclasses", () => {
+    const original = new TypeError("bad type");
+    const result = toError(original);
+    expect(result).toBe(original);
+    expect(result).toBeInstanceOf(TypeError);
+  });
+
+  it("wraps a string into an Error", () => {
+    const result = toError("raw string");
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("raw string");
+    expect(result.cause).toBe("raw string");
+  });
+
+  it("serializes a plain object as JSON", () => {
+    const thrown = { status: 400, message: "sandbox name too long" };
+    const result = toError(thrown);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('{"status":400,"message":"sandbox name too long"}');
+    expect(result.cause).toBe(thrown);
+  });
+
+  it("serializes an array as JSON", () => {
+    const thrown = ["error1", "error2"];
+    const result = toError(thrown);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('["error1","error2"]');
+    expect(result.cause).toBe(thrown);
+  });
+
+  it("serializes a Map as entries array", () => {
+    const thrown = new Map([["key", "value"]]);
+    const result = toError(thrown);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('[["key","value"]]');
+    expect(result.cause).toBe(thrown);
+  });
+
+  it("serializes a Set as values array", () => {
+    const thrown = new Set([1, 2, 3]);
+    const result = toError(thrown);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("[1,2,3]");
+    expect(result.cause).toBe(thrown);
+  });
+
+  it("handles circular references without throwing", () => {
+    const thrown: Record<string, unknown> = { name: "circular" };
+    thrown.self = thrown;
+    const result = toError(thrown);
+    expect(result).toBeInstanceOf(Error);
+    // Falls back to String() when JSON.stringify throws on circular refs
+    expect(result.message).toBe("[object Object]");
+    expect(result.cause).toBe(thrown);
+  });
+
+  it("handles null", () => {
+    const result = toError(null);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("null");
+  });
+
+  it("handles undefined", () => {
+    const result = toError(undefined);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("undefined");
+  });
+
+  it("handles numbers", () => {
+    const result = toError(42);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("42");
+  });
+
+  it("handles booleans", () => {
+    const result = toError(false);
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe("false");
+  });
+});
+
+describe("safeStringify", () => {
+  it("stringifies a plain object as JSON", () => {
+    expect(safeStringify({ status: 400 })).toBe('{"status":400}');
+  });
+
+  it("stringifies an array as JSON", () => {
+    expect(safeStringify([1, 2, 3])).toBe("[1,2,3]");
+  });
+
+  it("stringifies a Map as entries", () => {
+    expect(safeStringify(new Map([["k", "v"]]))).toBe('[["k","v"]]');
+  });
+
+  it("stringifies a Set as values", () => {
+    expect(safeStringify(new Set(["a", "b"]))).toBe('["a","b"]');
+  });
+
+  it("stringifies null", () => {
+    expect(safeStringify(null)).toBe("null");
+  });
+
+  it("stringifies undefined", () => {
+    expect(safeStringify(undefined)).toBe("undefined");
+  });
+
+  it("stringifies a number", () => {
+    expect(safeStringify(42)).toBe("42");
+  });
+
+  it("stringifies a boolean", () => {
+    expect(safeStringify(true)).toBe("true");
+  });
+
+  it("stringifies a string as-is", () => {
+    expect(safeStringify("hello")).toBe("hello");
+  });
+
+  it("falls back to String() for circular references", () => {
+    const circular: Record<string, unknown> = { name: "loop" };
+    circular.self = circular;
+    expect(safeStringify(circular)).toBe("[object Object]");
+  });
+});
+
+describe("safeStringifyJSON", () => {
+  it("serializes a plain object", () => {
+    expect(safeStringifyJSON({ a: 1, b: "two" })).toBe('{"a":1,"b":"two"}');
+  });
+
+  it("serializes an array", () => {
+    expect(safeStringifyJSON([1, 2, 3])).toBe("[1,2,3]");
+  });
+
+  it("serializes a Map as entries", () => {
+    expect(safeStringifyJSON(new Map([["k", "v"]]))).toBe('[["k","v"]]');
+  });
+
+  it("serializes a Set as values", () => {
+    expect(safeStringifyJSON(new Set(["a", "b"]))).toBe('["a","b"]');
+  });
+
+  it("serializes a string", () => {
+    expect(safeStringifyJSON("hello")).toBe('"hello"');
+  });
+
+  it("serializes null", () => {
+    expect(safeStringifyJSON(null)).toBe("null");
+  });
+
+  it("serializes a number", () => {
+    expect(safeStringifyJSON(42)).toBe("42");
+  });
+
+  it("returns empty string for circular references", () => {
+    const circular: Record<string, unknown> = { name: "loop" };
+    circular.self = circular;
+    expect(safeStringifyJSON(circular)).toBe("");
+  });
+
+  it("returns empty string for undefined input", () => {
+    expect(safeStringifyJSON(undefined)).toBe("");
+  });
+
+  it("returns empty string for functions", () => {
+    expect(safeStringifyJSON(() => "nope")).toBe("");
+  });
+});

package/src/utils/error.ts

@@ -0,0 +1,112 @@
+import { attempt, isError, isMap, isNil, isPrimitive, isSet, isString } from "es-toolkit";
+
+/**
+ * Coerces an unknown thrown value into a proper `Error` instance.
+ *
+ * Handles the common cases where libraries throw non-`Error` values
+ * (e.g. plain API response bodies, arrays, Maps) that would otherwise
+ * serialize as `[object Object]` in error messages.
+ *
+ * @param thrown - The caught value from a `catch` block.
+ * @returns An `Error` with a meaningful `.message`. If `thrown` is
+ *   already an `Error`, it is returned as-is. The original value is
+ *   preserved as `.cause` for debugging.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyCall()
+ * } catch (thrown) {
+ *   const error = toError(thrown)
+ *   console.error(error.message)
+ * }
+ * ```
+ */
+export function toError(thrown: unknown): Error {
+  if (isError(thrown)) {
+    return thrown;
+  }
+  if (isString(thrown)) {
+    return new Error(thrown, { cause: thrown });
+  }
+  return new Error(safeStringify(thrown), { cause: thrown });
+}
+
+/**
+ * Produce a human-readable string from any unknown value.
+ *
+ * Uses `JSON.stringify` for structured types (plain objects, arrays)
+ * so the message contains actual content instead of `[object Object]`.
+ * Maps and Sets are converted to their array representation first.
+ * Falls back to `String()` for primitives or when serialization fails
+ * (e.g. circular references).
+ *
+ * @param value - The value to stringify.
+ * @returns A meaningful string representation.
+ *
+ * @example
+ * ```typescript
+ * safeStringify({ status: 400 })          // '{"status":400}'
+ * safeStringify(new Map([['k', 'v']]))    // '[["k","v"]]'
+ * safeStringify(null)                     // 'null'
+ * safeStringify(42)                       // '42'
+ * ```
+ */
+export function safeStringify(value: unknown): string {
+  if (isNil(value) || isPrimitive(value)) {
+    return String(value);
+  }
+  return safeStringifyJSON(value) || String(value);
+}
+
+/**
+ * Safely serializes a value to a JSON string without throwing.
+ *
+ * Converts types that `JSON.stringify` handles poorly (Maps, Sets)
+ * into serializable equivalents before stringifying. Returns an empty
+ * string when serialization fails (e.g. circular references).
+ *
+ * @param value - The value to serialize.
+ * @returns The JSON string, or an empty string if serialization fails.
+ *
+ * @example
+ * ```typescript
+ * safeStringifyJSON({ status: 400 })        // '{"status":400}'
+ * safeStringifyJSON(new Map([['k', 'v']]))   // '[["k","v"]]'
+ * safeStringifyJSON(circularObj)              // ''
+ * ```
+ */
+export function safeStringifyJSON(value: unknown): string {
+  const serializable = toSerializable(value);
+  const [error, json] = attempt(() => JSON.stringify(serializable) as string | undefined);
+  if (!isNil(error) || isNil(json)) {
+    return "";
+  }
+  return json;
+}
+
+// ---------------------------------------------------------------------------
+// private helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert types that `JSON.stringify` handles poorly into
+ * serializable equivalents.
+ *
+ * - `Map` → array of `[key, value]` entries
+ * - `Set` → array of values
+ * - Everything else → passed through unchanged
+ *
+ * @private
+ * @param value - The value to normalize.
+ * @returns A JSON-friendly representation.
+ */
+function toSerializable(value: unknown): unknown {
+  if (isMap(value)) {
+    return Array.from(value.entries());
+  }
+  if (isSet(value)) {
+    return Array.from(value);
+  }
+  return value;
+}

package/src/utils/resolve.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+
+import { resolve } from "@/utils/resolve.js";
+
+describe("resolve", () => {
+  it("returns a static value as-is", async () => {
+    const result = await resolve("hello", {});
+    expect(result).toBe("hello");
+  });
+
+  it("returns undefined when value is undefined", async () => {
+    const result = await resolve(undefined, {});
+    expect(result).toBeUndefined();
+  });
+
+  it("calls a sync function with ctx and returns the result", async () => {
+    const result = await resolve((ctx: { name: string }) => `hi ${ctx.name}`, { name: "Ada" });
+    expect(result).toBe("hi Ada");
+  });
+
+  it("calls an async function with ctx and returns the resolved result", async () => {
+    const result = await resolve(async (ctx: { n: number }) => ctx.n * 2, { n: 21 });
+    expect(result).toBe(42);
+  });
+
+  it("returns static non-string values (number, object)", async () => {
+    expect(await resolve(42, {})).toBe(42);
+    expect(await resolve({ key: "value" }, {})).toEqual({ key: "value" });
+  });
+
+  it("propagates errors from the resolver function", async () => {
+    await expect(
+      resolve(() => {
+        throw new Error("resolver boom");
+      }, {}),
+    ).rejects.toThrow("resolver boom");
+  });
+});

package/src/utils/resolve.ts

@@ -0,0 +1,41 @@
+import { isFunction } from "es-toolkit";
+
+/**
+ * A value that is either static or dynamically resolved from context.
+ *
+ * Use this for agent/workflow definition fields that may depend on
+ * runtime state (e.g. tools, instructions, prompt).
+ *
+ * @typeParam T - The resolved value type.
+ * @typeParam TCtx - The context type passed when resolving dynamically.
+ *
+ * @example
+ * ```typescript
+ * // Static
+ * instructions: 'You are a helpful assistant'
+ *
+ * // Dynamic (sync)
+ * instructions: (ctx) => `Analyze ${ctx.input.repoName}`
+ *
+ * // Dynamic (async)
+ * instructions: async (ctx) => fetchPrompt(ctx.input.repoName)
+ * ```
+ */
+export type ResolveParam<T, TCtx> = T | ((ctx: TCtx) => T | Promise<T>);
+
+/**
+ * Resolve a {@link ResolveParam} value — if it's a function, call it with ctx.
+ *
+ * @param value - A static value, a function of context, or undefined.
+ * @param ctx - The context to pass if the value is a function.
+ * @returns The resolved value, or `undefined` if the input was `undefined`.
+ */
+export async function resolve<T, TCtx>(
+  value: ResolveParam<T, TCtx> | undefined,
+  ctx: TCtx,
+): Promise<T | undefined> {
+  if (isFunction(value)) {
+    return value(ctx);
+  }
+  return value;
+}

package/src/utils/result.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+
+import { ok, err, isOk, isErr } from "@/utils/result.js";
+import type { Result } from "@/utils/result.js";
+
+describe("ok", () => {
+  it("creates a success result with ok: true", () => {
+    const result = ok({ output: "hello" });
+    expect(result.ok).toBe(true);
+    expect(result.output).toBe("hello");
+  });
+
+  it("spreads all fields flat onto the result", () => {
+    const result = ok({ output: "text", messages: [], duration: 42 });
+    expect(result).toEqual({
+      ok: true,
+      output: "text",
+      messages: [],
+      duration: 42,
+    });
+  });
+});
+
+describe("err", () => {
+  it("creates a failure result with ok: false", () => {
+    const result = err("VALIDATION_ERROR", "Name is required");
+    expect(result.ok).toBe(false);
+    expect(result.error.code).toBe("VALIDATION_ERROR");
+    expect(result.error.message).toBe("Name is required");
+    expect(result.error.cause).toBeUndefined();
+  });
+
+  it("includes the cause when provided", () => {
+    const cause = new Error("root cause");
+    const result = err("AGENT_ERROR", "something broke", cause);
+    expect(result.error.cause).toBe(cause);
+  });
+});
+
+describe("isOk", () => {
+  it("returns true for success results", () => {
+    const result: Result<{ value: number }> = ok({ value: 1 });
+    expect(isOk(result)).toBe(true);
+  });
+
+  it("returns false for failure results", () => {
+    const result: Result<{ value: number }> = err("ERR", "fail");
+    expect(isOk(result)).toBe(false);
+  });
+
+  it("narrows the type so success fields are accessible", () => {
+    const result: Result<{ value: number }> = ok({ value: 42 });
+    if (isOk(result)) {
+      // This line would fail to compile if narrowing didn't work
+      expect(result.value).toBe(42);
+    }
+  });
+});
+
+describe("isErr", () => {
+  it("returns true for failure results", () => {
+    const result: Result<{ value: number }> = err("ERR", "fail");
+    expect(isErr(result)).toBe(true);
+  });
+
+  it("returns false for success results", () => {
+    const result: Result<{ value: number }> = ok({ value: 1 });
+    expect(isErr(result)).toBe(false);
+  });
+
+  it("narrows the type so error fields are accessible", () => {
+    const result: Result<{ value: number }> = err("MY_CODE", "my message");
+    if (isErr(result)) {
+      // This line would fail to compile if narrowing didn't work
+      expect(result.error.code).toBe("MY_CODE");
+      expect(result.error.message).toBe("my message");
+    }
+  });
+});

package/src/utils/result.ts

@@ -0,0 +1,151 @@
+/**
+ * Error information returned when an SDK operation fails.
+ *
+ * Every public method returns `Result<T>` instead of throwing.
+ * When `ok` is `false`, the error details are available on this interface.
+ */
+export interface ResultError {
+  /**
+   * Machine-readable error code.
+   *
+   * Identifies the category of failure. Stable across versions —
+   * safe to match against in application code.
+   *
+   * @example
+   * ```typescript
+   * switch (result.error.code) {
+   *   case 'VALIDATION_ERROR': // input schema failed
+   *   case 'ABORT_ERROR':      // signal was aborted
+   *   case 'AGENT_ERROR':      // agent execution failed
+   * }
+   * ```
+   */
+  code: string;
+
+  /**
+   * Human-readable error description.
+   *
+   * Suitable for logging but not for programmatic matching —
+   * use `code` for that.
+   */
+  message: string;
+
+  /**
+   * Original thrown error, if any.
+   *
+   * Preserved so callers can inspect the root cause when the
+   * SDK catches and wraps an exception.
+   */
+  cause?: Error;
+}
+
+/**
+ * Discriminated union for SDK operation results.
+ *
+ * Success fields are **flat on the object** — no `.value` wrapper.
+ * Callers pattern-match on `ok` instead of using try/catch.
+ *
+ * @typeParam T - The success payload shape. All fields from `T` are
+ *   spread directly onto the success branch alongside `ok: true`.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.generate({ topic: 'TypeScript' })
+ *
+ * if (!result.ok) {
+ *   // Error branch — only `ok` and `error` are present.
+ *   console.error(result.error.code, result.error.message)
+ *   return
+ * }
+ *
+ * // Success branch — all fields from T are directly on result.
+ * console.log(result.output)
+ * console.log(result.duration)
+ * console.log(result.trace)
+ * ```
+ */
+export type Result<T> = (T & { ok: true }) | { ok: false; error: ResultError };
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a success `Result`.
+ *
+ * Spreads the payload flat onto the object alongside `ok: true`.
+ *
+ * @param value - The success payload.
+ * @returns A success `Result<T>`.
+ *
+ * @example
+ * ```typescript
+ * return ok({ output: 'hello', messages: [] })
+ * // → { ok: true, output: 'hello', messages: [] }
+ * ```
+ */
+export function ok<T extends Record<string, unknown>>(value: T): T & { ok: true } {
+  return { ...value, ok: true as const };
+}
+
+/**
+ * Create a failure `Result`.
+ *
+ * @param code - Machine-readable error code.
+ * @param message - Human-readable error description.
+ * @param cause - Optional original thrown error.
+ * @returns A failure `Result` for any `T`.
+ *
+ * @example
+ * ```typescript
+ * return err('VALIDATION_ERROR', 'Name is required')
+ * return err('AGENT_ERROR', error.message, error)
+ * ```
+ */
+export function err(
+  code: string,
+  message: string,
+  cause?: Error,
+): { ok: false; error: ResultError } {
+  return { ok: false as const, error: { code, message, cause } };
+}
+
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+
+/**
+ * Narrow a `Result<T>` to its success branch.
+ *
+ * @param result - The result to check.
+ * @returns `true` when `result.ok` is `true`.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.generate('hello')
+ * if (isOk(result)) {
+ *   console.log(result.output)
+ * }
+ * ```
+ */
+export function isOk<T>(result: Result<T>): result is T & { ok: true } {
+  return result.ok;
+}
+
+/**
+ * Narrow a `Result<T>` to its failure branch.
+ *
+ * @param result - The result to check.
+ * @returns `true` when `result.ok` is `false`.
+ *
+ * @example
+ * ```typescript
+ * const result = await agent.generate('hello')
+ * if (isErr(result)) {
+ *   console.error(result.error.code, result.error.message)
+ * }
+ * ```
+ */
+export function isErr<T>(result: Result<T>): result is { ok: false; error: ResultError } {
+  return !result.ok;
+}

package/src/utils/zod.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { isZodArray, isZodObject, toJsonSchema } from "@/utils/zod.js";
+
+describe("toJsonSchema", () => {
+  it("converts an object schema to JSON Schema", () => {
+    const schema = z.object({ name: z.string() });
+    const result = toJsonSchema(schema);
+
+    expect(result.type).toBe("object");
+    expect(result.properties).toHaveProperty("name");
+    expect(result.required).toContain("name");
+  });
+
+  it("converts an array schema to JSON Schema", () => {
+    const schema = z.array(z.number());
+    const result = toJsonSchema(schema);
+
+    expect(result.type).toBe("array");
+  });
+
+  it("converts a string schema to JSON Schema", () => {
+    const result = toJsonSchema(z.string());
+    expect(result.type).toBe("string");
+  });
+
+  it("converts a number schema to JSON Schema", () => {
+    const result = toJsonSchema(z.number());
+    expect(result.type).toBe("number");
+  });
+
+  it("converts a boolean schema to JSON Schema", () => {
+    const result = toJsonSchema(z.boolean());
+    expect(result.type).toBe("boolean");
+  });
+});
+
+describe("isZodObject", () => {
+  it("returns true for object schemas", () => {
+    expect(isZodObject(z.object({ x: z.number() }))).toBe(true);
+  });
+
+  it("returns false for array schemas", () => {
+    expect(isZodObject(z.array(z.string()))).toBe(false);
+  });
+
+  it("returns false for primitive schemas", () => {
+    expect(isZodObject(z.string())).toBe(false);
+    expect(isZodObject(z.number())).toBe(false);
+    expect(isZodObject(z.boolean())).toBe(false);
+  });
+});
+
+describe("isZodArray", () => {
+  it("returns true for array schemas", () => {
+    expect(isZodArray(z.array(z.string()))).toBe(true);
+  });
+
+  it("returns false for object schemas", () => {
+    expect(isZodArray(z.object({ x: z.number() }))).toBe(false);
+  });
+
+  it("returns false for primitive schemas", () => {
+    expect(isZodArray(z.string())).toBe(false);
+    expect(isZodArray(z.number())).toBe(false);
+    expect(isZodArray(z.boolean())).toBe(false);
+  });
+});

package/src/utils/zod.ts

@@ -0,0 +1,31 @@
+import type { ZodType } from "zod";
+import { z } from "zod";
+
+type JSONSchema = z.core.JSONSchema.JSONSchema;
+
+/**
+ * Convert a Zod schema to a JSON Schema object.
+ */
+export function toJsonSchema(schema: ZodType): JSONSchema {
+  return z.toJSONSchema(schema);
+}
+
+/**
+ * Check if a Zod schema produces a JSON Schema with `type: 'object'`.
+ *
+ * Uses JSON Schema output rather than `instanceof` to correctly handle
+ * wrapped schemas (transforms, refinements, pipes).
+ */
+export function isZodObject(schema: ZodType): boolean {
+  return toJsonSchema(schema).type === "object";
+}
+
+/**
+ * Check if a Zod schema produces a JSON Schema with `type: 'array'`.
+ *
+ * Uses JSON Schema output rather than `instanceof` to correctly handle
+ * wrapped schemas (transforms, refinements, pipes).
+ */
+export function isZodArray(schema: ZodType): boolean {
+  return toJsonSchema(schema).type === "array";
+}