rhachet-brains-openai 0.2.1 → 0.3.1

package/dist/index.js

@@ -40,7 +40,6 @@ module.exports = __toCommonJS(index_exports);
 // src/domain.operations/atoms/genBrainAtom.ts
 var import_openai = __toESM(require("openai"));
 var import_brains = require("rhachet/brains");
-var import_zod = require("zod");
 
 // src/domain.objects/BrainAtom.config.ts
 var import_iso_price = require("iso-price");
@@ -802,7 +801,88 @@ var CONFIG_BY_ATOM_SLUG = {
   }
 };
 
+// src/infra/cast/castFromOpenaiFunctionCall.ts
+var castFromOpenaiFunctionCall = (input) => ({
+  exid: input.item.call_id,
+  slug: input.item.name,
+  input: JSON.parse(input.item.arguments)
+});
+
+// src/infra/cast/castIntoOpenaiFunctionCallOutput.ts
+var genFunctionCallOutputId = () => `fc_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+var castIntoOpenaiFunctionCallOutput = (input) => ({
+  type: "function_call_output",
+  id: genFunctionCallOutputId(),
+  call_id: input.execution.exid,
+  output: JSON.stringify(input.execution.output)
+});
+
+// src/infra/schema/asJsonSchema.ts
+var import_zod = require("zod");
+var asOpenaiStrictSchema = (schema) => {
+  if (!schema.properties) return schema;
+  const requiredSet = new Set(schema.required ?? []);
+  const allPropertyNames = Object.keys(schema.properties);
+  const propertiesTransformed = {};
+  for (const [name, prop] of Object.entries(schema.properties)) {
+    const isOptional = !requiredSet.has(name);
+    let propTransformed = { ...prop };
+    if (prop.type === "object" && prop.properties) {
+      propTransformed = asOpenaiStrictSchema(prop);
+    }
+    if (isOptional && propTransformed.type) {
+      const currentType = propTransformed.type;
+      if (Array.isArray(currentType)) {
+        if (!currentType.includes("null")) {
+          propTransformed = {
+            ...propTransformed,
+            type: [...currentType, "null"]
+          };
+        }
+      } else {
+        propTransformed = { ...propTransformed, type: [currentType, "null"] };
+      }
+    }
+    propertiesTransformed[name] = propTransformed;
+  }
+  return {
+    ...schema,
+    properties: propertiesTransformed,
+    required: allPropertyNames
+  };
+};
+var asJsonSchema = (input) => {
+  const schema = import_zod.z.toJSONSchema(input.schema, { target: "openAi" });
+  return asOpenaiStrictSchema(schema);
+};
+
+// src/infra/cast/castIntoOpenaiFunctionTool.ts
+var asOpenaiFunctionName = (slug) => slug.replace(/\./g, "_");
+var castIntoOpenaiFunctionTool = (input) => ({
+  type: "function",
+  name: asOpenaiFunctionName(input.definition.slug),
+  description: input.definition.description,
+  parameters: asJsonSchema({ schema: input.definition.schema.input }),
+  strict: true
+});
+
 // src/domain.operations/atoms/genBrainAtom.ts
+var reconstructAssistantItems = (exchangeOutput) => {
+  try {
+    const parsed = JSON.parse(exchangeOutput);
+    if (Array.isArray(parsed)) {
+      const hasResponseItems = parsed.some(
+        (item) => item?.type === "function_call" || item?.type === "message" || item?.type === "reasoning"
+      );
+      if (hasResponseItems) {
+        return parsed;
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof SyntaxError)) throw error;
+  }
+  return [{ role: "assistant", content: exchangeOutput }];
+};
 var genBrainAtom = (input) => {
   const config = CONFIG_BY_ATOM_SLUG[input.slug];
   return new import_brains.BrainAtom({
@@ -811,32 +891,52 @@ var genBrainAtom = (input) => {
     description: config.description,
     spec: config.spec,
     /**
-     * .what = stateless inference (no tool use)
-     * .why = provides direct model access for reason tasks
+     * .what = stateless inference with optional tool use
+     * .why = provides direct model access for reason tasks, supports tool invocations
      */
     ask: async (askInput, context) => {
       const startTime = Date.now();
       const systemPrompt = askInput.role.briefs ? await (0, import_brains.castBriefsToPrompt)({ briefs: askInput.role.briefs }) : void 0;
       const openai = context?.openai ?? new import_openai.default({ apiKey: process.env.OPENAI_API_KEY });
-      const jsonSchema = import_zod.z.toJSONSchema(askInput.schema.output);
+      const jsonSchema = asJsonSchema({ schema: askInput.schema.output });
       const isObjectSchema = typeof jsonSchema === "object" && jsonSchema !== null && "type" in jsonSchema && jsonSchema.type === "object";
-      const fullPrompt = systemPrompt ? `${systemPrompt}
+      const isToolExecutionArray = Array.isArray(askInput.prompt);
+      const pluggedTools = askInput.plugs?.tools ?? [];
+      const hasTools = pluggedTools.length > 0;
+      const fullPrompt = isToolExecutionArray ? null : systemPrompt ? `${systemPrompt}
 
 ---
 
 ${askInput.prompt}` : askInput.prompt;
+      const openaiFunctionTools = hasTools ? pluggedTools.map(
+        (definition) => castIntoOpenaiFunctionTool({ definition })
+      ) : [];
       const priorMessages = askInput.on?.episode?.exchanges.flatMap((exchange) => [
         { role: "user", content: exchange.input },
-        { role: "assistant", content: exchange.output }
+        ...reconstructAssistantItems(exchange.output)
       ]) ?? [];
+      const currentInput = isToolExecutionArray ? askInput.prompt.map(
+        (execution) => castIntoOpenaiFunctionCallOutput({ execution })
+      ) : [{ role: "user", content: fullPrompt }];
+      const systemInstruction = hasTools && isObjectSchema ? [
+        {
+          role: "system",
+          content: `When you have the final answer, respond with valid JSON matching this schema:
+${JSON.stringify(jsonSchema, null, 2)}`
+        }
+      ] : [];
       const inputMessages = [
+        ...systemInstruction,
         ...priorMessages,
-        { role: "user", content: fullPrompt }
+        ...currentInput
       ];
       const response = await openai.responses.create({
         model: config.model,
         input: inputMessages,
-        ...isObjectSchema && {
+        ...hasTools && {
+          tools: openaiFunctionTools
+        },
+        ...!hasTools && isObjectSchema && {
           text: {
             format: {
               type: "json_schema",
@@ -847,6 +947,14 @@ ${askInput.prompt}` : askInput.prompt;
           }
         }
       });
+      const functionCallItems = response.output.filter(
+        (item) => item.type === "function_call"
+      );
+      const calls = functionCallItems.length > 0 ? {
+        tools: functionCallItems.map(
+          (item) => castFromOpenaiFunctionCall({ item })
+        )
+      } : null;
       const outputItem = response.output.find(
         (item) => item.type === "message"
       );
@@ -856,7 +964,7 @@ ${askInput.prompt}` : askInput.prompt;
       const tokensOutput = response.usage?.output_tokens ?? 0;
       const tokensCacheGet = response.usage?.input_tokens_details?.cached_tokens ?? 0;
       const elapsedMs = Date.now() - startTime;
-      const charsInput = fullPrompt.length;
+      const charsInput = isToolExecutionArray ? JSON.stringify(askInput.prompt).length : fullPrompt.length;
       const charsOutput = content.length;
       const size = {
         tokens: {
@@ -881,7 +989,38 @@ ${askInput.prompt}` : askInput.prompt;
           cash
         }
       });
-      const output = isObjectSchema ? askInput.schema.output.parse(JSON.parse(content)) : askInput.schema.output.parse(content);
+      const output = (() => {
+        if (!content) return null;
+        if (hasTools && isObjectSchema) {
+          try {
+            return askInput.schema.output.parse(JSON.parse(content));
+          } catch (error) {
+            const isParseError = error instanceof SyntaxError || error?.constructor?.name === "ZodError";
+            if (!isParseError) throw error;
+            const jsonMatch = content.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+              try {
+                return askInput.schema.output.parse(JSON.parse(jsonMatch[0]));
+              } catch (extractError) {
+                const isExtractParseError = extractError instanceof SyntaxError || extractError?.constructor?.name === "ZodError";
+                if (!isExtractParseError) throw extractError;
+              }
+            }
+            if (calls) return null;
+            return null;
+          }
+        }
+        try {
+          return isObjectSchema ? askInput.schema.output.parse(JSON.parse(content)) : askInput.schema.output.parse(content);
+        } catch (error) {
+          const isParseError = error instanceof SyntaxError || error?.constructor?.name === "ZodError";
+          if (!isParseError) throw error;
+          if (calls) return null;
+          throw new Error("structured output parse failed with no tool calls");
+        }
+      })();
+      const exchangeInput = isToolExecutionArray ? JSON.stringify(askInput.prompt) : askInput.prompt;
+      const exchangeOutput = functionCallItems.length > 0 ? JSON.stringify(response.output) : content;
       const continuables = await (0, import_brains.genBrainContinuables)({
         for: { grain: "atom" },
         on: {
@@ -890,14 +1029,15 @@ ${askInput.prompt}` : askInput.prompt;
         },
         with: {
           exchange: {
-            input: askInput.prompt,
-            output: content,
+            input: exchangeInput,
+            output: exchangeOutput,
             exid: response.id
           }
         }
       });
       return new import_brains.BrainOutput({
         output,
+        calls,
         metrics,
         episode: continuables.episode,
         series: continuables.series
@@ -1264,14 +1404,6 @@ var Codex = class {
 var import_helpful_errors = require("helpful-errors");
 var import_brains2 = require("rhachet/brains");
 var import_wrapper_fns = require("wrapper-fns");
-
-// src/infra/schema/asJsonSchema.ts
-var import_zod2 = require("zod");
-var asJsonSchema = (input) => {
-  return import_zod2.z.toJSONSchema(input.schema, { target: "openAi" });
-};
-
-// src/domain.operations/repls/genBrainRepl.ts
 var CONFIG_BY_REPL_SLUG = {
   // default
   "openai/codex": CONFIG_BY_ATOM_SLUG["openai/gpt/codex/5.1-max"],
@@ -1384,6 +1516,7 @@ var invokeCodex = async (input) => {
   });
   return new import_brains2.BrainOutput({
     output,
+    calls: null,
     metrics,
     episode: continuables.episode,
     series: continuables.series
@@ -1396,11 +1529,10 @@ var genBrainRepl = (input) => {
     slug: input.slug,
     description: config.description,
     spec: config.spec,
-    /**
-     * .what = readonly analysis (research, queries, code review)
-     * .why = provides safe, non-mutate agent interactions via read-only sandbox
-     */
-    ask: async (askInput, _context) => invokeCodex({
+    // note: repls only accept string prompts (tool execution handled internally by codex SDK)
+    // type assertions needed because BrainRepl contract now supports AsBrainPromptFor<TPlugs>
+    // but codex SDK's thread.run() only accepts string prompts
+    ask: (async (askInput, _context) => invokeCodex({
       mode: "ask",
       model: config.model,
       spec: config.spec,
@@ -1409,12 +1541,8 @@ var genBrainRepl = (input) => {
       role: askInput.role,
       prompt: askInput.prompt,
       schema: askInput.schema
-    }),
-    /**
-     * .what = read+write actions (code changes, file edits)
-     * .why = provides full agentic capabilities via workspace-write sandbox
-     */
-    act: async (actInput, _context) => invokeCodex({
+    })),
+    act: (async (actInput, _context) => invokeCodex({
       mode: "act",
       model: config.model,
       spec: config.spec,
@@ -1423,7 +1551,7 @@ var genBrainRepl = (input) => {
       role: actInput.role,
       prompt: actInput.prompt,
       schema: actInput.schema
-    })
+    }))
   });
 };
 

package/dist/infra/cast/castFromOpenaiFunctionCall.d.ts

@@ -0,0 +1,9 @@
+import type OpenAI from 'openai';
+import type { BrainPlugToolInvocation } from 'rhachet/brains';
+/**
+ * .what = cast openai function_call to rhachet tool invocation
+ * .why = explicit boundary between openai sdk and rhachet domain
+ */
+export declare const castFromOpenaiFunctionCall: (input: {
+    item: OpenAI.Responses.ResponseFunctionToolCall;
+}) => BrainPlugToolInvocation<unknown>;

package/dist/infra/cast/castIntoOpenaiFunctionCallOutput.d.ts

@@ -0,0 +1,12 @@
+import type OpenAI from 'openai';
+import type { BrainPlugToolExecution } from 'rhachet/brains';
+/**
+ * .what = cast rhachet tool execution to openai function_call_output format
+ * .why = explicit boundary between rhachet domain and openai sdk
+ *
+ * .note = id is a new generated id for this output item (must start with fc_)
+ * .note = call_id references the original function_call this responds to
+ */
+export declare const castIntoOpenaiFunctionCallOutput: (input: {
+    execution: BrainPlugToolExecution<unknown, unknown>;
+}) => OpenAI.Responses.ResponseFunctionToolCallOutputItem;

package/dist/infra/cast/castIntoOpenaiFunctionTool.d.ts

@@ -0,0 +1,14 @@
+import type OpenAI from 'openai';
+import type { BrainPlugToolDefinition } from 'rhachet/brains';
+/**
+ * .what = transforms slug to valid openai function name
+ * .why = openai requires names match pattern ^[a-zA-Z0-9_-]+$
+ */
+export declare const asOpenaiFunctionName: (slug: string) => string;
+/**
+ * .what = cast rhachet tool definition to openai function tool format
+ * .why = explicit boundary between rhachet domain and openai sdk
+ */
+export declare const castIntoOpenaiFunctionTool: (input: {
+    definition: BrainPlugToolDefinition<unknown, unknown, 'atom', string>;
+}) => OpenAI.Responses.FunctionTool;

package/dist/infra/schema/asJsonSchema.d.ts

@@ -1,12 +1,15 @@
 import { z } from 'zod';
 /**
  * .what = convert a zod schema to JSON schema for native SDK enforcement
- * .why = enables native structured output support in SDKs, reducing
+ * .why = enables native structured output support in SDKs to reduce
  *   token waste on validation retries
  *
  * .note = different SDKs require different conversion options:
  *   - claude-agent-sdk: { $refStrategy: 'root' }
  *   - codex-sdk: { target: 'openAi' }
+ *
+ * .note = openai strict mode requires all properties in required array
+ *   with optional properties marked as nullable types
  */
 export declare const asJsonSchema: (input: {
     schema: z.ZodSchema;

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-brains-openai",
   "author": "ehmpathy",
   "description": "rhachet brain.atom and brain.repl adapter for openai",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "repository": "ehmpathy/rhachet-brains-openai",
   "homepage": "https://github.com/ehmpathy/rhachet-brains-openai",
   "keywords": [
@@ -54,7 +54,7 @@
     "preversion": "npm run prepush",
     "postversion": "git push origin HEAD --tags --no-verify",
     "prepare:husky": "husky install && chmod ug+x .husky/*",
-    "prepare:rhachet": "rhachet init --hooks --roles behaver mechanic reviewer",
+    "prepare:rhachet": "npm run build && rhachet init --hooks --roles behaver driver mechanic reviewer architect ergonomist librarian",
     "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi"
   },
   "dependencies": {
@@ -90,11 +90,11 @@
     "husky": "8.0.3",
     "iso-time": "1.11.1",
     "jest": "30.2.0",
-    "rhachet": "1.29.5",
-    "rhachet-brains-anthropic": "0.3.2",
-    "rhachet-roles-bhrain": "0.7.5",
-    "rhachet-roles-bhuild": "0.7.0",
-    "rhachet-roles-ehmpathy": "1.18.0",
+    "rhachet": "1.37.18",
+    "rhachet-brains-anthropic": "0.4.0",
+    "rhachet-roles-bhrain": "0.20.2",
+    "rhachet-roles-bhuild": "0.14.4",
+    "rhachet-roles-ehmpathy": "1.29.2",
     "test-fns": "1.10.0",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",