rhachet-brains-openai 0.2.0 → 0.3.0

package/dist/domain.operations/atoms/genBrainAtom.d.ts

@@ -1,4 +1,4 @@
-import { BrainAtom } from 'rhachet';
+import { BrainAtom } from 'rhachet/brains';
 import { type OpenaiBrainAtomSlug } from '../../domain.objects/BrainAtom.config';
 /**
  * .what = factory to generate openai brain atom instances

package/dist/domain.operations/repls/genBrainRepl.d.ts

@@ -1,4 +1,4 @@
-import { BrainRepl } from 'rhachet';
+import { BrainRepl } from 'rhachet/brains';
 /**
  * .what = supported openai brain repl slugs
  * .why = enables type-safe slug specification with model variants

package/dist/index.js

@@ -39,9 +39,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/domain.operations/atoms/genBrainAtom.ts
 var import_openai = __toESM(require("openai"));
-var import_rhachet = require("rhachet");
-var import_calcBrainOutputCost = require("rhachet/dist/domain.operations/brainCost/calcBrainOutputCost");
-var import_zod = require("zod");
+var import_brains = require("rhachet/brains");
 
 // src/domain.objects/BrainAtom.config.ts
 var import_iso_price = require("iso-price");
@@ -803,33 +801,109 @@ 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 asJsonSchema = (input) => {
+  return import_zod.z.toJSONSchema(input.schema, { target: "openAi" });
+};
+
+// 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_rhachet.BrainAtom({
+  return new import_brains.BrainAtom({
     repo: "openai",
     slug: input.slug,
     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_rhachet.castBriefsToPrompt)({ briefs: askInput.role.briefs }) : void 0;
+      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 },
+        ...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,
+        ...currentInput
+      ];
       const response = await openai.responses.create({
         model: config.model,
-        input: fullPrompt,
-        ...isObjectSchema && {
+        input: inputMessages,
+        ...hasTools && {
+          tools: openaiFunctionTools
+        },
+        ...!hasTools && isObjectSchema && {
           text: {
             format: {
               type: "json_schema",
@@ -840,6 +914,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"
       );
@@ -849,7 +931,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: {
@@ -863,19 +945,70 @@ ${askInput.prompt}` : askInput.prompt;
           cache: { get: 0, set: 0 }
         }
       };
-      const { cash } = (0, import_calcBrainOutputCost.calcBrainOutputCost)({
+      const { cash } = (0, import_brains.calcBrainOutputCost)({
         for: { tokens: size.tokens },
         with: { cost: { cash: config.spec.cost.cash } }
       });
-      const metrics = new import_rhachet.BrainOutputMetrics({
+      const metrics = new import_brains.BrainOutputMetrics({
         size,
         cost: {
           time: { milliseconds: elapsedMs },
           cash
         }
       });
-      const output = isObjectSchema ? askInput.schema.output.parse(JSON.parse(content)) : askInput.schema.output.parse(content);
-      return new import_rhachet.BrainOutput({ output, metrics });
+      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: {
+          episode: askInput.on?.episode ?? null,
+          series: null
+        },
+        with: {
+          exchange: {
+            input: exchangeInput,
+            output: exchangeOutput,
+            exid: response.id
+          }
+        }
+      });
+      return new import_brains.BrainOutput({
+        output,
+        calls,
+        metrics,
+        episode: continuables.episode,
+        series: continuables.series
+      });
     }
   });
 };
@@ -1235,17 +1368,9 @@ var Codex = class {
 };
 
 // src/domain.operations/repls/genBrainRepl.ts
-var import_rhachet2 = require("rhachet");
-var import_calcBrainOutputCost2 = require("rhachet/dist/domain.operations/brainCost/calcBrainOutputCost");
+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"],
@@ -1267,9 +1392,17 @@ var composePromptWithSystem = (userPrompt, systemPrompt) => {
 
 ${userPrompt}`;
 };
+var EXID_PREFIX = "openai/codex";
+var encodeExid = (threadId) => `${EXID_PREFIX}/${threadId}`;
+var decodeExid = (exid) => {
+  if (!exid.startsWith(`${EXID_PREFIX}/`)) return { valid: false };
+  const threadId = exid.slice(`${EXID_PREFIX}/`.length);
+  if (!threadId) return { valid: false };
+  return { valid: true, threadId };
+};
 var invokeCodex = async (input) => {
   const startTime = Date.now();
-  const systemPrompt = input.role.briefs ? await (0, import_rhachet2.castBriefsToPrompt)({ briefs: input.role.briefs }) : void 0;
+  const systemPrompt = input.role.briefs ? await (0, import_brains2.castBriefsToPrompt)({ briefs: input.role.briefs }) : void 0;
   const outputSchema = asJsonSchema({
     schema: input.schema.output
   });
@@ -1277,10 +1410,18 @@ var invokeCodex = async (input) => {
     apiKey: process.env.OPENAI_API_KEY
   });
   const sandboxMode = input.mode === "ask" ? "read-only" : "workspace-write";
-  const thread = codex.startThread({
-    model: input.model,
-    sandboxMode
-  });
+  const threadOptions = { model: input.model, sandboxMode };
+  const priorExid = input.on?.episode?.exid ?? null;
+  const thread = (() => {
+    if (!priorExid) return codex.startThread(threadOptions);
+    const decoded = decodeExid(priorExid);
+    if (!decoded.valid)
+      throw new import_helpful_errors.BadRequestError(
+        "episode continuation failed: exid is not from openai/codex. cross-supplier continuation is not supported.",
+        { priorExid }
+      );
+    return codex.resumeThread(decoded.threadId, threadOptions);
+  })();
   const fullPrompt = composePromptWithSystem(input.prompt, systemPrompt);
   const response = await (0, import_wrapper_fns.withRetry)(
     (0, import_wrapper_fns.withTimeout)(async () => thread.run(fullPrompt, { outputSchema }), {
@@ -1313,46 +1454,71 @@ var invokeCodex = async (input) => {
       cache: { get: 0, set: 0 }
     }
   };
-  const { cash } = (0, import_calcBrainOutputCost2.calcBrainOutputCost)({
+  const { cash } = (0, import_brains2.calcBrainOutputCost)({
     for: { tokens: size.tokens },
     with: { cost: { cash: input.spec.cost.cash } }
   });
-  const metrics = new import_rhachet2.BrainOutputMetrics({
+  const metrics = new import_brains2.BrainOutputMetrics({
     size,
     cost: {
       time: { milliseconds: elapsedMs },
       cash
     }
   });
-  return new import_rhachet2.BrainOutput({ output, metrics });
+  const threadExid = thread.id ? encodeExid(thread.id) : null;
+  const continuables = await (0, import_brains2.genBrainContinuables)({
+    for: { grain: "repl" },
+    on: {
+      episode: input.on?.episode ?? null,
+      series: input.on?.series ?? null
+    },
+    with: {
+      exchange: {
+        input: input.prompt,
+        output: content,
+        exid: thread.id
+      },
+      episode: { exid: threadExid }
+    }
+  });
+  return new import_brains2.BrainOutput({
+    output,
+    calls: null,
+    metrics,
+    episode: continuables.episode,
+    series: continuables.series
+  });
 };
 var genBrainRepl = (input) => {
   const config = CONFIG_BY_REPL_SLUG[input.slug];
-  return new import_rhachet2.BrainRepl({
+  return new import_brains2.BrainRepl({
     repo: "openai",
     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,
-      ...askInput
-    }),
-    /**
-     * .what = read+write actions (code changes, file edits)
-     * .why = provides full agentic capabilities via workspace-write sandbox
-     */
-    act: async (actInput, _context) => invokeCodex({
+      on: askInput.on,
+      plugs: askInput.plugs,
+      role: askInput.role,
+      prompt: askInput.prompt,
+      schema: askInput.schema
+    })),
+    act: (async (actInput, _context) => invokeCodex({
       mode: "act",
       model: config.model,
       spec: config.spec,
-      ...actInput
-    })
+      on: actInput.on,
+      plugs: actInput.plugs,
+      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/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.0",
+  "version": "0.3.0",
   "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 --mode upsert && rhachet roles link --repo ehmpathy --role mechanic && rhachet roles link --repo bhuild --role behaver && rhachet roles link --repo bhrain --role reviewer && rhachet roles init --role mechanic && rhachet roles init --role behaver",
+    "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,10 +90,11 @@
     "husky": "8.0.3",
     "iso-time": "1.11.1",
     "jest": "30.2.0",
-    "rhachet": "1.26.0",
-    "rhachet-roles-bhrain": "0.5.9",
-    "rhachet-roles-bhuild": "0.6.3",
-    "rhachet-roles-ehmpathy": "1.17.15",
+    "rhachet": "1.37.17",
+    "rhachet-brains-anthropic": "0.3.3",
+    "rhachet-roles-bhrain": "0.20.0",
+    "rhachet-roles-bhuild": "0.14.2",
+    "rhachet-roles-ehmpathy": "1.29.0",
     "test-fns": "1.10.0",
     "tsc-alias": "1.8.10",
     "tsx": "4.20.6",

package/readme.md

@@ -51,6 +51,60 @@ const { output: { proposal } } = await brainRepl.act({
 });
 ```
 
+## continuation support
+
+both atoms and repls support multi-turn conversations via episode continuation.
+
+### atoms
+
+atoms support continuation via the openai responses api. pass the prior episode to continue the conversation:
+
+```ts
+// first call establishes context
+const resultFirst = await brainAtom.ask({
+  role: {},
+  prompt: 'remember the secret word "PINEAPPLE42"',
+  schema: { output: z.object({ content: z.string() }) },
+});
+
+// second call continues with prior context
+const resultSecond = await brainAtom.ask({
+  on: { episode: resultFirst.episode },
+  role: {},
+  prompt: 'what is the secret word I told you?',
+  schema: { output: z.object({ content: z.string() }) },
+});
+// resultSecond.output.content contains "PINEAPPLE42"
+```
+
+### repls
+
+repls support continuation via the codex-sdk `resumeThread()` api. the episode exid contains the thread id prefixed with `openai/codex/` for cross-supplier validation:
+
+```ts
+// first call starts a new thread
+const resultFirst = await brainRepl.ask({
+  role: {},
+  prompt: 'remember the secret word "MANGO99"',
+  schema: { output: z.object({ content: z.string() }) },
+});
+// resultFirst.episode.exid = "openai/codex/{threadId}"
+
+// second call resumes the thread
+const resultSecond = await brainRepl.ask({
+  on: { episode: resultFirst.episode },
+  role: {},
+  prompt: 'what is the secret word I told you?',
+  schema: { output: z.object({ content: z.string() }) },
+});
+// resultSecond.output.content contains "MANGO99"
+```
+
+### limitations
+
+- **cross-supplier continuation is not supported**: episodes from other brain suppliers (e.g., anthropic) cannot be used to continue openai conversations. this throws a `BadRequestError`.
+- **exid validation**: the episode exid must start with `openai/codex/` for repl continuation. this prevents accidental cross-supplier continuation attempts.
+
 ## available brains
 
 ### atoms (via genBrainAtom)