@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/{chunk-DN2PACRI.js → chunk-K3NH62DG.js}

@@ -1,14 +1,17 @@
-import { currentCredentialPool, computeBackoffMs, sleepWithAbort, newPooledCredential, CredentialPool } from './chunk-TAZVKYWJ.js';
-import { invalidateSessionCache } from './chunk-WTMU7J4U.js';
-import { buildErrorMetadata, mapOpenAICompatibleError } from './chunk-7YGCPMGB.js';
-import { tryJson, isPlainObject, sanitizeToolInput } from './chunk-U54XCYG3.js';
+import { currentCredentialPool, newPooledCredential, CredentialPool } from './chunk-UBR5PWD7.js';
+import { invalidateSessionCache } from './chunk-2XC6KDJM.js';
+import { buildErrorMetadata, mapOpenAICompatibleError, parseErrorBody, httpStatusToErrorCode } from './chunk-XB4GI5RZ.js';
+import { computeBackoffMs, sleepWithAbort } from './chunk-24MGQDK3.js';
+import { tryJson, isPlainObject, sanitizeToolInput } from './chunk-FJWQP6EE.js';
 import { providerFromApiKeyPrefix } from './chunk-NAF4L3T6.js';
-import { reconstructMessages, SessionTranscript } from './chunk-UMP6OJIM.js';
-import { estimateTokens } from './chunk-A4JVILQU.js';
-import { globalSingleton, registerProvider, registerBuiltins, getProviderProfile, inferModelDialect, inferRegionFromModelId, stripBedrockPrefix, resolveBedrockBaseUrl, resolveVertexBaseUrl, stripVertexPrefix } from './chunk-WLQNMXQE.js';
-import { readStoredOAuth } from './chunk-C3NT3PVE.js';
-import { NetworkError, ConfigurationError, IntegrationNotConnectedError, AuthenticationError, RateLimitError, UnknownAgentError, CredentialPoolExhaustedError, isTransientError, TheokitAgentError } from './chunk-ZZMZWBR6.js';
-import { diag } from './chunk-XEQ3TM66.js';
+import { reconstructMessages, SessionTranscript } from './chunk-JOFVLOFY.js';
+import { estimateTokens } from './chunk-6M2OIS4Y.js';
+import { parseModelId } from './chunk-R7WIIPUR.js';
+import { registerProvider, registerBuiltins, getProviderProfile, inferModelDialect, inferRegionFromModelId, stripBedrockPrefix, resolveBedrockBaseUrl, resolveVertexBaseUrl, stripVertexPrefix } from './chunk-VWUXIVEI.js';
+import { globalSingleton } from './chunk-AGACYRJ2.js';
+import { readStoredOAuth } from './chunk-V22DZIXO.js';
+import { NetworkError, ConfigurationError, IntegrationNotConnectedError, AuthenticationError, RateLimitError, UnknownAgentError, TheokitAgentError, CredentialPoolExhaustedError, isTransientError } from './chunk-ALUN2B4W.js';
+import { diag } from './chunk-CZJ6Q7CW.js';
 import { existsSync, readFileSync } from 'fs';
 import { readdir } from 'fs/promises';
 import { homedir } from 'os';
@@ -142,9 +145,6 @@ function mapAnthropicError(args) {
   return new UnknownAgentError(message, { code: "anthropic_unknown", metadata });
 }
 function mapAnthropicStatusToCode(status, body) {
-  if (status === 401 || status === 403) return "auth_failed";
-  if (status === 429) return "rate_limit";
-  if (status === 408) return "timeout";
   if (status === 400) {
     const text = JSON.stringify(body ?? "").toLowerCase();
     if (text.includes("context") && (text.includes("too long") || text.includes("too_long") || text.includes("length"))) {
@@ -155,8 +155,7 @@ function mapAnthropicStatusToCode(status, body) {
     }
     return "invalid_request";
   }
-  if (status >= 500 && status < 600) return "server_error";
-  return "unknown";
+  return httpStatusToErrorCode(status);
 }
 function formatMessage(status, code) {
   return `Anthropic API error: ${code} (HTTP ${status})`;
@@ -476,13 +475,13 @@ function releaseReader(reader) {
 }
 
 // src/internal/llm/transport-error.ts
-function ehAbort(err) {
+function isAbortError(err) {
   if (typeof err !== "object" || err === null) return false;
-  const nome = err.name;
-  return nome === "AbortError" || nome === "TimeoutError";
+  const name = err.name;
+  return name === "AbortError" || name === "TimeoutError";
 }
 function wrapTransportError(err, ctx) {
-  if (ehAbort(err)) return err;
+  if (isAbortError(err)) return err;
   if (err instanceof TheokitAgentError) return err;
   const detail = err instanceof Error ? err.message : String(err);
   return new NetworkError(`${ctx.providerId} transport failure on ${ctx.endpoint}: ${detail}`, {
@@ -688,18 +687,17 @@ function buildAnthropicBody(request) {
 
 // src/internal/error-mappers/bedrock.ts
 function classifyBedrockError(args, awsType, message) {
-  if (args.status === 429 || awsType.includes("Throttling") || awsType.includes("TooManyRequests")) {
+  if (awsType.includes("Throttling") || awsType.includes("TooManyRequests")) {
     return "rate_limit";
   }
-  if (args.status === 401 || args.status === 403 || awsType.includes("AccessDenied") || awsType.includes("UnauthorizedOperation")) {
+  if (awsType.includes("AccessDenied") || awsType.includes("UnauthorizedOperation")) {
     return "auth_failed";
   }
-  if (args.status === 400 || args.status === 404 || awsType.includes("ValidationException") || awsType.includes("ResourceNotFound") || message.includes("use case details")) {
+  if (args.status === 404 || awsType.includes("ValidationException") || awsType.includes("ResourceNotFound") || message.includes("use case details")) {
     return "invalid_request";
   }
-  if (args.status === 408 || awsType.includes("Timeout")) return "timeout";
-  if (args.status >= 500) return "server_error";
-  return "unknown";
+  if (awsType.includes("Timeout")) return "timeout";
+  return httpStatusToErrorCode(args.status);
 }
 function buildBedrockMetadata(args, code) {
   return buildErrorMetadata({
@@ -712,7 +710,7 @@ function buildBedrockMetadata(args, code) {
   });
 }
 function mapBedrockError(args) {
-  const parsed = parseBody(args.body);
+  const parsed = parseErrorBody(args.body);
   const awsType = parsed.__type ?? "";
   const message = parsed.message ?? parsed.Message ?? "Bedrock request failed";
   const code = classifyBedrockError(args, awsType, message);
@@ -726,6 +724,8 @@ function mapBedrockError(args) {
       const friendly = message.includes("use case details") ? `Bedrock account setup required: ${message} (AWS Console \u2192 Bedrock \u2192 Model access \u2192 Anthropic \u2192 Submit use case form, then retry in 15 min.)` : `Bedrock validation: ${message}`;
       return new ConfigurationError(friendly, { metadata });
     }
+    case "quota_exceeded":
+      return new RateLimitError(`Bedrock quota exceeded: ${message}`, { metadata });
     case "timeout":
       return new NetworkError(`Bedrock timeout: ${message}`, { metadata });
     case "server_error":
@@ -734,17 +734,6 @@ function mapBedrockError(args) {
       return new UnknownAgentError(`Bedrock unknown: ${message}`, { metadata });
   }
 }
-function parseBody(body) {
-  if (body !== null && typeof body === "object") return body;
-  if (typeof body === "string") {
-    try {
-      return JSON.parse(body);
-    } catch {
-      return {};
-    }
-  }
-  return {};
-}
 var cachedToken = null;
 var CACHE_TTL_MS = 90 * 60 * 1e3;
 async function resolveBedrockToken(region) {
@@ -1025,7 +1014,7 @@ var OllamaNativeClient = class {
         endpoint: "/api/chat"
       });
       if (mapped !== void 0) throw mapped;
-      throw fetchErr;
+      throw wrapTransportError(fetchErr, { providerId: "ollama", endpoint: "/api/chat" });
     }
     if (!response.ok) {
       const text = await response.text().catch(() => "");
@@ -1042,7 +1031,13 @@ var OllamaNativeClient = class {
         endpoint: "/api/chat"
       });
       if (mapped !== void 0) throw mapped;
-      throw new Error(`Ollama /api/chat HTTP ${response.status}: ${text.slice(0, 200)}`);
+      throw mapOpenAICompatibleError({
+        providerId: "ollama",
+        status: response.status,
+        body: bodyJson,
+        headers: response.headers,
+        endpoint: "/api/chat"
+      });
     }
     const accumulator = new OllamaStreamAccumulator();
     if (response.body === null) {
@@ -1231,83 +1226,13 @@ function toOllamaTools(tools) {
     }
   }));
 }
-var FIXTURE_API_KEY_PREFIX = "theo_test_";
-function isFixtureApiKey(apiKey) {
-  if (apiKey === void 0) return false;
-  return apiKey.startsWith(FIXTURE_API_KEY_PREFIX);
-}
+
+// src/internal/base-url.ts
 function getConfiguredBaseUrl() {
   const value = process.env.THEOKIT_API_BASE_URL;
   if (value === void 0 || value.length === 0) return void 0;
   return value;
 }
-function shouldUseFixtureMode(apiKey) {
-  if (getConfiguredBaseUrl() !== void 0) return false;
-  return isFixtureApiKey(apiKey);
-}
-var PROVIDER_CREDENTIAL_ENV_VARS = [
-  "ANTHROPIC_API_KEY",
-  "OPENAI_API_KEY",
-  "OPENROUTER_API_KEY"
-];
-function presentProviderCredentialEnvVars() {
-  return PROVIDER_CREDENTIAL_ENV_VARS.filter((name) => {
-    const value = process.env[name];
-    return typeof value === "string" && value.length > 0;
-  });
-}
-function shouldUseRealLocalRuntime(apiKey) {
-  if (isFixtureApiKey(apiKey)) return false;
-  if (isStoredOAuthAvailable()) return true;
-  if (apiKey === void 0 || apiKey.length === 0) return false;
-  return presentProviderCredentialEnvVars().length > 0 || isAwsBedrockAuthAvailable() || isGcpVertexAuthAvailable() || isLocalNoAuthProviderAvailable();
-}
-var AMBIENT_STORE = {
-  home: homedir(),
-  dirName: ".theokit",
-  fileName: "auth.json",
-  homeEnvVar: "THEOKIT_AUTH_HOME"
-};
-function isStoredOAuthAvailable(env = process.env) {
-  try {
-    return readStoredOAuth(AMBIENT_STORE, env) !== void 0;
-  } catch {
-    return false;
-  }
-}
-function isAwsBedrockAuthAvailable() {
-  if (typeof process.env.AWS_BEARER_TOKEN_BEDROCK === "string" && process.env.AWS_BEARER_TOKEN_BEDROCK.length > 0) {
-    return true;
-  }
-  if (typeof process.env.AWS_ACCESS_KEY_ID === "string" && process.env.AWS_ACCESS_KEY_ID.length > 0) {
-    return true;
-  }
-  if (typeof process.env.AWS_PROFILE === "string" && process.env.AWS_PROFILE.length > 0) {
-    return true;
-  }
-  return awsCredentialsFileExists();
-}
-function awsCredentialsFileExists() {
-  try {
-    const home = process.env.HOME ?? process.env.USERPROFILE;
-    if (home === void 0 || home.length === 0) return false;
-    return existsSync(`${home}/.aws/credentials`) || existsSync(`${home}/.aws/config`);
-  } catch {
-    return false;
-  }
-}
-function isGcpVertexAuthAvailable() {
-  if (typeof process.env.GOOGLE_APPLICATION_CREDENTIALS === "string" && process.env.GOOGLE_APPLICATION_CREDENTIALS.length > 0) {
-    return true;
-  }
-  if (typeof process.env.GOOGLE_CLOUD_PROJECT === "string" && process.env.GOOGLE_CLOUD_PROJECT.length > 0) {
-    return true;
-  }
-  return false;
-}
-function isLocalNoAuthProviderAvailable() {
-  return true;
-}
 
 // src/internal/http.ts
 var DEFAULT_BASE_URL = "https://api.usetheo.dev";
@@ -1372,12 +1297,18 @@ function mapHttpStatusToError(status, body) {
       cause: body
     });
   }
+  return statusToError(status, message, errorOptions);
+}
+function statusToError(status, message, errorOptions) {
   if (status === 401 || status === 403) {
     return new AuthenticationError(message, errorOptions);
   }
   if (status === 429) {
     return new RateLimitError(message, errorOptions);
   }
+  if (status === 408) {
+    return new NetworkError(message, { ...errorOptions, code: errorOptions.code ?? "timeout" });
+  }
   if (status >= 400 && status < 500) {
     return new ConfigurationError(message, errorOptions);
   }
@@ -1897,7 +1828,7 @@ function encodeOpenAIResponseFormat(rf) {
   };
 }
 
-// src/internal/resilience/circuit-breaker.ts
+// src/internal/retry/circuit-breaker.ts
 var DEFAULT_MAX_TIMEOUTS = 3;
 var DEFAULT_COOLDOWN_MS = 6e4;
 var CircuitBreaker = class {
@@ -1939,6 +1870,12 @@ var CircuitBreaker = class {
   }
 };
 
+// src/internal/llm/abort-error.ts
+function abortError(signal) {
+  if (signal.reason instanceof Error) return signal.reason;
+  return new Error(signal.reason !== void 0 ? String(signal.reason) : "aborted");
+}
+
 // src/internal/llm/stream-relay.ts
 async function tryFirstEvent(client, request, signal, logFallback = false) {
   const generator = client.stream(request, signal);
@@ -2082,10 +2019,6 @@ function inferStatusCode(error) {
   if (error instanceof RateLimitError) return 429;
   return 0;
 }
-function abortError(signal) {
-  if (signal.reason instanceof Error) return signal.reason;
-  return new Error("AbortError");
-}
 
 // src/internal/llm/responses.ts
 function messageToInputItems(message, reasoningByCallId) {
@@ -2172,6 +2105,142 @@ function applyPromptCachingFields(body, request, options) {
   if (carryReasoning) body.include = ["reasoning.encrypted_content"];
   if (request.promptCacheKey !== void 0) body.prompt_cache_key = request.promptCacheKey;
 }
+var ResponsesStreamAccumulator = class {
+  constructor(rememberReasoning) {
+    this.rememberReasoning = rememberReasoning;
+  }
+  rememberReasoning;
+  text = "";
+  toolCalls = [];
+  stopReason = "end_turn";
+  inputTokens;
+  outputTokens;
+  reasoningTokens;
+  cacheReadTokens;
+  cacheWriteTokens;
+  /** Function-call accumulation keyed by the streamed output-item id. */
+  pending = {};
+  /**
+   * usetheokit/theokit-sdk#383 — reasoning items seen so far in THIS response and not yet claimed
+   * by a tool call. Claimed (and cleared) when the next `function_call` completes, which is what
+   * binds each batch to the call it produced.
+   */
+  unclaimedReasoning = [];
+  /** The message of a terminal failure event, or `undefined` when this is not one. */
+  static failureMessage(event) {
+    if (event.type !== "response.failed" && event.type !== "error") return void 0;
+    return event.response?.error?.message ?? event.message ?? "responses stream failed";
+  }
+  consume(event) {
+    return this.applyDelta(event) ?? this.applyStructural(event) ?? [];
+  }
+  /** The three event kinds that produce an event for the consumer. */
+  applyDelta(event) {
+    const t = event.type;
+    if (t === "response.output_text.delta") {
+      const d = event.delta ?? "";
+      if (d.length === 0) return [];
+      this.text += d;
+      return [{ type: "text_delta", text: d }];
+    }
+    if (t === "response.reasoning_summary_text.delta" || t === "response.reasoning_text.delta") {
+      const d = event.delta ?? "";
+      return d.length > 0 ? [{ type: "reasoning_delta", text: d }] : [];
+    }
+    return void 0;
+  }
+  /** The event kinds that only move accumulator state. Routing only — each arm is its own method. */
+  applyStructural(event) {
+    const t = event.type;
+    if (t === "response.output_item.added" || t === "response.output_item.done") {
+      this.applyOutputItem(t, event);
+      return [];
+    }
+    if (t === "response.function_call_arguments.delta") {
+      this.appendArguments(event);
+      return [];
+    }
+    if (t === "response.completed" || t === "response.incomplete") {
+      this.applyTerminal(t, event);
+      return [];
+    }
+    return void 0;
+  }
+  appendArguments(event) {
+    const c = event.item_id !== void 0 ? this.pending[event.item_id] : void 0;
+    if (c !== void 0) c.args += event.delta ?? "";
+  }
+  applyTerminal(t, event) {
+    this.applyUsage(event.response?.usage);
+    this.stopReason = t === "response.incomplete" ? "max_tokens" : "end_turn";
+  }
+  finish() {
+    const stopReason = this.toolCalls.length > 0 && this.stopReason === "end_turn" ? "tool_use" : this.stopReason;
+    return makeLlmFinish({
+      stopReason,
+      text: this.text,
+      toolCalls: this.toolCalls,
+      inputTokens: this.inputTokens,
+      outputTokens: this.outputTokens,
+      reasoningTokens: this.reasoningTokens,
+      cacheReadTokens: this.cacheReadTokens,
+      cacheWriteTokens: this.cacheWriteTokens
+    });
+  }
+  applyOutputItem(t, event) {
+    const item = event.item;
+    if (item === void 0) return;
+    if (t === "response.output_item.added") {
+      if (item.type === "function_call") this.beginFunctionCall(item);
+      return;
+    }
+    if (item.type === "reasoning") this.applyReasoningItem(item);
+    else if (item.type === "function_call") this.applyFunctionCallDone(item);
+  }
+  beginFunctionCall(item) {
+    const id = item.id ?? item.call_id ?? "call-0";
+    this.pending[id] = {
+      callId: item.call_id ?? id,
+      name: item.name ?? "",
+      args: item.arguments ?? ""
+    };
+  }
+  applyReasoningItem(item) {
+    const id = item.id;
+    const encrypted = item.encrypted_content;
+    if (id !== void 0 && encrypted !== void 0 && encrypted.length > 0) {
+      this.unclaimedReasoning.push({ id, encrypted_content: encrypted });
+    }
+  }
+  applyFunctionCallDone(item) {
+    const id = item.id ?? item.call_id ?? "call-0";
+    const c = this.pending[id] ?? {
+      callId: item.call_id ?? id,
+      name: item.name ?? "",
+      args: item.arguments ?? ""
+    };
+    const call = {
+      type: "tool_use",
+      id: c.callId,
+      name: c.name.length > 0 ? c.name : item.name ?? "",
+      input: parseToolArguments(item.arguments ?? c.args)
+    };
+    this.toolCalls.push(call);
+    if (this.unclaimedReasoning.length > 0) {
+      this.rememberReasoning(call.id, this.unclaimedReasoning);
+      this.unclaimedReasoning = [];
+    }
+    delete this.pending[id];
+  }
+  applyUsage(usage) {
+    if (usage === void 0) return;
+    this.inputTokens = usage.input_tokens;
+    this.outputTokens = usage.output_tokens;
+    this.reasoningTokens = usage.output_tokens_details?.reasoning_tokens;
+    this.cacheReadTokens = usage.input_tokens_details?.cached_tokens;
+    this.cacheWriteTokens = usage.input_tokens_details?.cache_write_tokens;
+  }
+};
 var MAX_REMEMBERED_REASONING_CALLS = 256;
 var ResponsesApiClient = class {
   constructor(options) {
@@ -2204,20 +2273,17 @@ var ResponsesApiClient = class {
       this.reasoningByCallId.delete(oldest.value);
     }
   }
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: the SSE dispatch (text / reasoning / tool-call add+delta+done / terminal+usage / error) is one cohesive state machine, mirroring OpenAIStreamAccumulator.consume.
-  async *stream(request, signal) {
-    const providerId = this.options.providerName ?? "openai";
-    const headers = {
-      "content-type": "application/json",
-      accept: "text/event-stream",
-      authorization: `Bearer ${this.options.apiKey}`,
-      ...this.options.extraHeaders ?? {}
-    };
-    const url = `${this.baseUrl}/responses`;
-    const response = await this.fetchImpl(url, {
+  /** Issues the streaming request. Separated so `stream()` reads as fetch → check → consume. */
+  async post(request, signal) {
+    return await this.fetchImpl(`${this.baseUrl}/responses`, {
       method: "POST",
       signal,
-      headers,
+      headers: {
+        "content-type": "application/json",
+        accept: "text/event-stream",
+        authorization: `Bearer ${this.options.apiKey}`,
+        ...this.options.extraHeaders ?? {}
+      },
       body: JSON.stringify(
         // Both options ride the SAME flag on purpose: a provider that never declared support gets
         // the byte-identical pre-#383 body, even in the impossible case where it returned ciphertext
@@ -2228,129 +2294,67 @@ var ResponsesApiClient = class {
         )
       )
     });
-    if (!response.ok) {
-      const text2 = await response.text().catch(() => "");
-      let body = text2;
+  }
+  /** Maps a non-2xx response to a typed error. Returns it rather than throwing, so the caller's
+   * control flow stays visible at the call site. */
+  async errorFor(response, providerId) {
+    const text = await response.text().catch(() => "");
+    let body = text;
+    try {
+      body = JSON.parse(text);
+    } catch {
+    }
+    return mapOpenAICompatibleError({
+      providerId,
+      status: response.status,
+      body,
+      headers: response.headers,
+      endpoint: "/responses"
+    });
+  }
+  /**
+   * SSE frames → parsed events, stopping at `[DONE]`. A frame that is not JSON is skipped rather
+   * than fatal: a provider that emits a keep-alive or a comment frame must not end the response.
+   */
+  async *decode(body, signal) {
+    for await (const record of parseSseStream(body, signal)) {
+      if (record.data === "[DONE]") return;
+      let event;
       try {
-        body = JSON.parse(text2);
+        event = JSON.parse(record.data);
       } catch {
+        continue;
       }
-      throw mapOpenAICompatibleError({
-        providerId,
-        status: response.status,
-        body,
-        headers: response.headers,
-        endpoint: "/responses"
-      });
+      yield event;
     }
-    let text = "";
-    const toolCalls = [];
-    let stopReason = "end_turn";
-    let inputTokens;
-    let outputTokens;
-    let reasoningTokens;
-    let cacheReadTokens;
-    let cacheWriteTokens;
-    const pending = {};
-    let unclaimedReasoning = [];
+  }
+  async *stream(request, signal) {
+    const providerId = this.options.providerName ?? "openai";
+    const response = await this.post(request, signal);
+    if (!response.ok) throw await this.errorFor(response, providerId);
+    const acc = new ResponsesStreamAccumulator(
+      (callId, items) => this.rememberReasoning(callId, items)
+    );
     if (response.body !== null) {
-      for await (const record of parseSseStream(response.body, signal)) {
-        if (record.data === "[DONE]") break;
-        let event;
-        try {
-          event = JSON.parse(record.data);
-        } catch {
-          continue;
-        }
-        const t = event.type;
-        if (t === "response.output_text.delta") {
-          const d = event.delta ?? "";
-          if (d.length > 0) {
-            text += d;
-            yield { type: "text_delta", text: d };
-          }
-        } else if (t === "response.reasoning_summary_text.delta" || t === "response.reasoning_text.delta") {
-          const d = event.delta ?? "";
-          if (d.length > 0) yield { type: "reasoning_delta", text: d };
-        } else if (t === "response.output_item.done" && event.item?.type === "reasoning") {
-          const id = event.item.id;
-          const encrypted = event.item.encrypted_content;
-          if (id !== void 0 && encrypted !== void 0 && encrypted.length > 0) {
-            unclaimedReasoning.push({ id, encrypted_content: encrypted });
-          }
-        } else if (t === "response.output_item.added" && event.item?.type === "function_call") {
-          const id = event.item.id ?? event.item.call_id ?? "call-0";
-          pending[id] = {
-            callId: event.item.call_id ?? id,
-            name: event.item.name ?? "",
-            args: event.item.arguments ?? ""
-          };
-        } else if (t === "response.function_call_arguments.delta") {
-          const c = event.item_id !== void 0 ? pending[event.item_id] : void 0;
-          if (c !== void 0) c.args += event.delta ?? "";
-        } else if (t === "response.output_item.done" && event.item?.type === "function_call") {
-          const id = event.item.id ?? event.item.call_id ?? "call-0";
-          const c = pending[id] ?? {
-            callId: event.item.call_id ?? id,
-            name: event.item.name ?? "",
-            args: event.item.arguments ?? ""
-          };
-          const rawArgs = event.item.arguments ?? c.args;
-          const call = {
-            type: "tool_use",
-            id: c.callId,
-            name: c.name.length > 0 ? c.name : event.item.name ?? "",
-            input: parseToolArguments(rawArgs)
-          };
-          toolCalls.push(call);
-          if (unclaimedReasoning.length > 0) {
-            this.rememberReasoning(call.id, unclaimedReasoning);
-            unclaimedReasoning = [];
-          }
-          delete pending[id];
-        } else if (t === "response.completed" || t === "response.incomplete") {
-          const usage = event.response?.usage;
-          if (usage !== void 0) {
-            inputTokens = usage.input_tokens;
-            outputTokens = usage.output_tokens;
-            reasoningTokens = usage.output_tokens_details?.reasoning_tokens;
-            cacheReadTokens = usage.input_tokens_details?.cached_tokens;
-            cacheWriteTokens = usage.input_tokens_details?.cache_write_tokens;
-          }
-          stopReason = t === "response.incomplete" ? "max_tokens" : "end_turn";
-        } else if (t === "response.failed" || t === "error") {
-          const msg = event.response?.error?.message ?? event.message ?? "responses stream failed";
-          yield { type: "error", message: msg };
+      for await (const event of this.decode(response.body, signal)) {
+        const failure = ResponsesStreamAccumulator.failureMessage(event);
+        if (failure !== void 0) {
+          yield { type: "error", message: failure };
           throw mapOpenAICompatibleError({
             providerId,
             status: 502,
-            body: { error: { message: msg } },
+            body: { error: { message: failure } },
             headers: response.headers,
             endpoint: "/responses"
           });
         }
+        yield* acc.consume(event);
       }
     }
-    if (toolCalls.length > 0 && stopReason === "end_turn") stopReason = "tool_use";
-    return makeLlmFinish({
-      stopReason,
-      text,
-      toolCalls,
-      inputTokens,
-      outputTokens,
-      reasoningTokens,
-      cacheReadTokens,
-      cacheWriteTokens
-    });
+    return acc.finish();
   }
 };
 
-// src/internal/llm/abort-error.ts
-function abortError2(signal) {
-  if (signal.reason instanceof Error) return signal.reason;
-  return new Error(signal.reason !== void 0 ? String(signal.reason) : "aborted");
-}
-
 // src/internal/llm/retrying-client.ts
 var MAX_ATTEMPTS = 3;
 function isRetriableError(err) {
@@ -2421,7 +2425,7 @@ var RetryingLlmClient = class {
   async *stream(request, signal) {
     let lastError;
     for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
-      if (signal.aborted) throw lastError ?? abortError2(signal);
+      if (signal.aborted) throw lastError ?? abortError(signal);
       const state = { emitted: false };
       try {
         return yield* consume(this.#inner.stream(request, signal), state);
@@ -2444,14 +2448,14 @@ var VERTEX_RULES = [
     test: (s, e) => s === 400 || e === "INVALID_ARGUMENT" || e === "FAILED_PRECONDITION" || e === "NOT_FOUND",
     code: "invalid_request"
   },
-  { test: (s, e) => s === 408 || e === "DEADLINE_EXCEEDED", code: "timeout" },
-  { test: (s) => s >= 500, code: "server_error" }
+  { test: (s, e) => s === 408 || e === "DEADLINE_EXCEEDED", code: "timeout" }
 ];
 function classifyVertexError(args, errStatus) {
   for (const rule of VERTEX_RULES) {
     if (rule.test(args.status, errStatus)) return rule.code;
   }
-  return "unknown";
+  const shared = httpStatusToErrorCode(args.status);
+  return shared === "auth_failed" ? "auth_permission" : shared;
 }
 function vertexMetadata(args, code) {
   return buildErrorMetadata({
@@ -2476,6 +2480,9 @@ var VERTEX_ERROR_BUILDERS = {
   invalid_request: (args, msg) => new ConfigurationError(`Vertex validation: ${msg}`, {
     metadata: vertexMetadata(args, "invalid_request")
   }),
+  quota_exceeded: (args, msg) => new RateLimitError(`Vertex quota exceeded: ${msg}`, {
+    metadata: vertexMetadata(args, "quota_exceeded")
+  }),
   timeout: (args, msg) => new NetworkError(`Vertex timeout: ${msg}`, { metadata: vertexMetadata(args, "timeout") }),
   server_error: (args, msg) => new NetworkError(`Vertex server error: ${msg}`, {
     metadata: vertexMetadata(args, "server_error")
@@ -2483,23 +2490,12 @@ var VERTEX_ERROR_BUILDERS = {
   unknown: (args, msg) => new UnknownAgentError(`Vertex unknown: ${msg}`, { metadata: vertexMetadata(args, "unknown") })
 };
 function mapVertexError(args) {
-  const parsed = parseBody2(args.body);
+  const parsed = parseErrorBody(args.body);
   const errStatus = parsed.error?.status ?? "";
   const message = parsed.error?.message ?? "Vertex request failed";
   const code = classifyVertexError(args, errStatus);
   return VERTEX_ERROR_BUILDERS[code](args, message);
 }
-function parseBody2(body) {
-  if (body !== null && typeof body === "object") return body;
-  if (typeof body === "string") {
-    try {
-      return JSON.parse(body);
-    } catch {
-      return {};
-    }
-  }
-  return {};
-}
 var cachedAuthClient;
 var SCOPE_CLOUD_PLATFORM = "https://www.googleapis.com/auth/cloud-platform";
 async function resolveVertexAccessToken() {
@@ -2685,20 +2681,18 @@ function buildChain(options) {
   }
   return clients;
 }
-function buildClient(name, routerOptions, perCallBaseUrl) {
+function buildTransport(name, routerOptions, perCallBaseUrl) {
   const baseProfile = getProviderProfile(name);
   if (baseProfile === void 0) return void 0;
   const profile = routerOptions.extractToolCallsFromContent === true && baseProfile.extractToolCallsFromContent !== true ? { ...baseProfile, extractToolCallsFromContent: true } : baseProfile;
   const resilience = routerOptions.onRateLimit !== void 0 ? { onRateLimit: routerOptions.onRateLimit } : {};
   const ambient = currentCredentialPool(name);
   if (ambient !== void 0) {
-    return new RetryingLlmClient(
-      new PoolAwareLlmClient(
-        ambient,
-        (apiKey) => selectTransport(profile, apiKey, perCallBaseUrl),
-        void 0,
-        resilience
-      )
+    return new PoolAwareLlmClient(
+      ambient,
+      (apiKey) => selectTransport(profile, apiKey, perCallBaseUrl),
+      void 0,
+      resilience
     );
   }
   const poolKeys = filterPoolKeys(routerOptions.apiKeys?.[name]);
@@ -2706,6 +2700,10 @@ function buildClient(name, routerOptions, perCallBaseUrl) {
   if (noAuthOverride !== void 0) return noAuthOverride;
   return buildPoolOrSingle({ name, profile, poolKeys, routerOptions, perCallBaseUrl });
 }
+function buildClient(name, routerOptions, perCallBaseUrl) {
+  const transport = buildTransport(name, routerOptions, perCallBaseUrl);
+  return transport === void 0 ? void 0 : new RetryingLlmClient(transport);
+}
 function maybeBuildNoAuthTransport(profile, poolKeys, baseUrl) {
   if (profile.authType !== "none" || poolKeys === void 0 || poolKeys.length === 0) {
     return void 0;
@@ -2724,18 +2722,16 @@ function buildPoolOrSingle(args) {
     );
     const pool = new CredentialPool(name, entries, strategy);
     const resilience = routerOptions.onRateLimit !== void 0 ? { onRateLimit: routerOptions.onRateLimit } : {};
-    return new RetryingLlmClient(
-      new PoolAwareLlmClient(
-        pool,
-        (apiKey2) => selectTransport(profile, apiKey2, perCallBaseUrl),
-        void 0,
-        resilience
-      )
+    return new PoolAwareLlmClient(
+      pool,
+      (apiKey2) => selectTransport(profile, apiKey2, perCallBaseUrl),
+      void 0,
+      resilience
     );
   }
   const apiKey = poolKeys?.[0] ?? resolveApiKey(profile.envVars) ?? sentinelForNoAuth(profile) ?? sentinelForLazyAuth(profile);
   if (apiKey === void 0) return void 0;
-  return new RetryingLlmClient(selectTransport(profile, apiKey, perCallBaseUrl));
+  return selectTransport(profile, apiKey, perCallBaseUrl);
 }
 function resolveBaseUrlEnvOverride(providerName) {
   switch (providerName) {
@@ -2804,7 +2800,7 @@ function selectTransport(profile, apiKey, baseUrl) {
     const ctx = { apiKey };
     return { fetch: profile.transform.fetch?.(ctx), headers: profile.transform.headers?.(ctx) };
   };
-  const comTransform = (opts, construct) => {
+  const withTransform = (opts, construct) => {
     const t = applyTransform();
     assertOAuthResolved(t);
     if (t.fetch !== void 0) opts.fetch = t.fetch;
@@ -2841,7 +2837,7 @@ function selectTransport(profile, apiKey, baseUrl) {
     const envOverride = resolveBaseUrlEnvOverride(profile.name);
     if (envOverride !== void 0) opts.baseUrl = envOverride;
     if (baseUrl !== void 0) opts.baseUrl = baseUrl;
-    return comTransform(opts, (o) => new OpenAIClient(o));
+    return withTransform(opts, (o) => new OpenAIClient(o));
   }
   if (profile.apiMode === "anthropic_messages") {
     if (profile.name === "vertex") {
@@ -2850,7 +2846,7 @@ function selectTransport(profile, apiKey, baseUrl) {
     }
     const opts = { apiKey };
     opts.baseUrl = baseUrl ?? process.env.ANTHROPIC_API_BASE_URL ?? profile.baseUrl;
-    return comTransform(opts, (o) => new AnthropicClient(o));
+    return withTransform(opts, (o) => new AnthropicClient(o));
   }
   if (profile.apiMode === "bedrock_anthropic") {
     const realKey = apiKey === "__bedrock_lazy_token__" ? void 0 : apiKey;
@@ -2876,11 +2872,166 @@ function selectTransport(profile, apiKey, baseUrl) {
     });
   }
   throw new ConfigurationError(
-    `Provider "${profile.name}" requires apiMode "${profile.apiMode}" but no transport is registered. Install a third-party transport plugin (@theokit-transport-${profile.apiMode}) or use a provider with apiMode "chat_completions" or "anthropic_messages".`,
+    `Provider "${profile.name}" declares apiMode "${profile.apiMode}", which this SDK has no transport for. Transports are built in and cannot be extended by a plugin; the supported modes are "chat_completions", "anthropic_messages", "bedrock_anthropic" and "responses_api". Change the provider's apiMode to one of those, or open an issue if the provider genuinely speaks a fifth protocol.`,
     { code: "transport_unavailable" }
   );
 }
 
+// src/internal/auth/api-key-validator.ts
+var FIXTURE_KEY_PREFIX = "theo_test_";
+var LOCAL_RUNTIME_MOCK_KEY = "local";
+var MIN_KEY_LENGTH = 16;
+var KNOWN_PROVIDER_PREFIXES = [
+  { provider: "openai", prefix: "sk-" },
+  { provider: "anthropic", prefix: "sk-ant-" },
+  { provider: "openrouter", prefix: "sk-or-" }
+];
+function validateApiKeyShape(key, options = {}) {
+  const opts = typeof options === "string" ? { provider: options } : options;
+  const tier1 = checkTier1(key);
+  if (tier1.malformed) return tier1;
+  const validKey = key;
+  if (validKey.startsWith(FIXTURE_KEY_PREFIX) || validKey === LOCAL_RUNTIME_MOCK_KEY) {
+    return { malformed: false };
+  }
+  if (opts.strict === false) return { malformed: false };
+  return checkTier2(validKey, opts.provider);
+}
+function checkTier1(key) {
+  if (key === void 0 || key.length === 0) {
+    return { malformed: true, reason: "empty", message: "API key is empty." };
+  }
+  if (key.trim().length === 0) {
+    return {
+      malformed: true,
+      reason: "whitespace_only",
+      message: "API key contains only whitespace."
+    };
+  }
+  if (key.length < 4) {
+    return {
+      malformed: true,
+      reason: "too_short",
+      message: `API key must be at least 4 chars (got ${key.length}).`
+    };
+  }
+  return { malformed: false };
+}
+function checkTier2(key, provider) {
+  if (key.length < MIN_KEY_LENGTH) {
+    return {
+      malformed: true,
+      reason: "too_short",
+      message: `API key must be at least ${MIN_KEY_LENGTH} chars (got ${key.length}).`
+    };
+  }
+  if (/\s/.test(key)) {
+    return {
+      malformed: true,
+      reason: "embedded_whitespace",
+      message: "API key contains embedded whitespace."
+    };
+  }
+  return checkProviderPrefix(key, provider);
+}
+function checkProviderPrefix(key, provider) {
+  if (provider === void 0) return { malformed: false };
+  const hint = KNOWN_PROVIDER_PREFIXES.find((p) => p.provider === provider.toLowerCase());
+  if (hint === void 0) return { malformed: false };
+  if (!key.startsWith(hint.prefix)) {
+    return {
+      malformed: true,
+      reason: "missing_known_prefix",
+      message: `API key for provider "${hint.provider}" expected to start with "${hint.prefix}".`
+    };
+  }
+  return { malformed: false };
+}
+
+// src/internal/providers/register-plugin-providers.ts
+function registerPluginProviderProfiles(entries) {
+  let registered = 0;
+  for (const entry of entries) {
+    registerProvider(entry.profile);
+    registered += 1;
+  }
+  return registered;
+}
+var PROVIDER_CREDENTIAL_ENV_VARS = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "OPENROUTER_API_KEY"
+];
+function presentProviderCredentialEnvVars() {
+  return PROVIDER_CREDENTIAL_ENV_VARS.filter((name) => {
+    const value = process.env[name];
+    return typeof value === "string" && value.length > 0;
+  });
+}
+var AMBIENT_STORE = {
+  home: homedir(),
+  dirName: ".theokit",
+  fileName: "auth.json",
+  homeEnvVar: "THEOKIT_AUTH_HOME"
+};
+function isStoredOAuthAvailable(env = process.env) {
+  try {
+    return readStoredOAuth(AMBIENT_STORE, env) !== void 0;
+  } catch {
+    return false;
+  }
+}
+function isAwsBedrockAuthAvailable() {
+  if (typeof process.env.AWS_BEARER_TOKEN_BEDROCK === "string" && process.env.AWS_BEARER_TOKEN_BEDROCK.length > 0) {
+    return true;
+  }
+  if (typeof process.env.AWS_ACCESS_KEY_ID === "string" && process.env.AWS_ACCESS_KEY_ID.length > 0) {
+    return true;
+  }
+  if (typeof process.env.AWS_PROFILE === "string" && process.env.AWS_PROFILE.length > 0) {
+    return true;
+  }
+  return awsCredentialsFileExists();
+}
+function awsCredentialsFileExists() {
+  try {
+    const home = process.env.HOME ?? process.env.USERPROFILE;
+    if (home === void 0 || home.length === 0) return false;
+    return existsSync(`${home}/.aws/credentials`) || existsSync(`${home}/.aws/config`);
+  } catch {
+    return false;
+  }
+}
+function isGcpVertexAuthAvailable() {
+  if (typeof process.env.GOOGLE_APPLICATION_CREDENTIALS === "string" && process.env.GOOGLE_APPLICATION_CREDENTIALS.length > 0) {
+    return true;
+  }
+  if (typeof process.env.GOOGLE_CLOUD_PROJECT === "string" && process.env.GOOGLE_CLOUD_PROJECT.length > 0) {
+    return true;
+  }
+  return false;
+}
+function isLocalNoAuthProviderAvailable() {
+  return true;
+}
+
+// src/internal/runtime/fixtures/fixture-mode.ts
+var FIXTURE_API_KEY_PREFIX = "theo_test_";
+function isFixtureApiKey(apiKey) {
+  if (apiKey === void 0) return false;
+  return apiKey.startsWith(FIXTURE_API_KEY_PREFIX);
+}
+function shouldUseFixtureMode(apiKey) {
+  if (getConfiguredBaseUrl() !== void 0) return false;
+  return isFixtureApiKey(apiKey);
+}
+function shouldUseRealLocalRuntime(apiKey) {
+  if (isFixtureApiKey(apiKey)) return false;
+  if (isStoredOAuthAvailable()) return true;
+  if (apiKey === void 0 || apiKey.length === 0) return false;
+  return presentProviderCredentialEnvVars().length > 0 || isAwsBedrockAuthAvailable() || isGcpVertexAuthAvailable() || isLocalNoAuthProviderAvailable();
+}
+
 // src/internal/local-agent/real-local-run-provider.ts
 function inferProviderFromApiKey(apiKey) {
   const provider = providerFromApiKeyPrefix(apiKey);
@@ -2910,6 +3061,32 @@ function warnProviderPrecedenceOnce(asked, used) {
 `
   );
 }
+var pluginProvidersAnnounced = false;
+function resolveRunProvider(options) {
+  registerBuiltins();
+  const profiles = options.pluginManager?.aggregated.providerProfiles ?? [];
+  const registered = registerPluginProviderProfiles(profiles);
+  if (registered > 0 && !pluginProvidersAnnounced) {
+    pluginProvidersAnnounced = true;
+    const names = profiles.map((e) => e.profile.name).join(", ");
+    diag(`[theokit-sdk] registered ${registered} plugin provider profile(s): ${names}
+`);
+  }
+  const parsedModel = parseModelId(options.model?.id);
+  const modelInferredProvider = parsedModel.provider !== void 0 && getProviderProfile(parsedModel.provider) !== void 0 ? parsedModel.provider : void 0;
+  const keyInferredProvider = inferProviderFromApiKey(options.agentOptions.apiKey);
+  const primary = options.agentOptions.providers?.routes?.[0]?.provider ?? keyInferredProvider ?? modelInferredProvider ?? detectPrimaryProvider();
+  warnProviderPrecedenceOnce(modelInferredProvider, primary);
+  const effectiveModelId = modelInferredProvider !== void 0 && modelInferredProvider === primary ? parsedModel.name : options.model?.id ?? "claude-sonnet-4-6";
+  return { primary, effectiveModelId };
+}
+function mergeExplicitApiKey(pools, primary, apiKey) {
+  if (apiKey === void 0 || apiKey.length === 0) return pools;
+  if (isFixtureApiKey(apiKey) || apiKey === LOCAL_RUNTIME_MOCK_KEY) return pools;
+  const existing = pools?.[primary];
+  if (existing !== void 0 && existing.length > 0) return pools;
+  return { ...pools ?? {}, [primary]: [apiKey] };
+}
 
 // src/internal/runtime/compression/compression-model-registry.ts
 var EXACT_REGISTRY = /* @__PURE__ */ new Map([
@@ -2946,12 +3123,13 @@ var WILDCARD_REGISTRY = [
   ["bedrock/anthropic.claude-3-5-sonnet*", "bedrock/anthropic.claude-3-5-haiku*"]
 ];
 var NO_AUTH_PROVIDERS = /* @__PURE__ */ new Set(["ollama", "lmstudio", "llamacpp"]);
-var CompressionModelUnresolvedError = class extends Error {
+var CompressionModelUnresolvedError = class extends TheokitAgentError {
   name = "CompressionModelUnresolvedError";
   agentModel;
   constructor(agentModel) {
     super(
-      `Could not resolve a same-family-cheaper-tier compression model for "${agentModel}". Provide Agent.create({compression: {model: "<your-cheaper-model>"}}) OR add "${agentModel}" to the compression-model-registry (see ADR D440).`
+      `Could not resolve a same-family-cheaper-tier compression model for "${agentModel}". Provide Agent.create({compression: {model: "<your-cheaper-model>"}}) OR add "${agentModel}" to the compression-model-registry (see ADR D440).`,
+      { code: "compression_model_unresolved", isRetryable: false }
     );
     this.agentModel = agentModel;
   }
@@ -2981,8 +3159,11 @@ function isNoAuthProvider(agentModel) {
 }
 
 // src/internal/runtime/compression/compression-summarizer.ts
-var CompressionFailedError = class extends Error {
+var CompressionFailedError = class extends TheokitAgentError {
   name = "CompressionFailedError";
+  constructor(message, options = {}) {
+    super(message, { ...options, code: "compression_failed", isRetryable: true });
+  }
 };
 function buildCompressionPrompt(messages) {
   const formatted = messages.map((m) => `[${m.role}]: ${m.content}`).join("\n\n");
@@ -3131,12 +3312,10 @@ function shouldAutoCompact(opts) {
   if (opts.usageTotal <= 0 || opts.contextWindow <= 0) return false;
   return opts.usageTotal >= Math.floor(opts.contextWindow * 9 / 10);
 }
-var autoCompactAttempts = (() => {
-  const g = globalThis;
-  const sym = /* @__PURE__ */ Symbol.for("theokit-sdk.session.auto-compact-attempts");
-  if (g[sym] === void 0) g[sym] = /* @__PURE__ */ new Map();
-  return g[sym];
-})();
+var autoCompactAttempts = globalSingleton(
+  "theokit-sdk.session.auto-compact-attempts",
+  () => /* @__PURE__ */ new Map()
+);
 async function autoCompactIfNeeded(opts) {
   if (!shouldAutoCompact(opts)) return false;
   const key = `${opts.loc.cwd}::${opts.loc.agentId}`;
@@ -3159,6 +3338,6 @@ async function autoCompactIfNeeded(opts) {
   }
 }
 
-export { COMPACT_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, CircuitBreaker, autoCompactIfNeeded, buildDefaultSummarizer, compactSessionTranscript, detectPrimaryProvider, discoverProviderPlugins, getConfiguredBaseUrl, httpRequest, inferProviderFromApiKey, isCompactSummary, isFixtureApiKey, mapOllamaHttpError, mapOllamaTransportError, parseSseStream, presentProviderCredentialEnvVars, readErrorResponseBody, relayStream, renderToolResultContentText, resolveProviderChain, resolveSummarizerRoute, shouldAutoCompact, shouldUseFixtureMode, shouldUseRealLocalRuntime, tryFirstEvent, warnProviderPrecedenceOnce };
-//# sourceMappingURL=chunk-DN2PACRI.js.map
-//# sourceMappingURL=chunk-DN2PACRI.js.map
+export { COMPACT_SUMMARY_MARKER, COMPACT_USER_MESSAGE_MAX_TOKENS, CircuitBreaker, abortError, autoCompactIfNeeded, buildDefaultSummarizer, compactSessionTranscript, discoverProviderPlugins, getConfiguredBaseUrl, httpRequest, isCompactSummary, isFixtureApiKey, mapOllamaHttpError, mapOllamaTransportError, mergeExplicitApiKey, parseSseStream, presentProviderCredentialEnvVars, readErrorResponseBody, relayStream, renderToolResultContentText, resolveProviderChain, resolveRunProvider, resolveSummarizerRoute, shouldAutoCompact, shouldUseFixtureMode, shouldUseRealLocalRuntime, tryFirstEvent, validateApiKeyShape };
+//# sourceMappingURL=chunk-K3NH62DG.js.map
+//# sourceMappingURL=chunk-K3NH62DG.js.map