@standardagents/builder 0.11.12 → 0.12.1

package/dist/test.d.ts

@@ -0,0 +1,256 @@
+import { ProviderFactoryConfig, LLMProviderInterface, ProviderRequest, ProviderResponse, ProviderStreamChunk } from '@standardagents/spec';
+import { l as ToolCall } from './index-DkbUJ4MM.js';
+import '@cloudflare/workers-types';
+import 'zod';
+import './types-pLkJx8vg.js';
+
+/**
+ * TestScript - Fluent builder for defining deterministic LLM response sequences.
+ *
+ * Use this to script exact responses for tests, enabling deterministic testing
+ * of agent behavior without calling real LLM APIs.
+ *
+ * @example
+ * ```typescript
+ * const script = TestScript.create()
+ *   .addTextResponse("Hello! How can I help?")
+ *   .addToolCallResponse([
+ *     { name: "search", arguments: { query: "test" } }
+ *   ])
+ *   .addTextResponse("Based on the search, here's what I found...");
+ * ```
+ */
+
+/**
+ * A single scripted response from the LLM
+ */
+interface ScriptedResponse {
+    /** Text content to return (null for pure tool calls) */
+    content?: string | null;
+    /** Tool calls to return (OpenAI format) */
+    toolCalls?: ToolCall[];
+    /** Reasoning content for o1-style models */
+    reasoningContent?: string | null;
+    /** Reasoning details for OpenRouter structured reasoning */
+    reasoningDetails?: any[];
+    /** Finish reason */
+    finishReason?: "stop" | "tool_calls" | "length" | "content_filter";
+    /** Token usage to report */
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        reasoningTokens?: number;
+    };
+    /** Simulate an error instead of a successful response */
+    error?: {
+        message: string;
+        code?: string;
+        status?: number;
+    };
+    /** Optional: Validate the input matches expectations */
+    expectInput?: InputExpectation;
+    /** Optional: Delay before responding (ms) - useful for streaming tests */
+    delayMs?: number;
+}
+/**
+ * Input validation expectations
+ */
+interface InputExpectation {
+    /** Check that a message contains this text (string or regex) */
+    containsMessage?: string | RegExp;
+    /** Check that a tool result for this tool exists */
+    containsToolResult?: {
+        toolName: string;
+        resultContains?: string;
+    };
+    /** Exact message count expected */
+    messageCount?: number;
+    /** Check that the system prompt contains this text */
+    systemPromptContains?: string | RegExp;
+}
+/**
+ * Configuration for streaming simulation
+ */
+interface StreamingConfig {
+    /** Characters per chunk */
+    chunkSize: number;
+    /** Delay between chunks in milliseconds */
+    chunkDelayMs: number;
+}
+/**
+ * Shorthand for creating tool calls
+ */
+interface ToolCallSpec {
+    name: string;
+    arguments: Record<string, any>;
+    id?: string;
+}
+/**
+ * Builder class for creating deterministic test scripts.
+ *
+ * Each call to addResponse/addTextResponse/etc adds a response to the sequence.
+ * When the TestProvider is used, it returns these responses in order.
+ */
+declare class TestScript {
+    private responses;
+    private streamingConfig?;
+    /**
+     * Create a new TestScript instance
+     */
+    static create(): TestScript;
+    /**
+     * Add a response to the sequence
+     */
+    addResponse(response: ScriptedResponse): this;
+    /**
+     * Add a simple text response (stops after response)
+     */
+    addTextResponse(content: string, options?: Partial<ScriptedResponse>): this;
+    /**
+     * Add a response with tool calls
+     */
+    addToolCallResponse(toolCalls: ToolCallSpec[], content?: string, options?: Partial<ScriptedResponse>): this;
+    /**
+     * Add an error response (simulates provider error)
+     */
+    addErrorResponse(message: string, code?: string, status?: number, options?: Partial<ScriptedResponse>): this;
+    /**
+     * Add a response with reasoning content (for o1-style models)
+     */
+    addReasoningResponse(content: string, reasoningContent: string, options?: Partial<ScriptedResponse>): this;
+    /**
+     * Enable streaming simulation for all responses
+     */
+    withStreamingSimulation(config: StreamingConfig): this;
+    /**
+     * Get all scripted responses
+     */
+    getResponses(): ScriptedResponse[];
+    /**
+     * Get streaming configuration
+     */
+    getStreamingConfig(): StreamingConfig | undefined;
+    /**
+     * Get total number of responses
+     */
+    get length(): number;
+    /**
+     * Check if script is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Create a clone of this script
+     */
+    clone(): TestScript;
+}
+
+/**
+ * TestProvider - Deterministic LLM provider for testing.
+ *
+ * Returns scripted responses in sequence, enabling deterministic testing
+ * of agent execution without real API calls.
+ *
+ * Implements the new LLMProviderInterface with generate() and stream() methods.
+ *
+ * @example
+ * ```typescript
+ * const script = TestScript.create()
+ *   .addTextResponse("Hello!")
+ *   .addToolCallResponse([{ name: "search", arguments: { q: "test" } }])
+ *   .addTextResponse("Found results.");
+ *
+ * const provider = createTestProvider(script);
+ * ```
+ */
+
+/**
+ * Extended provider config for TestProvider
+ */
+interface TestProviderConfig extends ProviderFactoryConfig {
+    /** The test script defining response sequence. If not provided, uses a default that echoes responses. */
+    script?: TestScript;
+    /** Whether to validate inputs match expectations (default: false) */
+    validateInputs?: boolean;
+    /** Log all requests for debugging (default: false) */
+    debugLog?: boolean;
+}
+/**
+ * Deterministic test provider that returns scripted LLM responses.
+ *
+ * Key features:
+ * - Returns responses in sequence as defined by TestScript
+ * - Supports streaming simulation
+ * - Optional input validation
+ * - Request logging for assertions
+ * - Clear error when script is exhausted
+ */
+declare class TestProvider implements LLMProviderInterface {
+    readonly name = "test";
+    readonly specificationVersion: "1";
+    private script;
+    private responseIndex;
+    private validateInputs;
+    private debugLog;
+    private requestLog;
+    private useDefaultResponse;
+    constructor(config: TestProviderConfig);
+    /**
+     * Test provider supports any model ID
+     */
+    supportsModel(_modelId: string): boolean;
+    /**
+     * Non-streaming generation - returns the next scripted response
+     */
+    generate(request: ProviderRequest): Promise<ProviderResponse>;
+    /**
+     * Streaming generation - yields chunks for the next scripted response
+     */
+    stream(request: ProviderRequest): Promise<AsyncIterable<ProviderStreamChunk>>;
+    /**
+     * Validate request matches expectations
+     */
+    private validateInput;
+    /**
+     * Simple token estimation (for mock usage stats)
+     */
+    private estimateTokens;
+    private sleep;
+    /**
+     * Get logged requests (for test assertions)
+     */
+    getRequestLog(): ProviderRequest[];
+    /**
+     * Get the last request made
+     */
+    getLastRequest(): ProviderRequest | undefined;
+    /**
+     * Reset provider state for reuse across tests
+     */
+    reset(): void;
+    /**
+     * Replace the script with a new one and reset
+     */
+    setScript(script: TestScript): void;
+    /**
+     * Check if all scripted responses were consumed
+     */
+    isScriptComplete(): boolean;
+    /**
+     * Get remaining unconsumed response count
+     */
+    remainingResponses(): number;
+    /**
+     * Get current response index
+     */
+    getCurrentIndex(): number;
+}
+/**
+ * Factory function to create a TestProvider
+ */
+declare function createTestProvider(script?: TestScript): TestProvider;
+/**
+ * ProviderFactory-compatible factory for test provider
+ */
+declare const test: (config: ProviderFactoryConfig) => LLMProviderInterface;
+
+export { type InputExpectation, type ScriptedResponse, TestProvider, type TestProviderConfig, TestScript, createTestProvider, test };

package/dist/test.js

@@ -0,0 +1,391 @@
+import { ProviderError } from '@standardagents/spec';
+
+// src/agents/providers/TestProvider.ts
+
+// src/agents/providers/TestScript.ts
+var TestScript = class _TestScript {
+  responses = [];
+  streamingConfig;
+  /**
+   * Create a new TestScript instance
+   */
+  static create() {
+    return new _TestScript();
+  }
+  /**
+   * Add a response to the sequence
+   */
+  addResponse(response) {
+    this.responses.push(response);
+    return this;
+  }
+  /**
+   * Add a simple text response (stops after response)
+   */
+  addTextResponse(content, options) {
+    return this.addResponse({
+      content,
+      finishReason: "stop",
+      ...options
+    });
+  }
+  /**
+   * Add a response with tool calls
+   */
+  addToolCallResponse(toolCalls, content, options) {
+    return this.addResponse({
+      content: content ?? null,
+      toolCalls: toolCalls.map((tc) => ({
+        id: tc.id || `call_${crypto.randomUUID().substring(0, 8)}`,
+        type: "function",
+        function: {
+          name: tc.name,
+          arguments: JSON.stringify(tc.arguments)
+        }
+      })),
+      finishReason: "tool_calls",
+      ...options
+    });
+  }
+  /**
+   * Add an error response (simulates provider error)
+   */
+  addErrorResponse(message, code, status, options) {
+    return this.addResponse({
+      error: { message, code, status },
+      ...options
+    });
+  }
+  /**
+   * Add a response with reasoning content (for o1-style models)
+   */
+  addReasoningResponse(content, reasoningContent, options) {
+    return this.addResponse({
+      content,
+      reasoningContent,
+      finishReason: "stop",
+      ...options
+    });
+  }
+  /**
+   * Enable streaming simulation for all responses
+   */
+  withStreamingSimulation(config) {
+    this.streamingConfig = config;
+    return this;
+  }
+  /**
+   * Get all scripted responses
+   */
+  getResponses() {
+    return [...this.responses];
+  }
+  /**
+   * Get streaming configuration
+   */
+  getStreamingConfig() {
+    return this.streamingConfig;
+  }
+  /**
+   * Get total number of responses
+   */
+  get length() {
+    return this.responses.length;
+  }
+  /**
+   * Check if script is empty
+   */
+  isEmpty() {
+    return this.responses.length === 0;
+  }
+  /**
+   * Create a clone of this script
+   */
+  clone() {
+    const cloned = new _TestScript();
+    cloned.responses = [...this.responses];
+    cloned.streamingConfig = this.streamingConfig ? { ...this.streamingConfig } : void 0;
+    return cloned;
+  }
+};
+
+// src/agents/providers/TestProvider.ts
+function contentToString(content) {
+  if (!content) return "";
+  if (typeof content === "string") return content;
+  return content.filter((part) => part.type === "text").map((part) => part.text).join(" ");
+}
+var TestProvider = class {
+  name = "test";
+  specificationVersion = "1";
+  script;
+  responseIndex = 0;
+  validateInputs;
+  debugLog;
+  requestLog = [];
+  useDefaultResponse;
+  constructor(config) {
+    this.useDefaultResponse = !config.script;
+    this.script = config.script ?? TestScript.create().addTextResponse("Test response received.");
+    this.validateInputs = config.validateInputs ?? false;
+    this.debugLog = config.debugLog ?? false;
+  }
+  /**
+   * Test provider supports any model ID
+   */
+  supportsModel(_modelId) {
+    return true;
+  }
+  /**
+   * Non-streaming generation - returns the next scripted response
+   */
+  async generate(request) {
+    if (this.debugLog) {
+      console.log(`[TestProvider] Request ${this.responseIndex + 1}:`, {
+        messageCount: request.messages.length,
+        lastMessage: request.messages.slice(-1)[0]
+      });
+    }
+    this.requestLog.push({ ...request });
+    if (request.signal?.aborted) {
+      throw new ProviderError("Request aborted", "timeout");
+    }
+    const responses = this.script.getResponses();
+    let scripted;
+    if (this.responseIndex >= responses.length) {
+      if (this.useDefaultResponse) {
+        scripted = responses[0];
+      } else {
+        const lastMessage = request.messages.slice(-1)[0];
+        const lastContent = lastMessage?.role === "user" ? contentToString(lastMessage.content) : lastMessage?.role === "assistant" ? lastMessage.content ?? "" : "";
+        throw new ProviderError(
+          `TestProvider: Script exhausted after ${this.responseIndex} responses. Expected ${responses.length} total requests. Received request with ${request.messages.length} messages. Last message role: "${lastMessage?.role}", content: "${String(lastContent).substring(0, 100)}..."`,
+          "invalid_request"
+        );
+      }
+    } else {
+      scripted = responses[this.responseIndex];
+    }
+    this.responseIndex++;
+    if (this.validateInputs && scripted.expectInput) {
+      this.validateInput(request, scripted.expectInput);
+    }
+    if (scripted.delayMs) {
+      await this.sleep(scripted.delayMs);
+    }
+    if (scripted.error) {
+      throw new ProviderError(
+        scripted.error.message,
+        scripted.error.code || "unknown",
+        scripted.error.status
+      );
+    }
+    const promptTokens = scripted.usage?.promptTokens ?? this.estimateTokens(request);
+    const completionTokens = scripted.usage?.completionTokens ?? Math.ceil((scripted.content?.length ?? 0) / 4);
+    const reasoningTokens = scripted.usage?.reasoningTokens ?? 0;
+    const toolCalls = scripted.toolCalls?.map((tc) => ({
+      id: tc.id,
+      name: tc.function.name,
+      arguments: JSON.parse(tc.function.arguments)
+    }));
+    const finishReason = scripted.finishReason === "tool_calls" ? "tool_calls" : "stop";
+    return {
+      content: scripted.content ?? null,
+      reasoning: scripted.reasoningContent ?? null,
+      reasoningDetails: scripted.reasoningDetails,
+      toolCalls,
+      finishReason,
+      usage: {
+        promptTokens,
+        completionTokens,
+        totalTokens: promptTokens + completionTokens,
+        reasoningTokens: reasoningTokens || void 0
+      }
+    };
+  }
+  /**
+   * Streaming generation - yields chunks for the next scripted response
+   */
+  async stream(request) {
+    const response = await this.generate(request);
+    const streamingConfig = this.script.getStreamingConfig();
+    const self = this;
+    return {
+      async *[Symbol.asyncIterator]() {
+        if (request.signal?.aborted) {
+          yield { type: "error", error: "Request aborted", code: "timeout" };
+          return;
+        }
+        if (response.content) {
+          if (streamingConfig) {
+            for (let i = 0; i < response.content.length; i += streamingConfig.chunkSize) {
+              const chunk = response.content.substring(i, i + streamingConfig.chunkSize);
+              yield { type: "content-delta", delta: chunk };
+              if (streamingConfig.chunkDelayMs > 0) {
+                await self.sleep(streamingConfig.chunkDelayMs);
+              }
+            }
+          } else {
+            yield { type: "content-delta", delta: response.content };
+          }
+          yield { type: "content-done" };
+        }
+        if (response.reasoning) {
+          yield { type: "reasoning-delta", delta: response.reasoning };
+          yield { type: "reasoning-done" };
+        }
+        if (response.toolCalls) {
+          for (const tc of response.toolCalls) {
+            yield { type: "tool-call-start", id: tc.id, name: tc.name };
+            yield { type: "tool-call-done", id: tc.id, arguments: tc.arguments };
+          }
+        }
+        yield {
+          type: "finish",
+          finishReason: response.finishReason,
+          usage: response.usage
+        };
+      }
+    };
+  }
+  /**
+   * Validate request matches expectations
+   */
+  validateInput(request, expectations) {
+    if (expectations.messageCount !== void 0) {
+      if (request.messages.length !== expectations.messageCount) {
+        throw new ProviderError(
+          `TestProvider: Expected ${expectations.messageCount} messages, got ${request.messages.length}`,
+          "invalid_request"
+        );
+      }
+    }
+    if (expectations.containsMessage) {
+      const pattern = expectations.containsMessage;
+      const found = request.messages.some((m) => {
+        const content = m.role === "user" ? contentToString(m.content) : m.role === "assistant" ? m.content : "";
+        if (!content) return false;
+        return typeof pattern === "string" ? content.includes(pattern) : pattern.test(content);
+      });
+      if (!found) {
+        throw new ProviderError(
+          `TestProvider: Expected message containing "${pattern}" not found`,
+          "invalid_request"
+        );
+      }
+    }
+    if (expectations.containsToolResult) {
+      const { toolName, resultContains } = expectations.containsToolResult;
+      const found = request.messages.some((m) => {
+        if (m.role !== "tool") return false;
+        const content = typeof m.content === "string" ? m.content : "";
+        return !resultContains || content.includes(resultContains);
+      });
+      if (!found) {
+        throw new ProviderError(
+          `TestProvider: Expected tool result for "${toolName}" not found`,
+          "invalid_request"
+        );
+      }
+    }
+    if (expectations.systemPromptContains) {
+      const pattern = expectations.systemPromptContains;
+      const systemMessage = request.messages.find((m) => m.role === "system");
+      const systemContent = systemMessage?.role === "system" ? systemMessage.content : "";
+      if (!systemContent) {
+        throw new ProviderError(`TestProvider: No system message found`, "invalid_request");
+      }
+      const matches = typeof pattern === "string" ? systemContent.includes(pattern) : pattern.test(systemContent);
+      if (!matches) {
+        throw new ProviderError(
+          `TestProvider: System prompt does not contain "${pattern}"`,
+          "invalid_request"
+        );
+      }
+    }
+  }
+  /**
+   * Simple token estimation (for mock usage stats)
+   */
+  estimateTokens(request) {
+    return request.messages.reduce((sum, m) => {
+      let content = "";
+      if (m.role === "system") {
+        content = m.content;
+      } else if (m.role === "user") {
+        content = contentToString(m.content);
+      } else if (m.role === "assistant") {
+        content = m.content ?? "";
+      } else if (m.role === "tool") {
+        content = typeof m.content === "string" ? m.content : "";
+      }
+      return sum + Math.ceil(content.length / 4);
+    }, 0);
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // ============ Test Utility Methods ============
+  /**
+   * Get logged requests (for test assertions)
+   */
+  getRequestLog() {
+    return [...this.requestLog];
+  }
+  /**
+   * Get the last request made
+   */
+  getLastRequest() {
+    return this.requestLog[this.requestLog.length - 1];
+  }
+  /**
+   * Reset provider state for reuse across tests
+   */
+  reset() {
+    this.responseIndex = 0;
+    this.requestLog = [];
+  }
+  /**
+   * Replace the script with a new one and reset
+   */
+  setScript(script) {
+    this.script = script;
+    this.reset();
+  }
+  /**
+   * Check if all scripted responses were consumed
+   */
+  isScriptComplete() {
+    return this.responseIndex === this.script.length;
+  }
+  /**
+   * Get remaining unconsumed response count
+   */
+  remainingResponses() {
+    return this.script.length - this.responseIndex;
+  }
+  /**
+   * Get current response index
+   */
+  getCurrentIndex() {
+    return this.responseIndex;
+  }
+};
+function createTestProvider(script) {
+  return new TestProvider({
+    apiKey: "test",
+    script
+  });
+}
+var test = (config) => {
+  return new TestProvider({
+    ...config,
+    script: config.script,
+    validateInputs: config.validateInputs,
+    debugLog: config.debugLog
+  });
+};
+
+export { TestProvider, TestScript, createTestProvider, test };
+//# sourceMappingURL=test.js.map
+//# sourceMappingURL=test.js.map