@funkai/agents 0.1.0

package/src/core/logger.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createDefaultLogger } from "@/core/logger.js";
+
+// ---------------------------------------------------------------------------
+// createDefaultLogger
+// ---------------------------------------------------------------------------
+
+describe("createDefaultLogger", () => {
+  it("returns a logger with all required methods", () => {
+    const log = createDefaultLogger();
+    expect(log.debug).toBeDefined();
+    expect(log.info).toBeDefined();
+    expect(log.warn).toBeDefined();
+    expect(log.error).toBeDefined();
+    expect(log.child).toBeDefined();
+  });
+
+  it("logs info with message-first signature", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const log = createDefaultLogger();
+
+    log.info("hello world");
+
+    expect(spy).toHaveBeenCalledWith({}, "hello world");
+    spy.mockRestore();
+  });
+
+  it("logs info with message and metadata", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const log = createDefaultLogger();
+
+    log.info("request completed", { status: 200 });
+
+    expect(spy).toHaveBeenCalledWith({ status: 200 }, "request completed");
+    spy.mockRestore();
+  });
+
+  it("logs info with object-first (pino) signature", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const log = createDefaultLogger();
+
+    log.info({ requestId: "abc" }, "started");
+
+    expect(spy).toHaveBeenCalledWith({ requestId: "abc" }, "started");
+    spy.mockRestore();
+  });
+
+  it("logs debug messages to console.debug", () => {
+    const spy = vi.spyOn(console, "debug").mockImplementation(() => {});
+    const log = createDefaultLogger();
+
+    log.debug("trace data");
+
+    expect(spy).toHaveBeenCalledWith({}, "trace data");
+    spy.mockRestore();
+  });
+
+  it("logs warn messages to console.warn", () => {
+    const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const log = createDefaultLogger();
+
+    log.warn("deprecation notice");
+
+    expect(spy).toHaveBeenCalledWith({}, "deprecation notice");
+    spy.mockRestore();
+  });
+
+  it("logs error messages to console.error", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const log = createDefaultLogger();
+
+    log.error("fatal", { code: 500 });
+
+    expect(spy).toHaveBeenCalledWith({ code: 500 }, "fatal");
+    spy.mockRestore();
+  });
+
+  it("creates initial bindings that appear in all log output", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const log = createDefaultLogger({ service: "api" });
+
+    log.info("boot");
+
+    expect(spy).toHaveBeenCalledWith({ service: "api" }, "boot");
+    spy.mockRestore();
+  });
+
+  it("merges initial bindings with per-call metadata", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const log = createDefaultLogger({ service: "api" });
+
+    log.info("req", { path: "/health" });
+
+    expect(spy).toHaveBeenCalledWith({ service: "api", path: "/health" }, "req");
+    spy.mockRestore();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// child loggers
+// ---------------------------------------------------------------------------
+
+describe("child loggers", () => {
+  it("creates a child logger that inherits parent bindings", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const parent = createDefaultLogger({ service: "api" });
+    const child = parent.child({ workflow: "deploy" });
+
+    child.info("step started");
+
+    expect(spy).toHaveBeenCalledWith({ service: "api", workflow: "deploy" }, "step started");
+    spy.mockRestore();
+  });
+
+  it("does not affect parent when child adds bindings", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const parent = createDefaultLogger({ service: "api" });
+    parent.child({ workflow: "deploy" });
+
+    parent.info("parent log");
+
+    expect(spy).toHaveBeenCalledWith({ service: "api" }, "parent log");
+    spy.mockRestore();
+  });
+
+  it("supports multiple levels of child nesting", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const root = createDefaultLogger({ app: "serenity" });
+    const mid = root.child({ workflow: "build" });
+    const leaf = mid.child({ step: "compile" });
+
+    leaf.info("compiling");
+
+    expect(spy).toHaveBeenCalledWith(
+      { app: "serenity", workflow: "build", step: "compile" },
+      "compiling",
+    );
+    spy.mockRestore();
+  });
+
+  it("child bindings override parent bindings with same key", () => {
+    const spy = vi.spyOn(console, "info").mockImplementation(() => {});
+    const parent = createDefaultLogger({ scope: "parent" });
+    const child = parent.child({ scope: "child" });
+
+    child.info("scoped");
+
+    expect(spy).toHaveBeenCalledWith({ scope: "child" }, "scoped");
+    spy.mockRestore();
+  });
+
+  it("child logger has all level methods", () => {
+    const parent = createDefaultLogger();
+    const child = parent.child({ step: "test" });
+
+    expect(child.debug).toBeDefined();
+    expect(child.info).toBeDefined();
+    expect(child.warn).toBeDefined();
+    expect(child.error).toBeDefined();
+    expect(child.child).toBeDefined();
+  });
+});

package/src/core/logger.ts

@@ -0,0 +1,152 @@
+/**
+ * Pino-compatible leveled logger with child logger support.
+ *
+ * Consumers inject a pino instance (or any compatible logger);
+ * the SDK defines only the interface. Each method supports both
+ * `(msg, meta?)` and `(meta, msg)` call signatures to match pino's API.
+ *
+ * Child loggers accumulate bindings from parents — the framework
+ * uses `child()` at each scope boundary (workflow, step, agent)
+ * so log output automatically includes execution context.
+ */
+export interface Logger {
+  /**
+   * Log a message at the DEBUG level.
+   *
+   * Use for verbose diagnostic output that is typically silenced
+   * in production (e.g. intermediate state, resolved config).
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  debug(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the DEBUG level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  debug(meta: Record<string, unknown>, msg: string): void;
+
+  /**
+   * Log a message at the INFO level.
+   *
+   * Use for routine operational events worth recording — step
+   * transitions, successful completions, and notable state changes.
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  info(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the INFO level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  info(meta: Record<string, unknown>, msg: string): void;
+
+  /**
+   * Log a message at the WARN level.
+   *
+   * Use for recoverable problems that do not halt execution but
+   * may indicate degraded behavior (e.g. retries, fallback paths).
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  warn(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the WARN level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  warn(meta: Record<string, unknown>, msg: string): void;
+
+  /**
+   * Log a message at the ERROR level.
+   *
+   * Use for failures that prevent an operation from completing
+   * successfully — unhandled exceptions, rejected promises, or
+   * invariant violations.
+   *
+   * @param msg - Human-readable log message.
+   * @param meta - Optional structured metadata merged into the log entry.
+   */
+  error(msg: string, meta?: Record<string, unknown>): void;
+  /**
+   * Log a message at the ERROR level (pino object-first overload).
+   *
+   * @param meta - Structured metadata merged into the log entry.
+   * @param msg - Human-readable log message.
+   */
+  error(meta: Record<string, unknown>, msg: string): void;
+
+  /**
+   * Create a child logger that inherits all parent bindings.
+   *
+   * The returned logger automatically includes the merged bindings
+   * in every log entry. The framework calls `child()` at each scope
+   * boundary (workflow, step, agent) so downstream logs carry full
+   * execution context without manual threading.
+   *
+   * @param bindings - Key-value pairs merged into every log entry
+   *   produced by the child (and its descendants).
+   * @returns A new {@link Logger} with the accumulated bindings.
+   */
+  child(bindings: Record<string, unknown>): Logger;
+}
+
+/**
+ * Create a minimal console-based logger satisfying the {@link Logger} interface.
+ *
+ * Supports `child()` by merging bindings into a prefix object.
+ * Each log call prepends the accumulated bindings to the output.
+ *
+ * Used as the default when no pino-compatible logger is injected.
+ */
+export function createDefaultLogger(bindings?: Record<string, unknown>): Logger {
+  const prefix = bindings ?? {};
+  return {
+    debug(first: string | Record<string, unknown>, second?: string | Record<string, unknown>) {
+      writeLog(prefix, "debug", first, second);
+    },
+    info(first: string | Record<string, unknown>, second?: string | Record<string, unknown>) {
+      writeLog(prefix, "info", first, second);
+    },
+    warn(first: string | Record<string, unknown>, second?: string | Record<string, unknown>) {
+      writeLog(prefix, "warn", first, second);
+    },
+    error(first: string | Record<string, unknown>, second?: string | Record<string, unknown>) {
+      writeLog(prefix, "error", first, second);
+    },
+    child(childBindings: Record<string, unknown>): Logger {
+      return createDefaultLogger({ ...prefix, ...childBindings });
+    },
+  };
+}
+
+/**
+ *
+ * @param bindings
+ * @param level
+ * @param first
+ * @param second
+ * @private
+ */
+function writeLog(
+  bindings: Record<string, unknown>,
+  level: "debug" | "info" | "warn" | "error",
+  first: string | Record<string, unknown>,
+  second?: string | Record<string, unknown>,
+): void {
+  if (typeof first === "string") {
+    const meta = second as Record<string, unknown> | undefined;
+    // eslint-disable-next-line security/detect-object-injection -- Log level is a controlled string from the logger, not user input
+    console[level]({ ...bindings, ...meta }, first);
+  } else {
+    // eslint-disable-next-line security/detect-object-injection -- Log level is a controlled string from the logger, not user input
+    console[level]({ ...bindings, ...first }, second as string);
+  }
+}

package/src/core/models/index.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+
+import { model, models, MODELS, tryModel } from "@/core/models/index.js";
+
+// ---------------------------------------------------------------------------
+// MODELS constant
+// ---------------------------------------------------------------------------
+
+describe("MODELS", () => {
+  it("is a non-empty array", () => {
+    expect(MODELS.length).toBeGreaterThan(0);
+  });
+
+  it("every entry has required fields", () => {
+    for (const m of MODELS) {
+      expect(typeof m.id).toBe("string");
+      expect(m.id.length).toBeGreaterThan(0);
+      expect(["chat", "coding", "reasoning"]).toContain(m.category);
+      expect(typeof m.pricing.prompt).toBe("number");
+      expect(typeof m.pricing.completion).toBe("number");
+    }
+  });
+
+  it("contains known model IDs", () => {
+    const ids = MODELS.map((m) => m.id);
+    expect(ids).toContain("openai/gpt-5.2-codex");
+    expect(ids).toContain("openai/o4-mini");
+  });
+
+  it("has no duplicate IDs", () => {
+    const ids = MODELS.map((m) => m.id);
+    const unique = new Set(ids);
+    expect(unique.size).toBe(ids.length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// model()
+// ---------------------------------------------------------------------------
+
+describe("model()", () => {
+  it("returns the model definition for a known ID", () => {
+    const result = model("openai/gpt-5.2-codex");
+
+    expect(result.id).toBe("openai/gpt-5.2-codex");
+    expect(result.category).toBe("coding");
+    expect(typeof result.pricing.prompt).toBe("number");
+    expect(typeof result.pricing.completion).toBe("number");
+  });
+
+  it("throws for an unknown model ID", () => {
+    expect(() => model("nonexistent/model-99")).toThrow("Unknown model: nonexistent/model-99");
+  });
+
+  it("returns correct category for reasoning models", () => {
+    const result = model("openai/o3");
+
+    expect(result.category).toBe("reasoning");
+  });
+
+  it("returns correct category for chat models", () => {
+    const result = model("openai/gpt-5.2");
+
+    expect(result.category).toBe("chat");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// tryModel()
+// ---------------------------------------------------------------------------
+
+describe("tryModel()", () => {
+  it("returns the model definition for a known ID", () => {
+    const result = tryModel("openai/gpt-5.2-codex");
+
+    expect(result).toBeDefined();
+    if (!result) {
+      throw new Error("Expected result to be defined");
+    }
+    expect(result.id).toBe("openai/gpt-5.2-codex");
+  });
+
+  it("returns undefined for an unknown model ID", () => {
+    const result = tryModel("nonexistent/model-99");
+
+    expect(result).toBeUndefined();
+  });
+
+  it("does not throw for unknown IDs", () => {
+    expect(() => tryModel("nonexistent/model-99")).not.toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// models()
+// ---------------------------------------------------------------------------
+
+describe("models()", () => {
+  it("returns all models when called without filter", () => {
+    const result = models();
+
+    expect(result.length).toBe(MODELS.length);
+  });
+
+  it("filters models by category", () => {
+    const codingModels = models((m) => m.category === "coding");
+
+    expect(codingModels.length).toBeGreaterThan(0);
+    for (const m of codingModels) {
+      expect(m.category).toBe("coding");
+    }
+  });
+
+  it("returns reasoning models when filtered", () => {
+    const reasoningModels = models((m) => m.category === "reasoning");
+
+    expect(reasoningModels.length).toBeGreaterThan(0);
+    for (const m of reasoningModels) {
+      expect(m.category).toBe("reasoning");
+    }
+  });
+
+  it("returns empty array when filter matches nothing", () => {
+    const result = models(() => false);
+
+    expect(result).toEqual([]);
+  });
+
+  it("supports arbitrary filter predicates", () => {
+    const result = models((m) => m.pricing.prompt > 0.000001);
+
+    expect(result.length).toBeGreaterThan(0);
+    for (const m of result) {
+      expect(m.pricing.prompt).toBeGreaterThan(0.000001);
+    }
+  });
+});

package/src/core/models/index.ts

@@ -0,0 +1,152 @@
+// ──────────────────────────────────────────────────────────────
+//  █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
+// ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
+// ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
+// ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
+// ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
+// ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
+//
+// AUTO-GENERATED — DO NOT EDIT
+// Update: pnpm --filter=@pkg/agent-sdk generate:models
+// ──────────────────────────────────────────────────────────────
+
+import { P, match } from "ts-pattern";
+import type { LiteralUnion } from "type-fest";
+
+import { OPENAI_MODELS } from "@/core/models/providers/openai.js";
+
+const GENERATED_MODELS = [...OPENAI_MODELS] as const;
+
+/**
+ * Supported OpenRouter model identifiers, derived from the generated {@link MODELS} array.
+ */
+export type OpenRouterLanguageModelId = (typeof GENERATED_MODELS)[number]["id"];
+
+/**
+ * A model identifier that suggests known OpenRouter models but accepts any string.
+ *
+ * Provides autocomplete for cataloged models while allowing arbitrary
+ * model IDs for new or custom models not yet in the catalog.
+ */
+export type ModelId = LiteralUnion<OpenRouterLanguageModelId, string>;
+
+/**
+ * Model category for classification and filtering.
+ */
+export type ModelCategory = "chat" | "coding" | "reasoning";
+
+/**
+ * Per-model pricing in USD per token.
+ *
+ * Field names match the OpenRouter API convention. All values are
+ * per-token (or per-unit) rates as numbers. Optional fields are
+ * omitted when the provider does not support them.
+ */
+export interface ModelPricing {
+  /** Cost per input (prompt) token. */
+  prompt: number;
+
+  /** Cost per output (completion) token. */
+  completion: number;
+
+  /** Cost per cached input token (read). */
+  inputCacheRead?: number;
+
+  /** Cost per cached input token (write). */
+  inputCacheWrite?: number;
+
+  /** Cost per web search request. */
+  webSearch?: number;
+
+  /** Cost per internal reasoning token. */
+  internalReasoning?: number;
+
+  /** Cost per image input token. */
+  image?: number;
+
+  /** Cost per audio input second. */
+  audio?: number;
+
+  /** Cost per audio output second. */
+  audioOutput?: number;
+}
+
+/**
+ * Model definition with metadata and pricing.
+ */
+export interface ModelDefinition {
+  /** OpenRouter model identifier (e.g. `"openai/gpt-5.2-codex"`). */
+  id: string;
+
+  /** Model category for classification. */
+  category: ModelCategory;
+
+  /** Token pricing rates. */
+  pricing: ModelPricing;
+}
+
+/**
+ * Supported OpenRouter models with pricing data.
+ */
+export const MODELS = GENERATED_MODELS satisfies readonly ModelDefinition[];
+
+/**
+ * Look up a model definition by its identifier.
+ *
+ * @param id - The model identifier to look up.
+ * @returns The matching model definition.
+ * @throws {Error} If no model matches the given ID.
+ *
+ * @example
+ * ```typescript
+ * const m = model('openai/gpt-5.2-codex')
+ * console.log(m.pricing.prompt) // 0.00000175
+ * console.log(m.category)       // 'coding'
+ * ```
+ */
+export function model(id: ModelId): ModelDefinition {
+  const found = MODELS.find((m) => m.id === id);
+  if (!found) {
+    throw new Error(`Unknown model: ${id}`);
+  }
+  return found;
+}
+
+/**
+ * Look up a model definition by its identifier, returning `undefined` if not found.
+ *
+ * Unlike {@link model}, this does not throw for unknown IDs — useful when
+ * the caller can gracefully handle missing pricing (e.g. non-OpenRouter models).
+ *
+ * @param id - The model identifier to look up.
+ * @returns The matching model definition, or `undefined`.
+ *
+ * @example
+ * ```typescript
+ * const m = tryModel('anthropic/claude-sonnet-4-20250514')
+ * if (m) {
+ *   console.log(m.pricing.prompt)
+ * }
+ * ```
+ */
+export function tryModel(id: ModelId): ModelDefinition | undefined {
+  return MODELS.find((m) => m.id === id);
+}
+
+/**
+ * Return supported model definitions, optionally filtered.
+ *
+ * @param filter - Optional predicate to filter models.
+ * @returns A readonly array of matching model definitions.
+ *
+ * @example
+ * ```typescript
+ * const all = models()
+ * const reasoning = models((m) => m.category === 'reasoning')
+ * ```
+ */
+export function models(filter?: (m: ModelDefinition) => boolean): readonly ModelDefinition[] {
+  return match(filter)
+    .with(P.nullish, () => MODELS)
+    .otherwise((fn) => MODELS.filter(fn));
+}

package/src/core/models/providers/openai.ts

@@ -0,0 +1,84 @@
+// ──────────────────────────────────────────────────────────────
+//  █████╗  ██████╗ ███████╗███╗   ██╗████████╗███████╗
+// ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔════╝
+// ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ███████╗
+// ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ╚════██║
+// ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ███████║
+// ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚══════╝
+//
+// AUTO-GENERATED — DO NOT EDIT
+// Update: pnpm --filter=@pkg/agent-sdk generate:models
+// ──────────────────────────────────────────────────────────────
+
+export const OPENAI_MODELS = [
+  {
+    id: "openai/gpt-5.2-codex",
+    category: "coding",
+    pricing: { prompt: 0.00000175, completion: 0.000014, inputCacheRead: 1.75e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5.2",
+    category: "chat",
+    pricing: { prompt: 0.00000175, completion: 0.000014, inputCacheRead: 1.75e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5.1",
+    category: "chat",
+    pricing: { prompt: 0.00000125, completion: 0.00001, inputCacheRead: 1.25e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5",
+    category: "chat",
+    pricing: { prompt: 0.00000125, completion: 0.00001, inputCacheRead: 1.25e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5-mini",
+    category: "chat",
+    pricing: { prompt: 2.5e-7, completion: 0.000002, inputCacheRead: 2.5e-8, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-5-nano",
+    category: "chat",
+    pricing: { prompt: 5e-8, completion: 4e-7, inputCacheRead: 5e-9, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4.1",
+    category: "chat",
+    pricing: { prompt: 0.000002, completion: 0.000008, inputCacheRead: 5e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4.1-mini",
+    category: "chat",
+    pricing: { prompt: 4e-7, completion: 0.0000016, inputCacheRead: 1e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4.1-nano",
+    category: "chat",
+    pricing: { prompt: 1e-7, completion: 4e-7, inputCacheRead: 2.5e-8, webSearch: 0.01 },
+  },
+  {
+    id: "openai/gpt-4o",
+    category: "chat",
+    pricing: { prompt: 0.0000025, completion: 0.00001, inputCacheRead: 0.00000125 },
+  },
+  {
+    id: "openai/gpt-4o-mini",
+    category: "chat",
+    pricing: { prompt: 1.5e-7, completion: 6e-7, inputCacheRead: 7.5e-8 },
+  },
+  {
+    id: "openai/o3",
+    category: "reasoning",
+    pricing: { prompt: 0.000002, completion: 0.000008, inputCacheRead: 5e-7, webSearch: 0.01 },
+  },
+  {
+    id: "openai/o3-mini",
+    category: "reasoning",
+    pricing: { prompt: 0.0000011, completion: 0.0000044, inputCacheRead: 5.5e-7 },
+  },
+  {
+    id: "openai/o4-mini",
+    category: "reasoning",
+    pricing: { prompt: 0.0000011, completion: 0.0000044, inputCacheRead: 2.75e-7, webSearch: 0.01 },
+  },
+] as const;