@rcrsr/rill-ext-openai 0.16.0 → 0.18.1

package/dist/index.js

@@ -5,11 +5,12 @@ import { createRequire } from "module";
 import OpenAI from "openai";
 import {
   RuntimeError as RuntimeError6,
+  createRillStream,
   emitExtensionEvent,
   createVector,
-  isDict as isDict2,
   isVector,
-  rillTypeToTypeValue
+  structureToTypeValue,
+  toCallable
 } from "@rcrsr/rill";
 
 // ../../shared/ext-llm/dist/validation.js
@@ -49,7 +50,7 @@ function validateEmbedBatch(texts) {
     if (typeof item !== "string") {
       throw new RuntimeError("RILL-R001", "embed_batch requires list of strings");
     }
-    if (item === "") {
+    if (item.trim() === "") {
       throw new RuntimeError("RILL-R001", `embed text cannot be empty at index ${i}`);
     }
     validated.push(item);
@@ -101,28 +102,29 @@ function mapRillType(rillType) {
   return jsonType;
 }
 function buildPropertyFromStructuralType(rillType) {
-  if (rillType.type === "closure" || rillType.type === "tuple") {
-    throw new RuntimeError3("RILL-R004", `unsupported type for JSON Schema: ${rillType.type}`);
+  if (rillType.kind === "closure" || rillType.kind === "tuple") {
+    throw new RuntimeError3("RILL-R004", `unsupported type for JSON Schema: ${rillType.kind}`);
   }
-  if (rillType.type === "any") {
+  if (rillType.kind === "any") {
     return {};
   }
-  if (rillType.type === "list") {
+  if (rillType.kind === "list") {
+    const listType = rillType;
     const property = { type: "array" };
-    if (rillType.element !== void 0) {
-      property.items = buildPropertyFromStructuralType(rillType.element);
+    if (listType.element !== void 0) {
+      property.items = buildPropertyFromStructuralType(listType.element);
     }
     return property;
   }
-  if (rillType.type === "dict") {
+  if (rillType.kind === "dict") {
     return { type: "object" };
   }
-  return { type: mapRillType(rillType.type) };
+  return { type: mapRillType(rillType.kind) };
 }
 function buildJsonSchemaFromStructuralType(type, params) {
   const properties = {};
   const required = [];
-  if (type.type === "closure") {
+  if (type.kind === "closure") {
     const closureParams = type.params ?? [];
     for (let i = 0; i < closureParams.length; i++) {
       const fieldDef = closureParams[i];
@@ -238,7 +240,7 @@ async function executeToolCall(toolName, toolInput, tools, context) {
           return value !== void 0 ? value : void 0;
         });
       } else {
-        args = [inputDict];
+        args = [];
       }
       return await invokeCallable(callable, args, context);
     }
@@ -323,7 +325,7 @@ function patchResponseToolCallNames(response, nameMap) {
     }
   }
 }
-async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent, maxTurns = 10, context) {
+async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent, maxTurns = 10, context, yieldChunk, signal) {
   if (tools === void 0) {
     throw new RuntimeError4("RILL-R004", "tools parameter is required");
   }
@@ -345,8 +347,8 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
     const params = callable.kind === "application" ? callable.params ?? [] : callable.kind === "script" ? callable.params : [];
     if (params.length > 0) {
       const closureType = {
-        type: "closure",
-        params: params.map((p2) => ({ name: p2.name, type: p2.type ?? { type: "any" } }))
+        kind: "closure",
+        params: params.map((p2) => ({ name: p2.name, type: p2.type ?? { kind: "any" } }))
       };
       const builtSchema = buildJsonSchemaFromStructuralType(closureType, [...params]);
       inputSchema = {
@@ -371,10 +373,20 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
   let currentMessages = [...messages];
   let turnCount = 0;
   while (turnCount < maxTurns) {
+    if (signal?.aborted) {
+      throw new RuntimeError4("RILL-R004", "tool_loop cancelled");
+    }
     turnCount++;
     let response;
     try {
-      response = await callbacks.callAPI(currentMessages, providerTools);
+      if (yieldChunk !== void 0 && callbacks.callAPIStreaming !== void 0) {
+        const onTextDelta = (text) => {
+          yieldChunk({ type: "text_delta", text });
+        };
+        response = await callbacks.callAPIStreaming(currentMessages, providerTools, onTextDelta, signal);
+      } else {
+        response = await callbacks.callAPI(currentMessages, providerTools, signal);
+      }
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       throw new RuntimeError4("RILL-R004", `Provider API error: ${message}`, void 0, { cause: error });
@@ -412,6 +424,13 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
     for (const toolCall of toolCalls) {
       const { id, name, input } = toolCall;
       emitEvent("tool_call", { tool_name: name, args: input });
+      if (yieldChunk !== void 0) {
+        yieldChunk({
+          type: "tool_call",
+          name,
+          args: input
+        });
+      }
       const toolStartTime = Date.now();
       try {
         const result = await executeToolCall(name, input, tools, context);
@@ -419,6 +438,9 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
         toolResults.push({ id, name, result });
         executedToolCalls.push({ name, result });
         consecutiveErrors = 0;
+        if (yieldChunk !== void 0) {
+          yieldChunk({ type: "tool_result", name, result });
+        }
         emitEvent("tool_result", { tool_name: name, duration });
       } catch (error) {
         const duration = Date.now() - toolStartTime;
@@ -471,6 +493,9 @@ async function executeToolLoop(messages, tools, maxErrors, callbacks, emitEvent,
     turns: turnCount
   };
 }
+function buildResponseMessages(inputMessages, assistantContent) {
+  return [...inputMessages, { role: "assistant", content: assistantContent }];
+}
 
 // ../../shared/ext-param/dist/param.js
 import { RuntimeError as RuntimeError5 } from "@rcrsr/rill";
@@ -500,7 +525,7 @@ var p = {
     validateParamName(name);
     return {
       name,
-      type: { type: "string" },
+      type: { kind: "string" },
       defaultValue: void 0,
       annotations: buildAnnotations(desc)
     };
@@ -517,7 +542,7 @@ var p = {
     validateParamName(name);
     return {
       name,
-      type: { type: "number" },
+      type: { kind: "number" },
       defaultValue: def,
       annotations: buildAnnotations(desc)
     };
@@ -534,7 +559,7 @@ var p = {
     validateParamName(name);
     return {
       name,
-      type: { type: "bool" },
+      type: { kind: "bool" },
       defaultValue: def,
       annotations: buildAnnotations(desc)
     };
@@ -550,7 +575,7 @@ var p = {
    */
   dict(name, desc, def, fields) {
     validateParamName(name);
-    const type = fields !== void 0 ? { type: "dict", fields } : { type: "dict" };
+    const type = fields !== void 0 ? { kind: "dict", fields } : { kind: "dict" };
     return {
       name,
       type,
@@ -568,7 +593,7 @@ var p = {
    */
   list(name, itemType, desc) {
     validateParamName(name);
-    const type = itemType !== void 0 ? { type: "list", element: itemType } : { type: "list" };
+    const type = itemType !== void 0 ? { kind: "list", element: itemType } : { kind: "list" };
     return {
       name,
       type,
@@ -587,7 +612,7 @@ var p = {
     validateParamName(name);
     return {
       name,
-      type: { type: "closure" },
+      type: { kind: "closure" },
       defaultValue: void 0,
       annotations: buildAnnotations(desc)
     };
@@ -638,238 +663,303 @@ function createOpenAIExtension(config) {
       console.warn(`Failed to cleanup OpenAI SDK: ${message}`);
     }
   };
-  const result = {
+  const fnDict = {
     // IR-4: openai::message
     message: {
       params: [
         p.str("text"),
         p.dict("options", void 0, {}, {
-          system: { type: { type: "string" }, defaultValue: "" },
-          max_tokens: { type: { type: "number" }, defaultValue: 0 }
+          system: { type: { kind: "string" }, defaultValue: "" },
+          max_tokens: { type: { kind: "number" }, defaultValue: 0 }
         })
       ],
-      fn: async (args, ctx) => {
-        const startTime = Date.now();
-        try {
-          const text = args["text"];
-          const options = args["options"] ?? {};
-          if (text.trim().length === 0) {
-            throw new RuntimeError6("RILL-R004", "prompt text cannot be empty");
-          }
-          const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
-          const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
-          const apiMessages = [];
-          if (system !== void 0) {
-            apiMessages.push({
-              role: "system",
-              content: system
-            });
-          }
+      fn: (args, ctx) => {
+        const text = args["text"];
+        const options = args["options"] ?? {};
+        if (text.trim().length === 0) {
+          throw new RuntimeError6("RILL-R004", "prompt text cannot be empty");
+        }
+        const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
+        const maxTokens = typeof options["max_tokens"] === "number" && options["max_tokens"] > 0 ? options["max_tokens"] : factoryMaxTokens;
+        const apiMessages = [];
+        if (system !== void 0) {
           apiMessages.push({
-            role: "user",
-            content: text
+            role: "system",
+            content: system
           });
-          const apiParams = {
-            model: factoryModel,
-            max_completion_tokens: maxTokens,
-            messages: apiMessages
-          };
-          if (factoryTemperature !== void 0) {
-            apiParams.temperature = factoryTemperature;
+        }
+        apiMessages.push({
+          role: "user",
+          content: text
+        });
+        const runner = client.chat.completions.stream({
+          model: factoryModel,
+          max_completion_tokens: maxTokens,
+          messages: apiMessages,
+          stream_options: { include_usage: true },
+          ...factoryTemperature !== void 0 ? { temperature: factoryTemperature } : {}
+        });
+        async function* chunks() {
+          try {
+            for await (const chunk of runner) {
+              const delta = chunk.choices[0]?.delta?.content;
+              if (delta) {
+                yield delta;
+              }
+            }
+          } catch (error) {
+            throw mapProviderError("OpenAI", error, detectOpenAIError);
           }
-          const response = await client.chat.completions.create(apiParams);
-          const content = response.choices[0]?.message?.content ?? "";
-          const result2 = {
-            content,
-            model: response.model,
-            usage: {
-              input: response.usage?.prompt_tokens ?? 0,
-              output: response.usage?.completion_tokens ?? 0
-            },
-            stop_reason: response.choices[0]?.finish_reason ?? "unknown",
-            id: response.id,
-            messages: [
-              ...system ? [{ role: "system", content: system }] : [],
-              { role: "user", content: text },
-              { role: "assistant", content }
-            ]
-          };
-          const duration = Date.now() - startTime;
-          emitExtensionEvent(ctx, {
-            event: "openai:message",
-            subsystem: "extension:openai",
-            duration,
-            model: response.model,
-            usage: result2.usage,
-            request: apiMessages,
-            content
-          });
-          return result2;
-        } catch (error) {
-          const duration = Date.now() - startTime;
-          const rillError = mapProviderError(
-            "OpenAI",
-            error,
-            detectOpenAIError
-          );
-          emitExtensionEvent(ctx, {
-            event: "openai:error",
-            subsystem: "extension:openai",
-            error: rillError.message,
-            duration
-          });
-          throw rillError;
         }
+        const resolve = async () => {
+          const startTime = Date.now();
+          try {
+            const response = await runner.finalChatCompletion();
+            const content = response.choices[0]?.message?.content ?? "";
+            const result = {
+              content,
+              model: response.model,
+              usage: {
+                input: response.usage?.prompt_tokens ?? 0,
+                output: response.usage?.completion_tokens ?? 0
+              },
+              stop_reason: response.choices[0]?.finish_reason ?? "unknown",
+              id: response.id,
+              messages: buildResponseMessages(
+                [
+                  ...system ? [{ role: "system", content: system }] : [],
+                  { role: "user", content: text }
+                ],
+                content
+              )
+            };
+            const duration = Date.now() - startTime;
+            emitExtensionEvent(ctx, {
+              event: "openai:message",
+              subsystem: "extension:openai",
+              duration,
+              model: response.model,
+              usage: result.usage,
+              request: apiMessages,
+              content
+            });
+            return result;
+          } catch (error) {
+            const duration = Date.now() - startTime;
+            const rillError = mapProviderError("OpenAI", error, detectOpenAIError);
+            emitExtensionEvent(ctx, {
+              event: "openai:error",
+              subsystem: "extension:openai",
+              error: rillError.message,
+              duration
+            });
+            throw rillError;
+          }
+        };
+        const retType = {
+          kind: "dict",
+          fields: {
+            content: { type: { kind: "string" } },
+            model: { type: { kind: "string" } },
+            usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+            stop_reason: { type: { kind: "string" } },
+            id: { type: { kind: "string" } },
+            messages: { type: { kind: "list", element: { kind: "dict" } } }
+          }
+        };
+        return createRillStream({
+          chunks: chunks(),
+          resolve,
+          dispose: () => {
+            runner.abort();
+          },
+          chunkType: { kind: "string" },
+          retType
+        });
       },
       annotations: { description: "Send single message to OpenAI API" },
-      returnType: rillTypeToTypeValue({
-        type: "dict",
-        fields: {
-          content: { type: { type: "string" } },
-          model: { type: { type: "string" } },
-          usage: { type: { type: "dict", fields: { input: { type: { type: "number" } }, output: { type: { type: "number" } } } } },
-          stop_reason: { type: { type: "string" } },
-          id: { type: { type: "string" } },
-          messages: { type: { type: "list", element: { type: "dict" } } }
+      returnType: structureToTypeValue({
+        kind: "stream",
+        chunk: { kind: "string" },
+        ret: {
+          kind: "dict",
+          fields: {
+            content: { type: { kind: "string" } },
+            model: { type: { kind: "string" } },
+            usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+            stop_reason: { type: { kind: "string" } },
+            id: { type: { kind: "string" } },
+            messages: { type: { kind: "list", element: { kind: "dict" } } }
+          }
         }
       })
     },
     // IR-5: openai::messages
     messages: {
       params: [
-        p.list("messages", { type: "dict", fields: { role: { type: { type: "string" } }, content: { type: { type: "string" } } } }),
+        p.list("messages", { kind: "dict", fields: { role: { type: { kind: "string" } }, content: { type: { kind: "string" } } } }),
         p.dict("options", void 0, {}, {
-          system: { type: { type: "string" }, defaultValue: "" },
-          max_tokens: { type: { type: "number" }, defaultValue: 0 }
+          system: { type: { kind: "string" }, defaultValue: "" },
+          max_tokens: { type: { kind: "number" }, defaultValue: 0 }
         })
       ],
-      fn: async (args, ctx) => {
-        const startTime = Date.now();
-        try {
-          const messages = args["messages"];
-          const options = args["options"] ?? {};
-          if (messages.length === 0) {
+      fn: (args, ctx) => {
+        const messages = args["messages"];
+        const options = args["options"] ?? {};
+        if (messages.length === 0) {
+          throw new RuntimeError6(
+            "RILL-R004",
+            "messages list cannot be empty"
+          );
+        }
+        const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
+        const maxTokens = typeof options["max_tokens"] === "number" && options["max_tokens"] > 0 ? options["max_tokens"] : factoryMaxTokens;
+        const apiMessages = [];
+        if (system !== void 0) {
+          apiMessages.push({
+            role: "system",
+            content: system
+          });
+        }
+        for (let i = 0; i < messages.length; i++) {
+          const msg = messages[i];
+          if (!msg || typeof msg !== "object" || !("role" in msg)) {
             throw new RuntimeError6(
               "RILL-R004",
-              "messages list cannot be empty"
+              "message missing required 'role' field"
             );
           }
-          const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
-          const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
-          const apiMessages = [];
-          if (system !== void 0) {
-            apiMessages.push({
-              role: "system",
-              content: system
-            });
+          const role = msg["role"];
+          if (role !== "user" && role !== "assistant" && role !== "tool") {
+            throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
           }
-          for (let i = 0; i < messages.length; i++) {
-            const msg = messages[i];
-            if (!msg || typeof msg !== "object" || !("role" in msg)) {
+          if (role === "user" || role === "tool") {
+            if (!("content" in msg) || typeof msg["content"] !== "string") {
               throw new RuntimeError6(
                 "RILL-R004",
-                "message missing required 'role' field"
+                `${role} message requires 'content'`
               );
             }
-            const role = msg["role"];
-            if (role !== "user" && role !== "assistant" && role !== "tool") {
-              throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
+            apiMessages.push({
+              role,
+              content: msg["content"]
+            });
+          } else if (role === "assistant") {
+            const hasContent = "content" in msg && msg["content"];
+            const hasToolCalls = "tool_calls" in msg && msg["tool_calls"];
+            if (!hasContent && !hasToolCalls) {
+              throw new RuntimeError6(
+                "RILL-R004",
+                "assistant message requires 'content' or 'tool_calls'"
+              );
             }
-            if (role === "user" || role === "tool") {
-              if (!("content" in msg) || typeof msg["content"] !== "string") {
-                throw new RuntimeError6(
-                  "RILL-R004",
-                  `${role} message requires 'content'`
-                );
-              }
+            if (hasContent) {
               apiMessages.push({
-                role,
+                role: "assistant",
                 content: msg["content"]
               });
-            } else if (role === "assistant") {
-              const hasContent = "content" in msg && msg["content"];
-              const hasToolCalls = "tool_calls" in msg && msg["tool_calls"];
-              if (!hasContent && !hasToolCalls) {
-                throw new RuntimeError6(
-                  "RILL-R004",
-                  "assistant message requires 'content' or 'tool_calls'"
-                );
-              }
-              if (hasContent) {
-                apiMessages.push({
-                  role: "assistant",
-                  content: msg["content"]
-                });
-              }
             }
           }
-          const apiParams = {
-            model: factoryModel,
-            max_completion_tokens: maxTokens,
-            messages: apiMessages
-          };
-          if (factoryTemperature !== void 0) {
-            apiParams.temperature = factoryTemperature;
+        }
+        const runner = client.chat.completions.stream({
+          model: factoryModel,
+          max_completion_tokens: maxTokens,
+          messages: apiMessages,
+          stream_options: { include_usage: true },
+          ...factoryTemperature !== void 0 ? { temperature: factoryTemperature } : {}
+        });
+        async function* chunks() {
+          try {
+            for await (const chunk of runner) {
+              const delta = chunk.choices[0]?.delta?.content;
+              if (delta) {
+                yield delta;
+              }
+            }
+          } catch (error) {
+            throw mapProviderError("OpenAI", error, detectOpenAIError);
           }
-          const response = await client.chat.completions.create(apiParams);
-          const content = response.choices[0]?.message?.content ?? "";
-          const fullMessages = [
-            ...messages.map((m) => {
-              const normalized = { role: m["role"] };
-              if ("content" in m) normalized["content"] = m["content"];
-              if ("tool_calls" in m) normalized["tool_calls"] = m["tool_calls"];
-              return normalized;
-            }),
-            { role: "assistant", content }
-          ];
-          const result2 = {
-            content,
-            model: response.model,
-            usage: {
-              input: response.usage?.prompt_tokens ?? 0,
-              output: response.usage?.completion_tokens ?? 0
-            },
-            stop_reason: response.choices[0]?.finish_reason ?? "unknown",
-            id: response.id,
-            messages: fullMessages
-          };
-          const duration = Date.now() - startTime;
-          emitExtensionEvent(ctx, {
-            event: "openai:messages",
-            subsystem: "extension:openai",
-            duration,
-            model: response.model,
-            usage: result2.usage,
-            request: apiMessages,
-            content
-          });
-          return result2;
-        } catch (error) {
-          const duration = Date.now() - startTime;
-          const rillError = mapProviderError(
-            "OpenAI",
-            error,
-            detectOpenAIError
-          );
-          emitExtensionEvent(ctx, {
-            event: "openai:error",
-            subsystem: "extension:openai",
-            error: rillError.message,
-            duration
-          });
-          throw rillError;
         }
+        const resolve = async () => {
+          const startTime = Date.now();
+          try {
+            const response = await runner.finalChatCompletion();
+            const content = response.choices[0]?.message?.content ?? "";
+            const result = {
+              content,
+              model: response.model,
+              usage: {
+                input: response.usage?.prompt_tokens ?? 0,
+                output: response.usage?.completion_tokens ?? 0
+              },
+              stop_reason: response.choices[0]?.finish_reason ?? "unknown",
+              id: response.id,
+              messages: buildResponseMessages(
+                messages.map((m) => ({
+                  role: m["role"],
+                  content: m["content"] ?? ""
+                })),
+                content
+              )
+            };
+            const duration = Date.now() - startTime;
+            emitExtensionEvent(ctx, {
+              event: "openai:messages",
+              subsystem: "extension:openai",
+              duration,
+              model: response.model,
+              usage: result.usage,
+              request: apiMessages,
+              content
+            });
+            return result;
+          } catch (error) {
+            const duration = Date.now() - startTime;
+            const rillError = mapProviderError("OpenAI", error, detectOpenAIError);
+            emitExtensionEvent(ctx, {
+              event: "openai:error",
+              subsystem: "extension:openai",
+              error: rillError.message,
+              duration
+            });
+            throw rillError;
+          }
+        };
+        const retType = {
+          kind: "dict",
+          fields: {
+            content: { type: { kind: "string" } },
+            model: { type: { kind: "string" } },
+            usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+            stop_reason: { type: { kind: "string" } },
+            id: { type: { kind: "string" } },
+            messages: { type: { kind: "list", element: { kind: "dict" } } }
+          }
+        };
+        return createRillStream({
+          chunks: chunks(),
+          resolve,
+          dispose: () => {
+            runner.abort();
+          },
+          chunkType: { kind: "string" },
+          retType
+        });
       },
       annotations: { description: "Send multi-turn conversation to OpenAI API" },
-      returnType: rillTypeToTypeValue({
-        type: "dict",
-        fields: {
-          content: { type: { type: "string" } },
-          model: { type: { type: "string" } },
-          usage: { type: { type: "dict", fields: { input: { type: { type: "number" } }, output: { type: { type: "number" } } } } },
-          stop_reason: { type: { type: "string" } },
-          id: { type: { type: "string" } },
-          messages: { type: { type: "list", element: { type: "dict" } } }
+      returnType: structureToTypeValue({
+        kind: "stream",
+        chunk: { kind: "string" },
+        ret: {
+          kind: "dict",
+          fields: {
+            content: { type: { kind: "string" } },
+            model: { type: { kind: "string" } },
+            usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+            stop_reason: { type: { kind: "string" } },
+            id: { type: { kind: "string" } },
+            messages: { type: { kind: "list", element: { kind: "dict" } } }
+          }
         }
       })
     },
@@ -922,7 +1012,7 @@ function createOpenAIExtension(config) {
         }
       },
       annotations: { description: "Generate embedding vector for text" },
-      returnType: rillTypeToTypeValue({ type: "vector" })
+      returnType: structureToTypeValue({ kind: "vector" })
     },
     // IR-7: openai::embed_batch
     embed_batch: {
@@ -983,263 +1073,313 @@ function createOpenAIExtension(config) {
         }
       },
       annotations: { description: "Generate embedding vectors for multiple texts" },
-      returnType: rillTypeToTypeValue({ type: "list", element: { type: "vector" } })
+      returnType: structureToTypeValue({ kind: "list", element: { kind: "vector" } })
     },
     // IR-8: openai::tool_loop
     tool_loop: {
       params: [
         p.str("prompt"),
-        p.dict("options", void 0, {}, {
-          tools: { type: { type: "dict" } },
-          system: { type: { type: "string" }, defaultValue: "" },
-          max_tokens: { type: { type: "number" }, defaultValue: 0 },
-          max_errors: { type: { type: "number" }, defaultValue: 3 },
-          max_turns: { type: { type: "number" }, defaultValue: 10 },
-          messages: { type: { type: "list", element: { type: "dict", fields: { role: { type: { type: "string" } }, content: { type: { type: "string" } } } } }, defaultValue: [] }
+        {
+          name: "tools",
+          type: { kind: "dict", valueType: { kind: "closure" } },
+          defaultValue: void 0,
+          annotations: {}
+        },
+        p.dict("options", void 0, void 0, {
+          system: { type: { kind: "string" }, defaultValue: "" },
+          max_tokens: { type: { kind: "number" }, defaultValue: 0 },
+          max_errors: { type: { kind: "number" }, defaultValue: 3 },
+          max_turns: { type: { kind: "number" }, defaultValue: 10 },
+          messages: { type: { kind: "list", element: { kind: "dict", fields: { role: { type: { kind: "string" } }, content: { type: { kind: "string" } } } } }, defaultValue: [] }
         })
       ],
-      fn: async (args, ctx) => {
-        const startTime = Date.now();
-        try {
-          const prompt = args["prompt"];
-          const options = args["options"] ?? {};
-          if (prompt.trim().length === 0) {
-            throw new RuntimeError6("RILL-R004", "prompt text cannot be empty");
-          }
-          if (!("tools" in options) || !isDict2(options["tools"])) {
-            throw new RuntimeError6(
-              "RILL-R004",
-              "tool_loop requires 'tools' option"
-            );
-          }
-          const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
-          const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
-          const maxErrors = typeof options["max_errors"] === "number" ? options["max_errors"] : 3;
-          const maxTurns = typeof options["max_turns"] === "number" ? options["max_turns"] : 10;
-          const messages = [];
-          if (system !== void 0) {
+      fn: (args, ctx) => {
+        const prompt = args["prompt"];
+        const toolsDict = args["tools"];
+        const options = args["options"] ?? {};
+        if (prompt.trim().length === 0) {
+          throw new RuntimeError6("RILL-R004", "prompt text cannot be empty");
+        }
+        const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
+        const maxTokens = typeof options["max_tokens"] === "number" && options["max_tokens"] > 0 ? options["max_tokens"] : factoryMaxTokens;
+        const maxErrors = typeof options["max_errors"] === "number" ? options["max_errors"] : 3;
+        const maxTurns = typeof options["max_turns"] === "number" ? options["max_turns"] : 10;
+        const messages = [];
+        if (system !== void 0) {
+          messages.push({
+            role: "system",
+            content: system
+          });
+        }
+        if ("messages" in options && Array.isArray(options["messages"])) {
+          const prependedMessages = options["messages"];
+          for (const msg of prependedMessages) {
+            if (!msg || typeof msg !== "object" || !("role" in msg)) {
+              throw new RuntimeError6(
+                "RILL-R004",
+                "message missing required 'role' field"
+              );
+            }
+            const role = msg["role"];
+            if (role !== "user" && role !== "assistant") {
+              throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
+            }
+            if (!("content" in msg) || typeof msg["content"] !== "string") {
+              throw new RuntimeError6(
+                "RILL-R004",
+                `${role} message requires 'content'`
+              );
+            }
             messages.push({
-              role: "system",
-              content: system
+              role,
+              content: msg["content"]
             });
           }
-          if ("messages" in options && Array.isArray(options["messages"])) {
-            const prependedMessages = options["messages"];
-            for (const msg of prependedMessages) {
-              if (!msg || typeof msg !== "object" || !("role" in msg)) {
-                throw new RuntimeError6(
-                  "RILL-R004",
-                  "message missing required 'role' field"
-                );
+        }
+        messages.push({
+          role: "user",
+          content: prompt
+        });
+        const callbacks = {
+          // Build OpenAI Tool format from tool definitions
+          buildTools: (toolDefs) => {
+            return toolDefs.map((def) => ({
+              type: "function",
+              function: {
+                name: def.name,
+                description: def.description,
+                parameters: def.input_schema
               }
-              const role = msg["role"];
-              if (role !== "user" && role !== "assistant") {
-                throw new RuntimeError6("RILL-R004", `invalid role '${role}'`);
+            }));
+          },
+          // Call OpenAI API (non-streaming fallback)
+          callAPI: async (msgs, tools, signal) => {
+            const apiParams = {
+              model: factoryModel,
+              max_completion_tokens: maxTokens,
+              messages: msgs,
+              tools,
+              tool_choice: "auto"
+            };
+            if (factoryTemperature !== void 0) {
+              apiParams.temperature = factoryTemperature;
+            }
+            const response = await client.chat.completions.create(apiParams, { signal });
+            return {
+              ...response,
+              usage: {
+                input_tokens: response.usage?.prompt_tokens ?? 0,
+                output_tokens: response.usage?.completion_tokens ?? 0
               }
-              if (!("content" in msg) || typeof msg["content"] !== "string") {
-                throw new RuntimeError6(
-                  "RILL-R004",
-                  `${role} message requires 'content'`
-                );
+            };
+          },
+          // Call OpenAI API with streaming — IR-3: callAPIStreaming
+          callAPIStreaming: async (msgs, tools, onTextDelta, signal) => {
+            const streamRunner = client.chat.completions.stream({
+              model: factoryModel,
+              max_completion_tokens: maxTokens,
+              messages: msgs,
+              tools,
+              tool_choice: "auto",
+              stream_options: { include_usage: true },
+              ...factoryTemperature !== void 0 ? { temperature: factoryTemperature } : {}
+            }, { signal });
+            streamRunner.on("content", (delta) => {
+              onTextDelta(delta);
+            });
+            const response = await streamRunner.finalChatCompletion();
+            return {
+              ...response,
+              usage: {
+                input_tokens: response.usage?.prompt_tokens ?? 0,
+                output_tokens: response.usage?.completion_tokens ?? 0
               }
-              messages.push({
-                role,
-                content: msg["content"]
-              });
+            };
+          },
+          // Extract tool calls from OpenAI response
+          extractToolCalls: (response) => {
+            if (!response || typeof response !== "object" || !("choices" in response)) {
+              return null;
             }
-          }
-          messages.push({
-            role: "user",
-            content: prompt
-          });
-          const callbacks = {
-            // Build OpenAI Tool format from tool definitions
-            buildTools: (toolDefs) => {
-              return toolDefs.map((def) => ({
-                type: "function",
-                function: {
-                  name: def.name,
-                  description: def.description,
-                  parameters: def.input_schema
-                }
-              }));
-            },
-            // Call OpenAI API
-            callAPI: async (msgs, tools) => {
-              const apiParams = {
-                model: factoryModel,
-                max_completion_tokens: maxTokens,
-                messages: msgs,
-                tools,
-                tool_choice: "auto"
-              };
-              if (factoryTemperature !== void 0) {
-                apiParams.temperature = factoryTemperature;
+            const choices = response.choices;
+            if (!Array.isArray(choices) || choices.length === 0) {
+              return null;
+            }
+            const choice = choices[0];
+            if (!choice || typeof choice !== "object" || !("message" in choice)) {
+              return null;
+            }
+            const message = choice.message;
+            if (!message || typeof message !== "object" || !("tool_calls" in message)) {
+              return null;
+            }
+            const toolCalls = message.tool_calls;
+            if (!toolCalls || !Array.isArray(toolCalls)) {
+              return null;
+            }
+            const functionToolCalls = toolCalls.filter(
+              (tc) => typeof tc === "object" && tc !== null && "type" in tc && tc.type === "function"
+            );
+            return functionToolCalls.map((tc) => {
+              const functionCall = tc;
+              const args2 = functionCall.function.arguments;
+              let parsedArgs;
+              try {
+                parsedArgs = JSON.parse(args2);
+              } catch {
+                parsedArgs = {};
               }
-              const response2 = await client.chat.completions.create(apiParams);
               return {
-                ...response2,
-                usage: {
-                  input_tokens: response2.usage?.prompt_tokens ?? 0,
-                  output_tokens: response2.usage?.completion_tokens ?? 0
-                }
+                id: tc.id,
+                name: functionCall.function.name,
+                input: parsedArgs
               };
-            },
-            // Extract tool calls from OpenAI response
-            extractToolCalls: (response2) => {
-              if (!response2 || typeof response2 !== "object" || !("choices" in response2)) {
-                return null;
-              }
-              const choices = response2.choices;
-              if (!Array.isArray(choices) || choices.length === 0) {
-                return null;
-              }
-              const choice = choices[0];
-              if (!choice || typeof choice !== "object" || !("message" in choice)) {
-                return null;
-              }
-              const message = choice.message;
-              if (!message || typeof message !== "object" || !("tool_calls" in message)) {
-                return null;
-              }
-              const toolCalls = message.tool_calls;
-              if (!toolCalls || !Array.isArray(toolCalls)) {
-                return null;
-              }
-              const functionToolCalls = toolCalls.filter(
-                (tc) => typeof tc === "object" && tc !== null && "type" in tc && tc.type === "function"
-              );
-              return functionToolCalls.map((tc) => {
-                const functionCall = tc;
-                const args2 = functionCall.function.arguments;
-                let parsedArgs;
-                try {
-                  parsedArgs = JSON.parse(args2);
-                } catch {
-                  parsedArgs = {};
-                }
-                return {
-                  id: tc.id,
-                  name: functionCall.function.name,
-                  input: parsedArgs
-                };
-              });
-            },
-            // Extract assistant message (with tool_calls) from OpenAI response
-            formatAssistantMessage: (response2) => {
-              if (!response2 || typeof response2 !== "object" || !("choices" in response2)) {
-                return null;
-              }
-              const choices = response2.choices;
-              if (!Array.isArray(choices) || choices.length === 0) {
-                return null;
-              }
-              const choice = choices[0];
-              if (!choice || typeof choice !== "object" || !("message" in choice)) {
-                return null;
-              }
-              return choice.message;
-            },
-            // Format tool results into OpenAI message format
-            formatToolResult: (toolResults) => {
-              return toolResults.map((tr) => ({
-                role: "tool",
-                tool_call_id: tr.id,
-                content: tr.error ? JSON.stringify({ error: tr.error, code: "RILL-R001" }) : typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result)
-              }));
+            });
+          },
+          // Extract assistant message (with tool_calls) from OpenAI response
+          formatAssistantMessage: (response) => {
+            if (!response || typeof response !== "object" || !("choices" in response)) {
+              return null;
             }
-          };
-          const loopResult = await executeToolLoop(
-            messages,
-            options["tools"],
-            maxErrors,
-            callbacks,
-            (event, data) => {
-              const eventMap = {
-                tool_call: "openai:tool_call",
-                tool_result: "openai:tool_result"
-              };
-              emitExtensionEvent(ctx, {
-                event: eventMap[event] || event,
-                subsystem: "extension:openai",
-                ...data
-              });
-            },
-            maxTurns,
-            ctx
-          );
-          const response = loopResult.response;
-          const content = response?.choices[0]?.message?.content ?? "";
-          const stopReason = loopResult.turns >= maxTurns ? "max_turns" : response?.choices[0]?.finish_reason ?? "stop";
-          const fullMessages = [];
-          for (const msg of messages) {
-            if ("role" in msg && msg.role !== "system") {
-              const historyMsg = {
-                role: msg.role
-              };
-              if ("content" in msg && msg.content) {
-                historyMsg["content"] = msg.content;
-              }
-              if ("tool_calls" in msg && msg.tool_calls) {
-                historyMsg["tool_calls"] = msg.tool_calls;
-              }
-              fullMessages.push(historyMsg);
+            const choices = response.choices;
+            if (!Array.isArray(choices) || choices.length === 0) {
+              return null;
             }
+            const choice = choices[0];
+            if (!choice || typeof choice !== "object" || !("message" in choice)) {
+              return null;
+            }
+            return choice.message;
+          },
+          // Format tool results into OpenAI message format
+          formatToolResult: (toolResults) => {
+            return toolResults.map((tr) => ({
+              role: "tool",
+              tool_call_id: tr.id,
+              content: tr.error ? JSON.stringify({ error: tr.error, code: "RILL-R001" }) : typeof tr.result === "string" ? tr.result : JSON.stringify(tr.result)
+            }));
           }
-          if (response) {
-            fullMessages.push({
-              role: "assistant",
-              content
+        };
+        const chunkBuffer = [];
+        const yieldChunk = (chunk) => {
+          chunkBuffer.push(chunk);
+        };
+        const toolLoopAbortController = new AbortController();
+        const loopPromise = executeToolLoop(
+          messages,
+          toolsDict,
+          maxErrors,
+          callbacks,
+          (event, data) => {
+            const eventMap = {
+              tool_call: "openai:tool_call",
+              tool_result: "openai:tool_result"
+            };
+            emitExtensionEvent(ctx, {
+              event: eventMap[event] || event,
+              subsystem: "extension:openai",
+              ...data
             });
+          },
+          maxTurns,
+          ctx,
+          yieldChunk,
+          toolLoopAbortController.signal
+        );
+        async function* chunks() {
+          try {
+            await loopPromise;
+            for (const chunk of chunkBuffer) {
+              yield chunk;
+            }
+          } catch (error) {
+            const rillError = mapProviderError("OpenAI", error, detectOpenAIError);
+            throw rillError;
           }
-          const result2 = {
-            content,
-            model: factoryModel,
-            usage: {
-              input: loopResult.totalTokens.input,
-              output: loopResult.totalTokens.output
-            },
-            stop_reason: stopReason,
-            turns: loopResult.turns,
-            messages: fullMessages
-          };
-          const duration = Date.now() - startTime;
-          emitExtensionEvent(ctx, {
-            event: "openai:tool_loop",
-            subsystem: "extension:openai",
-            turns: loopResult.turns,
-            total_duration: duration,
-            usage: result2.usage,
-            request: messages,
-            content
-          });
-          return result2;
-        } catch (error) {
-          const duration = Date.now() - startTime;
-          const rillError = mapProviderError(
-            "OpenAI",
-            error,
-            detectOpenAIError
-          );
-          emitExtensionEvent(ctx, {
-            event: "openai:error",
-            subsystem: "extension:openai",
-            error: rillError.message,
-            duration
-          });
-          throw rillError;
         }
+        const resolve = async () => {
+          const startTime = Date.now();
+          try {
+            const loopResult = await loopPromise;
+            const response = loopResult.response;
+            const content = response?.choices[0]?.message?.content ?? "";
+            const stopReason = loopResult.turns >= maxTurns ? "max_turns" : response?.choices[0]?.finish_reason ?? "stop";
+            const inputMessages = messages.filter((m) => "role" in m && m["role"] !== "system").map((m) => {
+              const msg = m;
+              return {
+                role: msg["role"],
+                content: msg["content"] == null ? "" : typeof msg["content"] === "string" ? msg["content"] : JSON.stringify(msg["content"])
+              };
+            });
+            const result = {
+              content,
+              model: factoryModel,
+              usage: {
+                input: loopResult.totalTokens.input,
+                output: loopResult.totalTokens.output
+              },
+              stop_reason: stopReason,
+              turns: loopResult.turns,
+              messages: response ? buildResponseMessages(inputMessages, content) : inputMessages
+            };
+            const duration = Date.now() - startTime;
+            emitExtensionEvent(ctx, {
+              event: "openai:tool_loop",
+              subsystem: "extension:openai",
+              turns: loopResult.turns,
+              total_duration: duration,
+              usage: result.usage,
+              request: messages,
+              content
+            });
+            return result;
+          } catch (error) {
+            const duration = Date.now() - startTime;
+            const rillError = mapProviderError("OpenAI", error, detectOpenAIError);
+            emitExtensionEvent(ctx, {
+              event: "openai:error",
+              subsystem: "extension:openai",
+              error: rillError.message,
+              duration
+            });
+            throw rillError;
+          }
+        };
+        const retType = {
+          kind: "dict",
+          fields: {
+            content: { type: { kind: "string" } },
+            model: { type: { kind: "string" } },
+            usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+            stop_reason: { type: { kind: "string" } },
+            turns: { type: { kind: "number" } },
+            messages: { type: { kind: "list", element: { kind: "dict" } } }
+          }
+        };
+        return createRillStream({
+          chunks: chunks(),
+          resolve,
+          dispose: () => {
+            toolLoopAbortController.abort();
+          },
+          chunkType: { kind: "dict" },
+          retType
+        });
       },
       annotations: { description: "Execute tool-use loop with OpenAI API" },
-      returnType: rillTypeToTypeValue({
-        type: "dict",
-        fields: {
-          content: { type: { type: "string" } },
-          model: { type: { type: "string" } },
-          usage: { type: { type: "dict", fields: { input: { type: { type: "number" } }, output: { type: { type: "number" } } } } },
-          stop_reason: { type: { type: "string" } },
-          turns: { type: { type: "number" } },
-          messages: { type: { type: "list", element: { type: "dict" } } }
+      returnType: structureToTypeValue({
+        kind: "stream",
+        chunk: { kind: "dict" },
+        ret: {
+          kind: "dict",
+          fields: {
+            content: { type: { kind: "string" } },
+            model: { type: { kind: "string" } },
+            usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+            stop_reason: { type: { kind: "string" } },
+            turns: { type: { kind: "number" } },
+            messages: { type: { kind: "list", element: { kind: "dict" } } }
+          }
         }
       })
     },
@@ -1248,10 +1388,10 @@ function createOpenAIExtension(config) {
       params: [
         p.str("prompt"),
         p.dict("options", void 0, {}, {
-          schema: { type: { type: "dict" } },
-          system: { type: { type: "string" }, defaultValue: "" },
-          max_tokens: { type: { type: "number" }, defaultValue: 0 },
-          messages: { type: { type: "list", element: { type: "dict", fields: { role: { type: { type: "string" } }, content: { type: { type: "string" } } } } }, defaultValue: [] }
+          schema: { type: { kind: "dict" } },
+          system: { type: { kind: "string" }, defaultValue: "" },
+          max_tokens: { type: { kind: "number" }, defaultValue: 0 },
+          messages: { type: { kind: "list", element: { kind: "dict", fields: { role: { type: { kind: "string" } }, content: { type: { kind: "string" } } } } }, defaultValue: [] }
         })
       ],
       fn: async (args, ctx) => {
@@ -1268,7 +1408,7 @@ function createOpenAIExtension(config) {
           const rillSchema = options["schema"];
           const jsonSchema = buildJsonSchema(rillSchema);
           const system = typeof options["system"] === "string" ? options["system"] : factorySystem;
-          const maxTokens = typeof options["max_tokens"] === "number" ? options["max_tokens"] : factoryMaxTokens;
+          const maxTokens = typeof options["max_tokens"] === "number" && options["max_tokens"] > 0 ? options["max_tokens"] : factoryMaxTokens;
           const apiMessages = [];
           if (system !== void 0) {
             apiMessages.push({
@@ -1330,7 +1470,7 @@ function createOpenAIExtension(config) {
               `generate: failed to parse response JSON: ${detail}`
             );
           }
-          const result2 = {
+          const result = {
             data,
             raw,
             model: response.model,
@@ -1347,11 +1487,11 @@ function createOpenAIExtension(config) {
             subsystem: "extension:openai",
             duration,
             model: response.model,
-            usage: result2.usage,
+            usage: result.usage,
             request: apiMessages,
             content: raw
           });
-          return result2;
+          return result;
         } catch (error) {
           const duration = Date.now() - startTime;
           const rillError = error instanceof RuntimeError6 ? error : mapProviderError("OpenAI", error, detectOpenAIError);
@@ -1365,21 +1505,28 @@ function createOpenAIExtension(config) {
         }
       },
       annotations: { description: "Generate structured output from OpenAI API" },
-      returnType: rillTypeToTypeValue({
-        type: "dict",
+      returnType: structureToTypeValue({
+        kind: "dict",
         fields: {
-          data: { type: { type: "any" } },
-          raw: { type: { type: "string" } },
-          model: { type: { type: "string" } },
-          usage: { type: { type: "dict", fields: { input: { type: { type: "number" } }, output: { type: { type: "number" } } } } },
-          stop_reason: { type: { type: "string" } },
-          id: { type: { type: "string" } }
+          data: { type: { kind: "any" } },
+          raw: { type: { kind: "string" } },
+          model: { type: { kind: "string" } },
+          usage: { type: { kind: "dict", fields: { input: { type: { kind: "number" } }, output: { type: { kind: "number" } } } } },
+          stop_reason: { type: { kind: "string" } },
+          id: { type: { kind: "string" } }
         }
       })
     }
   };
-  result.dispose = dispose;
-  return result;
+  const callableDict = {
+    message: toCallable(fnDict.message),
+    messages: toCallable(fnDict.messages),
+    embed: toCallable(fnDict.embed),
+    embed_batch: toCallable(fnDict.embed_batch),
+    tool_loop: toCallable(fnDict.tool_loop),
+    generate: toCallable(fnDict.generate)
+  };
+  return { value: callableDict, dispose };
 }
 
 // src/index.ts