@startsimpli/llm 0.4.13 → 0.4.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.13",
+  "version": "0.4.14",
   "description": "Generic LLM service infrastructure — provider abstraction, retry logic, JSON extraction",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/__tests__/agent.test.ts

@@ -6,7 +6,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { runAgentTurn, buildToolRegistry } from '../agent/agent';
 import type { ToolProvider } from '../agent/types';
 import type { ILLMProvider } from '../providers/interface';
-import type { LLMResponse } from '../types';
+import type { LLMResponse, NativeToolResponse } from '../types';
 
 /** Returns the queued responses in order; repeats the last once exhausted. */
 class QueuedProvider implements ILLMProvider {
@@ -111,3 +111,76 @@ describe('runAgentTurn', () => {
     expect(() => buildToolRegistry([a, b])).toThrow(/duplicate tool name 'dup'/);
   });
 });
+
+/** Provider that supports NATIVE tool-calling: returns queued {content, toolCalls}. */
+class NativeQueuedProvider implements ILLMProvider {
+  readonly name = 'native';
+  readonly availableModels = ['n'] as const;
+  readonly defaultModel = 'n';
+  private i = 0;
+  constructor(private readonly turns: NativeToolResponse[]) {}
+  async generate(): Promise<LLMResponse> {
+    return { content: '', usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 }, model: 'n' };
+  }
+  async generateWithTools(): Promise<NativeToolResponse> {
+    const t = this.turns[Math.min(this.i, this.turns.length - 1)];
+    this.i += 1;
+    return t;
+  }
+  isAvailable() {
+    return true;
+  }
+}
+
+describe('runAgentTurn (native tool-calling)', () => {
+  it('uses the native loop, dispatches the structured call, returns plain-text final', async () => {
+    const handler = vi.fn(async (input: { types: string[] }) => ({ saved: input.types.length }));
+    const provider = new NativeQueuedProvider([
+      { content: null, toolCalls: [{ id: 'c1', name: 'save_schema', arguments: { types: ['Creator', 'Campaign'] } }] },
+      { content: 'All set — I created Creator and Campaign.', toolCalls: [] },
+    ]);
+    const foundry: ToolProvider = {
+      name: 'foundry',
+      tools: [{ name: 'save_schema', description: 'persist', inputSchema: { type: 'object' }, handler }],
+    };
+    const res = await runAgentTurn({
+      provider,
+      toolProviders: [foundry],
+      messages: msgs('track creators and campaigns'),
+      context: { tenant: 'x' },
+    });
+    expect(handler).toHaveBeenCalledWith({ types: ['Creator', 'Campaign'] }, { tenant: 'x' });
+    expect(res.toolCalls).toEqual([
+      { tool: 'save_schema', input: { types: ['Creator', 'Campaign'] }, output: { saved: 2 } },
+    ]);
+    // The final is the model's REAL text — no JSON echo, no synthesized fallback needed.
+    expect(res.finalText).toBe('All set — I created Creator and Campaign.');
+    expect(res.steps).toBe(2);
+  });
+
+  it('does NOT retry a satisfied call (unlike the forced-json string protocol)', async () => {
+    const handler = vi.fn(async () => ({ ok: true }));
+    const provider = new NativeQueuedProvider([
+      { content: null, toolCalls: [{ id: 'c1', name: 'save', arguments: {} }] },
+      { content: 'Done.', toolCalls: [] },
+    ]);
+    const p: ToolProvider = { name: 'p', tools: [{ name: 'save', description: 'd', handler }] };
+    const res = await runAgentTurn({ provider, toolProviders: [p], messages: msgs('go') });
+    expect(handler).toHaveBeenCalledTimes(1); // one clean call, not N retries
+    expect(res.finalText).toBe('Done.');
+  });
+
+  it('captures a handler error in the native loop', async () => {
+    const provider = new NativeQueuedProvider([
+      { content: null, toolCalls: [{ id: 'c1', name: 'boom', arguments: {} }] },
+      { content: 'handled', toolCalls: [] },
+    ]);
+    const p: ToolProvider = {
+      name: 'p',
+      tools: [{ name: 'boom', description: 'd', handler: async () => { throw new Error('db down'); } }],
+    };
+    const res = await runAgentTurn({ provider, toolProviders: [p], messages: msgs('go') });
+    expect(res.toolCalls[0].error).toBe('db down');
+    expect(res.finalText).toBe('handled');
+  });
+});

package/src/agent/agent.ts

@@ -10,6 +10,7 @@
  * changing the ToolProvider API.
  */
 import { extractJson } from '../utils/json-extraction';
+import type { NativeChatMessage, NativeToolSpec } from '../types';
 import type {
   AgentMessage,
   AgentToolCall,
@@ -75,9 +76,76 @@ function parseToolCall(content: string): ParsedToolCall | null {
   return { tool: obj.tool, input: 'input' in obj ? obj.input : {} };
 }
 
+/** Native (structured) tool loop for providers that implement generateWithTools.
+ *  Tool calls come back structured (no JSON-in-text parsing) and finals are real
+ *  text, so there's no ambiguity and the model doesn't re-emit a satisfied call. */
+async function runNativeToolLoop(
+  opts: RunAgentOptions,
+  registry: Map<string, ToolDefinition>,
+): Promise<AgentTurnResult> {
+  const { provider, context = {}, maxSteps = 6, generateOptions } = opts;
+  const system = opts.systemPrompt?.trim() ?? '';
+  const toolSpecs: NativeToolSpec[] = [...registry.values()].map((t) => ({
+    name: t.name,
+    description: t.description,
+    parameters: t.inputSchema ?? { type: 'object', properties: {} },
+  }));
+
+  const messages: NativeChatMessage[] = opts.messages.map((m) => ({
+    role: m.role === 'tool' ? 'tool' : m.role,
+    content: m.content,
+  }));
+  const toolCalls: AgentToolCall[] = [];
+  const toAgent = (): AgentMessage[] =>
+    messages.map((m) => ({ role: m.role, content: m.content ?? '' }));
+
+  for (let step = 1; step <= maxSteps; step++) {
+    const resp = await provider.generateWithTools!(messages, system, toolSpecs, generateOptions);
+    if (!resp.toolCalls.length) {
+      messages.push({ role: 'assistant', content: resp.content ?? '' });
+      return { finalText: resp.content ?? '', toolCalls, messages: toAgent(), steps: step, stoppedReason: 'final' };
+    }
+    messages.push({ role: 'assistant', content: resp.content, toolCalls: resp.toolCalls });
+    for (const call of resp.toolCalls) {
+      const record: AgentToolCall = { tool: call.name, input: call.arguments };
+      const tool = registry.get(call.name);
+      if (!tool) {
+        record.error = `unknown tool '${call.name}'`;
+        messages.push({ role: 'tool', toolCallId: call.id, content: `ERROR: ${record.error}` });
+      } else {
+        try {
+          const output = await tool.handler(call.arguments, context);
+          record.output = output;
+          messages.push({ role: 'tool', toolCallId: call.id, content: JSON.stringify(output ?? null) });
+        } catch (err) {
+          record.error = err instanceof Error ? err.message : String(err);
+          messages.push({ role: 'tool', toolCallId: call.id, content: `ERROR: ${record.error}` });
+        }
+      }
+      toolCalls.push(record);
+    }
+  }
+
+  // Budget exhausted — ask for a plain-text wrap-up (tool_choice stays 'auto').
+  const resp = await provider.generateWithTools!(
+    messages,
+    `${system}\n\nYou have reached the tool-call limit. Reply to the user now in plain text.`,
+    toolSpecs,
+    generateOptions,
+  );
+  messages.push({ role: 'assistant', content: resp.content ?? '' });
+  return { finalText: resp.content ?? '', toolCalls, messages: toAgent(), steps: maxSteps, stoppedReason: 'max_steps' };
+}
+
 export async function runAgentTurn(opts: RunAgentOptions): Promise<AgentTurnResult> {
   const { provider, toolProviders, context = {}, maxSteps = 6, generateOptions } = opts;
   const registry = buildToolRegistry(toolProviders);
+
+  // Prefer native structured tool-calling when the provider supports it.
+  if (typeof provider.generateWithTools === 'function' && registry.size > 0) {
+    return runNativeToolLoop(opts, registry);
+  }
+
   const protocol = toolProtocolPrompt(registry);
   const baseSystem = [opts.systemPrompt?.trim(), protocol].filter(Boolean).join('\n\n');
 

package/src/index.ts

@@ -11,6 +11,10 @@ export type {
   JsonExtractionResult,
   ValidationResult,
   LLMServiceConfig,
+  NativeToolSpec,
+  NativeToolCall,
+  NativeChatMessage,
+  NativeToolResponse,
 } from './types';
 export { LLM_DEFAULTS } from './types';
 

package/src/providers/interface.ts

@@ -1,4 +1,10 @@
-import type { LLMResponse, GenerateOptions } from '../types';
+import type {
+  LLMResponse,
+  GenerateOptions,
+  NativeToolSpec,
+  NativeChatMessage,
+  NativeToolResponse,
+} from '../types';
 
 /**
  * Contract that every LLM provider must implement.
@@ -29,6 +35,20 @@ export interface ILLMProvider {
     options?: GenerateOptions
   ): Promise<LLMResponse>;
 
+  /**
+   * Optional NATIVE (structured) tool-calling. Providers backed by a real tools
+   * API (OpenAI functions, Anthropic tool blocks) implement this so the agent
+   * harness can use structured tool calls + plain-text finals instead of the
+   * fragile JSON-in-text protocol. If omitted, the harness falls back to the
+   * string protocol — so existing providers (Mock, etc.) keep working unchanged.
+   */
+  generateWithTools?(
+    messages: NativeChatMessage[],
+    systemPrompt: string,
+    tools: NativeToolSpec[],
+    options?: GenerateOptions
+  ): Promise<NativeToolResponse>;
+
   /** Check if the provider is properly configured and available */
   isAvailable(): boolean;
 

package/src/providers/openai.ts

@@ -10,7 +10,14 @@
  */
 
 import type { ILLMProvider } from './interface';
-import type { LLMResponse, GenerateOptions, ProviderConfig } from '../types';
+import type {
+  LLMResponse,
+  GenerateOptions,
+  ProviderConfig,
+  NativeToolSpec,
+  NativeChatMessage,
+  NativeToolResponse,
+} from '../types';
 import { LLM_DEFAULTS } from '../types';
 import { LLMProviderError } from '../errors';
 import type { LLMErrorCode } from '../errors';
@@ -54,6 +61,30 @@ interface OpenAIErrorResponse {
   };
 }
 
+interface OpenAIToolCall {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+}
+
+interface OpenAIToolMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | null;
+  tool_calls?: OpenAIToolCall[];
+  tool_call_id?: string;
+}
+
+interface OpenAIToolsResponse {
+  id: string;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: { role: string; content: string | null; tool_calls?: OpenAIToolCall[] };
+    finish_reason: string;
+  }>;
+  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number };
+}
+
 const OPENAI_MODELS = [
   'gpt-5.2',
   'gpt-5.1',
@@ -210,6 +241,136 @@ export class OpenAIProvider implements ILLMProvider {
     }
   }
 
+  /**
+   * Native tool-calling via OpenAI's `tools` API. Unlike generate(), this does
+   * NOT force response_format=json_object — so the model returns structured
+   * tool_calls when calling a tool and plain text when it's done, which the agent
+   * harness can tell apart unambiguously (no JSON-in-text parsing).
+   */
+  async generateWithTools(
+    messages: NativeChatMessage[],
+    systemPrompt: string,
+    tools: NativeToolSpec[],
+    options?: GenerateOptions
+  ): Promise<NativeToolResponse> {
+    if (!this.isAvailable()) {
+      throw new LLMProviderError(
+        'OpenAI API key not configured',
+        'AUTHENTICATION_ERROR',
+        false,
+        undefined,
+        this.name
+      );
+    }
+
+    const model = options?.model ?? this.config.defaultModel;
+    const isBaseGpt5 = model === 'gpt-5' || model === 'gpt-5.1' || model === 'gpt-5.2';
+    const isFineTuned = model.startsWith('ft:');
+    const temperature = isBaseGpt5 && !isFineTuned
+      ? 1.0
+      : (options?.temperature ?? this.config.defaultTemperature);
+    const maxTokens = options?.maxTokens ?? this.config.defaultMaxTokens;
+    const timeout = options?.timeout ?? this.config.timeoutMs;
+
+    const oaiMessages: OpenAIToolMessage[] = [
+      { role: 'system', content: systemPrompt },
+      ...messages.map((m): OpenAIToolMessage => {
+        if (m.role === 'tool') {
+          return { role: 'tool', content: m.content ?? '', tool_call_id: m.toolCallId };
+        }
+        if (m.role === 'assistant' && m.toolCalls?.length) {
+          return {
+            role: 'assistant',
+            content: m.content,
+            tool_calls: m.toolCalls.map((tc) => ({
+              id: tc.id,
+              type: 'function',
+              function: { name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) },
+            })),
+          };
+        }
+        return { role: m.role, content: m.content ?? '' };
+      }),
+    ];
+
+    const requestBody = {
+      model,
+      messages: oaiMessages,
+      temperature,
+      max_tokens: maxTokens,
+      tools: tools.map((t) => ({
+        type: 'function' as const,
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+      })),
+      tool_choice: 'auto' as const,
+    };
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify(requestBody),
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({
+          error: { message: 'Unknown error' },
+        }))) as OpenAIErrorResponse;
+        throw this.handleApiError(response.status, errorData);
+      }
+
+      const data = (await response.json()) as OpenAIToolsResponse;
+      const choice = data.choices?.[0];
+      const msg = choice?.message;
+      const toolCalls = (msg?.tool_calls ?? []).map((tc) => {
+        let args: unknown = {};
+        try {
+          args = tc.function.arguments ? JSON.parse(tc.function.arguments) : {};
+        } catch {
+          args = { _raw: tc.function.arguments };
+        }
+        return { id: tc.id, name: tc.function.name, arguments: args };
+      });
+      return {
+        content: msg?.content ?? null,
+        toolCalls,
+        usage: {
+          promptTokens: data.usage?.prompt_tokens ?? 0,
+          completionTokens: data.usage?.completion_tokens ?? 0,
+          totalTokens: data.usage?.total_tokens ?? 0,
+        },
+        model: data.model,
+        finishReason: choice?.finish_reason,
+      };
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof LLMProviderError) throw error;
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new LLMProviderError(
+          `Request timed out after ${timeout}ms`,
+          'TIMEOUT',
+          true,
+          undefined,
+          this.name
+        );
+      }
+      throw new LLMProviderError(
+        `OpenAI tools request failed: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        'UNKNOWN_ERROR',
+        true,
+        undefined,
+        this.name
+      );
+    }
+  }
+
   estimateCost(
     promptTokens: number,
     completionTokens: number,

package/src/types.ts

@@ -41,6 +41,44 @@ export interface GenerateOptions {
   extra?: Record<string, unknown>;
 }
 
+/**
+ * Native (structured) tool-calling types. Providers that support a real tools API
+ * (OpenAI functions, Anthropic tool blocks) implement ILLMProvider.generateWithTools
+ * so the agent harness can use structured calls instead of the JSON-in-text protocol.
+ */
+export interface NativeToolSpec {
+  name: string;
+  description: string;
+  /** JSON Schema for the tool's arguments. */
+  parameters: Record<string, unknown>;
+}
+
+/** A structured tool call the model emitted (arguments already parsed from JSON). */
+export interface NativeToolCall {
+  id: string;
+  name: string;
+  arguments: unknown;
+}
+
+/** One message in a native tool-calling conversation. */
+export interface NativeChatMessage {
+  role: 'user' | 'assistant' | 'tool';
+  content: string | null;
+  /** Set on assistant turns that called tools. */
+  toolCalls?: NativeToolCall[];
+  /** Set on tool-result turns: which call this answers. */
+  toolCallId?: string;
+}
+
+/** Result of one native tool-calling round-trip. */
+export interface NativeToolResponse {
+  content: string | null;
+  toolCalls: NativeToolCall[];
+  usage?: TokenUsage;
+  model?: string;
+  finishReason?: string;
+}
+
 /**
  * Provider configuration — everything needed to construct a provider instance.
  */