@ank1015/agents-provider-openai 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @ank1015/agents-provider-openai
+
+## 0.1.0
+
+- Added support for direct-value API key secret references when creating the default OpenAI SDK client.
+- Initial OpenAI Responses API runtime adapter.
+- Added request mapping, stream translation, error normalization, factory helpers, and unit tests.

package/README.md

@@ -0,0 +1,159 @@
+# @ank1015/agents-provider-openai
+
+OpenAI Responses API runtime adapter for the `@ank1015/agents` packages.
+
+This package turns normalized `LLMRequest<"openai">` objects into OpenAI Responses API streaming calls and translates OpenAI stream events back into normalized assistant events and messages. It also re-exports `@ank1015/agents-provider-openai-spec` so consumers can import the provider id, config schema, model catalog, and OpenAI-specific types from one package.
+
+## Install
+
+```sh
+pnpm add @ank1015/agents-provider-openai
+```
+
+## What This Package Provides
+
+- `OpenAIProviderAdapter`, a provider adapter for direct OpenAI API calls.
+- `createOpenAIProviderAdapter` helper for app wiring.
+- `createOpenAIProviderAdapterFactory` for transport/container integration.
+- `OpenAIResponsesClient` and `OpenAIProviderAdapterDeps` test/injection types.
+- Re-exports from `@ank1015/agents-provider-openai-spec`, including `OPENAI_PROVIDER`, `OPENAI_MODELS`, and config/model types.
+
+## Import Paths
+
+```ts
+import {
+  OPENAI_PROVIDER,
+  createOpenAIProviderAdapter,
+} from '@ank1015/agents-provider-openai';
+
+import { OpenAIProviderAdapter } from '@ank1015/agents-provider-openai/adapter';
+```
+
+The root import is the normal application entrypoint. The `./adapter` subpath exposes the runtime adapter APIs without making internal mapping helpers public.
+
+## Basic Usage
+
+```ts
+import { createAdapterTransport } from '@ank1015/agents-core/transport';
+import {
+  OPENAI_PROVIDER,
+  createOpenAIProviderAdapter,
+} from '@ank1015/agents-provider-openai';
+
+const openai = createOpenAIProviderAdapter({
+  provider: OPENAI_PROVIDER,
+  apiKey: {
+    type: 'env',
+    name: 'OPENAI_API_KEY',
+  },
+});
+
+const transport = createAdapterTransport([openai]);
+
+const stream = transport.stream({
+  provider: OPENAI_PROVIDER,
+  modelId: 'gpt-5.4-mini',
+  messages: [
+    {
+      role: 'user',
+      id: 'user_1',
+      timestamp: Date.now(),
+      content: [{ type: 'text', content: 'Write a short haiku about types.' }],
+    },
+  ],
+});
+
+for await (const event of stream) {
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta);
+  }
+}
+
+const message = await stream.result();
+```
+
+## Configuration
+
+The adapter accepts `OpenAIProviderConfig` from the spec package:
+
+```ts
+import { createOpenAIProviderAdapter } from '@ank1015/agents-provider-openai';
+
+const adapter = createOpenAIProviderAdapter({
+  provider: 'openai',
+  apiKey: {
+    type: 'env',
+    name: 'OPENAI_API_KEY',
+  },
+  baseUrl: 'https://api.openai.com/v1',
+  headers: {
+    'x-app': 'agents',
+  },
+  organization: 'org_123',
+  project: 'proj_123',
+});
+```
+
+`apiKey` is a secret reference. The adapter resolves environment references from `process.env`, or uses a direct value reference when the key comes from another secret source:
+
+```ts
+createOpenAIProviderAdapter({
+  provider: 'openai',
+  apiKey: {
+    type: 'value',
+    value: openAIKey,
+  },
+});
+```
+
+## Request Mapping
+
+The adapter maps the normalized request shape into OpenAI Responses API streaming parameters:
+
+- `instructions` becomes OpenAI `instructions`.
+- Text and image user content becomes OpenAI response input content.
+- Tool result messages become function or custom tool call output items.
+- Prior OpenAI-native assistant responses are reused when available.
+- Normalized assistant text, thinking, and tool calls are converted back into OpenAI response input history.
+- Function tools become OpenAI function tools with JSON Schema parameters.
+- `strict` is preserved when a function tool sets it to `true` or `false`.
+- Custom grammar tools become OpenAI custom tools.
+
+`providerOptions` are forwarded to OpenAI after the generic fields owned by the adapter are removed. The adapter does not default `max_output_tokens`; callers can set it through `providerOptions`.
+
+## Streaming Behavior
+
+`adapter.stream(request)` returns an `AssistantMessageEventStreamSource<"openai">`.
+
+The stream may emit:
+
+- `start`
+- `text_start`, `text_delta`, `text_end`
+- `thinking_start`, `thinking_delta`, `thinking_end`
+- `toolcall_start`, `toolcall_delta`, `toolcall_end`
+- `done`
+- `error`
+- `aborted`
+
+Successful messages include the OpenAI native response, normalized assistant content, usage, cost estimates from the static model catalog, duration, and mapped stop reason. Failed or aborted messages preserve any normalized content that was produced before the stream ended.
+
+## Testing And Injection
+
+The adapter accepts dependency overrides for unit tests and custom runtime containers:
+
+```ts
+import { OpenAIProviderAdapter } from '@ank1015/agents-provider-openai/adapter';
+
+const adapter = new OpenAIProviderAdapter(config, {
+  client: fakeOpenAIClient,
+  createMessageId: () => 'msg_test',
+  now: () => 1_700_000_000_000,
+  resolveModel: (modelId) => modelRegistry.get('openai', modelId),
+});
+```
+
+If no client override is provided, the adapter creates an `openai` SDK client from the provider config.
+
+## Versioning
+
+This package is currently `0.1.0`. Until `1.0.0`, adapter APIs and event mapping behavior may evolve as the surrounding agent runtime settles.

package/dist/adapter.d.ts

@@ -0,0 +1,33 @@
+import type { AssistantMessageEventStreamSource, LLMProviderAdapter, LLMProviderAdapterFactory, LLMRequest, Model } from '@ank1015/agents-contracts';
+import type { ResponseCreateParamsStreaming, ResponseStreamEvent } from 'openai/resources/responses/responses.js';
+import type { OpenAIProvider, OpenAIProviderConfig } from '@ank1015/agents-provider-openai-spec';
+export interface OpenAIResponsesClient {
+    responses: {
+        create(params: ResponseCreateParamsStreaming, options?: {
+            signal?: AbortSignal;
+        }): AsyncIterable<ResponseStreamEvent> | Promise<AsyncIterable<ResponseStreamEvent>>;
+    };
+}
+export interface OpenAIProviderAdapterDeps {
+    readonly client?: OpenAIResponsesClient;
+    readonly createClient?: (config: OpenAIProviderConfig) => OpenAIResponsesClient;
+    readonly createMessageId?: () => string;
+    readonly now?: () => number;
+    /** Resolves a model id to its descriptor. Defaults to the package's static catalog. */
+    readonly resolveModel?: (modelId: string) => Model<OpenAIProvider> | undefined;
+}
+export declare class OpenAIProviderAdapter implements LLMProviderAdapter<OpenAIProvider> {
+    #private;
+    readonly provider: "openai";
+    constructor(config: OpenAIProviderConfig, deps?: OpenAIProviderAdapterDeps);
+    stream(request: LLMRequest<OpenAIProvider>): AssistantMessageEventStreamSource<OpenAIProvider>;
+}
+export declare class OpenAIProviderAdapterFactory implements LLMProviderAdapterFactory<OpenAIProvider> {
+    #private;
+    readonly provider: "openai";
+    constructor(deps?: OpenAIProviderAdapterDeps);
+    create(config: OpenAIProviderConfig): OpenAIProviderAdapter;
+}
+export declare function createOpenAIProviderAdapter(config: OpenAIProviderConfig, deps?: OpenAIProviderAdapterDeps): OpenAIProviderAdapter;
+export declare function createOpenAIProviderAdapterFactory(deps?: OpenAIProviderAdapterDeps): OpenAIProviderAdapterFactory;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAKV,iCAAiC,EAMjC,kBAAkB,EAClB,yBAAyB,EACzB,UAAU,EACV,KAAK,EAIN,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAEV,6BAA6B,EAM7B,mBAAmB,EACpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,KAAK,EACV,cAAc,EACd,oBAAoB,EACrB,MAAM,sCAAsC,CAAC;AAS9C,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE;QACT,MAAM,CACJ,MAAM,EAAE,6BAA6B,EACrC,OAAO,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE,WAAW,CAAA;SAAE,GAEhC,aAAa,CAAC,mBAAmB,CAAC,GAClC,OAAO,CAAC,aAAa,CAAC,mBAAmB,CAAC,CAAC,CAAC;KACjD,CAAC;CACH;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,qBAAqB,CAAC;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,KAAK,CAAC,cAAc,CAAC,GAAG,SAAS,CAAC;CAChF;AA6DD,qBAAa,qBAAsB,YAAW,kBAAkB,CAAC,cAAc,CAAC;;IAC9E,QAAQ,CAAC,QAAQ,WAAmB;gBAOxB,MAAM,EAAE,oBAAoB,EAAE,IAAI,GAAE,yBAA8B;IAS9E,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,cAAc,CAAC,GAAG,iCAAiC,CAAC,cAAc,CAAC;CA2J/F;AAED,qBAAa,4BACX,YAAW,yBAAyB,CAAC,cAAc,CAAC;;IAEpD,QAAQ,CAAC,QAAQ,WAAmB;gBAGxB,IAAI,GAAE,yBAA8B;IAIhD,MAAM,CAAC,MAAM,EAAE,oBAAoB,GAAG,qBAAqB;CAG5D;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,CAAC,EAAE,yBAAyB,GAC/B,qBAAqB,CAEvB;AAED,wBAAgB,kCAAkC,CAChD,IAAI,CAAC,EAAE,yBAAyB,GAC/B,4BAA4B,CAE9B"}