@yolk-sdk/openai 0.0.1-canary.2 → 0.0.1-canary.4

package/README.md

@@ -1,11 +1,11 @@
 # @yolk-sdk/openai
 
-OpenAI-family provider mechanics for Codex/ChatGPT OAuth and broker integration.
+OpenAI-family OAuth helpers and agent provider mechanics for Yolk hosts.
 
 ## Install
 
 ```bash
-pnpm add @yolk-sdk/openai@canary @yolk-sdk/oauth@canary effect
+pnpm add @yolk-sdk/openai@canary @yolk-sdk/agent@canary @yolk-sdk/oauth@canary effect
 ```
 
 Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
@@ -14,7 +14,10 @@ Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
 
 | Subpath | Purpose |
 | --- | --- |
-| `@yolk-sdk/openai` | OpenAI Codex OAuth constants, token schemas, broker helpers, and auth headers |
+| `@yolk-sdk/openai` | Convenience root for Codex OAuth helpers |
+| `@yolk-sdk/openai/codex` | Codex OAuth constants, token schemas, broker helpers, and auth headers |
+| `@yolk-sdk/openai/codex-provider` | Codex `LLMProvider` layer, request lowering, SSE/JSON stream parsing, and usage mapping |
+| `@yolk-sdk/openai/provider` | OpenAI API-key Chat Completions `LLMProvider` layer |
 
 ## Imports
 
@@ -24,10 +27,85 @@ import {
   makeOpenAiCodexTokenBrokerClient,
   openAiCodexAuthorizationHeaders,
   openAiCodexProviderId,
-  toOAuthAccessToken
-} from '@yolk-sdk/openai'
+  toOpenAiCodexOAuthAccessToken
+} from '@yolk-sdk/openai/codex'
+
+import { makeOpenAiCodexProviderLayer } from '@yolk-sdk/openai/codex-provider'
+import { makeOpenAiProviderLayer } from '@yolk-sdk/openai/provider'
+```
+
+## Codex provider layer
+
+Use `makeOpenAiCodexProviderLayer` with `@yolk-sdk/agent/loop` when a host already owns Codex
+OAuth/device-flow credentials.
+
+```ts
+import { FetchHttpClient } from 'effect/unstable/http'
+import { Layer, Stream } from 'effect'
+import { makeOpenAiCodexProviderLayer } from '@yolk-sdk/openai/codex-provider'
+import { ContextTransformer, LoopConfig, run } from '@yolk-sdk/agent/loop'
+
+const providerLayer = makeOpenAiCodexProviderLayer({
+  token,
+  defaultReasoningEffort: 'low',
+  reasoningSummary: 'auto'
+}).pipe(Layer.provide(FetchHttpClient.layer))
+
+const runtimeLayer = Layer.mergeAll(
+  ContextTransformer.identity,
+  LoopConfig.defaultLayer,
+  providerLayer
+)
+
+const events = run({
+  messages,
+  systemPrompt,
+  tools,
+  model: 'gpt-5.4'
+}).pipe(Stream.provide(runtimeLayer))
+```
+
+The Codex provider:
+
+- Lowers Yolk `LLMRequest` messages/tools/images to Codex Responses input.
+- Handles Codex JSON and SSE response bodies, including non-`event-stream` SSE bodies.
+- Emits Yolk loop events: text deltas, reasoning deltas, tool calls, done, and usage.
+- Preserves `originator` and optional `ChatGPT-Account-Id` auth headers.
+
+Config:
+
+| Option | Purpose |
+| --- | --- |
+| `token` | Required `OAuthAccessToken` from `@yolk-sdk/oauth` |
+| `responsesUrl` | Optional Codex Responses URL override for tests/gateways |
+| `defaultReasoningEffort` | Fallback reasoning effort when request omits one |
+| `reasoningSummary` | Codex reasoning summary mode; defaults to `auto` |
+| `extraHeaders` | Optional host/gateway headers |
+
+## OpenAI API-key provider layer
+
+`makeOpenAiProviderLayer` provides a Chat Completions-compatible `LLMProvider` for hosts with
+an OpenAI API key.
+
+```ts
+import { Layer, Redacted } from 'effect'
+import { FetchHttpClient } from 'effect/unstable/http'
+import { makeOpenAiProviderLayer } from '@yolk-sdk/openai/provider'
+
+const providerLayer = makeOpenAiProviderLayer({
+  apiKey: Redacted.make(process.env.OPENAI_API_KEY ?? '')
+}).pipe(Layer.provide(FetchHttpClient.layer))
 ```
 
+Config:
+
+| Option | Purpose |
+| --- | --- |
+| `apiKey` | Required redacted OpenAI API key |
+| `chatCompletionsUrl` | Optional Chat Completions URL override |
+| `maxCompletionTokens` | Optional output token limit override |
+| `extraHeaders` | Optional host/gateway headers |
+
 ## Broker request
 
 ```ts
@@ -45,7 +123,8 @@ Hosts route this request to an authenticated token broker. The package never sto
 const headers = openAiCodexAuthorizationHeaders(token)
 ```
 
-Use these headers in host-owned Codex request adapters.
+Use these headers in host-owned Codex request adapters. Prefer
+`makeOpenAiCodexProviderLayer` when executing the Yolk agent loop directly.
 
 ## Exposed constants
 
@@ -58,10 +137,11 @@ Use these headers in host-owned Codex request adapters.
 
 - Own device flow UI, session mapping, refresh-token storage, and policy.
 - Provide token brokers through `@yolk-sdk/oauth` contracts.
-- Own network execution, telemetry, error reporting, and product routing.
+- Own token lookup/refresh, telemetry, error reporting, and product routing.
 
 ## Boundaries
 
 - No app users, sessions, DB, Better Auth, routes, or Durable Objects.
 - No OpenAI SDK dependency.
-- API-key mode can be added later without changing OAuth contracts.
+- Provider layers depend only on Yolk agent/OAuth contracts plus Effect HTTP.
+- Hosts own token storage, refresh, model routing, app policy, and telemetry.

package/dist/codex-provider.d.mts

@@ -0,0 +1,72 @@
+import { Effect, Layer, Stream } from "effect";
+import { HttpClient, HttpClientResponse } from "effect/unstable/http";
+import { AgentReasoningEffort } from "@yolk-sdk/agent/protocol";
+import { LLMError, LLMEvent, LLMProvider, LLMRequest } from "@yolk-sdk/agent/loop";
+import { OAuthAccessToken } from "@yolk-sdk/oauth";
+
+//#region src/codex-provider.d.ts
+type OpenAiCodexReasoningSummary = 'auto' | 'concise' | 'detailed';
+type OpenAiCodexProviderConfig = {
+  readonly token: OAuthAccessToken;
+  readonly responsesUrl?: string;
+  readonly extraHeaders?: Readonly<Record<string, string>>;
+  readonly defaultReasoningEffort?: AgentReasoningEffort;
+  readonly reasoningSummary?: OpenAiCodexReasoningSummary;
+};
+type OpenAiCodexMessageInput = {
+  readonly role: 'user' | 'assistant';
+  readonly content: string | ReadonlyArray<OpenAiCodexInputContentPart>;
+};
+type OpenAiCodexInputTextPart = {
+  readonly type: 'input_text';
+  readonly text: string;
+};
+type OpenAiCodexInputImagePart = {
+  readonly type: 'input_image';
+  readonly image_url: string;
+};
+type OpenAiCodexOutputTextPart = {
+  readonly type: 'output_text';
+  readonly text: string;
+};
+type OpenAiCodexInputContentPart = OpenAiCodexInputTextPart | OpenAiCodexInputImagePart | OpenAiCodexOutputTextPart;
+type OpenAiCodexFunctionCallInput = {
+  readonly type: 'function_call';
+  readonly call_id: string;
+  readonly name: string;
+  readonly arguments: string;
+};
+type OpenAiCodexFunctionOutputInput = {
+  readonly type: 'function_call_output';
+  readonly call_id: string;
+  readonly output: string;
+};
+type OpenAiCodexInputItem = OpenAiCodexMessageInput | OpenAiCodexFunctionCallInput | OpenAiCodexFunctionOutputInput;
+type OpenAiCodexTool = {
+  readonly type: 'function';
+  readonly name: string;
+  readonly description: string;
+  readonly parameters: unknown;
+};
+type OpenAiCodexRequestBody = {
+  readonly model: string;
+  readonly instructions: string;
+  readonly input: ReadonlyArray<OpenAiCodexInputItem>;
+  readonly store: false;
+  readonly stream: true;
+  readonly reasoning: {
+    readonly effort: AgentReasoningEffort;
+    readonly summary: OpenAiCodexReasoningSummary;
+  };
+  readonly tools?: ReadonlyArray<OpenAiCodexTool>;
+  readonly parallel_tool_calls?: true;
+};
+declare const toOpenAiCodexRequestBody: (request: LLMRequest, config?: {
+  readonly defaultReasoningEffort?: AgentReasoningEffort;
+  readonly reasoningSummary?: OpenAiCodexReasoningSummary;
+}) => Effect.Effect<OpenAiCodexRequestBody, LLMError>;
+declare const streamOpenAiCodexResponse: (response: HttpClientResponse.HttpClientResponse) => Stream.Stream<LLMEvent, LLMError>;
+declare const makeOpenAiCodexProviderLayer: (config: OpenAiCodexProviderConfig) => Layer.Layer<LLMProvider, never, HttpClient.HttpClient>;
+//#endregion
+export { OpenAiCodexProviderConfig, OpenAiCodexReasoningSummary, makeOpenAiCodexProviderLayer, streamOpenAiCodexResponse, toOpenAiCodexRequestBody };
+//# sourceMappingURL=codex-provider.d.mts.map

package/dist/codex-provider.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-provider.d.mts","names":[],"sources":["../src/codex-provider.ts"],"mappings":";;;;;;;KAoCY,2BAAA;AAAA,KAEA,yBAAA;EAAA,SACD,KAAA,EAAO,gBAAA;EAAA,SACP,YAAA;EAAA,SACA,YAAA,GAAe,QAAA,CAAS,MAAA;EAAA,SACxB,sBAAA,GAAyB,oBAAA;EAAA,SACzB,gBAAA,GAAmB,2BAAA;AAAA;AAAA,KAGzB,uBAAA;EAAA,SACM,IAAA;EAAA,SACA,OAAA,WAAkB,aAAa,CAAC,2BAAA;AAAA;AAAA,KAGtC,wBAAA;EAAA,SACM,IAAA;EAAA,SACA,IAAI;AAAA;AAAA,KAGV,yBAAA;EAAA,SACM,IAAA;EAAA,SACA,SAAS;AAAA;AAAA,KAGf,yBAAA;EAAA,SACM,IAAA;EAAA,SACA,IAAI;AAAA;AAAA,KAGV,2BAAA,GACD,wBAAA,GACA,yBAAA,GACA,yBAAA;AAAA,KAEC,4BAAA;EAAA,SACM,IAAA;EAAA,SACA,OAAA;EAAA,SACA,IAAA;EAAA,SACA,SAAA;AAAA;AAAA,KAGN,8BAAA;EAAA,SACM,IAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA;AAAA;AAAA,KAGN,oBAAA,GACD,uBAAA,GACA,4BAAA,GACA,8BAAA;AAAA,KAEC,eAAA;EAAA,SACM,IAAA;EAAA,SACA,IAAA;EAAA,SACA,WAAA;EAAA,SACA,UAAA;AAAA;AAAA,KAGN,sBAAA;EAAA,SACM,KAAA;EAAA,SACA,YAAA;EAAA,SACA,KAAA,EAAO,aAAA,CAAc,oBAAA;EAAA,SACrB,KAAA;EAAA,SACA,MAAA;EAAA,SACA,SAAA;IAAA,SACE,MAAA,EAAQ,oBAAA;IAAA,SACR,OAAA,EAAS,2BAAA;EAAA;EAAA,SAEX,KAAA,GAAQ,aAAA,CAAc,eAAA;EAAA,SACtB,mBAAA;AAAA;AAAA,cA4NE,wBAAA,GACX,OAAA,EAAS,UAAA,EACT,MAAA;EAAA,SACW,sBAAA,GAAyB,oBAAA;EAAA,SACzB,gBAAA,GAAmB,2BAAA;AAAA,MAE7B,MAAA,CAAO,MAAA,CAAO,sBAAA,EAAwB,QAAA;AAAA,cA0iB5B,yBAAA,GACX,QAAA,EAAU,kBAAA,CAAmB,kBAAA,KAC5B,MAAA,CAAO,MAAA,CAAO,QAAA,EAAU,QAAA;AAAA,cA2Ed,4BAAA,GAAgC,MAAA,EAAQ,yBAAA,KAAyB,KAAA,CAAA,KAAA,CAAA,WAAA,SAAA,UAAA,CAAA,UAAA"}