@opencode/ai 0.0.0-beta-19275

package/dist/protocols/openai-responses.js

@@ -0,0 +1,260 @@
+import { Effect, Encoding, Schema } from "effect";
+import { Headers } from "effect/unstable/http";
+import { Route } from "../route/client.js";
+import { Auth } from "../route/auth.js";
+import { Endpoint } from "../route/endpoint.js";
+import { Protocol } from "../route/protocol.js";
+import { HttpTransport } from "../route/transport/index.js";
+import { LLMRequest, mergeJsonRecords } from "../schema/index.js";
+import { OpenResponses } from "./open-responses.js";
+import { JsonObject, optionalArray, optionalNull, ProviderShared } from "./shared.js";
+import { OpenAIImage } from "./utils/openai-image.js";
+import { ResponsesHostedTools } from "./utils/responses-hosted-tools.js";
+import { ToolSchemaProjection } from "./utils/tool-schema.js";
+import { OpenResponsesChannel } from "./open-responses-channel.js";
+import { ResponsesCompaction } from "./utils/responses-compaction.js";
+import { ResponsesCheckpoint } from "./utils/responses-checkpoint.js";
+const ADAPTER = "openai-responses";
+const NAME = "OpenAI Responses";
+const WEBSOCKET_PROTOCOL_HEADER = "responses_websockets=2026-02-06";
+const WEBSOCKET_ROTATE_AFTER_MS = 55 * 60 * 1000;
+export const DEFAULT_BASE_URL = "https://api.openai.com/v1";
+export const PATH = OpenResponses.PATH;
+export const ContextManagement = Schema.Array(Schema.Struct({
+    type: Schema.Literal("compaction"),
+    compactThreshold: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+}));
+const OpenAIResponsesImageGenerationTool = Schema.Struct({
+    type: Schema.tag("image_generation"),
+    action: Schema.optional(Schema.Literals(["auto", "generate", "edit"])),
+    background: Schema.optional(Schema.Literals(["auto", "opaque", "transparent"])),
+    input_fidelity: Schema.optional(Schema.Literals(["low", "high"])),
+    output_compression: Schema.optional(Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: 100 }))),
+    output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
+    partial_images: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
+    quality: Schema.optional(Schema.Literals(["auto", "low", "medium", "high"])),
+    size: Schema.optional(OpenAIImage.Size),
+});
+const OpenAIResponsesHostedToolItem = Schema.Union([
+    Schema.StructWithRest(Schema.Struct({
+        type: Schema.tag("computer_call"),
+        id: Schema.String,
+        status: Schema.optional(Schema.String),
+        call_id: Schema.optional(Schema.String),
+        action: optionalNull(JsonObject),
+        pending_safety_checks: Schema.optional(Schema.Array(JsonObject)),
+    }), [JsonObject]),
+    Schema.StructWithRest(Schema.Struct({
+        type: Schema.tag("web_search_preview_call"),
+        id: Schema.String,
+        status: Schema.optional(Schema.String),
+        action: optionalNull(JsonObject),
+    }), [JsonObject]),
+    Schema.StructWithRest(Schema.Struct({
+        type: Schema.tag("image_generation_call"),
+        id: Schema.String,
+        status: Schema.optional(Schema.String),
+        result: optionalNull(Schema.String),
+        output_format: Schema.optional(Schema.Literals(["png", "jpeg", "webp"])),
+        revised_prompt: optionalNull(Schema.String),
+    }), [JsonObject]),
+]);
+const OpenAIResponsesNamespace = Schema.Struct({
+    type: Schema.tag("namespace"),
+    name: Schema.String,
+    description: Schema.String,
+    tools: Schema.Array(OpenResponses.Tool),
+});
+const OpenAIResponsesTools = Schema.Union([
+    OpenResponses.Tool,
+    OpenAIResponsesNamespace,
+    OpenAIResponsesImageGenerationTool,
+]);
+const OpenAIResponsesToolChoice = Schema.Union([
+    OpenResponses.ToolChoice,
+    Schema.Struct({ type: Schema.tag("image_generation") }),
+]);
+const OpenAIResponsesCoreFields = {
+    ...OpenResponses.coreFields,
+    input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem])),
+    tools: optionalArray(OpenAIResponsesTools),
+    tool_choice: Schema.optional(OpenAIResponsesToolChoice),
+    context_management: Schema.optional(Schema.Array(Schema.Struct({
+        type: Schema.Literal("compaction"),
+        compact_threshold: Schema.optional(Schema.Int.check(Schema.isGreaterThan(0))),
+    }))),
+};
+const OpenAIResponsesBody = Schema.Struct({
+    ...OpenAIResponsesCoreFields,
+    stream: Schema.Literal(true),
+});
+/** Request control, never conversation content. */
+export const CompactionTrigger = Schema.Struct({ type: Schema.Literal("compaction_trigger") });
+const CheckpointBody = Schema.Struct({
+    ...OpenAIResponsesBody.fields,
+    input: Schema.Array(Schema.Union([OpenResponses.InputItem, OpenAIResponsesHostedToolItem, CompactionTrigger])),
+    store: Schema.Literal(false),
+    prompt_cache_retention: optionalNull(Schema.String),
+    prompt_cache_options: optionalNull(Schema.Struct({ mode: Schema.optional(Schema.String), ttl: Schema.optional(Schema.String) })),
+});
+const adapter = {
+    id: ADAPTER,
+    name: NAME,
+    restoreHostedToolItem: (item) => (Schema.is(OpenAIResponsesHostedToolItem)(item) ? item : undefined),
+};
+const nativeImageToolInput = (tool) => {
+    const native = tool.native?.openai;
+    return ProviderShared.isRecord(native) && native.type === "image_generation" ? native : undefined;
+};
+const nativeImageTool = (tool) => {
+    const native = nativeImageToolInput(tool);
+    return Schema.is(OpenAIResponsesImageGenerationTool)(native) ? native : undefined;
+};
+const lowerTool = Effect.fn("OpenAIResponses.lowerTool")(function* (tool, inputSchema) {
+    const native = nativeImageToolInput(tool);
+    if (native !== undefined) {
+        if (Schema.is(OpenAIResponsesImageGenerationTool)(native))
+            return native;
+        return yield* ProviderShared.invalidRequest("OpenAI Responses image generation tool options are invalid");
+    }
+    return yield* OpenResponses.lowerTool(NAME, tool, inputSchema);
+});
+// Native namespaces hold only function tools, so deeper levels flatten into
+// the leaf names the same way non-native protocols flatten the whole tree.
+const lowerToolEntry = Effect.fn("OpenAIResponses.lowerToolEntry")(function* (tool, compatibility) {
+    if (tool.type === "tool")
+        return yield* lowerTool(tool, ToolSchemaProjection.modelCompatibility(tool.inputSchema, compatibility));
+    // OpenAI requires a namespace description; fall back to a generic one so a
+    // missing description never blocks the request.
+    return {
+        type: "namespace",
+        name: tool.name,
+        description: tool.description ?? `Tools in the ${tool.name} namespace.`,
+        tools: yield* Effect.forEach(ProviderShared.flattenTools(tool.tools), (leaf) => OpenResponses.lowerTool(NAME, leaf, ToolSchemaProjection.modelCompatibility(leaf.inputSchema, compatibility))),
+    };
+});
+const lowerToolChoice = (toolChoice, tools) => ProviderShared.matchToolChoice(NAME, toolChoice, {
+    auto: () => "auto",
+    none: () => "none",
+    required: () => "required",
+    tool: (name) => tools.some((tool) => tool.type === "tool" && tool.name === name && nativeImageTool(tool) !== undefined)
+        ? { type: "image_generation" }
+        : { type: "function", name },
+});
+const decodeBody = ProviderShared.validateWith(Schema.decodeUnknownEffect(OpenAIResponsesBody));
+const fromRequest = Effect.fn("OpenAIResponses.fromRequest")(function* (request) {
+    const management = yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(Schema.UndefinedOr(ContextManagement)))(request.providerOptions?.contextManagement);
+    const toolSchemaCompatibility = request.model.compatibility?.toolSchema;
+    return yield* decodeBody({
+        ...(yield* OpenResponses.lowerConversation(request, adapter)),
+        ...OpenResponses.lowerGeneration(request),
+        context_management: management?.map((edit) => ({ type: edit.type, compact_threshold: edit.compactThreshold })),
+        tools: request.tools.length === 0
+            ? undefined
+            : yield* Effect.forEach(request.tools, (tool) => lowerToolEntry(tool, toolSchemaCompatibility)),
+        tool_choice: OpenResponses.allowedToolChoice(request) ??
+            (request.toolChoice ? yield* lowerToolChoice(request.toolChoice, request.tools) : undefined),
+    });
+});
+const checkpointBody = {
+    schema: CheckpointBody,
+    from: Effect.fn("OpenAIResponses.checkpointBody")(function* (request) {
+        const native = yield* fromRequest(LLMRequest.update(request, { toolChoice: undefined }));
+        const overlay = request.http?.body;
+        // Complete history is required for stateless replay and SSE recovery. Raw input overrides bypass that contract.
+        if (overlay?.input !== undefined ||
+            overlay?.previous_response_id !== undefined ||
+            overlay?.conversation !== undefined)
+            return yield* ProviderShared.invalidRequest("Trigger compaction requires complete canonical history, not an input or continuation override");
+        return yield* ProviderShared.validateWith(Schema.decodeUnknownEffect(CheckpointBody))({
+            ...mergeJsonRecords(native, overlay),
+            input: [...native.input, { type: "compaction_trigger" }],
+            stream: true,
+            store: false,
+            parallel_tool_calls: true,
+            tool_choice: undefined,
+            context_management: undefined,
+            text: undefined,
+            max_output_tokens: undefined,
+            max_tool_calls: undefined,
+        });
+    }),
+};
+const hostedToolResult = Effect.fn("OpenAIResponses.hostedToolResult")(function* (item) {
+    const isError = item.error !== undefined && item.error !== null;
+    if (item.type === "image_generation_call" && item.result) {
+        yield* Effect.fromResult(Encoding.decodeBase64(item.result)).pipe(Effect.mapError((cause) => ProviderShared.eventError(ADAPTER, "OpenAI Responses returned invalid image base64", undefined, cause)));
+        const format = item.output_format ?? "png";
+        return {
+            type: "content",
+            value: [
+                {
+                    type: "file",
+                    uri: `data:image/${format};base64,${item.result}`,
+                    mime: `image/${format}`,
+                },
+            ],
+        };
+    }
+    return isError ? { type: "error", value: item.error } : { type: "json", value: item };
+});
+const HOSTED_TOOLS = {
+    web_search_call: { name: "web_search", input: (item) => item.action ?? {} },
+    web_search_preview_call: { name: "web_search_preview", input: (item) => item.action ?? {} },
+    file_search_call: { name: "file_search", input: (item) => ({ queries: item.queries ?? [] }) },
+    code_interpreter_call: {
+        name: "code_interpreter",
+        input: (item) => ({ code: item.code, container_id: item.container_id }),
+    },
+    computer_call: { name: "computer_use", input: (item) => item.action ?? {} },
+    image_generation_call: { name: "image_generation", input: () => ({}), result: hostedToolResult },
+    mcp_call: {
+        name: "mcp",
+        input: (item) => ({ server_label: item.server_label, name: item.name, arguments: item.arguments }),
+    },
+};
+const step = (state, input) => {
+    const event = OpenResponses.normalize(state, input);
+    if (event.type === "response.reasoning_text.delta")
+        return event.item_id !== undefined
+            ? Effect.succeed(OpenResponses.onReasoningDelta(state, event, event.item_id))
+            : ProviderShared.eventError(ADAPTER, `${event.type} is missing item_id`);
+    if (event.type === "response.output_item.done" && event.item && ResponsesHostedTools.isItem(event.item, HOSTED_TOOLS))
+        return ResponsesHostedTools.onDone(state, event.item, HOSTED_TOOLS);
+    return OpenResponses.step(state, event);
+};
+export const protocol = Protocol.make({
+    id: ADAPTER,
+    body: {
+        schema: OpenAIResponsesBody,
+        from: fromRequest,
+    },
+    stream: {
+        event: OpenResponses.protocol.stream.event,
+        initial: (request) => OpenResponses.initial(request, adapter),
+        step,
+        terminal: OpenResponses.terminal,
+    },
+});
+const endpoint = Endpoint.path(PATH, { baseURL: DEFAULT_BASE_URL });
+const auth = Auth.none;
+export const httpTransport = HttpTransport.sseJson.with();
+export const channelTransport = (OpenResponsesChannel.transport);
+export const transport = channelTransport({
+    id: ADAPTER,
+    name: NAME,
+    rotateAfterMs: WEBSOCKET_ROTATE_AFTER_MS,
+    headers: (headers) => Headers.set(headers, "openai-beta", headers["openai-beta"] ?? WEBSOCKET_PROTOCOL_HEADER),
+});
+export const route = Route.make({
+    compact: { endpoint: ResponsesCompaction.make(adapter), trigger: ResponsesCheckpoint.make(checkpointBody) },
+    id: ADAPTER,
+    provider: "openai",
+    providerMetadataKey: "openai",
+    protocol,
+    endpoint,
+    auth,
+    transport,
+    defaults: { providerOptions: { store: false, include: ["reasoning.encrypted_content"] } },
+});
+export * as OpenAIResponses from "./openai-responses.js";

package/dist/protocols/shared.d.ts

@@ -0,0 +1,193 @@
+import { Tool } from "@opencode/schema/tool";
+import { Effect, Schema, Stream } from "effect";
+import { Headers, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import { AIError, LLMRequest, Message, ToolDefinition, type ContentPart, type MediaPart, type ProviderID, type ToolEntry, type ToolResultPart } from "../schema/index.js";
+import { isRecord } from "../utils/record.js";
+export { isRecord };
+export declare const Json: Schema.fromJsonString<Schema.Unknown>;
+export declare const decodeJson: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => unknown;
+export declare const encodeJson: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => string;
+export declare const JsonObject: Schema.$Record<Schema.String, Schema.Unknown>;
+export declare const optionalArray: <const S extends Schema.Top>(schema: S) => Schema.optional<Schema.$Array<S>>;
+export declare const optionalNull: <const S extends Schema.Top>(schema: S) => Schema.optional<Schema.NullOr<S>>;
+export declare const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
+export declare const promptCacheKey: (request: LLMRequest) => string | undefined;
+/**
+ * Streaming tool-call accumulator. Adapters that build a tool call across
+ * multiple `tool-input-delta` chunks store the partial JSON input string here
+ * and finalize it with `parseToolInput` once the call completes.
+ */
+export interface ToolAccumulator {
+    readonly id: string;
+    readonly name: string;
+    readonly namespace?: string;
+    readonly input: string;
+}
+/**
+ * `Usage.totalTokens` policy shared by every route. Honors a provider-
+ * supplied total; otherwise falls back to `inputTokens + outputTokens` only
+ * when at least one is defined. Returns `undefined` when neither input nor
+ * output is known so routes don't publish a misleading `0`.
+ *
+ * Under the inclusive `AI.Usage` contract, `inputTokens` includes cached input
+ * and `outputTokens` includes reasoning. Protocol mappers normalize those
+ * inclusive values before calling this helper. The provider-supplied total is
+ * the source of truth when present; otherwise their sum is the canonical total.
+ */
+export declare const totalTokens: (inputTokens: number | undefined, outputTokens: number | undefined, total: number | undefined) => number | undefined;
+/**
+ * Subtract `subtrahend` from `total`, clamping to zero if the provider
+ * reports a non-sensical breakdown (e.g. `cached_tokens > prompt_tokens`).
+ * Used by protocol mappers when deriving a non-overlapping breakdown field
+ * from a provider's inclusive total — `nonCachedInputTokens` from
+ * `inputTokens - cacheReadInputTokens - cacheWriteInputTokens`.
+ *
+ * If `total` is `undefined`, returns `undefined` (we don't fabricate
+ * counts). If `subtrahend` is `undefined`, returns `total` unchanged. The
+ * provider-native breakdown stays available on `Usage.providerMetadata` for debugging.
+ */
+export declare const subtractTokens: (total: number | undefined, subtrahend: number | undefined) => number | undefined;
+/**
+ * Sum a list of optional token counts, returning `undefined` only when
+ * every value is `undefined` (so we don't fabricate a `0`). Used by
+ * protocol mappers to derive the inclusive `inputTokens` total from a
+ * provider that natively reports a non-overlapping breakdown
+ * (e.g. Anthropic, whose `input_tokens` is already non-cached only).
+ */
+export declare const sumTokens: (...values: ReadonlyArray<number | undefined>) => number | undefined;
+export declare const eventError: (route: string, message: string, body?: string, cause?: unknown) => AIError;
+export declare const parseJson: (route: string, input: string, message: string) => Effect.Effect<unknown, AIError, never>;
+/**
+ * Join the `text` field of a list of parts with newlines. Used by routes
+ * that flatten system / message content arrays into a single provider string
+ * (OpenAI Chat `system` content, OpenAI Responses `system` content, Gemini
+ * `systemInstruction.parts[].text`).
+ */
+export declare const joinText: (parts: ReadonlyArray<{
+    readonly text: string;
+}>) => string;
+/**
+ * Stable fallback representation for chronological `Message.system(...)`
+ * updates on routes that do not support that privileged role natively. The
+ * wrapper remains visibly lower-authority user text, preserves the original
+ * temporal position, and XML-escapes content so it cannot close the wrapper.
+ */
+export declare const wrapSystemUpdate: (parts: ReadonlyArray<{
+    readonly text: string;
+}>) => string;
+/**
+ * Chronological system updates deliberately accept text only. Do not insert
+ * raw retrieved, tool, or web content into privileged updates: keep untrusted
+ * data in ordinary user/tool messages instead.
+ */
+export declare const systemUpdateText: (route: string, message: Message) => Effect.Effect<{
+    readonly type: "text";
+    readonly text: string;
+    readonly metadata?: {
+        readonly [x: string]: unknown;
+    } | undefined;
+    readonly cache?: import("../schema/options.js").CacheHint | undefined;
+    readonly providerMetadata?: {
+        readonly [x: string]: {
+            readonly [x: string]: unknown;
+        };
+    } | undefined;
+}[], AIError, never>;
+/** Lower an unsupported privileged update into visible, in-order user text. */
+export declare const wrappedSystemUpdate: (route: string, message: Message) => Effect.Effect<{
+    type: "text";
+    text: string;
+    cache: import("../schema/options.js").CacheHint | undefined;
+}, AIError, never>;
+/**
+ * Parse the streamed JSON input of a tool call. Treats an empty string as
+ * `"{}"` — providers occasionally finish a tool call without ever emitting
+ * input deltas (e.g. zero-arg tools). The error message is uniform across
+ * routes: `Invalid JSON input for <route> tool call <name>`.
+ */
+export declare const parseToolInput: (route: string, name: string, raw: string) => Effect.Effect<unknown, AIError, never>;
+export interface NormalizedMedia {
+    readonly mime: string;
+    readonly base64: string;
+    readonly dataUrl: string;
+}
+export declare const normalizeMedia: (part: MediaPart) => NormalizedMedia;
+export declare const normalizeToolFile: (part: Tool.FileContent) => NormalizedMedia;
+export declare const trimBaseUrl: (value: string) => string;
+export declare const toolResultText: (part: ToolResultPart) => string;
+export declare const errorText: (error: unknown) => string;
+/**
+ * `framing` step for Server-Sent Events. Decodes UTF-8, runs the SSE channel
+ * decoder, optionally filters named events, and drops empty events. `[DONE]`
+ * is dropped by default or retained for protocols that use it as their stream
+ * boundary. Retry control events are ignored without interrupting the stream.
+ * Decoder failures become provider output errors so the public error channel
+ * stays `AIError`.
+ */
+export declare const sseFraming: (bytes: Stream.Stream<Uint8Array, AIError>, events?: ReadonlySet<string>, includeDone?: boolean) => Stream.Stream<string, AIError>;
+/**
+ * Canonical invalid-request constructor shared by protocol lowering.
+ */
+export declare const invalidRequest: (message: string, cause?: unknown) => AIError;
+/**
+ * Canonical constructor for operations the selected route does not implement.
+ * Prefer this over `invalidRequest` when the failure is a missing route
+ * capability rather than a malformed caller input, so consumers can branch on
+ * `reason._tag` plus `reason.operation` instead of matching message text.
+ */
+export declare const unsupportedOperation: (input: {
+    readonly operation: string;
+    readonly message: string;
+    readonly provider?: ProviderID;
+    readonly route?: string;
+    readonly cause?: unknown;
+}) => AIError;
+/**
+ * Lower namespaces to flat definitions for protocols without a native
+ * namespace construct. Leaf names join their namespace path with `_` because
+ * `.` is not broadly accepted in provider tool names.
+ */
+export declare const flattenTools: (tools: ReadonlyArray<ToolEntry>, path?: ReadonlyArray<string>) => ToolDefinition[];
+export declare const flattenToolRequest: (request: LLMRequest) => {
+    tools: ToolDefinition[];
+    request: LLMRequest<import("../schema/options.js").LanguageModel<{
+        readonly [x: string]: unknown;
+    }, import("../route.js").CompactionOperations | undefined>>;
+};
+export declare const imageResponse: (route: string, name: string, response: HttpClientResponse.HttpClientResponse) => Effect.Effect<{
+    body: string;
+    invalid: (message: string, cause?: unknown) => AIError;
+}, AIError, never>;
+export declare const matchToolChoice: <Auto, None, Required, Tool>(route: string, toolChoice: NonNullable<LLMRequest["toolChoice"]>, cases: {
+    readonly auto: () => Auto;
+    readonly none: () => None;
+    readonly required: () => Required;
+    readonly tool: (name: string) => Tool;
+}) => Effect.Effect<Auto | None | Required | Tool, AIError, never>;
+type ContentType = ContentPart["type"];
+export declare const supportsContent: <const Type extends ContentType>(part: ContentPart, types: ReadonlyArray<Type>) => part is Extract<ContentPart, {
+    readonly type: Type;
+}>;
+export declare const unsupportedContent: (route: string, role: LLMRequest["messages"][number]["role"], types: ReadonlyArray<ContentType>) => AIError;
+/**
+ * Build a `validate` step from a Schema decoder. Replaces the per-route
+ * lambda body `(payload) => decode(payload).pipe(Effect.mapError((e) =>
+ * invalid(e.message)))`. Any decode error is translated into
+ * `AIError` carrying the original parse-error message.
+ */
+export declare const validateWith: <A, I, E extends {
+    readonly message: string;
+}>(decode: (input: I) => Effect.Effect<A, E>) => (payload: I) => Effect.Effect<A, AIError, never>;
+/**
+ * Build an HTTP POST with a JSON body. Sets `content-type: application/json`
+ * automatically after caller-supplied headers so routes cannot accidentally
+ * send JSON with a stale content type. The body is passed pre-encoded so
+ * routes can choose between
+ * `Schema.encodeSync(payload)` and `ProviderShared.encodeJson(payload)`.
+ */
+export declare const jsonPost: (input: {
+    readonly url: string;
+    readonly body: string;
+    readonly headers?: Headers.Input;
+}) => HttpClientRequest.HttpClientRequest;
+export * as ProviderShared from "./shared.js";