okengine 0.22.0 → 0.23.0

package/src/drivers/ai-anthropic.ts

@@ -11,8 +11,11 @@ import type {
   AiDriver,
   AiModelClient,
   AiOpenOptions,
+  AiStreamChunk,
+  AiToolCall,
 } from "./ai-types.ts";
 import { hostFromUrl } from "./external.ts";
+import { preconnectFetch } from "./ai-preconnect.ts";
 
 const DEFAULT_BASE = "https://api.anthropic.com";
 const ANTHROPIC_VERSION = "2023-06-01";
@@ -30,10 +33,7 @@ export async function openAnthropic(options: AiOpenOptions = {}): Promise<AiMode
   const model = options.model ?? "claude-sonnet-4-20250514";
   const baseUrl = (options.baseUrl ?? DEFAULT_BASE).replace(/\/$/, "");
   const fetchFn = options.fetch ?? globalThis.fetch;
-  const preconnect = (fetchFn as { preconnect?: (href: string) => void }).preconnect;
-  if (typeof preconnect === "function") {
-    preconnect(baseUrl);
-  }
+  preconnectFetch(fetchFn, baseUrl);
   const host = hostFromUrl(baseUrl);
   const external = host
     ? {
@@ -48,21 +48,10 @@ export async function openAnthropic(options: AiOpenOptions = {}): Promise<AiMode
     model,
     async complete(opts: AiCompleteOptions): Promise<AiCompleteResult> {
       const resolvedModel = opts.model ?? model;
-      const { system, messages } = splitSystem(opts.messages);
       const res = await fetchFn(`${baseUrl}/v1/messages`, {
         method: "POST",
-        headers: {
-          "content-type": "application/json",
-          "x-api-key": apiKey,
-          "anthropic-version": ANTHROPIC_VERSION,
-        },
-        body: JSON.stringify({
-          model: resolvedModel,
-          max_tokens: opts.maxTokens ?? 1024,
-          ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
-          ...(system !== undefined ? { system } : {}),
-          messages,
-        }),
+        headers: anthropicHeaders(apiKey),
+        body: JSON.stringify(anthropicBody(resolvedModel, opts)),
         ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
       });
       const raw = (await res.json().catch(() => ({}))) as AnthropicMessagesResponse;
@@ -71,11 +60,13 @@ export async function openAnthropic(options: AiOpenOptions = {}): Promise<AiMode
         throw new Error(`anthropic: ${msg}`);
       }
       const text = textFromContent(raw.content);
+      const toolCalls = toolCallsFromContent(raw.content);
       return {
         text,
         raw,
         model: raw.model ?? resolvedModel,
         driverId: "anthropic",
+        ...(toolCalls !== undefined ? { toolCalls } : {}),
         usage: {
           inputTokens: raw.usage?.input_tokens,
           outputTokens: raw.usage?.output_tokens,
@@ -83,6 +74,21 @@ export async function openAnthropic(options: AiOpenOptions = {}): Promise<AiMode
         ...(external !== undefined ? { external } : {}),
       };
     },
+    async *stream(opts: AiCompleteOptions): AsyncIterable<AiStreamChunk> {
+      const resolvedModel = opts.model ?? model;
+      const res = await fetchFn(`${baseUrl}/v1/messages`, {
+        method: "POST",
+        headers: anthropicHeaders(apiKey),
+        body: JSON.stringify({ ...anthropicBody(resolvedModel, opts), stream: true }),
+        ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+      });
+      if (!res.ok) {
+        const raw = (await res.json().catch(() => ({}))) as AnthropicMessagesResponse;
+        const msg = raw.error?.message ?? `anthropic HTTP ${res.status}`;
+        throw new Error(`anthropic: ${msg}`);
+      }
+      yield* readAnthropicSse(res, opts.signal);
+    },
   };
 }
 
@@ -92,9 +98,17 @@ export const anthropicAiDriver: AiDriver = {
   open: openAnthropic,
 };
 
+interface AnthropicBlock {
+  readonly type?: string;
+  readonly text?: string;
+  readonly id?: string;
+  readonly name?: string;
+  readonly input?: unknown;
+}
+
 interface AnthropicMessagesResponse {
   readonly model?: string;
-  readonly content?: readonly { readonly type?: string; readonly text?: string }[];
+  readonly content?: readonly AnthropicBlock[];
   readonly usage?: {
     readonly input_tokens?: number;
     readonly output_tokens?: number;
@@ -102,19 +116,70 @@ interface AnthropicMessagesResponse {
   readonly error?: { readonly message?: string };
 }
 
+function anthropicHeaders(apiKey: string): Record<string, string> {
+  return {
+    "content-type": "application/json",
+    "x-api-key": apiKey,
+    "anthropic-version": ANTHROPIC_VERSION,
+  };
+}
+
+function anthropicBody(model: string, opts: AiCompleteOptions): Record<string, unknown> {
+  const { system, messages } = splitSystem(opts.messages);
+  return {
+    model,
+    max_tokens: opts.maxTokens ?? 1024,
+    ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+    ...(system !== undefined ? { system } : {}),
+    messages,
+    ...(opts.tools !== undefined && opts.tools.length > 0
+      ? {
+          tools: opts.tools.map((tool) => ({
+            name: tool.name,
+            ...(tool.description !== undefined ? { description: tool.description } : {}),
+            input_schema: tool.parameters ?? { type: "object", properties: {} },
+          })),
+        }
+      : {}),
+  };
+}
+
 function splitSystem(messages: AiCompleteOptions["messages"]): {
   system?: string;
-  messages: Array<{ role: "user" | "assistant"; content: string }>;
+  messages: Array<{ role: "user" | "assistant"; content: unknown }>;
 } {
   const systemParts: string[] = [];
-  const out: Array<{ role: "user" | "assistant"; content: string }> = [];
+  const out: Array<{ role: "user" | "assistant"; content: unknown }> = [];
   for (const m of messages) {
     if (m.role === "system") {
       systemParts.push(m.content);
       continue;
     }
     if (m.role === "tool") {
-      out.push({ role: "user", content: m.content });
+      out.push({
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            tool_use_id: m.toolCallId ?? "",
+            content: m.content,
+          },
+        ],
+      });
+      continue;
+    }
+    if (m.role === "assistant" && m.toolCalls && m.toolCalls.length > 0) {
+      const blocks: unknown[] = [];
+      if (m.content) blocks.push({ type: "text", text: m.content });
+      for (const call of m.toolCalls) {
+        blocks.push({
+          type: "tool_use",
+          id: call.id,
+          name: call.name,
+          input: call.arguments ?? {},
+        });
+      }
+      out.push({ role: "assistant", content: blocks });
       continue;
     }
     out.push({ role: m.role, content: m.content });
@@ -132,3 +197,129 @@ function textFromContent(content: AnthropicMessagesResponse["content"]): string
     .map((b) => b.text!)
     .join("");
 }
+
+function toolCallsFromContent(
+  content: AnthropicMessagesResponse["content"],
+): readonly AiToolCall[] | undefined {
+  const calls = (content ?? []).filter((block) => block.type === "tool_use" && block.name);
+  if (calls.length === 0) return undefined;
+  return calls.map((block, index) => ({
+    id: block.id ?? `toolu_${index}`,
+    name: block.name ?? "",
+    arguments: block.input ?? {},
+  }));
+}
+
+/**
+ * Parse Anthropic Messages SSE into text and tool-call chunks.
+ *
+ * @param res - Streaming response
+ * @param signal - Optional abort
+ */
+async function* readAnthropicSse(
+  res: Response,
+  signal?: AbortSignal,
+): AsyncGenerator<AiStreamChunk> {
+  const stream = (res as Response & { textStream?: () => AsyncIterable<string> }).textStream;
+  if (typeof stream !== "function") {
+    throw new Error("anthropic: Response.textStream is required (Bun >= 1.4.2)");
+  }
+  let buffer = "";
+  let inputTokens: number | undefined;
+  let outputTokens: number | undefined;
+  let stopped = false;
+  for await (const piece of stream.call(res)) {
+    if (signal?.aborted) {
+      const err = new Error("This operation was aborted");
+      err.name = "AbortError";
+      throw err;
+    }
+    buffer += piece;
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("data:")) continue;
+      const data = trimmed.slice(5).trim();
+      if (!data || data === "[DONE]") continue;
+      let event: {
+        type?: string;
+        index?: number;
+        content_block?: AnthropicBlock;
+        delta?: {
+          type?: string;
+          text?: string;
+          partial_json?: string;
+          stop_reason?: string;
+        };
+        message?: { usage?: { input_tokens?: number; output_tokens?: number } };
+        usage?: { output_tokens?: number; input_tokens?: number };
+      };
+      try {
+        event = JSON.parse(data) as typeof event;
+      } catch {
+        continue;
+      }
+      if (event.type === "error") {
+        const message =
+          typeof (event as { error?: { message?: string } }).error?.message === "string"
+            ? (event as { error?: { message?: string } }).error?.message
+            : "anthropic stream error";
+        throw new Error(`anthropic: ${message}`);
+      }
+      if (event.type === "message_stop") {
+        stopped = true;
+        continue;
+      }
+      if (event.type === "message_start") {
+        inputTokens = event.message?.usage?.input_tokens ?? inputTokens;
+        continue;
+      }
+      if (event.type === "content_block_start" && event.content_block?.type === "tool_use") {
+        yield {
+          text: "",
+          toolCall: {
+            index: event.index ?? 0,
+            ...(event.content_block.id !== undefined ? { id: event.content_block.id } : {}),
+            ...(event.content_block.name !== undefined ? { name: event.content_block.name } : {}),
+            argumentsDelta: "",
+          },
+        };
+        continue;
+      }
+      if (event.type === "content_block_delta" && event.delta?.type === "text_delta") {
+        if (event.delta.text) yield { text: event.delta.text };
+        continue;
+      }
+      if (event.type === "content_block_delta" && event.delta?.type === "input_json_delta") {
+        yield {
+          text: "",
+          toolCall: {
+            index: event.index ?? 0,
+            ...(event.delta.partial_json !== undefined
+              ? { argumentsDelta: event.delta.partial_json }
+              : {}),
+          },
+        };
+        continue;
+      }
+      if (event.type === "message_delta") {
+        outputTokens = event.usage?.output_tokens ?? outputTokens;
+        inputTokens = event.usage?.input_tokens ?? inputTokens;
+      }
+    }
+  }
+  if (!stopped) throw new Error("anthropic: stream ended without message_stop");
+  yield {
+    text: "",
+    done: true,
+    ...(inputTokens !== undefined || outputTokens !== undefined
+      ? {
+          usage: {
+            ...(inputTokens !== undefined ? { inputTokens } : {}),
+            ...(outputTokens !== undefined ? { outputTokens } : {}),
+          },
+        }
+      : {}),
+  };
+}

package/src/drivers/ai-mock.ts

@@ -97,6 +97,39 @@ export const mockAiDriver: AiDriver = {
             break;
           }
         }
+        if (
+          payload &&
+          typeof payload === "object" &&
+          payload !== null &&
+          "__toolCalls" in payload
+        ) {
+          const script = payload as { __toolCalls: readonly AiToolCall[]; text?: string };
+          const text = script.text ?? "";
+          const size = Math.max(1, Math.ceil(text.length / 2) || 1);
+          for (let i = 0; i < text.length; i += size) {
+            yield { text: text.slice(i, i + size) };
+          }
+          for (const [index, tc] of script.__toolCalls.entries()) {
+            const args =
+              typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments ?? {});
+            yield {
+              text: "",
+              toolCall: { index, id: tc.id, name: tc.name, argumentsDelta: "" },
+            };
+            const mid = Math.max(1, Math.ceil(args.length / 2));
+            yield { text: "", toolCall: { index, argumentsDelta: args.slice(0, mid) } };
+            if (mid < args.length) {
+              yield { text: "", toolCall: { index, argumentsDelta: args.slice(mid) } };
+            }
+          }
+          yield {
+            text: "",
+            done: true,
+            raw: payload,
+            usage: { inputTokens: last.length, outputTokens: text.length, cost: 0 },
+          };
+          return;
+        }
         const text = typeof payload === "string" ? payload : JSON.stringify(payload);
         const size = Math.max(1, Math.ceil(text.length / 3));
         for (let i = 0; i < text.length; i += size) {
@@ -107,7 +140,7 @@ export const mockAiDriver: AiDriver = {
           }
           yield { text: text.slice(i, i + size) };
         }
-        yield { text: "", done: true };
+        yield { text: "", done: true, raw: payload };
       },
       async embed(opts: AiEmbedOptions): Promise<AiEmbedResult> {
         const inputs = Array.isArray(opts.input) ? opts.input : [opts.input];

package/src/drivers/ai-openai-compatible.ts

@@ -20,6 +20,7 @@ import type {
 } from "./ai-types.ts";
 import type { DriverExternal } from "./external.ts";
 import { hostFromUrl } from "./external.ts";
+import { preconnectFetch } from "./ai-preconnect.ts";
 
 /** Default OpenAI cloud base — apiKey is required for this origin. */
 export const OPENAI_COMPAT_DEFAULT_BASE = "https://api.openai.com/v1";
@@ -151,9 +152,23 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
         model: resolvedModel,
         messages: opts.messages.map(serializeMessage),
         stream: true,
+        stream_options: { include_usage: true },
       };
       if (opts.temperature !== undefined) body.temperature = opts.temperature;
       if (opts.maxTokens !== undefined) body.max_tokens = opts.maxTokens;
+      if (opts.responseFormat !== undefined) {
+        body.response_format = wireOpenaiResponseFormat(opts.responseFormat);
+      }
+      if (opts.tools !== undefined && opts.tools.length > 0) {
+        body.tools = opts.tools.map((t) => ({
+          type: "function",
+          function: {
+            name: t.name,
+            ...(t.description !== undefined ? { description: t.description } : {}),
+            ...(t.parameters !== undefined ? { parameters: t.parameters } : {}),
+          },
+        }));
+      }
 
       const res = await fetchFn(`${baseUrl}/chat/completions`, {
         method: "POST",
@@ -166,7 +181,7 @@ export async function openOpenaiCompatible(options: AiOpenOptions = {}): Promise
         const msg = raw.error?.message ?? `openai-compatible HTTP ${res.status}`;
         throwHttp(`openai-compatible: ${msg}`, res.status);
       }
-      yield* readOpenaiSse(res, opts.signal);
+      yield* readOpenaiSse(res, opts.signal, externalBase);
     },
     async embed(opts: AiEmbedOptions): Promise<AiEmbedResult> {
       const resolvedModel = opts.model ?? model;
@@ -290,8 +305,13 @@ function parseToolCalls(
  * @param res - Streaming response
  * @param signal - Optional abort
  */
-async function* readOpenaiSse(res: Response, signal?: AbortSignal): AsyncGenerator<AiStreamChunk> {
+async function* readOpenaiSse(
+  res: Response,
+  signal?: AbortSignal,
+  external?: AiStreamChunk["external"],
+): AsyncGenerator<AiStreamChunk> {
   let buffer = "";
+  let closed = false;
   for await (const piece of responseTextStream(res)) {
     if (signal?.aborted) throw abortAsError(signal.reason);
     buffer += piece;
@@ -302,30 +322,64 @@ async function* readOpenaiSse(res: Response, signal?: AbortSignal): AsyncGenerat
       if (!trimmed.startsWith("data:")) continue;
       const data = trimmed.slice(5).trim();
       if (data === "[DONE]") {
-        yield { text: "", done: true };
+        yield { text: "", done: true, ...(external !== undefined ? { external } : {}) };
         return;
       }
       try {
         const chunk = JSON.parse(data) as {
           choices?: readonly {
-            delta?: { content?: string | null };
+            delta?: {
+              content?: string | null;
+              tool_calls?: readonly {
+                index?: number;
+                id?: string;
+                function?: { name?: string; arguments?: string };
+              }[];
+            };
             finish_reason?: string | null;
           }[];
+          usage?: { prompt_tokens?: number; completion_tokens?: number };
         };
-        const delta = chunk.choices?.[0]?.delta?.content;
-        if (typeof delta === "string" && delta.length > 0) {
-          yield { text: delta };
+        if (chunk.choices?.[0]?.finish_reason) closed = true;
+        const delta = chunk.choices?.[0]?.delta;
+        const content = delta?.content;
+        if (typeof content === "string" && content.length > 0) {
+          yield { text: content };
+        }
+        for (const call of delta?.tool_calls ?? []) {
+          const args = call.function?.arguments;
+          yield {
+            text: "",
+            toolCall: {
+              index: call.index ?? 0,
+              ...(call.id !== undefined ? { id: call.id } : {}),
+              ...(call.function?.name !== undefined ? { name: call.function.name } : {}),
+              ...(typeof args === "string" ? { argumentsDelta: args } : {}),
+            },
+          };
         }
-        if (chunk.choices?.[0]?.finish_reason) {
-          yield { text: "", done: true };
-          return;
+        if (chunk.usage) {
+          yield {
+            text: "",
+            usage: {
+              ...(chunk.usage.prompt_tokens !== undefined
+                ? { inputTokens: chunk.usage.prompt_tokens }
+                : {}),
+              ...(chunk.usage.completion_tokens !== undefined
+                ? { outputTokens: chunk.usage.completion_tokens }
+                : {}),
+            },
+          };
         }
-      } catch {
-        // ignore malformed SSE lines
+      } catch (err) {
+        if (err instanceof Error && err.message.startsWith("openai-compatible:")) throw err;
       }
     }
   }
-  yield { text: "", done: true };
+  if (!closed) {
+    throw new Error("openai-compatible: stream ended without [DONE] or finish_reason");
+  }
+  yield { text: "", done: true, ...(external !== undefined ? { external } : {}) };
 }
 
 /**
@@ -341,19 +395,6 @@ function responseTextStream(res: Response): AsyncIterable<string> {
   return stream.call(res);
 }
 
-/**
- * Warm DNS+TCP+TLS for a cloud origin. No-op when `fetch` is a test stub.
- *
- * @param fetchFn - Fetch implementation
- * @param url - Provider base URL
- */
-function preconnectFetch(fetchFn: typeof fetch, url: string): void {
-  const preconnect = (fetchFn as { preconnect?: (href: string) => void }).preconnect;
-  if (typeof preconnect === "function") {
-    preconnect(url);
-  }
-}
-
 function abortAsError(reason?: unknown): Error {
   if (reason instanceof Error) return reason;
   const err = new Error(reason !== undefined ? String(reason) : "This operation was aborted");

package/src/drivers/ai-preconnect.ts

@@ -0,0 +1,18 @@
+/**
+ * Best-effort `fetch.preconnect` for AI HTTP drivers.
+ *
+ * Bun throws `Invalid port` when the URL uses an implicit 80/443. A failed
+ * preconnect must not fail the request and must not log.
+ *
+ * @param fetchFn - Injected or global fetch
+ * @param url - Origin or base URL to warm
+ */
+export function preconnectFetch(fetchFn: typeof fetch, url: string): void {
+  const preconnect = (fetchFn as { preconnect?: (href: string) => void }).preconnect;
+  if (typeof preconnect !== "function") return;
+  try {
+    preconnect(url);
+  } catch {
+    // Bun rejects default ports. The request still runs.
+  }
+}

package/src/drivers/ai-stream.test.ts

@@ -6,6 +6,7 @@ import { describe, expect, test } from "bun:test";
 import { withAbortSignal } from "../kernel/abort-scope.ts";
 import { createFx, createFxContext } from "../kernel/fx.ts";
 import { ai, createAiRuntime } from "../elements/ai.ts";
+import { openAnthropic } from "./ai-anthropic.ts";
 import { openOpenaiCompatible } from "./ai-openai-compatible.ts";
 import { mockAiDriver } from "./ai-mock.ts";
 
@@ -44,6 +45,29 @@ describe("openai-compatible SSE stream", () => {
       if (chunk.text) parts.push(chunk.text);
     }
     expect(parts.join("")).toBe("Hello");
+    const bodies: unknown[] = [];
+    const formatFetch = Object.assign(
+      async (_input: string | URL | Request, init?: RequestInit) => {
+        bodies.push(JSON.parse(String(init?.body)));
+        return new Response(sse, { status: 200, headers: { "content-type": "text/event-stream" } });
+      },
+      { preconnect: () => {} },
+    ) as typeof fetch;
+    const formatted = await openOpenaiCompatible({
+      apiKey: "sk-test",
+      baseUrl: "https://example.test/v1",
+      fetch: formatFetch,
+    });
+    for await (const _chunk of formatted.stream!({
+      messages: [{ role: "user", content: "hi" }],
+      responseFormat: {
+        type: "json_schema",
+        json_schema: { name: "out", schema: { type: "object" } },
+      },
+    })) {
+      // drain
+    }
+    expect(bodies[0]).toMatchObject({ response_format: { type: "json_object" } });
 
     const ac = new AbortController();
     const iter = client.stream!({
@@ -58,6 +82,44 @@ describe("openai-compatible SSE stream", () => {
   });
 });
 
+describe("anthropic messages stream", () => {
+  test("text deltas, input_json_delta, and message_delta usage", async () => {
+    const sse = [
+      'data: {"type":"message_start","message":{"usage":{"input_tokens":4,"output_tokens":1}}}',
+      'data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Ok"}}',
+      'data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_1","name":"orders.get","input":{}}}',
+      'data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\\"id\\":"}}',
+      'data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\\"14\\"}"}}',
+      'data: {"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":6}}',
+      'data: {"type":"message_stop"}',
+      "",
+    ].join("\n");
+    const fetchFn = Object.assign(
+      async () =>
+        new Response(sse, { status: 200, headers: { "content-type": "text/event-stream" } }),
+      { preconnect: () => {} },
+    ) as typeof fetch;
+    const client = await openAnthropic({
+      apiKey: "sk-test",
+      fetch: fetchFn,
+    });
+    const texts: string[] = [];
+    const args: string[] = [];
+    let usage: { inputTokens?: number; outputTokens?: number } | undefined;
+    for await (const chunk of client.stream!({
+      messages: [{ role: "user", content: "status" }],
+      tools: [{ name: "orders.get" }],
+    })) {
+      if (chunk.text) texts.push(chunk.text);
+      if (chunk.toolCall?.argumentsDelta) args.push(chunk.toolCall.argumentsDelta);
+      if (chunk.usage) usage = chunk.usage;
+    }
+    expect(texts.join("")).toBe("Ok");
+    expect(args.join("")).toBe('{"id":"14"}');
+    expect(usage).toEqual({ inputTokens: 4, outputTokens: 6 });
+  });
+});
+
 describe("fx.stream uses ambient AbortSignal", () => {
   test("race abort cancels in-flight stream fetch", async () => {
     let sawAbort = false;

package/src/drivers/ai-types.ts

@@ -66,10 +66,30 @@ export interface AiCompleteResult {
   readonly external?: DriverExternal;
 }
 
+/** One tool-call fragment inside a model stream. */
+export interface AiStreamToolCallDelta {
+  /** Provider index for this call within the turn. */
+  readonly index: number;
+  readonly id?: string;
+  readonly name?: string;
+  /** Partial JSON arguments. Empty when the call is only announced. */
+  readonly argumentsDelta?: string;
+}
+
 /** One streamed token / delta from a model. */
 export interface AiStreamChunk {
   readonly text: string;
   readonly done?: boolean;
+  readonly toolCall?: AiStreamToolCallDelta;
+  readonly usage?: {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly cost?: number;
+  };
+  /** Provider payload. Present on the terminal chunk when the driver has one. */
+  readonly raw?: unknown;
+  /** Egress identity, matching {@link AiCompleteResult.external}. */
+  readonly external?: DriverExternal;
 }
 
 /** Embedding request. */