@robota-sdk/agent-provider-openai 3.0.0-beta.83 → 3.0.0-beta.85

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @robota-sdk/agent-provider-openai
 
+## 3.0.0-beta.85
+
+### Patch Changes
+
+- 3ab2eca: - External presets accept every permission mode a session does, `auto` included; `auto` used to fail validation.
+  - `createDagFramework({ ports: { costMeta } })` wires cost-metadata management; without it cost operations still report that they are unsupported.
+  - `startCli()` runs the subagent worker when a subagent starts the embedder's entry script again, as the `robota` executable already did; an embedded CLI used to start a second CLI there.
+  - The provider `executor` option docs no longer import a `RemoteExecutor` that does not exist, and `IRemoteExecutorConfig` is marked deprecated: nothing implements a remote executor.
+- Updated dependencies [41cca13]
+- Updated dependencies [ada3841]
+- Updated dependencies [5093a30]
+- Updated dependencies [94b2c87]
+- Updated dependencies [3ab2eca]
+  - @robota-sdk/agent-core@3.0.0-beta.85
+  - @robota-sdk/agent-provider-openai-compatible@3.0.0-beta.85
+
+## 3.0.0-beta.84
+
+### Patch Changes
+
+- 9c6a8db: Provider adapters now throw the specific typed failure a vendor response describes, instead of a
+  generic `ProviderError` carrying only its status. A 401/403 (or a vendor-specific authentication type)
+  becomes an `AuthenticationError`; a response naming an unavailable model — by code or, when the vendor
+  gives neither (Anthropic's and Gemini's real bodies carry no distinguishing code), by its message —
+  becomes a `ModelNotAvailableError`, whose `model` is now optional since a bare HTTP status does not
+  always name one; a transport failure becomes a `NetworkError`, which now also carries the provider
+  name. A 429's `retry-after` header (a delta or an HTTP-date) is read into `RateLimitError.retryAfter`
+  when the vendor sends one.
+
+  Vendor error text is scrubbed of anything that reads like a credential — an `Authorization`/`Bearer`
+  value, an API key in a header, query string or JSON body, a bare `sk-`/`AIza…` token — before it is
+  kept on any of these typed errors, so a misconfigured self-hosted gateway that echoes a request back
+  can no longer leak one into a message or a "Details" disclosure. The new `scrubSecrets` export applies
+  the same scrubbing to arbitrary text.
+
+- Updated dependencies [9f46375]
+- Updated dependencies [9c6a8db]
+  - @robota-sdk/agent-core@3.0.0-beta.84
+  - @robota-sdk/agent-provider-openai-compatible@3.0.0-beta.84
+
 ## 3.0.0-beta.83
 
 ### Patch Changes

package/README.md

@@ -44,6 +44,7 @@ const provider = new OpenAIProvider({
   baseURL: 'https://ai-gateway.vercel.sh/v1',
 });
 // then: defaultModel: { provider: 'openai', model: 'anthropic/claude-sonnet-4-5' }
+// (a gateway model slug, passed through to the gateway as written)
 ```
 
 The API surface follows `baseURL` unless `apiSurface` is set:
@@ -63,28 +64,52 @@ tool is sent with `strict: true` on both the Responses and Chat Completions surf
 OpenAI-compatible endpoint that rejects the `strict` field needs `strictTools` left off. With
 `strictTools` off (the default) tool schemas are forwarded as authored and no `strict` field is sent.
 
+### Reasoning effort and web tools
+
+A reasoning-effort selection (`defaultModel.effort` on a `Robota` agent, or `effort` on a chat call)
+is sent as `reasoning.effort` only on the official Responses API (no `baseURL`) and only for models
+in the provider's verified effort table. On Chat Completions, behind a custom `baseURL`, or for other
+models, the effort is reported as not applied and no native field is sent. When a call selects an
+effort, a static `reasoning` option's `effort` must equal the value sent; a different value, or any
+value when no native effort is sent, is rejected.
+
+Native web search and web fetch are not available through this provider on either surface. Setting
+`nativeWebTools.webSearch` or `nativeWebTools.webFetch` to `true` makes the constructor throw.
+
 ## Options
 
 `new OpenAIProvider(options: IOpenAIProviderOptions)`. One of `apiKey`, `client` or `executor` is
 required; the constructor throws otherwise.
 
-| Option               | Type                                       | Description                                                                                                     |
-| -------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `apiKey`             | `string`                                   | API key used to create the `openai` client.                                                                     |
-| `baseURL`            | `string`                                   | Endpoint base URL (default `https://api.openai.com/v1`). Also switches the default surface to Chat Completions. |
-| `apiSurface`         | `'responses' \| 'chat-completions'`        | Forces the API surface instead of deriving it from `baseURL`.                                                   |
-| `defaultModel`       | `string`                                   | Model used when a call does not name one.                                                                       |
-| `organization`       | `string`                                   | OpenAI organization ID.                                                                                         |
-| `timeout`            | `number`                                   | Request timeout in milliseconds.                                                                                |
-| `strictTools`        | `boolean`                                  | Closes tool object schemas and requests OpenAI strict function calling (see above).                             |
-| `responseFormat`     | `'text' \| 'json_object' \| 'json_schema'` | Response format; `'json_schema'` uses `jsonSchema`.                                                             |
-| `jsonSchema`         | `IOpenAIJsonSchemaDefinition`              | Schema for Structured Outputs when `responseFormat` is `'json_schema'`.                                         |
-| `reasoning`          | `IOpenAIResponsesReasoningOptions`         | Responses API reasoning controls (`effort`, `summary`).                                                         |
-| `includeStreamUsage` | `boolean`                                  | Requests token usage on streaming Chat Completions turns (default `true`).                                      |
-| `client`             | `OpenAI`                                   | A pre-built `openai` client, used instead of `apiKey`.                                                          |
-| `executor`           | `IExecutor`                                | Delegates chat calls to an executor instead of calling the API directly.                                        |
-| `payloadLogger`      | `IPayloadLogger`                           | Logs a summary of each Chat Completions request (model, message count, tools present, temperature, max tokens). |
-| `logger`             | `ILogger`                                  | Logger for internal provider messages (silent by default).                                                      |
+| Option                      | Type                                       | Description                                                                                                     |
+| --------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `apiKey`                    | `string`                                   | API key used to create the `openai` client.                                                                     |
+| `baseURL`                   | `string`                                   | Endpoint base URL (default `https://api.openai.com/v1`). Also switches the default surface to Chat Completions. |
+| `apiSurface`                | `'responses' \| 'chat-completions'`        | Forces the API surface instead of deriving it from `baseURL`.                                                   |
+| `defaultModel`              | `string`                                   | Model used when a call does not name one.                                                                       |
+| `organization`              | `string`                                   | OpenAI organization ID.                                                                                         |
+| `timeout`                   | `number`                                   | Request timeout in milliseconds.                                                                                |
+| `strictTools`               | `boolean`                                  | Closes tool object schemas and requests OpenAI strict function calling (see above).                             |
+| `responseFormat`            | `'text' \| 'json_object' \| 'json_schema'` | Response format; `'json_schema'` uses `jsonSchema`.                                                             |
+| `jsonSchema`                | `IOpenAIJsonSchemaDefinition`              | Schema for Structured Outputs when `responseFormat` is `'json_schema'`.                                         |
+| `reasoning`                 | `IOpenAIResponsesReasoningOptions`         | Responses API reasoning controls (`effort`, `summary`).                                                         |
+| `store`                     | `boolean`                                  | Responses API only: whether OpenAI stores the response; when unset, OpenAI's default applies.                   |
+| `includeEncryptedReasoning` | `boolean`                                  | Responses API only: asks for encrypted reasoning items, so reasoning can continue without server-side state.    |
+| `nativeWebTools`            | `IOpenAINativeWebToolsOptions`             | Not supported: `true` for `webSearch` or `webFetch` throws (see above).                                         |
+| `includeStreamUsage`        | `boolean`                                  | Requests token usage on streaming Chat Completions turns (default `true`).                                      |
+| `client`                    | `OpenAI`                                   | A pre-built `openai` client, used instead of `apiKey`.                                                          |
+| `executor`                  | `IExecutor`                                | Delegates chat calls to an executor instead of calling the API directly.                                        |
+| `payloadLogger`             | `IPayloadLogger`                           | Logs a summary of each Chat Completions request (model, message count, tools present, temperature, max tokens). |
+| `logger`                    | `ILogger`                                  | Logger for internal provider messages (silent by default).                                                      |
+
+## Errors
+
+A failed API call throws a typed error from `@robota-sdk/agent-core`: `RateLimitError` (with
+`retryAfter` from the `retry-after` header), `AuthenticationError`, `ModelNotAvailableError` or
+`NetworkError` when the failure is one of those, otherwise a `ProviderError` that carries the HTTP
+`status` and the error `type` the endpoint reported and keeps the SDK error as `originalError`. Both
+API surfaces, streaming included, map failures the same way. An aborted call rethrows the abort
+unchanged. See [Provider failures](../../content/guide/error-handling.md#provider-failures).
 
 ## Exports
 

package/dist/node/index.d.cts

@@ -173,26 +173,18 @@ interface IOpenAIProviderOptions {
   /**
    * Optional executor for handling AI requests
    *
-   * When provided, the provider will delegate all chat operations to this executor
-   * instead of making direct API calls. This enables remote execution capabilities.
+   * When provided, the provider delegates every chat call to this executor instead of calling the
+   * API itself — for example to route calls through your own server. Implement `IExecutor` from
+   * `@robota-sdk/agent-core`; `LocalExecutor` is the in-process one.
    *
    * @example
    * ```typescript
-   * import { LocalExecutor, RemoteExecutor } from '@robota-sdk/agent-core';
+   * import { LocalExecutor } from '@robota-sdk/agent-core';
    *
-   * // Local execution (registers this provider)
-   * const localExecutor = new LocalExecutor();
-   * localExecutor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
+   * const executor = new LocalExecutor();
+   * executor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
    *
-   * // Remote execution
-   * const remoteExecutor = new RemoteExecutor({
-   *   serverUrl: 'https://api.robota.io',
-   *   userApiKey: 'user-token-123'
-   * });
-   *
-   * const provider = new OpenAIProvider({
-   *   executor: remoteExecutor // No direct API key needed
-   * });
+   * const provider = new OpenAIProvider({ executor });
    * ```
    */
   executor?: IExecutor;

package/dist/node/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/openai/types.ts","../../src/openai/provider.ts","../../src/openai/adapter.ts","../../src/openai/provider-definition.ts"],"mappings":";;;;KAIY;UAEK;EACf;EACA;EACA,SAAS,eAAe;EACxB;;UAGe;EACf;EACA;;UAGe;EACf;EACA;;;;;KAMU,4EAMR,8BACA,+BACA,mCACA,SACA,iBACA,UACA,YACA,2BACA;GACG,cAAc;;;;;UAKJ;;;;GAId,cAAc;;;;EAKf;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BA;;;;EAKA;;;;;;;EAQA,aAAa;;;;;;;EAQb;;;;EAKA,aAAa;;;;;EAMb,YAAY;;;;EAKZ;;;;EAKA;;;;;;;;;;;;;;;;;EAkBA;;;;;;;;EASA,iBAAiB;;;;EAKjB,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BT,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BhB,WAAW;;;;;EAMX,SAAS;;;;;;;;;;;;cC1ME,uBAAuB;WAChB;WACA;mBAED;mBACA;mBACA;mBACA;mBACA;;;;;;;EAQjB,cAAc;EAEF,YAAA,SAAS;EA6BN,KACb,UAAU,qBACV,UAAU,eACT,QAAQ;EAgDK,WACd,UAAU,qBACV,UAAU,eACT,cAAc;UAiCF;;;;;;;;;;EAuCf;;;;;;EASA;UAIQ;UAKA;EAKC,eAAe;UAMhB;;;;;YAcW,qBAAqB;;;;;;;;UAahC;UAYA;EAiCC;EAIA,mBAAmB;EAwBnB;EAIM,WAAW;YAIP,iBAAiB,UAAU;;;;;;;;;;;;cC/UnC;;;;;;;;;SASJ,wBAAwB,UAAU,sBAAsB;;;;;SAqBxD,eAAe,UAAU,sBAAsB,OAAO,KAAK;;;;;SAU3D,eAAe,KAAK,oBAAoB,OAAO,KAAK;;;;SA2EpD,wBACL,UAAU,OAAO,KAAK,8BACtB,wBACC,OAAO,KAAK;;;;cC1HJ;cACA;iBAeG,kCAAkC"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/openai/types.ts","../../src/openai/provider.ts","../../src/openai/adapter.ts","../../src/openai/provider-definition.ts"],"mappings":";;;;KAIY;UAEK;EACf;EACA;EACA,SAAS,eAAe;EACxB;;UAGe;EACf;EACA;;UAGe;EACf;EACA;;;;;KAMU,4EAMR,8BACA,+BACA,mCACA,SACA,iBACA,UACA,YACA,2BACA;GACG,cAAc;;;;;UAKJ;;;;GAId,cAAc;;;;EAKf;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BA;;;;EAKA;;;;;;;EAQA,aAAa;;;;;;;EAQb;;;;EAKA,aAAa;;;;;EAMb,YAAY;;;;EAKZ;;;;EAKA;;;;;;;;;;;;;;;;;EAkBA;;;;;;;;EASA,iBAAiB;;;;EAKjB,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BT,gBAAgB;;;;;;;;;;;;;;;;;;EAmBhB,WAAW;;;;;EAMX,SAAS;;;;;;;;;;;;cClME,uBAAuB;WAChB;WACA;mBAED;mBACA;mBACA;mBACA;mBACA;;;;;;;EAQjB,cAAc;EAEF,YAAA,SAAS;EA6BN,KACb,UAAU,qBACV,UAAU,eACT,QAAQ;EAgDK,WACd,UAAU,qBACV,UAAU,eACT,cAAc;UAiCF;;;;;;;;;;EAuCf;;;;;;EASA;UAIQ;UAKA;EAKC,eAAe;UAMhB;;;;;YAcW,qBAAqB;;;;;;;;UAahC;UAYA;EAiCC;EAIA,mBAAmB;EAwBnB;EAIM,WAAW;YAIP,iBAAiB,UAAU;;;;;;;;;;;;cC/UnC;;;;;;;;;SASJ,wBAAwB,UAAU,sBAAsB;;;;;SAqBxD,eAAe,UAAU,sBAAsB,OAAO,KAAK;;;;;SAU3D,eAAe,KAAK,oBAAoB,OAAO,KAAK;;;;SA2EpD,wBACL,UAAU,OAAO,KAAK,8BACtB,wBACC,OAAO,KAAK;;;;cC1HJ;cACA;iBAeG,kCAAkC"}

package/dist/node/index.d.ts

@@ -173,26 +173,18 @@ interface IOpenAIProviderOptions {
   /**
    * Optional executor for handling AI requests
    *
-   * When provided, the provider will delegate all chat operations to this executor
-   * instead of making direct API calls. This enables remote execution capabilities.
+   * When provided, the provider delegates every chat call to this executor instead of calling the
+   * API itself — for example to route calls through your own server. Implement `IExecutor` from
+   * `@robota-sdk/agent-core`; `LocalExecutor` is the in-process one.
    *
    * @example
    * ```typescript
-   * import { LocalExecutor, RemoteExecutor } from '@robota-sdk/agent-core';
+   * import { LocalExecutor } from '@robota-sdk/agent-core';
    *
-   * // Local execution (registers this provider)
-   * const localExecutor = new LocalExecutor();
-   * localExecutor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
+   * const executor = new LocalExecutor();
+   * executor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
    *
-   * // Remote execution
-   * const remoteExecutor = new RemoteExecutor({
-   *   serverUrl: 'https://api.robota.io',
-   *   userApiKey: 'user-token-123'
-   * });
-   *
-   * const provider = new OpenAIProvider({
-   *   executor: remoteExecutor // No direct API key needed
-   * });
+   * const provider = new OpenAIProvider({ executor });
    * ```
    */
   executor?: IExecutor;

package/dist/node/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/openai/types.ts","../../src/openai/provider.ts","../../src/openai/adapter.ts","../../src/openai/provider-definition.ts"],"mappings":";;;;KAIY;UAEK;EACf;EACA;EACA,SAAS,eAAe;EACxB;;UAGe;EACf;EACA;;UAGe;EACf;EACA;;;;;KAMU,4EAMR,8BACA,+BACA,mCACA,SACA,iBACA,UACA,YACA,2BACA;GACG,cAAc;;;;;UAKJ;;;;GAId,cAAc;;;;EAKf;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BA;;;;EAKA;;;;;;;EAQA,aAAa;;;;;;;EAQb;;;;EAKA,aAAa;;;;;EAMb,YAAY;;;;EAKZ;;;;EAKA;;;;;;;;;;;;;;;;;EAkBA;;;;;;;;EASA,iBAAiB;;;;EAKjB,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BT,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BhB,WAAW;;;;;EAMX,SAAS;;;;;;;;;;;;cC1ME,uBAAuB;WAChB;WACA;mBAED;mBACA;mBACA;mBACA;mBACA;;;;;;;EAQjB,cAAc;EAEF,YAAA,SAAS;EA6BN,KACb,UAAU,qBACV,UAAU,eACT,QAAQ;EAgDK,WACd,UAAU,qBACV,UAAU,eACT,cAAc;UAiCF;;;;;;;;;;EAuCf;;;;;;EASA;UAIQ;UAKA;EAKC,eAAe;UAMhB;;;;;YAcW,qBAAqB;;;;;;;;UAahC;UAYA;EAiCC;EAIA,mBAAmB;EAwBnB;EAIM,WAAW;YAIP,iBAAiB,UAAU;;;;;;;;;;;;cC/UnC;;;;;;;;;SASJ,wBAAwB,UAAU,sBAAsB;;;;;SAqBxD,eAAe,UAAU,sBAAsB,OAAO,KAAK;;;;;SAU3D,eAAe,KAAK,oBAAoB,OAAO,KAAK;;;;SA2EpD,wBACL,UAAU,OAAO,KAAK,8BACtB,wBACC,OAAO,KAAK;;;;cC1HJ;cACA;iBAeG,kCAAkC"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/openai/types.ts","../../src/openai/provider.ts","../../src/openai/adapter.ts","../../src/openai/provider-definition.ts"],"mappings":";;;;KAIY;UAEK;EACf;EACA;EACA,SAAS,eAAe;EACxB;;UAGe;EACf;EACA;;UAGe;EACf;EACA;;;;;KAMU,4EAMR,8BACA,+BACA,mCACA,SACA,iBACA,UACA,YACA,2BACA;GACG,cAAc;;;;;UAKJ;;;;GAId,cAAc;;;;EAKf;;;;EAKA;;;;EAKA;;;;;;;EAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BA;;;;EAKA;;;;;;;EAQA,aAAa;;;;;;;EAQb;;;;EAKA,aAAa;;;;;EAMb,YAAY;;;;EAKZ;;;;EAKA;;;;;;;;;;;;;;;;;EAkBA;;;;;;;;EASA,iBAAiB;;;;EAKjB,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6BT,gBAAgB;;;;;;;;;;;;;;;;;;EAmBhB,WAAW;;;;;EAMX,SAAS;;;;;;;;;;;;cClME,uBAAuB;WAChB;WACA;mBAED;mBACA;mBACA;mBACA;mBACA;;;;;;;EAQjB,cAAc;EAEF,YAAA,SAAS;EA6BN,KACb,UAAU,qBACV,UAAU,eACT,QAAQ;EAgDK,WACd,UAAU,qBACV,UAAU,eACT,cAAc;UAiCF;;;;;;;;;;EAuCf;;;;;;EASA;UAIQ;UAKA;EAKC,eAAe;UAMhB;;;;;YAcW,qBAAqB;;;;;;;;UAahC;UAYA;EAiCC;EAIA,mBAAmB;EAwBnB;EAIM,WAAW;YAIP,iBAAiB,UAAU;;;;;;;;;;;;cC/UnC;;;;;;;;;SASJ,wBAAwB,UAAU,sBAAsB;;;;;SAqBxD,eAAe,UAAU,sBAAsB,OAAO,KAAK;;;;;SAU3D,eAAe,KAAK,oBAAoB,OAAO,KAAK;;;;SA2EpD,wBACL,UAAU,OAAO,KAAK,8BACtB,wBACC,OAAO,KAAK;;;;cC1HJ;cACA;iBAeG,kCAAkC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-provider-openai",
-  "version": "3.0.0-beta.83",
+  "version": "3.0.0-beta.85",
   "description": "OpenAI provider implementation for Robota SDK",
   "type": "module",
   "publishConfig": {
@@ -78,10 +78,11 @@
     "url": "https://github.com/woojubb/robota.git",
     "directory": "packages/agent-provider-openai"
   },
+  "homepage": "https://docs.robota.io/en/packages/agent-provider-openai/",
   "dependencies": {
     "openai": "^4.104.0",
-    "@robota-sdk/agent-core": "3.0.0-beta.83",
-    "@robota-sdk/agent-provider-openai-compatible": "3.0.0-beta.83"
+    "@robota-sdk/agent-core": "3.0.0-beta.85",
+    "@robota-sdk/agent-provider-openai-compatible": "3.0.0-beta.85"
   },
   "volta": {
     "extends": "../../package.json"

package/src/openai/__tests__/provider-errors.test.ts

@@ -3,7 +3,14 @@
  * collapsing into a bare `Error` whose only trace of the status is its message text.
  */
 
-import { ProviderError, RateLimitError, classifyProviderFailure } from '@robota-sdk/agent-core';
+import {
+  AuthenticationError,
+  ModelNotAvailableError,
+  NetworkError,
+  ProviderError,
+  RateLimitError,
+  classifyProviderFailure,
+} from '@robota-sdk/agent-core';
 import { APIConnectionError, APIError, APIUserAbortError } from 'openai';
 import { describe, expect, it, vi } from 'vitest';
 
@@ -44,7 +51,6 @@ const statuses: Array<[number, string]> = [
   [529, 'overloaded_error'],
   [503, 'server_error'],
   [500, 'server_error'],
-  [401, 'invalid_api_key'],
 ];
 
 describe('OpenAI provider errors', () => {
@@ -73,7 +79,7 @@ describe('OpenAI provider errors', () => {
       expect(classifyProviderFailure(error)).toEqual({ switchable: false, reason: 'aborted' });
     });
 
-    it(`${surface} classifies an SDK connection failure as network`, async () => {
+    it(`${surface} classifies an SDK connection failure as a NetworkError`, async () => {
       const provider = providerWith(
         surface,
         new APIConnectionError({
@@ -82,11 +88,11 @@ describe('OpenAI provider errors', () => {
         }),
       );
       const error = await failure(() => provider.chat(messages, { model: 'gpt-4o' }));
-      expect(error).toBeInstanceOf(ProviderError);
+      expect(error).toBeInstanceOf(NetworkError);
       expect(classifyProviderFailure(error)).toEqual({ switchable: false, reason: 'network' });
     });
 
-    it(`${surface} classifies a 400 model_not_found as model-unavailable`, async () => {
+    it(`${surface} maps a 400 model_not_found to ModelNotAvailableError`, async () => {
       const provider = providerWith(
         surface,
         APIError.generate(
@@ -99,6 +105,7 @@ describe('OpenAI provider errors', () => {
         ),
       );
       const error = await failure(() => provider.chat(messages, { model: 'gpt-4o' }));
+      expect(error).toBeInstanceOf(ModelNotAvailableError);
       expect(classifyProviderFailure(error)).toEqual({
         switchable: true,
         reason: 'model-unavailable',
@@ -110,5 +117,27 @@ describe('OpenAI provider errors', () => {
       const error = await failure(() => provider.chat(messages, { model: 'gpt-4o' }));
       expect(error).toBeInstanceOf(RateLimitError);
     });
+
+    it(`${surface} chat maps 401 to AuthenticationError, carrying the provider name`, async () => {
+      const provider = providerWith(surface, httpError(401, 'invalid_api_key'));
+      const error = await failure(() => provider.chat(messages, { model: 'gpt-4o' }));
+      expect(error).toBeInstanceOf(AuthenticationError);
+      expect((error as AuthenticationError).provider).toBe('openai');
+    });
+
+    it(`${surface} chat reads the retry-after header off a 429 into RateLimitError.retryAfter`, async () => {
+      const provider = providerWith(
+        surface,
+        APIError.generate(
+          429,
+          { error: { type: 'rate_limit_exceeded', message: 'slow down' } },
+          undefined,
+          { 'retry-after': '12' },
+        ),
+      );
+      const error = await failure(() => provider.chat(messages, { model: 'gpt-4o' }));
+      expect(error).toBeInstanceOf(RateLimitError);
+      expect((error as RateLimitError).retryAfter).toBe(12);
+    });
   }
 });

package/src/openai/types.ts

@@ -208,26 +208,18 @@ export interface IOpenAIProviderOptions {
   /**
    * Optional executor for handling AI requests
    *
-   * When provided, the provider will delegate all chat operations to this executor
-   * instead of making direct API calls. This enables remote execution capabilities.
+   * When provided, the provider delegates every chat call to this executor instead of calling the
+   * API itself — for example to route calls through your own server. Implement `IExecutor` from
+   * `@robota-sdk/agent-core`; `LocalExecutor` is the in-process one.
    *
    * @example
    * ```typescript
-   * import { LocalExecutor, RemoteExecutor } from '@robota-sdk/agent-core';
+   * import { LocalExecutor } from '@robota-sdk/agent-core';
    *
-   * // Local execution (registers this provider)
-   * const localExecutor = new LocalExecutor();
-   * localExecutor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
+   * const executor = new LocalExecutor();
+   * executor.registerProvider('openai', new OpenAIProvider({ apiKey: 'sk-...' }));
    *
-   * // Remote execution
-   * const remoteExecutor = new RemoteExecutor({
-   *   serverUrl: 'https://api.robota.io',
-   *   userApiKey: 'user-token-123'
-   * });
-   *
-   * const provider = new OpenAIProvider({
-   *   executor: remoteExecutor // No direct API key needed
-   * });
+   * const provider = new OpenAIProvider({ executor });
    * ```
    */
   executor?: IExecutor;