@startsimpli/llm 0.4.13 → 0.4.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/llm",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "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/__tests__/anthropic-provider.test.ts

@@ -0,0 +1,171 @@
+/**
+ * What the Anthropic provider actually PUTS ON THE WIRE (bd startsim-768w.38).
+ *
+ * These assert the request body, not the response, because the bug they exist
+ * for was a 400 from a parameter we sent — `temperature` is rejected outright by
+ * the Claude 5 family, so a provider that always sends it can never call the
+ * models we want to be on.
+ *
+ * The acceptance boundary below is not invented. It was measured against
+ * api.anthropic.com with a real key on 2026-08-10:
+ *
+ *   claude-sonnet-5      temperature -> 400 `temperature` is deprecated for this model.
+ *   claude-opus-5        temperature -> 400   (same; also top_p, top_k)
+ *   claude-fable-5       temperature -> 400
+ *   claude-opus-4-8      temperature -> 400
+ *   claude-opus-4-7      temperature -> 400
+ *   claude-opus-4-6      temperature -> 200
+ *   claude-sonnet-4-6    temperature -> 200
+ *   claude-sonnet-4-5-*  temperature -> 200
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+import { AnthropicProvider } from '../providers/anthropic';
+import { LLMProviderError } from '../errors';
+
+interface Sent {
+  model: string;
+  temperature?: number;
+  top_p?: number;
+  max_tokens: number;
+}
+
+const OK_BODY = {
+  id: 'msg_1',
+  type: 'message',
+  role: 'assistant',
+  content: [{ type: 'text', text: '{"ok":true}' }],
+  model: 'server-reported-model',
+  stop_reason: 'end_turn',
+  usage: { input_tokens: 10, output_tokens: 4 },
+};
+
+function ok() {
+  return {
+    ok: true,
+    status: 200,
+    json: async () => OK_BODY,
+  } as unknown as Response;
+}
+
+function deprecated(param: string) {
+  return {
+    ok: false,
+    status: 400,
+    json: async () => ({
+      type: 'error',
+      error: {
+        type: 'invalid_request_error',
+        message: `\`${param}\` is deprecated for this model.`,
+      },
+    }),
+  } as unknown as Response;
+}
+
+let sent: Sent[];
+let fetchMock: ReturnType<typeof vi.fn>;
+
+function provider(defaultModel: string) {
+  return new AnthropicProvider({ apiKey: 'sk-ant-test', defaultModel, defaultTemperature: 0.2 });
+}
+
+beforeEach(() => {
+  sent = [];
+  fetchMock = vi.fn(async (_url: unknown, init: RequestInit) => {
+    sent.push(JSON.parse(String(init.body)) as Sent);
+    return ok();
+  });
+  vi.stubGlobal('fetch', fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('AnthropicProvider request body — sampling parameters', () => {
+  it('omits temperature for a Claude 5 model that rejects it', async () => {
+    await provider('claude-sonnet-5').generate('hi', 'sys', { temperature: 0.2 });
+
+    expect(sent).toHaveLength(1);
+    expect(sent[0].model).toBe('claude-sonnet-5');
+    expect(sent[0]).not.toHaveProperty('temperature');
+    // The parameters that ARE required still go, or the call is malformed.
+    expect(sent[0].max_tokens).toBeGreaterThan(0);
+  });
+
+  it.each(['claude-opus-5', 'claude-fable-5', 'claude-opus-4-8', 'claude-opus-4-7'])(
+    'omits temperature for %s',
+    async (model) => {
+      await provider(model).generate('hi', 'sys', { temperature: 0.2 });
+      expect(sent[0]).not.toHaveProperty('temperature');
+    },
+  );
+
+  it('still sends temperature for a 4.6-era model, which accepts it', async () => {
+    await provider('claude-sonnet-4-6').generate('hi', 'sys', { temperature: 0.2 });
+
+    expect(sent[0].model).toBe('claude-sonnet-4-6');
+    expect(sent[0].temperature).toBe(0.2);
+  });
+
+  it.each(['claude-opus-4-6', 'claude-sonnet-4-5-20250929', 'claude-haiku-4-5-20251001'])(
+    'still sends temperature for %s',
+    async (model) => {
+      await provider(model).generate('hi', 'sys', { temperature: 0.35 });
+      expect(sent[0].temperature).toBe(0.35);
+    },
+  );
+
+  it('omits temperature for a model id it has never heard of', async () => {
+    // The whole point of the allowlist shape: an id that does not exist yet gets
+    // the request that CANNOT 400, not the one that historically could.
+    await provider('claude-sonnet-7-hypothetical').generate('hi', 'sys', { temperature: 0.2 });
+    expect(sent[0]).not.toHaveProperty('temperature');
+  });
+
+  it('names a model that is actually callable as the package default', async () => {
+    // The old default, claude-sonnet-4-20250514, was retired and 404s. A default
+    // nobody can call is a broken default.
+    const p = new AnthropicProvider({ apiKey: 'sk-ant-test' });
+    await p.generate('hi', 'sys');
+    expect(sent[0].model).toBe(p.defaultModel);
+    expect(p.availableModels).toContain(p.defaultModel);
+  });
+});
+
+describe('AnthropicProvider — recovering from a parameter the model rejects', () => {
+  it('drops the named parameter and retries once when the API calls it deprecated', async () => {
+    // A model on the allowlist that the API has since changed its mind about:
+    // the safety net must un-break it without waiting for a release.
+    fetchMock.mockImplementationOnce(async (_url: unknown, init: RequestInit) => {
+      sent.push(JSON.parse(String(init.body)) as Sent);
+      return deprecated('temperature');
+    });
+
+    const response = await provider('claude-opus-4-6').generate('hi', 'sys', { temperature: 0.2 });
+
+    expect(sent).toHaveLength(2);
+    expect(sent[0].temperature).toBe(0.2);
+    expect(sent[1]).not.toHaveProperty('temperature');
+    expect(response.content).toBe('{"ok":true}');
+  });
+
+  it('does not retry a 400 that is not about a deprecated parameter', async () => {
+    fetchMock.mockImplementation(async (_url: unknown, init: RequestInit) => {
+      sent.push(JSON.parse(String(init.body)) as Sent);
+      return {
+        ok: false,
+        status: 400,
+        json: async () => ({
+          type: 'error',
+          error: { type: 'invalid_request_error', message: 'messages: at least one message required' },
+        }),
+      } as unknown as Response;
+    });
+
+    await expect(provider('claude-sonnet-4-6').generate('hi', 'sys')).rejects.toBeInstanceOf(
+      LLMProviderError,
+    );
+    expect(sent).toHaveLength(1);
+  });
+});

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';
 
@@ -19,7 +23,11 @@ export type { ILLMProvider } from './providers/interface';
 
 // Provider implementations
 export { OpenAIProvider, createOpenAIProvider } from './providers/openai';
-export { AnthropicProvider, createAnthropicProvider } from './providers/anthropic';
+export {
+  AnthropicProvider,
+  createAnthropicProvider,
+  supportsSamplingParams,
+} from './providers/anthropic';
 export { MockLLMProvider, setMockBehavior, resetMockBehavior } from './providers/mock';
 export type { MockBehavior } from './providers/mock';
 

package/src/providers/anthropic.ts

@@ -2,7 +2,7 @@
  * Anthropic Provider Implementation
  *
  * Uses native fetch to minimize dependencies.
- * Supports Claude 4 and Claude 3.x models.
+ * Supports the Claude 5 family and the Claude 4.x models still served.
  */
 
 import type { ILLMProvider } from './interface';
@@ -21,6 +21,10 @@ interface AnthropicRequest {
   max_tokens: number;
   messages: AnthropicMessage[];
   system?: string;
+  /**
+   * Sent ONLY for models known to accept it — see `supportsSamplingParams`.
+   * The Claude 5 family rejects it outright.
+   */
   temperature?: number;
 }
 
@@ -45,30 +49,94 @@ interface AnthropicErrorResponse {
   };
 }
 
+/**
+ * The models this provider advertises. Verified callable against
+ * api.anthropic.com on 2026-08-10 — every id in the previous version of this
+ * list except the two 4.6 entries had been retired and returned 404, which is
+ * the same staleness failure the temperature handling below is designed around.
+ */
 const ANTHROPIC_MODELS = [
+  'claude-opus-5',
+  'claude-sonnet-5',
+  'claude-fable-5',
+  'claude-opus-4-8',
+  'claude-opus-4-7',
   'claude-opus-4-6',
-  'claude-opus-4-20250514',
   'claude-sonnet-4-6',
-  'claude-sonnet-4-20250514',
-  'claude-3-5-sonnet-20241022',
-  'claude-3-5-haiku-20241022',
-  'claude-3-opus-20240229',
-  'claude-3-sonnet-20240229',
-  'claude-3-haiku-20240307',
+  'claude-opus-4-5-20251101',
+  'claude-sonnet-4-5-20250929',
+  'claude-haiku-4-5-20251001',
 ] as const;
 
+/** USD per 1K tokens (list prices per million, divided by 1000). */
 const MODEL_COSTS: Record<string, { input: number; output: number }> = {
-  'claude-opus-4-6': { input: 0.015, output: 0.075 },
-  'claude-opus-4-20250514': { input: 0.015, output: 0.075 },
+  'claude-fable-5': { input: 0.01, output: 0.05 },
+  'claude-opus-5': { input: 0.005, output: 0.025 },
+  'claude-opus-4-8': { input: 0.005, output: 0.025 },
+  'claude-opus-4-7': { input: 0.005, output: 0.025 },
+  'claude-opus-4-6': { input: 0.005, output: 0.025 },
+  'claude-opus-4-5-20251101': { input: 0.005, output: 0.025 },
+  'claude-sonnet-5': { input: 0.003, output: 0.015 },
   'claude-sonnet-4-6': { input: 0.003, output: 0.015 },
-  'claude-sonnet-4-20250514': { input: 0.003, output: 0.015 },
-  'claude-3-5-sonnet-20241022': { input: 0.003, output: 0.015 },
-  'claude-3-5-haiku-20241022': { input: 0.0008, output: 0.004 },
-  'claude-3-opus-20240229': { input: 0.015, output: 0.075 },
-  'claude-3-sonnet-20240229': { input: 0.003, output: 0.015 },
-  'claude-3-haiku-20240307': { input: 0.00025, output: 0.00125 },
+  'claude-sonnet-4-5-20250929': { input: 0.003, output: 0.015 },
+  'claude-haiku-4-5-20251001': { input: 0.001, output: 0.005 },
 };
 
+/**
+ * Model-id prefixes KNOWN to accept the sampling parameters (`temperature`,
+ * `top_p`, `top_k`). Anything not on this list is sent WITHOUT them.
+ *
+ * WHY AN ALLOWLIST, NOT A LIST OF MODELS THAT REJECT IT. A deny-list of literal
+ * ids — the shape `OpenAIProvider` uses for its `gpt-5` temperature=1 special
+ * case — is correct exactly until the next model ships, and then it silently
+ * sends a parameter the API refuses. That is not hypothetical: it is the bug
+ * this list exists to fix, and the failure is total (every call 400s) rather
+ * than degraded. Inverting it makes an unknown id — i.e. every future model —
+ * get the request that CANNOT 400. The two error cases are not symmetric:
+ * omitting temperature from a model that would have accepted it costs some
+ * determinism; sending it to a model that rejects it costs the whole feature.
+ *
+ * WHY NOT A VERSION COMPARISON. Measured against api.anthropic.com 2026-08-10:
+ * 4.5 and 4.6 accept `temperature`; 4.7, 4.8 and the entire 5 family return
+ * `400 \`temperature\` is deprecated for this model.` The boundary sits between
+ * 4.6 and 4.7, which no plausible "removed in v5" or "removed in 4.8" rule
+ * predicts — so this is recorded from observation, not derived from a guess.
+ *
+ * The list is also closed in the direction that matters: it can only ever go
+ * stale by omitting a NEW model that would have accepted the parameter, never
+ * by naming one that rejects it. Should that happen, the retry in `generate()`
+ * covers it without a release.
+ */
+const SAMPLING_PARAM_MODEL_PREFIXES = [
+  'claude-3',
+  'claude-opus-4-5',
+  'claude-opus-4-6',
+  'claude-sonnet-4-5',
+  'claude-sonnet-4-6',
+  'claude-haiku-4-5',
+  'claude-haiku-4-6',
+  'claude-opus-4-2025',
+  'claude-sonnet-4-2025',
+  'claude-opus-4-1',
+] as const;
+
+/** True when `model` is known to accept `temperature` / `top_p` / `top_k`. */
+export function supportsSamplingParams(model: string): boolean {
+  const id = model.trim().toLowerCase();
+  return SAMPLING_PARAM_MODEL_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+
+/**
+ * The parameter named by a "deprecated for this model" 400, if that is what the
+ * error is. Anthropic's message is `` `temperature` is deprecated for this model. ``
+ * and the same wording covers `top_p` and `top_k`, so one matcher handles every
+ * sampling parameter — including ones not yet deprecated when this was written.
+ */
+export function deprecatedParameter(message: string): string | null {
+  const match = /`([a-z_]+)`\s+is\s+deprecated\s+for\s+this\s+model/i.exec(message);
+  return match ? match[1] : null;
+}
+
 const DEFAULTS = {
   baseUrl: 'https://api.anthropic.com/v1',
   model: LLM_DEFAULTS.anthropicModel,
@@ -133,35 +201,32 @@ Please respond with a valid JSON object only. Do not include any text before or
       max_tokens: maxTokens,
       messages: [{ role: 'user', content: jsonWrappedPrompt }],
       system: systemPrompt,
-      temperature,
     };
-
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    // Only for models known to take it. The Claude 5 family answers a request
+    // carrying `temperature` with a 400 and nothing else.
+    if (supportsSamplingParams(model)) {
+      requestBody.temperature = temperature;
+    }
 
     try {
-      const response = await fetch(`${this.config.baseUrl}/messages`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'x-api-key': this.config.apiKey,
-          'anthropic-version': this.apiVersion,
-        },
-        body: JSON.stringify(requestBody),
-        signal: controller.signal,
-      });
-
-      clearTimeout(timeoutId);
-
-      if (!response.ok) {
-        const errorData = (await response.json().catch(() => ({
-          error: { type: 'unknown', message: 'Unknown error' },
-        }))) as AnthropicErrorResponse;
-        throw this.handleApiError(response.status, errorData);
+      let data: AnthropicResponse;
+      try {
+        data = await this.post(requestBody, timeout);
+      } catch (error) {
+        // SAFETY NET for a parameter the API has since stopped accepting on a
+        // model the allowlist still vouches for. It also covers parameters this
+        // provider does not send today (`top_p`, `top_k`), so adding one later
+        // cannot reintroduce this failure. One retry, only when the API itself
+        // named the offending key — never a blind resend.
+        const param =
+          error instanceof LLMProviderError && error.statusCode === 400
+            ? deprecatedParameter(error.message)
+            : null;
+        if (!param || !(param in requestBody)) throw error;
+        delete (requestBody as unknown as Record<string, unknown>)[param];
+        data = await this.post(requestBody, timeout);
       }
 
-      const data = (await response.json()) as AnthropicResponse;
-
       const textContent = data.content.find((c) => c.type === 'text');
       if (!textContent?.text) {
         throw new LLMProviderError(
@@ -185,8 +250,6 @@ Please respond with a valid JSON object only. Do not include any text before or
         finishReason: data.stop_reason ?? undefined,
       };
     } catch (error) {
-      clearTimeout(timeoutId);
-
       if (error instanceof LLMProviderError) {
         throw error;
       }
@@ -211,6 +274,39 @@ Please respond with a valid JSON object only. Do not include any text before or
     }
   }
 
+  /**
+   * One POST to /messages. Each attempt gets its own timeout — a retry that
+   * strips a rejected parameter is a fresh request, and inheriting an
+   * already-consumed deadline would abort it before it could succeed.
+   */
+  private async post(body: AnthropicRequest, timeout: number): Promise<AnthropicResponse> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+    try {
+      const response = await fetch(`${this.config.baseUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.config.apiKey,
+          'anthropic-version': this.apiVersion,
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({
+          error: { type: 'unknown', message: 'Unknown error' },
+        }))) as AnthropicErrorResponse;
+        throw this.handleApiError(response.status, errorData);
+      }
+
+      return (await response.json()) as AnthropicResponse;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
   estimateCost(
     promptTokens: number,
     completionTokens: number,

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.
  */
@@ -95,11 +133,17 @@ export interface LLMServiceConfig {
  */
 export const LLM_DEFAULTS = {
   openaiModel: 'gpt-4o-mini',
-  anthropicModel: 'claude-sonnet-4-20250514',
+  /**
+   * The previous default, `claude-sonnet-4-20250514`, was retired and returns
+   * 404 — a default nobody can call. Verified callable 2026-08-10.
+   */
+  anthropicModel: 'claude-sonnet-5',
   /**
    * Default sampling temperature.
    * Note: base gpt-5 models (gpt-5, gpt-5.1, gpt-5.2) require temperature=1.0
-   * and the OpenAI provider enforces this automatically.
+   * and the OpenAI provider enforces this automatically. On Anthropic the
+   * parameter is not sent at all to models that reject it (Claude 4.7+),
+   * so this is a request, not a guarantee — see providers/anthropic.ts.
    */
   temperature: 0.7,
   maxTokens: 8192,