@guava-ai/guava-sdk 0.18.0 → 0.20.0

package/src/testing/chat.ts

@@ -0,0 +1,196 @@
+import { format as utilFormat } from "node:util";
+import type { TestSession } from "./session.ts";
+
+type SystemLevel = "log" | "info" | "debug" | "warn" | "error";
+type Message =
+  | { speaker: "agent" | "you"; text: string }
+  | { speaker: "system"; text: string; level: SystemLevel };
+
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED_BOLD = "\x1b[1;31m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+function moveTo(row: number, col: number): string {
+  return `\x1b[${row};${col}H`;
+}
+
+function wordWrap(text: string, width: number): string[] {
+  if (width <= 0 || text.length <= width) return [text];
+  const lines: string[] = [];
+  let remaining = text;
+  while (remaining.length > width) {
+    let breakAt = remaining.lastIndexOf(" ", width);
+    if (breakAt <= 0) breakAt = width;
+    lines.push(remaining.slice(0, breakAt));
+    remaining = remaining.slice(breakAt).trimStart();
+  }
+  if (remaining) lines.push(remaining);
+  return lines;
+}
+
+function lineColor(speaker: Message["speaker"], level?: SystemLevel): string {
+  if (speaker === "agent") return CYAN;
+  if (speaker === "you") return GREEN;
+  if (level === "warn") return YELLOW;
+  if (level === "error") return RED_BOLD;
+  return DIM;
+}
+
+function render(messages: Message[], inputBuf: string, sessionEnded: boolean): void {
+  const width = process.stdout.columns || 80;
+  const height = process.stdout.rows || 24;
+  const convHeight = Math.max(1, height - 2);
+
+  const allLines: { text: string; speaker: Message["speaker"]; level?: SystemLevel }[] = [];
+  for (const msg of messages) {
+    if (msg.speaker === "system") {
+      const wrapped = wordWrap(msg.text, width);
+      for (const line of wrapped) {
+        allLines.push({ text: line, speaker: "system", level: msg.level });
+      }
+    } else {
+      const prefix = msg.speaker === "agent" ? "agent: " : "you:   ";
+      const continuation = " ".repeat(prefix.length);
+      const innerWidth = Math.max(1, width - prefix.length);
+      const wrapped = wordWrap(msg.text, innerWidth);
+      wrapped.forEach((line, i) => {
+        allLines.push({ text: (i === 0 ? prefix : continuation) + line, speaker: msg.speaker });
+      });
+    }
+  }
+
+  const visibleLines = allLines.slice(-convHeight);
+
+  let out = "\x1b[?25l\x1b[2J\x1b[H";
+
+  for (let i = 0; i < convHeight; i++) {
+    out += moveTo(i + 1, 1);
+    const line = visibleLines[i];
+    if (line) {
+      const color = lineColor(line.speaker, line.level);
+      out += color + line.text.slice(0, width) + RESET;
+    }
+  }
+
+  out += moveTo(height - 1, 1) + "─".repeat(width);
+
+  if (sessionEnded) {
+    out += `${moveTo(height, 1)}Session ended. Press any key to exit.`;
+  } else {
+    const label = "you: ";
+    const maxLen = Math.max(0, width - label.length);
+    out += moveTo(height, 1) + label + inputBuf.slice(-maxLen);
+  }
+
+  out += "\x1b[?25h";
+  process.stdout.write(out);
+}
+
+function hookConsole(
+  messages: Message[],
+  getState: () => { inputBuf: string; sessionEnded: boolean; cleaned: boolean },
+): () => void {
+  const orig = {
+    log: console.log,
+    info: console.info,
+    debug: console.debug,
+    warn: console.warn,
+    error: console.error,
+  };
+
+  function makeHook(level: SystemLevel) {
+    return (...args: unknown[]) => {
+      const { cleaned, inputBuf, sessionEnded } = getState();
+      messages.push({
+        speaker: "system",
+        text: utilFormat(...args),
+        level,
+      });
+      if (!cleaned) render(messages, inputBuf, sessionEnded);
+    };
+  }
+
+  console.log = makeHook("log");
+  console.info = makeHook("info");
+  console.debug = makeHook("debug");
+  console.warn = makeHook("warn");
+  console.error = makeHook("error");
+
+  return () => {
+    console.log = orig.log;
+    console.info = orig.info;
+    console.debug = orig.debug;
+    console.warn = orig.warn;
+    console.error = orig.error;
+  };
+}
+
+export async function runChat(session: TestSession): Promise<void> {
+  const messages: Message[] = [];
+  let inputBuf = "";
+  let sessionEnded = false;
+  let cleaned = false;
+
+  const restoreConsole = hookConsole(messages, () => ({ inputBuf, sessionEnded, cleaned }));
+
+  // Consume agent messages in the background
+  void (async () => {
+    try {
+      while (true) {
+        const event = await session.recv();
+        if (event.message_type === "bot-tts") {
+          messages.push({ speaker: "agent", text: event.transcript });
+          if (!cleaned) render(messages, inputBuf, sessionEnded);
+        }
+      }
+    } catch {
+      if (!cleaned) {
+        sessionEnded = true;
+        render(messages, inputBuf, sessionEnded);
+      }
+    }
+  })();
+
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  render(messages, inputBuf, sessionEnded);
+
+  try {
+    await new Promise<void>((resolve) => {
+      const onData = (chunk: Buffer) => {
+        const ch = chunk[0]!;
+
+        if (sessionEnded || ch === 0x03 /* Ctrl+C */) {
+          process.stdin.off("data", onData);
+          resolve();
+          return;
+        }
+
+        if (ch === 0x0d || ch === 0x0a /* Enter */) {
+          const utterance = inputBuf.trim();
+          if (utterance) {
+            messages.push({ speaker: "you", text: utterance });
+            session.say(utterance);
+          }
+          inputBuf = "";
+        } else if (ch === 0x7f || ch === 0x08 /* Backspace */) {
+          inputBuf = inputBuf.slice(0, -1);
+        } else if (ch >= 0x20 && ch < 0x7f /* Printable ASCII */) {
+          inputBuf += String.fromCharCode(ch);
+        }
+
+        render(messages, inputBuf, sessionEnded);
+      };
+
+      process.stdin.on("data", onData);
+    });
+  } finally {
+    cleaned = true;
+    restoreConsole();
+    process.stdin.setRawMode(false);
+    process.stdout.write("\x1b[?25h\x1b[2J\x1b[H");
+  }
+}

package/src/testing/mocks.ts

@@ -0,0 +1,12 @@
+import { Call } from "../call.ts";
+import type { Command } from "../commands.ts";
+
+export class MockCall extends Call {
+  get commands(): Command[] {
+    return this._commandQueue;
+  }
+
+  setField(fieldName: string, fieldValue: unknown): void {
+    this._fieldValues[fieldName] = fieldValue;
+  }
+}

package/src/testing/protocol.ts

@@ -0,0 +1,40 @@
+import * as z from "zod";
+
+export const Ping = z.object({ message_type: z.literal("ping") });
+export type Ping = z.infer<typeof Ping>;
+
+export const Pong = z.object({ message_type: z.literal("pong") });
+export type Pong = z.infer<typeof Pong>;
+
+export const InjectASR = z.object({
+  message_type: z.literal("inject-asr"),
+  utterance: z.string(),
+});
+export type InjectASR = z.infer<typeof InjectASR>;
+
+export const WaitForTurn = z.object({
+  message_type: z.literal("wait-for-caller-turn"),
+  request_id: z.string(),
+});
+export type WaitForTurn = z.infer<typeof WaitForTurn>;
+
+export const BotTTS = z.object({
+  message_type: z.literal("bot-tts"),
+  transcript: z.string(),
+});
+export type BotTTS = z.infer<typeof BotTTS>;
+
+export const TurnStarted = z.object({
+  message_type: z.literal("caller-turn-started"),
+  request_id: z.string(),
+});
+export type TurnStarted = z.infer<typeof TurnStarted>;
+
+export const SessionStarted = z.object({
+  message_type: z.literal("session-started"),
+  session_id: z.string(),
+});
+export type SessionStarted = z.infer<typeof SessionStarted>;
+
+export const TestingEvent = z.discriminatedUnion("message_type", [Ping, Pong, BotTTS, TurnStarted]);
+export type TestingEvent = z.infer<typeof TestingEvent>;

package/src/testing/session.ts

@@ -0,0 +1,218 @@
+import type WebSocket from "ws";
+import { randomBytes } from "node:crypto";
+import * as z from "zod";
+import { type BotTTS, type InjectASR, TestingEvent } from "./protocol.ts";
+import type { Client } from "../client.ts";
+import { _generate } from "../helpers/llm.ts";
+
+type SessionEvent = InjectASR | BotTTS;
+
+const _evalResponseSchema = z.object({
+  results: z.array(
+    z.object({
+      passed: z.boolean(),
+      reasoning: z.string().optional(),
+    }),
+  ),
+});
+
+export class TestSession {
+  private readonly _ws: WebSocket;
+  private readonly _client: Client;
+  private _sessionEvents: SessionEvent[] = [];
+  private _recvBuffer: TestingEvent[] = [];
+  private _recvWaiters: Array<{
+    resolve: (v: TestingEvent) => void;
+    reject: (e: Error) => void;
+  }> = [];
+  private _closed = false;
+
+  executedActions: string[] = [];
+  terminationReason: string | null = null;
+
+  /** @internal */
+  get _events(): ReadonlyArray<InjectASR | BotTTS> {
+    return this._sessionEvents;
+  }
+
+  constructor(ws: WebSocket, client: Client) {
+    this._ws = ws;
+    this._client = client;
+
+    ws.on("message", (data) => {
+      let event: TestingEvent;
+      try {
+        event = TestingEvent.parse(JSON.parse(data.toString()));
+      } catch {
+        return;
+      }
+      const waiter = this._recvWaiters.shift();
+      if (waiter) {
+        waiter.resolve(event);
+      } else {
+        this._recvBuffer.push(event);
+      }
+    });
+
+    const onClose = () => {
+      this._closed = true;
+      const err = new Error("Test session WebSocket closed");
+      for (const waiter of this._recvWaiters) {
+        waiter.reject(err);
+      }
+      this._recvWaiters = [];
+    };
+
+    ws.once("close", onClose);
+    ws.once("error", onClose);
+  }
+
+  private _rawSend(msg: object): void {
+    this._ws.send(JSON.stringify(msg));
+  }
+
+  say(utterance: string): void {
+    const msg: InjectASR = { message_type: "inject-asr", utterance };
+    this._sessionEvents.push(msg);
+    this._rawSend(msg);
+  }
+
+  async recv(): Promise<TestingEvent> {
+    while (true) {
+      let event: TestingEvent;
+
+      const buffered = this._recvBuffer.shift();
+      if (buffered !== undefined) {
+        event = buffered;
+      } else {
+        event = await new Promise<TestingEvent>((resolve, reject) => {
+          if (this._closed) {
+            reject(new Error("Test session WebSocket closed"));
+            return;
+          }
+          this._recvWaiters.push({ resolve, reject });
+        });
+      }
+
+      if (event.message_type === "ping") {
+        this._rawSend({ message_type: "pong" });
+        continue;
+      }
+
+      if (event.message_type === "bot-tts") {
+        this._sessionEvents.push(event);
+      }
+
+      return event;
+    }
+  }
+
+  getTranscript(): string {
+    const lines: string[] = [];
+    for (const event of this._sessionEvents) {
+      if (event.message_type === "inject-asr") {
+        lines.push(`[caller]: ${event.utterance}`);
+      } else {
+        lines.push(`[agent]: ${event.transcript}`);
+      }
+    }
+    return lines.join("\n");
+  }
+
+  async waitForTurn(): Promise<void> {
+    const requestId = randomBytes(8).toString("hex");
+    this._rawSend({ message_type: "wait-for-caller-turn", request_id: requestId });
+    while (true) {
+      const event = await this.recv();
+      if (event.message_type === "caller-turn-started" && event.request_id === requestId) {
+        return;
+      }
+    }
+  }
+
+  async waitForEnd(): Promise<void> {
+    try {
+      while (true) {
+        await this.recv();
+      }
+    } catch {
+      // Connection closed — session has ended.
+    }
+  }
+
+  async evaluate({
+    passCriteria = [],
+    failCriteria = [],
+  }: {
+    passCriteria?: string[];
+    failCriteria?: string[];
+  } = {}): Promise<void> {
+    const allCriteria = [
+      ...passCriteria.map((c) => ({ kind: "pass" as const, criterion: c })),
+      ...failCriteria.map((c) => ({ kind: "fail" as const, criterion: c })),
+    ];
+
+    if (allCriteria.length === 0) return;
+
+    const transcript = this.getTranscript();
+    const criteriaList = allCriteria.map((c, i) => `${i + 1}. ${c.criterion}`).join("\n");
+
+    const prompt = `Evaluate whether the following criteria are met based on the conversation transcript below.
+Return one result object per criterion in the same order as listed.
+
+Transcript:
+${transcript || "(empty — no conversation occurred)"}
+
+Criteria:
+${criteriaList}`;
+
+    const evalSchema = {
+      type: "object",
+      properties: {
+        results: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              passed: { type: "boolean" },
+              reasoning: { type: "string" },
+            },
+            required: ["passed"],
+            additionalProperties: false,
+          },
+        },
+      },
+      required: ["results"],
+      additionalProperties: false,
+    };
+
+    const evalResponse = _evalResponseSchema.parse(
+      JSON.parse(await _generate(this._client, prompt, evalSchema)),
+    );
+
+    if (evalResponse.results.length !== allCriteria.length) {
+      throw new Error(
+        `Evaluation returned ${evalResponse.results.length} results for ${allCriteria.length} criteria.`,
+      );
+    }
+
+    const failures: string[] = [];
+    for (let i = 0; i < allCriteria.length; i++) {
+      const { kind, criterion } = allCriteria[i]!;
+      const result = evalResponse.results[i]!;
+      if (kind === "pass" && !result.passed) {
+        let msg = `Pass criterion not met: ${JSON.stringify(criterion)}`;
+        if (result.reasoning) msg += ` — ${result.reasoning}`;
+        failures.push(msg);
+      } else if (kind === "fail" && result.passed) {
+        let msg = `Fail criterion triggered: ${JSON.stringify(criterion)}`;
+        if (result.reasoning) msg += ` — ${result.reasoning}`;
+        failures.push(msg);
+      }
+    }
+
+    if (failures.length > 0) {
+      throw new Error(`Session evaluation failed:\n${failures.map((f) => `  • ${f}`).join("\n")}`);
+    }
+  }
+}

package/src/utils.ts

@@ -1,3 +1,4 @@
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
@@ -15,8 +16,21 @@ export function getPlatformConfigDir(): string {
   return process.env.XDG_CONFIG_HOME ?? path.join(home, ".config");
 }
 
+export function getCliConfigPath(): string {
+  return path.join(getPlatformConfigDir(), "guava", "config.json");
+}
+
 export function getBaseUrl(): string {
-  return process.env.GUAVA_BASE_URL ?? DEFAULT_BASE_URL;
+  if (process.env.GUAVA_BASE_URL) return process.env.GUAVA_BASE_URL;
+
+  // Try reading from the CLI config.
+  const configPath = getCliConfigPath();
+  if (fs.existsSync(configPath)) {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8")) as { base_url?: string };
+    if (config.base_url) return config.base_url;
+  }
+
+  return DEFAULT_BASE_URL;
 }
 
 class HttpStatusError extends Error {
@@ -31,6 +45,10 @@ class HttpStatusError extends Error {
   }
 }
 
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 export async function fetchOrThrow(
   input: RequestInfo | URL,
   init?: RequestInit,

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.18.0";
+export const SDK_VERSION = "0.20.0";