@alexkroman1/aai 0.12.2 → 1.0.2

package/host/runtime-barrel.ts

@@ -0,0 +1,25 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Runtime barrel — the full Node.js runtime engine for running agents.
+ *
+ * Used by aai-server (sandbox) and aai-cli (dev server).
+ */
+
+// biome-ignore-all lint/performance/noReExportAll: barrel file by design
+
+// Note: ./_runtime-conformance.ts is intentionally NOT re-exported here.
+// It imports `vitest`, which is a devDependency. Re-exporting it would pull
+// `vitest` into the production bundle of this barrel and break runtime
+// imports in environments without dev deps installed (e.g. the deployed
+// platform server). It is consumed directly by sibling test files.
+
+export * from "./builtin-tools.ts";
+export * from "./runtime.ts";
+export * from "./runtime-config.ts";
+export * from "./s2s.ts";
+export * from "./server.ts";
+export * from "./session.ts";
+export * from "./session-ctx.ts";
+export * from "./tool-executor.ts";
+export * from "./unstorage-kv.ts";
+export * from "./ws-handler.ts";

package/host/runtime-config.test.ts

@@ -0,0 +1,71 @@
+// Copyright 2025 the AAI authors. MIT license.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { jsonLogger } from "./runtime-config.ts";
+
+/** Parse the JSON line at `index` from `chunks`, failing if missing. */
+function parseEntry(chunks: string[], index: number): Record<string, unknown> {
+  const raw = chunks[index];
+  if (raw === undefined) throw new Error(`No chunk at index ${index}`);
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+describe("jsonLogger", () => {
+  let stdoutChunks: string[];
+  let stderrChunks: string[];
+
+  beforeEach(() => {
+    stdoutChunks = [];
+    stderrChunks = [];
+    vi.spyOn(process.stdout, "write").mockImplementation((chunk: string | Uint8Array) => {
+      stdoutChunks.push(String(chunk));
+      return true;
+    });
+    vi.spyOn(process.stderr, "write").mockImplementation((chunk: string | Uint8Array) => {
+      stderrChunks.push(String(chunk));
+      return true;
+    });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("outputs single-line JSON with timestamp, level, and msg", () => {
+    jsonLogger.info("hello world");
+    expect(stdoutChunks).toHaveLength(1);
+
+    const entry = parseEntry(stdoutChunks, 0);
+    expect(entry.level).toBe("info");
+    expect(entry.msg).toBe("hello world");
+    expect(entry.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  it("includes caller-provided context fields", () => {
+    jsonLogger.info("with ctx", { sessionId: "abc", count: 3 });
+
+    const entry = parseEntry(stdoutChunks, 0);
+    expect(entry.sessionId).toBe("abc");
+    expect(entry.count).toBe(3);
+  });
+
+  it("writes warn and error to stderr", () => {
+    jsonLogger.warn("a warning");
+    jsonLogger.error("an error");
+
+    expect(stderrChunks).toHaveLength(2);
+    expect(parseEntry(stderrChunks, 0).level).toBe("warn");
+    expect(parseEntry(stderrChunks, 1).level).toBe("error");
+    expect(stdoutChunks).toHaveLength(0);
+  });
+
+  it("writes info and debug to stdout", () => {
+    jsonLogger.info("info msg");
+    jsonLogger.debug("debug msg");
+
+    expect(stdoutChunks).toHaveLength(2);
+    expect(parseEntry(stdoutChunks, 0).level).toBe("info");
+    expect(parseEntry(stdoutChunks, 1).level).toBe("debug");
+    expect(stderrChunks).toHaveLength(0);
+  });
+});

package/host/runtime-config.ts

@@ -0,0 +1,99 @@
+// Copyright 2025 the AAI authors. MIT license.
+
+/**
+ * Runtime dependencies injected into the session pipeline.
+ *
+ * Defines the {@link Logger} interface, a default {@link consoleLogger},
+ * and the {@link S2SConfig} for Speech-to-Speech endpoint configuration.
+ */
+
+import { DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE } from "../sdk/constants.ts";
+
+/** Structured context attached to log messages. */
+export type LogContext = Record<string, unknown>;
+
+/**
+ * Structured logger interface. Used by tests to suppress output and by
+ * consumers to plug in custom logging backends.
+ *
+ * @example
+ * ```ts
+ * const myLogger: Logger = {
+ *   info: (msg, ctx) => myBackend.log("info", msg, ctx),
+ *   warn: (msg, ctx) => myBackend.log("warn", msg, ctx),
+ *   error: (msg, ctx) => myBackend.log("error", msg, ctx),
+ *   debug: (msg, ctx) => myBackend.log("debug", msg, ctx),
+ * };
+ * createServer({ agent, logger: myLogger });
+ * ```
+ */
+export type Logger = {
+  info(msg: string, ctx?: LogContext): void;
+  warn(msg: string, ctx?: LogContext): void;
+  error(msg: string, ctx?: LogContext): void;
+  debug(msg: string, ctx?: LogContext): void;
+};
+
+function consoleLog(fn: typeof console.log): Logger[keyof Logger] {
+  return (msg: string, ctx?: LogContext) => (ctx ? fn(msg, ctx) : fn(msg));
+}
+
+/** Default console-backed logger. */
+export const consoleLogger: Logger = {
+  info: consoleLog(console.log),
+  warn: consoleLog(console.warn),
+  error: consoleLog(console.error),
+  debug: consoleLog(console.debug),
+};
+
+/**
+ * Structured JSON logger for production diagnostics. Each log entry is a
+ * single-line JSON object with `timestamp`, `level`, `msg`, and any
+ * caller-provided context fields.
+ */
+function jsonLog(level: string) {
+  return (msg: string, ctx?: LogContext): void => {
+    const entry: Record<string, unknown> = {
+      timestamp: new Date().toISOString(),
+      level,
+      msg,
+    };
+
+    if (ctx) {
+      Object.assign(entry, ctx);
+    }
+
+    // Single-line JSON to stdout/stderr based on level.
+    const out = level === "error" || level === "warn" ? process.stderr : process.stdout;
+    out.write(`${JSON.stringify(entry)}\n`);
+  };
+}
+
+export const jsonLogger: Logger = {
+  info: jsonLog("info"),
+  warn: jsonLog("warn"),
+  error: jsonLog("error"),
+  debug: jsonLog("debug"),
+};
+
+/**
+ * Speech-to-Speech (S2S) endpoint configuration.
+ *
+ * Controls which AssemblyAI real-time WebSocket endpoint to connect to and
+ * the audio sample rates for input (microphone → STT) and output (TTS → speaker).
+ */
+export type S2SConfig = {
+  /** The WebSocket URL of the S2S real-time endpoint. */
+  wssUrl: string;
+  /** Sample rate in Hz for audio sent to STT (microphone capture). */
+  inputSampleRate: number;
+  /** Sample rate in Hz for TTS audio received from the server. */
+  outputSampleRate: number;
+};
+
+/** Default S2S endpoint configuration. */
+export const DEFAULT_S2S_CONFIG: S2SConfig = {
+  wssUrl: "wss://agents.assemblyai.com/v1/voice",
+  inputSampleRate: DEFAULT_STT_SAMPLE_RATE,
+  outputSampleRate: DEFAULT_TTS_SAMPLE_RATE,
+};