fix!: build judge input as string and narrow Runner.run signature

Aligns the JS AI SDK with the spec change implemented in
launchdarkly/python-server-sdk-ai#165 and launchdarkly/sdk-specs#160.

Judges now build a single formatted string ("MESSAGE HISTORY:\n...\n\n
RESPONSE TO EVALUATE:\n...") and pass it to the runner instead of an
interpolated message list. Legacy judge configs that contain
{{message_history}} or {{response_to_evaluate}} placeholders in
non-system messages are stripped at config-construction time so old and
new flag values both work without behavioral surprises.

BREAKING CHANGE: Runner.run is narrowed from
`run(input: string | LDMessage[], outputType?)` to
`run(input: string, outputType?)`. The OpenAI, LangChain, and Vercel
provider runners no longer accept a pre-built message array; they
always prepend any config messages and append the prompt as a user
turn. The Judge no longer interpolates {{message_history}} or
{{response_to_evaluate}} into config messages — the SDK builds the
input string directly and the runner receives that string verbatim.
The "Judge configuration must include messages" early-return was
removed; a judge with no messages now proceeds to invoke the runner
with the formatted input.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jsonbailey

packages/ai-providers/server-ai-langchain/__tests__/LangChainModelRunner.test.ts

@@ -1,6 +1,6 @@
 import { AIMessage } from '@langchain/core/messages';
 
-import type { LDAICompletionConfig, LDMessage } from '@launchdarkly/server-sdk-ai';
+import type { LDAICompletionConfig } from '@launchdarkly/server-sdk-ai';
 
 import { LangChainModelRunner } from '../src/LangChainModelRunner';
 
@@ -63,25 +63,6 @@ describe('LangChainModelRunner', () => {
     expect(passed[1].content).toBe('hi');
   });
 
-  it('uses a LDMessage[] as-is without prepending config messages', async () => {
-    const response = new AIMessage('direct reply');
-    mockLLM.invoke.mockResolvedValue(response);
-
-    const configWithMessages: LDAICompletionConfig = {
-      ...baseConfig,
-      messages: [{ role: 'system', content: 'You are X' }],
-    };
-    const r = new LangChainModelRunner(mockLLM, configWithMessages, mockLogger);
-    const inputMessages: LDMessage[] = [
-      { role: 'user', content: 'direct question' },
-    ];
-    await r.run(inputMessages);
-
-    const passed = mockLLM.invoke.mock.calls[0][0];
-    expect(passed).toHaveLength(1);
-    expect(passed[0].content).toBe('direct question');
-  });
-
   it('marks success=false and warns when content is non-string (multimodal)', async () => {
     mockLLM.invoke.mockResolvedValue(new AIMessage([{ type: 'image' }] as any));
 

packages/ai-providers/server-ai-langchain/src/LangChainModelRunner.ts

@@ -29,19 +29,20 @@ export class LangChainModelRunner implements Runner {
   }
 
   /**
-   * Run the LangChain model with the given prompt.
+   * Run the LangChain model with the given user prompt.
    *
-   * @param input The user prompt string or a pre-built message array to send to the model.
-   *   When a string is provided, config messages are prepended before the user prompt.
-   *   When an {@link LDMessage} array is provided, it is used as-is (config messages are
-   *   not prepended).
+   * Prepends any messages defined in the AI config (system prompt, etc.) before
+   * the user prompt.
+   *
+   * @param input The user prompt string.
    * @param outputType Optional JSON schema for structured output. When provided,
    *   the parsed result is exposed via {@link RunnerResult.parsed}.
    */
-  async run(input: string | LDMessage[], outputType?: Record<string, unknown>): Promise<RunnerResult> {
-    const messages: LDMessage[] = Array.isArray(input)
-      ? input
-      : [...(this._config.messages ?? []), { role: 'user', content: input }];
+  async run(input: string, outputType?: Record<string, unknown>): Promise<RunnerResult> {
+    const messages: LDMessage[] = [
+      ...(this._config.messages ?? []),
+      { role: 'user', content: input },
+    ];
 
     if (outputType !== undefined) {
       return this._runStructured(messages, outputType);

packages/ai-providers/server-ai-openai/__tests__/OpenAIModelRunner.test.ts

@@ -75,27 +75,6 @@ describe('OpenAIModelRunner', () => {
       });
     });
 
-    it('passes a LDMessage[] input directly without prepending config messages', async () => {
-      const mockResponse = {
-        choices: [{ message: { content: 'Evaluation result' } }],
-        usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
-      };
-      (mockOpenAI.chat.completions.create as jest.Mock).mockResolvedValue(mockResponse as any);
-
-      const messages = [
-        { role: 'system' as const, content: 'You are a judge' },
-        { role: 'user' as const, content: 'Rate this: hello' },
-      ];
-      const result = await runner.run(messages);
-
-      expect(mockOpenAI.chat.completions.create).toHaveBeenCalledWith({
-        model: 'gpt-3.5-turbo',
-        messages,
-      });
-      expect(result.content).toBe('Evaluation result');
-      expect(result.metrics.success).toBe(true);
-    });
-
     it('marks the result unsuccessful when response has no content', async () => {
       const mockResponse = { choices: [{ message: {} }] };
       (mockOpenAI.chat.completions.create as jest.Mock).mockResolvedValue(mockResponse as any);

packages/ai-providers/server-ai-openai/src/OpenAIAgentRunner.ts

@@ -48,7 +48,7 @@ export class OpenAIAgentRunner implements Runner {
 
   async run(input: string, _outputType?: Record<string, unknown>): Promise<RunnerResult> {
     try {
-      const result = await this._agentRun(this._agent, String(input), { maxTurns: MAX_TURNS });
+      const result = await this._agentRun(this._agent, input, { maxTurns: MAX_TURNS });
 
       const toolCalls = getToolCallsFromRunItems(result.newItems ?? []).reduce(
         (acc: string[], fnName: string) => {

packages/ai-providers/server-ai-openai/src/OpenAIModelRunner.ts

@@ -32,20 +32,20 @@ export class OpenAIModelRunner implements Runner {
   }
 
   /**
-   * Run the OpenAI model with the given prompt or message array.
+   * Run the OpenAI model with the given user prompt.
    *
-   * When `input` is a string it is wrapped as a user turn and appended to any
-   * messages defined in the config. When `input` is already a `LDMessage[]`
-   * (e.g. when called from the Judge evaluation path) it is used as-is.
+   * Prepends any messages defined in the AI config (system prompt,
+   * instructions, etc.) before the user prompt.
    *
-   * @param input The user prompt string, or a pre-built message array.
+   * @param input The user prompt string.
    * @param outputType Optional JSON schema for structured output. When provided,
    *   the response is parsed and exposed via {@link RunnerResult.parsed}.
    */
-  async run(input: string | LDMessage[], outputType?: Record<string, unknown>): Promise<RunnerResult> {
-    const messages: LDMessage[] = Array.isArray(input)
-      ? input
-      : [...(this._config.messages ?? []), { role: 'user', content: input }];
+  async run(input: string, outputType?: Record<string, unknown>): Promise<RunnerResult> {
+    const messages: LDMessage[] = [
+      ...(this._config.messages ?? []),
+      { role: 'user', content: input },
+    ];
 
     if (outputType !== undefined) {
       return this._runStructured(messages, outputType);

packages/ai-providers/server-ai-vercel/__tests__/VercelModelRunner.test.ts

@@ -90,30 +90,6 @@ describe('VercelModelRunner', () => {
       expect(out.metrics.usage).toEqual({ total: 100, input: 40, output: 60 });
     });
 
-    it('uses a LDMessage[] directly without prepending config messages', async () => {
-      (generateText as jest.Mock).mockResolvedValue({
-        text: 'direct',
-        usage: { totalTokens: 5, promptTokens: 2, completionTokens: 3 },
-      });
-
-      const configWithMessages: LDAICompletionConfig = {
-        ...baseConfig,
-        messages: [{ role: 'system', content: 'Should not appear' }],
-      };
-      const r = new VercelModelRunner(fakeModel as any, configWithMessages, {}, mockLogger);
-      const prebuilt = [
-        { role: 'system' as const, content: 'Custom system' },
-        { role: 'user' as const, content: 'Direct input' },
-      ];
-      await r.run(prebuilt);
-
-      expect(generateText).toHaveBeenCalledWith({
-        model: fakeModel,
-        messages: prebuilt,
-        experimental_telemetry: { isEnabled: true },
-      });
-    });
-
     it('returns success=false when generateText throws', async () => {
       const err = new Error('boom');
       (generateText as jest.Mock).mockRejectedValue(err);

packages/ai-providers/server-ai-vercel/src/VercelModelRunner.ts

@@ -36,19 +36,20 @@ export class VercelModelRunner implements Runner {
   }
 
   /**
-   * Run the Vercel AI model with the given prompt.
+   * Run the Vercel AI model with the given user prompt.
    *
-   * @param input The user prompt string, or a pre-built message array. When a
-   *   string is supplied the config's system messages are prepended automatically.
-   *   When a `LDMessage[]` is supplied it is used as-is (config messages are NOT
-   *   prepended — the caller is responsible for the full message list).
+   * Prepends any messages defined in the AI config (system prompt, etc.) before
+   * the user prompt.
+   *
+   * @param input The user prompt string.
    * @param outputType Optional JSON schema for structured output. When provided,
    *   the parsed object is exposed via {@link RunnerResult.parsed}.
    */
-  async run(input: string | LDMessage[], outputType?: Record<string, unknown>): Promise<RunnerResult> {
-    const messages: LDMessage[] = Array.isArray(input)
-      ? input
-      : [...(this._config.messages ?? []), { role: 'user', content: input }];
+  async run(input: string, outputType?: Record<string, unknown>): Promise<RunnerResult> {
+    const messages: LDMessage[] = [
+      ...(this._config.messages ?? []),
+      { role: 'user', content: input },
+    ];
 
     if (outputType !== undefined) {
       return this._runStructured(messages, outputType);