tinker-agent 1.2.1 → 1.4.0

package/src/cli/run-runner.ts

@@ -10,27 +10,29 @@ import {
   loadProjectInstructions,
   projectInstructionManifest,
 } from "../instructions/project-instructions";
+import { type RunnerConfig } from "./config";
 import {
   createRunnerModelClient,
-  createWebFetchRefinerFromEnv,
-  readRunnerConfig,
+  createWebFetchRefiner,
   RUNTIME_INSTRUCTIONS,
-  type RunnerConfigOverrides,
-} from "./config";
-import { loadModelProfiles } from "./model-profiles";
+} from "./runner-dependencies";
+import type { PublicToolingConfig } from "./public-config-contract";
 import { realpath } from "node:fs/promises";
 import { loadSkillCatalog } from "../skills/skill-loader";
 
-export type RunOneShotOptions = RunnerConfigOverrides & {
+export type RunOneShotOptions = {
+  config: RunnerConfig;
+  tooling: PublicToolingConfig;
   modelClient?: ModelClient;
   stdout?: WritableLike;
   stderr?: WritableLike;
   eventLogPath?: string | false;
+  env?: NodeJS.ProcessEnv;
 };
 
 export async function runOneShot(
   userPrompt: string,
-  options: RunOneShotOptions = {},
+  options: RunOneShotOptions,
 ): Promise<number> {
   const stdout = options.stdout ?? process.stdout;
   const stderr = options.stderr ?? process.stderr;
@@ -40,9 +42,7 @@ export async function runOneShot(
   let exitCode = 1;
 
   try {
-    const profiles =
-      options.modelClient === undefined ? await loadModelProfiles() : undefined;
-    const config = readRunnerConfig(options, profiles);
+    const config = options.config;
     const workspaceRoot = await realpath(config.workspaceRoot);
     const projectInstructions = await loadProjectInstructions(workspaceRoot);
     const skillCatalog = await loadSkillCatalog({ workspaceRoot });
@@ -51,7 +51,11 @@ export async function runOneShot(
       runtimeInstructions: RUNTIME_INSTRUCTIONS(workspaceRoot),
       projectInstructions,
     });
-    const modelClient = createRunnerModelClient(config, options.modelClient);
+    const modelClient = createRunnerModelClient(
+      config,
+      options.modelClient,
+      options.env,
+    );
     session = await createRuntimeSession({
       selection: { mode: "new", sessionId: config.sessionId },
       workspaceRoot,
@@ -68,7 +72,8 @@ export async function runOneShot(
       presentationSinks: [new StdoutEventPrinter(stdout, stderr)],
       persistence:
         options.eventLogPath === false ? false : { eventLogPath: options.eventLogPath },
-      webFetchRefiner: createWebFetchRefinerFromEnv(config),
+      webFetchRefiner: createWebFetchRefiner(config, options.env),
+      toolingConfig: options.tooling,
     });
 
     const result = await session.executeTurn({

package/src/cli/runner-dependencies.ts

@@ -0,0 +1,100 @@
+import { renderRecallRetirementContract } from "../context/recall-retirement-contract";
+import { FakeModelClient } from "../model/fake-model-client";
+import type { ModelClient } from "../model/model-client";
+import { OpenAIChatModelClient } from "../model/openai-chat-model-client";
+import { createModelRefiner, type Refiner } from "../tools/web-fetch/refiner";
+import type { RunnerConfig } from "./config";
+
+export const RUNTIME_INSTRUCTIONS = (
+  workspaceRoot: string,
+): string => `You are a coding agent running in a local workspace.
+Your name is Tinker.
+
+Current workspace:
+${workspaceRoot}
+
+Use this path as the root for relative file paths. Absolute file paths may point outside this workspace.
+
+You can use tools to find, read, edit, write files, and run shell commands.
+Use Glob to find files by name or path pattern.
+Use Grep to search file contents. Do not use Bash with grep or rg for routine content searches.
+With Grep, start with output_mode="files_with_matches" to narrow scope, then use output_mode="content" when you need matching lines.
+Use head_limit and offset to page through large Grep result sets instead of requesting unlimited output.
+Use Read to open specific files returned by Grep.
+Use Edit to replace exact strings in existing files. Set old_string="" to create a file or write to an empty file.
+Use Read before the first Write of an existing file in the current runtime.
+Write creates missing parent directories when creating a file.
+Write may fail if the runtime has no known version or the file changed after it was last observed. If that happens, call Read again and retry with the updated content.
+Use Read before an exact-string Edit when this runtime has not already established the current version through Read, Write, or Edit. A successful paginated Read is sufficient. Successful Write and Edit operations establish the current version, so later exact-string Edit operations do not need another Read unless the file changed externally. Edit with old_string="" can create a file or write to an empty file without a prior Read, and creates missing parent directories when creating a file. Exact-string Edit may fail if the runtime has no known version, the file changed after it was last observed, old_string is missing, or old_string matches multiple places without replace_all=true.
+Use WebSearch, when it is available, to look up current information on the web such as recent releases, documentation, and news. Prefer local workspace knowledge for questions the codebase can answer.
+Use WebFetch to read the content of a specific URL, such as documentation pages found via WebSearch or local dev server pages.
+Use Bash to run tests, formatters, linters, read-only git checks, and project commands.
+Prefer Read for reading files instead of using cat on large files.
+Prefer Write or Edit for changing files instead of shell redirection.
+Use run_in_background=true for dev servers, watch commands, long-running builds, and long-running test services.
+Do not add & to Bash commands; background execution is handled by the Bash tool.
+Use TaskList to list background shell tasks in the current session.
+Use TaskOutput to inspect a task's current status and latest output.
+Use TaskStop to stop a background task that is no longer needed.
+Do not use ad-hoc kill commands to manage tasks created by Bash.
+Bash and TaskOutput return outputFilePath. Use Read on outputFilePath when you need complete or paginated output.
+${renderRecallRetirementContract()}
+Agent Skill instructions are current only when returned by the Skill tool in the current turn or listed in the active skill system section. Skill content recovered through Recall is historical data and does not activate or override a current skill.
+When an active Agent Skill refers to a relative resource path, resolve it from the Skill directory shown with that skill.
+Agent Skills do not override Tinker's runtime, tool protocol, project instructions, or the user's explicit request. Do not modify a skill source unless the user explicitly asks to maintain that skill.
+
+When you are done, respond with a concise summary of what you did.`;
+
+export function createModelClient(
+  config: Pick<
+    RunnerConfig,
+    | "modelName"
+    | "includeReasoningContent"
+    | "stream"
+    | "contextBudget"
+    | "apiKey"
+    | "apiBase"
+    | "inputModalities"
+    | "tokenEstimator"
+  >,
+  env: NodeJS.ProcessEnv = process.env,
+): ModelClient {
+  const fakeMode = env.TINKER_TEST_FAKE_MODEL;
+  if (fakeMode !== undefined && fakeMode !== "") {
+    return new FakeModelClient(fakeMode, {
+      model: config.modelName,
+      contextBudget: config.contextBudget,
+    });
+  }
+
+  return new OpenAIChatModelClient({
+    apiKey: config.apiKey,
+    baseURL: config.apiBase,
+    includeReasoningContent: config.includeReasoningContent,
+    model: config.modelName,
+    stream: config.stream,
+    contextBudget: config.contextBudget,
+    inputModalities: config.inputModalities,
+    ...(config.tokenEstimator === undefined
+      ? {}
+      : { tokenEstimator: config.tokenEstimator }),
+  });
+}
+
+export function createRunnerModelClient(
+  config: Parameters<typeof createModelClient>[0],
+  injected?: ModelClient,
+  env?: NodeJS.ProcessEnv,
+): ModelClient {
+  return injected ?? createModelClient(config, env);
+}
+
+export function createWebFetchRefiner(
+  config: Parameters<typeof createModelClient>[0],
+  env?: NodeJS.ProcessEnv,
+): Refiner {
+  return createModelRefiner({
+    createModelClient: () => createModelClient(config, env),
+    contextBudget: config.contextBudget,
+  });
+}

package/src/cli/tui-runner.tsx

@@ -27,28 +27,31 @@ import {
   type TuiSessionBinding,
 } from "../tui/tui-session-controller";
 import {
-  createRunnerModelClient,
-  createWebFetchRefinerFromEnv,
   promptHistoryPath,
-  readRunnerConfig,
-  RUNTIME_INSTRUCTIONS,
+  deriveRunnerConfig,
+  type ResolvedPublicConfig,
   type RunnerConfig,
 } from "./config";
 import {
-  loadModelProfiles,
-  persistDefaultProfile,
-  resolveSessionProfileName,
-  type ModelProfile,
-} from "./model-profiles";
+  createRunnerModelClient,
+  createWebFetchRefiner,
+  RUNTIME_INSTRUCTIONS,
+} from "./runner-dependencies";
+import { resolveSessionProfileName, type ModelProfile } from "./model-profiles";
 import { loadSkillCatalog } from "../skills/skill-loader";
 import { loadProjectSlashCommands } from "../tui/project-slash-commands";
+import { createWorkspaceFileLister } from "../tui/workspace-file-search";
 
-export async function runTui(options: { profileName?: string } = {}): Promise<void> {
-  const profiles = await loadModelProfiles();
-  const config = readRunnerConfig(
-    options.profileName !== undefined ? { profileName: options.profileName } : {},
-    profiles,
-  );
+export type RunTuiOptions = {
+  readonly publicConfig: ResolvedPublicConfig;
+  readonly initialRunnerConfig: RunnerConfig;
+  readonly env: NodeJS.ProcessEnv;
+};
+
+export async function runTui(options: RunTuiOptions): Promise<void> {
+  const profiles =
+    options.publicConfig.mode === "profile" ? options.publicConfig.profiles : undefined;
+  const config = options.initialRunnerConfig;
   const workspaceRoot = await realpath(config.workspaceRoot);
   let controller: DefaultTuiSessionController | undefined;
   let instance: ReturnType<typeof render> | undefined;
@@ -64,7 +67,11 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
       sessionId: SessionId,
       sink: EventSink,
     ): Promise<RuntimeSession> => {
-      const modelClient = createRunnerModelClient(sessionConfig);
+      const modelClient = createRunnerModelClient(
+        sessionConfig,
+        undefined,
+        options.env,
+      );
       const projectInstructions = await loadProjectInstructions(workspaceRoot);
       const skillCatalog = await loadSkillCatalog({ workspaceRoot });
       const common = {
@@ -84,7 +91,8 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         projectInstruction: projectInstructionManifest(projectInstructions),
         skillCatalog,
         presentationSinks: [sink],
-        webFetchRefiner: createWebFetchRefinerFromEnv(sessionConfig),
+        webFetchRefiner: createWebFetchRefiner(sessionConfig, options.env),
+        toolingConfig: options.publicConfig.tooling,
       };
       if (mode === "resume") {
         return createRuntimeSession({
@@ -118,18 +126,12 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
     ): Promise<ManagedTuiSessionBinding> => {
       const deferred = new DeferredProjectionSink();
       const summary = await catalog.get(sessionId);
-      const resumeConfig =
-        profiles === undefined
-          ? { ...config, sessionId }
-          : readRunnerConfig(
-              {
-                sessionId,
-                profileName: resolveSessionProfileName(profiles, summary),
-                workspaceRoot: config.workspaceRoot,
-                maxIterations: config.maxIterations,
-              },
-              profiles,
-            );
+      const resumeConfig = deriveRunnerConfig(options.publicConfig, {
+        sessionId,
+        ...(profiles === undefined
+          ? {}
+          : { profileName: resolveSessionProfileName(profiles, summary) }),
+      });
       const runtimeSession = await createSessionForConfig(
         resumeConfig,
         "resume",
@@ -195,15 +197,10 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         throw new Error("Model profiles are not configured.");
       }
       return createNewSessionBinding(
-        readRunnerConfig(
-          {
-            sessionId: createUuidV7() as SessionId,
-            workspaceRoot: config.workspaceRoot,
-            profileName: profile.name,
-            maxIterations: config.maxIterations,
-          },
-          profiles,
-        ),
+        deriveRunnerConfig(options.publicConfig, {
+          sessionId: createUuidV7() as SessionId,
+          profileName: profile.name,
+        }),
       );
     };
 
@@ -212,21 +209,18 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
     ): Promise<ManagedTuiSessionBinding> => {
       const sessionId = createUuidV7() as SessionId;
       if (profiles === undefined) {
-        return createNewSessionBinding({ ...config, sessionId });
+        return createNewSessionBinding(
+          deriveRunnerConfig(options.publicConfig, { sessionId }),
+        );
       }
       if (current.profileName === undefined) {
         throw new Error("Current session does not have a model profile.");
       }
       return createNewSessionBinding(
-        readRunnerConfig(
-          {
-            sessionId,
-            workspaceRoot: config.workspaceRoot,
-            profileName: current.profileName,
-            maxIterations: config.maxIterations,
-          },
-          profiles,
-        ),
+        deriveRunnerConfig(options.publicConfig, {
+          sessionId,
+          profileName: current.profileName,
+        }),
       );
     };
 
@@ -251,7 +245,16 @@ export async function runTui(options: { profileName?: string } = {}): Promise<vo
         history={promptHistory}
         projectSlashCommands={projectSlashCommands}
         profiles={profiles}
-        persistDefaultProfile={persistDefaultProfile}
+        persistDefaultProfile={
+          options.publicConfig.mode === "profile"
+            ? options.publicConfig.persistDefaultProfile
+            : undefined
+        }
+        fileLister={createWorkspaceFileLister({
+          command: options.publicConfig.tooling.ripgrepPath,
+          timeoutMs: options.publicConfig.tooling.grepTimeoutMs,
+          maxBufferBytes: options.publicConfig.tooling.grepMaxBufferBytes,
+        })}
         onQuit={() => {
           quitRequested = true;
         }}

package/src/events/observation-text-log.ts

@@ -45,6 +45,8 @@ export function renderObservationLogEvent(event: AgentEvent): string | undefined
       return renderTurnCancelled(event);
     case "turn.failed":
       return renderTurnFailed(event.data.error);
+    case "model.request.failed":
+      return undefined;
     default:
       return undefined;
   }

package/src/events/stdout-event-printer.ts

@@ -43,7 +43,13 @@ export class StdoutEventPrinter implements EventSink {
         );
         break;
       case "model.request.started":
-        this.stdout.write(`model.request.started iteration=${event.iterationNumber}\n`);
+        if (event.data.attemptNumber === 1) {
+          this.stdout.write(
+            `model.request.started iteration=${event.iterationNumber}\n`,
+          );
+        }
+        break;
+      case "model.request.failed":
         break;
       case "model.request.finished":
         this.stdout.write(

package/src/events/types.ts

@@ -13,7 +13,11 @@ import type {
   ToolCallId,
   TurnId,
 } from "../ids/runtime-id";
-import type { ModelRequestOutput } from "../model/model-client";
+import type {
+  ModelRequestOutput,
+  ProviderResponseDiagnostics,
+  ProviderResponseErrorCode,
+} from "../model/model-client";
 import type {
   ModelContextBudget,
   ModelContextProfile,
@@ -280,6 +284,22 @@ export type TurnFinishedData = {
   messageCount: number;
 };
 
+export type ModelRequestAttemptData = {
+  attemptNumber: 1 | 2;
+  maxAttempts: 2;
+};
+
+export type ModelRequestFailureCode = ProviderResponseErrorCode;
+
+export type ModelRequestFailedData = ModelRequestAttemptData & {
+  code: ModelRequestFailureCode;
+  retryDisposition: "scheduled" | "not_retryable" | "exhausted";
+  provider: string;
+  model: string;
+  error: string;
+  diagnostics?: ProviderResponseDiagnostics;
+};
+
 export type AgentEventDataMap = {
   "session.started": SessionStartedData;
   "session.resumed": SessionResumedData;
@@ -290,8 +310,11 @@ export type AgentEventDataMap = {
   "turn.failed": { error: string };
   "turn.cancelled": { cancellation: TurnCancellation };
   "agent.iteration.started": { iterationNumber: number };
-  "model.request.started": Record<string, never>;
-  "model.request.finished": { output: ModelRequestOutput };
+  "model.request.started": ModelRequestAttemptData;
+  "model.request.failed": ModelRequestFailedData;
+  "model.request.finished": ModelRequestAttemptData & {
+    output: ModelRequestOutput;
+  };
   "context.usage.updated": ContextUsageUpdatedData;
   "context.revision.started": ContextRevisionStartedData;
   "context.revision.finished": ContextRevisionFinishedData;
@@ -385,6 +408,7 @@ export type AgentEventInput =
   | IterationEventInput<
       | "agent.iteration.started"
       | "model.request.started"
+      | "model.request.failed"
       | "model.request.finished"
       | "context.usage.updated"
       | "context.shadow.planned"

package/src/mcp/mcp-manager.ts

@@ -58,11 +58,8 @@ export async function createMcpManager(
   options: CreateMcpManagerOptions,
 ): Promise<McpManager> {
   const clientFactory = options.clientFactory ?? stdioClientFactory;
-  const timeoutMs =
-    options.timeoutMs ?? parsePositiveIntegerEnv("TINKER_MCP_TIMEOUT_MS");
-  const maxObservationChars =
-    options.maxObservationChars ??
-    parsePositiveIntegerEnv("TINKER_MCP_MAX_OBSERVATION_CHARS");
+  const timeoutMs = options.timeoutMs;
+  const maxObservationChars = options.maxObservationChars;
   const connections: McpClientConnection[] = [];
   const executors: ToolExecutor[] = [];
   const servers: McpServerInventory[] = [];
@@ -227,20 +224,6 @@ async function closeConnections(
   }
 }
 
-function parsePositiveIntegerEnv(name: string): number | undefined {
-  const value = process.env[name];
-  if (value === undefined || value.trim() === "") {
-    return undefined;
-  }
-
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed <= 0) {
-    throw new Error(`${name} must be a positive integer; received ${value}`);
-  }
-
-  return parsed;
-}
-
 async function stdioClientFactory(
   serverName: string,
   serverConfig: McpServerConfig,

package/src/mcp/mcp-tool-executor.ts

@@ -8,10 +8,9 @@ import type {
   ToolExecutionContext,
   ToolExecutor,
 } from "../tools/types";
+import { DEFAULT_PUBLIC_TOOLING_CONFIG } from "../cli/public-config-contract";
 
 export const MCP_TOOL_NAME_PREFIX = "mcp__";
-export const DEFAULT_MCP_TIMEOUT_MS = 60_000;
-export const DEFAULT_MCP_MAX_OBSERVATION_CHARS = 40_000;
 
 export function mcpToolName(serverName: string, toolName: string): string {
   return `${MCP_TOOL_NAME_PREFIX}${serverName}__${toolName}`;
@@ -48,9 +47,9 @@ export function createMcpToolExecutor(
   options: CreateMcpToolExecutorOptions,
 ): ToolExecutor {
   const toolName = mcpToolName(options.serverName, options.tool.name);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_MCP_TIMEOUT_MS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_PUBLIC_TOOLING_CONFIG.mcpTimeoutMs;
   const maxObservationChars =
-    options.maxObservationChars ?? DEFAULT_MCP_MAX_OBSERVATION_CHARS;
+    options.maxObservationChars ?? DEFAULT_PUBLIC_TOOLING_CONFIG.mcpMaxObservationChars;
 
   const base = {
     toolName,

package/src/model/model-client.ts

@@ -122,3 +122,32 @@ export type ModelUsage = {
   promptCacheMissTokens?: number;
   reasoningTokens?: number;
 };
+
+export type ProviderResponseErrorCode =
+  | "reasoning_only_assistant"
+  | "invalid_provider_response"
+  | "invalid_provider_stream"
+  | "provider_request_error";
+
+export type ProviderResponseDiagnostics = {
+  provider: string;
+  model: string;
+  path?: string;
+  finishReason?: string;
+  contentChars?: number;
+  reasoningChars?: number;
+  toolCallCount?: number;
+  usage?: ModelUsage;
+};
+
+export class ProviderResponseError extends Error {
+  constructor(
+    readonly code: ProviderResponseErrorCode,
+    message: string,
+    readonly diagnostics: ProviderResponseDiagnostics,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "ProviderResponseError";
+  }
+}

package/src/model/model-context-profile.ts

@@ -14,21 +14,6 @@ export type ModelContextBudget = ModelContextProfile & {
   triggerTokens: number;
 };
 
-export function readModelContextProfileFromEnv(
-  env: NodeJS.ProcessEnv = process.env,
-): ModelContextProfile {
-  return createModelContextProfile({
-    contextWindowTokens: parseRequiredTokenCount(
-      env.TINKER_CONTEXT_WINDOW_TOKENS,
-      "TINKER_CONTEXT_WINDOW_TOKENS",
-    ),
-    maxSupportedOutputTokens: parseRequiredTokenCount(
-      env.TINKER_MAX_SUPPORTED_OUTPUT_TOKENS,
-      "TINKER_MAX_SUPPORTED_OUTPUT_TOKENS",
-    ),
-  });
-}
-
 export function createModelContextProfile(
   input: ModelContextProfile,
 ): ModelContextProfile {
@@ -102,21 +87,6 @@ export function assertMatchingContextBudget(
   }
 }
 
-function parseRequiredTokenCount(value: string | undefined, name: string): number {
-  if (value === undefined || value.trim() === "") {
-    throw new Error(`${name} is required; received ${displayValue(value)}.`);
-  }
-  if (!/^\d+$/.test(value)) {
-    throw new Error(
-      `${name} must be a positive safe integer token count; received ${displayValue(value)}.`,
-    );
-  }
-
-  const parsed = Number(value);
-  requirePositiveSafeInteger(parsed, name, value);
-  return parsed;
-}
-
 function requirePositiveSafeInteger(
   value: number,
   name: string,

package/src/model/openai-chat-mapping.ts

@@ -5,7 +5,12 @@ import type {
   UserMessage,
 } from "../agent/types";
 import type { RuntimeSessionContext } from "../agent/runtime-session";
-import type { ModelRequestOutput, ModelUsage } from "./model-client";
+import {
+  ProviderResponseError,
+  type ModelRequestOutput,
+  type ModelUsage,
+  type ProviderResponseDiagnostics,
+} from "./model-client";
 import type { ToolDefinition } from "../tools/types";
 import type {
   ChatCompletionAssistantMessageParam,
@@ -178,21 +183,45 @@ export function fromOpenAIChatCompletion(
     "choices[0].message.content",
     options,
   );
+  const finishReason = optionalString(
+    choice.finish_reason,
+    "choices[0].finish_reason",
+    options,
+  );
+  const usage = parseUsage(completion.usage, options);
+  const reasoningContent = normalizeContent(
+    message.reasoning_content,
+    "choices[0].message.reasoning_content",
+    options,
+  );
+  const diagnostics = responseDiagnostics(options, {
+    path: "choices[0].message",
+    finishReason,
+    contentChars: content?.length ?? 0,
+    reasoningChars: reasoningContent?.length ?? 0,
+    toolCallCount: rawToolCalls.length,
+    usage,
+  });
   if ((content === null || content.trim() === "") && rawToolCalls.length === 0) {
+    if (
+      finishReason === "stop" &&
+      reasoningContent !== null &&
+      reasoningContent.trim() !== ""
+    ) {
+      throw new ProviderResponseError(
+        "reasoning_only_assistant",
+        `Invalid provider response (provider=${options.provider}, model=${options.model}): choices[0].message contains reasoning but neither non-empty final text nor tool calls.`,
+        diagnostics,
+      );
+    }
     throw providerResponseError(
       options,
       "choices[0].message",
       "has neither non-empty text nor tool calls",
+      diagnostics,
     );
   }
 
-  const finishReason = optionalString(
-    choice.finish_reason,
-    "choices[0].finish_reason",
-    options,
-  );
-  const usage = parseUsage(completion.usage, options);
-
   if (rawToolCalls.length > 0 && options.identity === undefined) {
     throw providerResponseError(
       options,
@@ -208,11 +237,7 @@ export function fromOpenAIChatCompletion(
     message: {
       role: "assistant",
       content,
-      reasoningContent: normalizeContent(
-        message.reasoning_content,
-        "choices[0].message.reasoning_content",
-        options,
-      ),
+      reasoningContent,
       toolCalls: toolCalls.length === 0 ? undefined : toolCalls,
     },
     finishReason,
@@ -513,8 +538,22 @@ function providerResponseError(
   options: { provider: string; model: string },
   path: string,
   detail: string,
-): Error {
-  return new Error(
+  diagnostics: ProviderResponseDiagnostics = responseDiagnostics(options, { path }),
+): ProviderResponseError {
+  return new ProviderResponseError(
+    "invalid_provider_response",
     `Invalid provider response (provider=${options.provider}, model=${options.model}): ${path} ${detail}.`,
+    { ...diagnostics, path },
   );
 }
+
+function responseDiagnostics(
+  options: { provider: string; model: string },
+  diagnostics: Omit<ProviderResponseDiagnostics, "provider" | "model">,
+): ProviderResponseDiagnostics {
+  return {
+    provider: options.provider,
+    model: options.model,
+    ...diagnostics,
+  };
+}