loopengine 0.0.1 → 0.0.3

package/README.md

@@ -1,4 +1,6 @@
-# loopengine
+# LoopEngine
+
+[![CI](https://github.com/evanyan22/loopengine/actions/workflows/ci.yml/badge.svg)](https://github.com/evanyan22/loopengine/actions/workflows/ci.yml)
 
 A minimal framework for defining and running tool-using AI agents. Write an
 agent as a plain config object — persona, tools, permission rules — and run
@@ -23,6 +25,13 @@ out, in `session-store.ts`, since it persists what `run-agent.ts` produces
 rather than participating in the loop itself. Everything else in this repo
 — agent definitions, channel adapters — is built on top of those.
 
+A seventh package, [`mcpplug`](https://www.npmjs.com/package/mcpplug), sits
+one layer further out still: it's not part of the loop either, just a
+`ToolSource` an agent's own config can draw from — `loadTools()` returns
+`ToolDefinition[]`, the exact shape `AgentConfig.tools` already expects, so
+its output merges straight in with no adapter code. See "External tool
+gateways" below.
+
 ## Using loopengine as a library
 
 This repo is two things in one: a small library (the loop itself) and a
@@ -30,9 +39,16 @@ reference app built on top of it (demo agents, a CLI, an HTTP server). Only
 the library half ships to npm:
 
 ```bash
-npm install loopengine actauth contextclip reflowkit toollane skillgarden
+npm install loopengine
 ```
 
+`actauth`, `contextclip`, `reflowkit`, `toollane`, `skillgarden`, and the
+rest are regular dependencies of `loopengine` itself — installing it alone
+already pulls them into `node_modules`, fully resolvable for both imports
+and TypeScript types. Install one of them directly only if you want to use
+it standalone, outside `runAgent` (e.g. just `toollane`'s parallel/solo
+scheduling in your own loop).
+
 ```ts
 import { runAgent, type AgentConfig, type ToolDefinition } from 'loopengine'
 
@@ -57,10 +73,10 @@ console.log(result.text)
 ```
 
 The full exported surface: `runAgent`, `AgentConfig`/`ToolSchema`/`ToolDefinition`,
-`loadAgent` (for MCP-backed tools), `connectMcpTools`, `FileSessionStore`/
-`RedisSessionStore`/`createSessionStore`, `VectorIndex`/`embed`/
-`cosineSimilarity` (for RAG — see below), and `createAnthropicModelCall` (a
-real, ready-to-use `ModelCall`). See `index.ts` for the exact list.
+`FileSessionStore`/`RedisSessionStore`/`createSessionStore`, `VectorIndex`/
+`embed`/`cosineSimilarity` (for RAG — see below), and `createAnthropicModelCall`/
+`createOpenAIModelCall` (real, ready-to-use `ModelCall`s). See `index.ts` for
+the exact list.
 
 **Not** part of the package: `agents/*.ts` (this repo's own demo agents),
 `agent-registry.ts` (this repo's own name → config lookup table — build your
@@ -118,42 +134,11 @@ To make a new agent runnable through the adapters, add one line to
 `agent-registry.ts` mapping its name to its `config` and a `createModelCall`
 factory.
 
-## Connecting MCP tools
-
-A tool doesn't have to be hand-written — `AgentConfig.mcpServers` connects to
-a real MCP server and turns everything it exposes into ordinary tools, with
-the same ActAuth gating and ToolLane scheduling as `do_thing` above:
-
-```ts
-export const config: AgentConfig = {
-  name: 'my-mcp-agent',
-  systemPrompt: 'You are ...',
-  mcpServers: [
-    { command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '/some/dir'] },
-  ],
-  rules: [
-    { scopePattern: 'default/production/my-mcp-agent', tool: 'read_text_file', decision: 'allow' },
-  ],
-  defaultDecision: 'ask', // any tool the server exposes that you didn't write a rule for
-}
-```
-
-`agents/mcp-filesystem-agent.ts` is a complete example — it has zero hand-written
-tools; every one comes from the official
-`@modelcontextprotocol/server-filesystem`, spawned as a real subprocess.
-`load-agent.ts` is what resolves `mcpServers` into real tools: it runs for
-every agent (a no-op if `mcpServers` is absent), which is what makes this a
-config change rather than a bespoke loader function per server — write rules
-for the tool names you expect the server to expose (check its docs, or
-connect once and call `listTools()` yourself), the same way you'd write
-rules for a hand-written tool. Anything the server exposes that you didn't
-write a rule for still safely falls through to `defaultDecision`.
-
 ## Retrieval (RAG)
 
 RAG is just another tool — the model decides when to call it, `run-agent.ts`
 doesn't know or care that "executing" this particular tool means a vector
-search instead of a filesystem read or an MCP round-trip:
+search instead of a plain HTTP call:
 
 ```ts
 const searchDocs: ToolDefinition = {
@@ -178,6 +163,51 @@ implementation, the package proves the pipeline" pattern as ContextClip's
 ordinary tool result, subject to the same ActAuth gating, ToolLane
 scheduling, and ContextClip budget tracking as any other tool call.
 
+## External tool gateways
+
+A hand-written tool needs an `execute` function you write yourself; an
+external SaaS action (list GitHub repos, send a Slack message) needs
+someone to own that vendor's auth. Connecting straight to a vendor's own
+MCP server means owning its OAuth flow (authorization code, PKCE, token
+storage/refresh) yourself, repeated per vendor. Routing through a gateway
+like [Composio](https://composio.dev) avoids that — it already holds the
+OAuth relationship with 1000+ apps — and [`mcpplug`](https://www.npmjs.com/package/mcpplug)
+wraps that gateway behind the same `ToolDefinition` shape as everything
+else:
+
+```ts
+import { connectComposioSource } from 'mcpplug'
+
+// Resolved once, at module-eval time — not per runAgent() call. A gateway
+// connection is exactly the kind of setup cost runAgent() shouldn't pay on
+// every turn; see agents/file-agent.ts for the working example this is
+// drawn from.
+const composioTools = await connectComposioSource('composio', {
+  slugs: ['GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER'],
+}).then((source) => source.loadTools())
+
+const config: AgentConfig = {
+  name: 'my-agent',
+  systemPrompt: 'You are ...',
+  tools: [...handWrittenTools, ...composioTools],
+  rules: [
+    // mcpplug namespaces each tool `${sourceName}_${slug}` — falls
+    // through to defaultDecision unless a rule names it explicitly.
+    { scopePattern: 'default/production/my-agent', tool: 'composio_GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER', decision: 'allow' },
+  ],
+  defaultDecision: 'ask',
+}
+```
+
+Same ActAuth gating, ToolLane scheduling, and ContextClip budget tracking
+as any other tool call — `runAgent` has no idea one `execute` shells out
+through Composio instead of touching the filesystem or a vector index.
+`agents/file-agent.ts` is a complete, working example, verified end-to-end
+against a real linked GitHub account. `slugs` is explicit, not
+auto-discovered — an agent should only see the Composio actions its own
+config actually lists; find them with the `composio` CLI's
+`composio tools list <toolkit>` or `composio search "<use case>"`.
+
 ## Running an agent
 
 **CLI:**
@@ -195,10 +225,29 @@ curl -X POST localhost:8787/agents/customer-service/messages \
   -d '{"customerEmail":"a@example.com","message":"order A-1001 arrived broken"}'
 ```
 
+`customerEmail` is specific to `customer-service` — it defines its own
+`AgentConfig.sessionIdFor` (see "Sessions and multi-tenancy" below). Other
+agents take a plain `sessionId` field instead — and it's optional: omit it
+for a fresh, one-off session (a generated id, echoed back in the response
+as `sessionId` so you can pass it in explicitly to continue that same
+conversation on a later request):
+
+```bash
+curl -X POST localhost:8787/agents/file-agent/messages \
+  -H 'content-type: application/json' \
+  -d '{"sessionId":"s1","message":"Summarize a.txt and b.txt into summary.txt."}'
+```
+
+`customer-service` is the exception here too — a request with no
+`customerEmail` is a genuine validation error (`400`), not "start me an
+anonymous session," since `customerEmail` is a real, meaningful identity
+for that agent, not an arbitrary key.
+
 **HTTP, streamed:** same request, `/stream` suffix, one Server-Sent Event per
 loop step instead of a single response after the whole thing finishes —
-`contextclip:check`, `actauth:decision`, `toollane:result`, ..., a final
-`done` with the answer:
+a `session` event first (announcing whatever `sessionId` got used, generated
+or not), then `contextclip:check`, `actauth:decision`, `toollane:result`,
+..., a final `done` with the answer:
 
 ```bash
 curl -N -X POST localhost:8787/agents/customer-service/messages/stream \
@@ -233,13 +282,13 @@ rewrite can't:
 
 - **Non-blocking, debounced writes** instead of a full read-modify-write of
   the entire session every turn.
-- **Interruption detection.** `run-agent.ts` pushes one
-  `[requested: tool_a, tool_b]` message before any tool runs, then one
-  `[... result]` message per completed tool as they finish. If the process
-  dies in that window, the next `resume()` sees a request with no result
-  behind it, flags the session as resumed-after-interruption, and injects a
-  note into context saying so — instead of silently resending an
-  incomplete turn as if it were clean.
+- **Interruption detection.** `run-agent.ts` pushes the assistant's full
+  response — tool_use blocks included — as one message before any tool
+  runs, then one message bundling every tool_result once they've all
+  settled. If the process dies in that window, the next `resume()` sees an
+  assistant message with an unanswered tool_use block, flags the session
+  as resumed-after-interruption, and injects a note into context saying so
+  — instead of silently resending an incomplete turn as if it were clean.
 
 Two implementations, same `SessionStore` interface:
 
@@ -247,19 +296,57 @@ Two implementations, same `SessionStore` interface:
   locked in-process. Fine for local dev and the CLI.
 - `RedisSessionStore` — same log shape (a Redis list of entries, one
   `RPUSH` per append), with a real distributed lock, safe across multiple
-  server instances.
+  server instances. The lock renews itself (`lockTtlMs / 3` by default)
+  for as long as a turn runs, instead of a flat TTL that a long turn (a
+  real model call plus several tool round-trips) could outlast — if
+  renewal ever confirms the lock was lost anyway (not just a failed
+  renewal attempt — a network blip there isn't proof of loss), the turn's
+  result is rejected rather than silently returned as if mutual exclusion
+  held the whole time.
 
 `createSessionStore()` picks between them based on `REDIS_URL` — set it and
 you get Redis, otherwise it falls back to the file store. Either way,
 turn-level exclusivity (no two concurrent turns for the same session
 interleaving) is still this module's job, not SessionKnit's — SessionKnit's
-own topology repair handles branching *within* one resumed chain (parallel
-tool calls, crash recovery), not races between two full concurrent turns.
-
-The HTTP adapter derives the session key from `customerEmail` (hashed, so
-raw emails never end up in storage keys), so different customers can never
+own topology repair (reattaching sibling branches under a shared
+`parentId`) is a defensive read-side repair for crash/corruption recovery,
+not something normal operation exercises. `run-agent.ts` bundles a whole
+turn's `tool_use`/`tool_result` blocks into one message each, and
+`withSession` appends new messages sequentially, so even a turn with
+several parallel tool calls only ever produces a linear chain in the
+durable log — not races between two full concurrent turns, which is what
+the lock above actually prevents.
+
+Session-key derivation is `AgentConfig.sessionIdFor(body)` — deliberately
+not the HTTP adapter's call, since what counts as "one conversation" is
+business logic specific to what the agent is for, not a transport concern.
+`customer-service-agent.ts` defines its own, hashing `customerEmail` so raw
+addresses never end up in storage keys — different customers can never
 read or write each other's history, and concurrent messages from the same
-customer are serialized rather than dropped.
+customer are serialized rather than dropped. A missing `customerEmail` is a
+real validation failure for that agent (`400`), not something to paper over.
+
+An agent that doesn't define `sessionIdFor` falls back to a plain
+client-supplied `sessionId` field (`adapters/http.ts`'s
+`defaultSessionIdFor`) — the same shape `adapters/cli.ts`'s `--session`
+flag already uses — and if that's missing too, one gets generated rather
+than the request being rejected, mirroring what omitting `--session` now
+does for the CLI: a fresh, isolated, one-off session rather than an error
+or (worse) a shared bucket every untagged caller collides into. The
+generated id comes back in the response (`sessionId` in the JSON body, a
+`session` SSE event first for the streamed route) so a caller that wants to
+continue that exact conversation can pass it in explicitly next time.
+
+`SessionStore` itself is agent-agnostic — nothing in `session-store.ts` or
+`sessionknit` knows which agent is calling `withSession`, so both adapters
+namespace the *actual* key by agent name before it ever reaches
+`SessionStore`: `` `${agentName}:${sessionIdFor(...)}` `` in
+`adapters/http.ts`, `` `${agent}:${session}` `` in `adapters/cli.ts`.
+Without that, two different agents given the same session identifier (a
+client reusing one `sessionId`/`--session` value across agents, most
+likely) would read and write the exact same underlying log — one agent's
+tool calls and results spliced straight into another's conversation as if
+it had always been there.
 
 ## Deployment
 
@@ -276,11 +363,9 @@ and any tool-specific secrets set as environment variables.
 ## Wiring a real model
 
 Every example agent (`agents/file-agent.ts`, `agents/customer-service-agent.ts`,
-`agents/mcp-filesystem-agent.ts`, `agents/rag-agent.ts`) still uses a canned,
-turn-counting `ModelCall` so the whole loop is runnable and testable with no
-API key. To go live, swap it
-for `createAnthropicModelCall` (`anthropic-model-call.ts`), the one real
-`ModelCall` implementation this repo ships:
+`agents/rag-agent.ts`) still uses a canned, turn-counting `ModelCall` so the
+whole loop is runnable and testable with no API key. To go live, swap it for
+one of the two real `ModelCall` implementations this repo ships:
 
 ```ts
 import { createAnthropicModelCall } from './anthropic-model-call.js'
@@ -290,27 +375,69 @@ const modelCall = createAnthropicModelCall({ model: 'claude-sonnet-5' }) // read
 const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
 ```
 
+```ts
+import { createOpenAIModelCall } from './openai-model-call.js'
+
+// model is required (no built-in default) — OpenAI's current flagship
+// name changes too often to hardcode safely; reads OPENAI_API_KEY from the env
+const modelCall = createOpenAIModelCall({ model: 'gpt-4.1' })
+
+const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
+```
+
 Nothing else in `run-agent.ts`, the adapters, or any `AgentConfig` needs to
 change — `ModelCall` is the only seam a real API call needs.
 
-One tradeoff worth knowing: loopengine's `Message` type (from `contextclip`)
-is deliberately generic — `{role, content: string}` — so conversation
-history round-trips to the API as plain user/assistant text turns, not
-Anthropic's native `tool_use`/`tool_result` content blocks. Claude reads
-`"[lookup_order result] {...}"` as plain text just fine and the conversation
-still works correctly, but it's not the structured, block-native history the
-API is built around. This was verified against the real SDK (with a stubbed
-`fetch`, not a live call) — request shape, tool schemas, and response
-mapping all round-trip correctly end to end.
+loopengine's own `Message` type carries real block-native history: `content`
+is either a plain string or a `ModelContentBlock[]` — the same shape
+`ModelResponse.content` already used — so a model's `tool_use` requests and
+this loop's `tool_result` replies round-trip with real per-call identity
+(`tool_use_id`) rather than being flattened into prose. That's what makes
+parallel tool calls unambiguous (a result links back to the exact call that
+requested it, not just "a call to this tool name") and lets a denied or
+failed call carry `is_error: true`, which Claude is specifically trained to
+react to. `anthropic-model-call.ts` translates directly to and from
+Anthropic's native `TextBlockParam`/`ToolUseBlockParam`/`ToolResultBlockParam`
+types — no flattening step in between. This was verified against the real
+SDK (with a stubbed `fetch`, not a live call) — request shape, tool schemas,
+and response mapping all round-trip correctly end to end.
+
+`openai-model-call.ts` translates to and from OpenAI's Chat Completions
+shape instead, verified the same way (stubbed `fetch`, real SDK, full
+`runAgent` round trip including a tool call). The one structural mismatch:
+loopengine bundles a whole turn's `tool_result` blocks into a single
+user-role message (mirroring Anthropic's shape); OpenAI has no equivalent —
+each becomes its own top-level `role: 'tool'` message, so one loopengine
+`Message` can expand into several OpenAI messages, never the reverse.
 
 ## Skills
 
 Agents can discover and invoke `SKILL.md` files (see `skills/`), the same
 convention production coding agents use: a short frontmatter index (`name`,
 `description`) stays in context at all times, and the full body is loaded
-only when the model actually invokes that skill. Set `skillsDirs` on an
-`AgentConfig` to enable it; omit it for agents that don't need skills
-(`agents/customer-service-agent.ts` doesn't).
+only when the model actually invokes that skill — through a real `Skill`
+tool schema (`{skill: string, args?: string}`) declared to the model
+whenever `skillsDirs` is set, not just handled after the fact. Set
+`skillsDirs` on an `AgentConfig` to enable it; omit it for agents that
+don't need skills (`agents/rag-agent.ts` doesn't).
+
+Point `skillsDirs` at a subdirectory scoped to that agent
+(`skills/file-agent/`, not the shared `skills/` root) — `SkillGarden`'s
+discovery recursively walks whatever root it's given with no per-agent
+filtering, so two agents both pointed at `skills/` would each see every
+skill under it, not just their own.
+
+To install one of SkillGarden's bundled skills (e.g. `firecrawl`) into an
+agent's own subdirectory, use its `add` CLI:
+
+```bash
+npx skillgarden add firecrawl --agent file-agent
+# -> Added file-agent:firecrawl -> skills/file-agent/firecrawl/SKILL.md
+```
+
+That writes `skills/file-agent/firecrawl/SKILL.md`, which discovery then
+surfaces as `file-agent:firecrawl` — no code change needed beyond having
+already set `skillsDirs: 'skills/file-agent'` on that agent's config.
 
 ## Project layout
 
@@ -318,19 +445,17 @@ only when the model actually invokes that skill. Set `skillsDirs` on an
 index.ts                    Public API surface — what actually ships to npm
 agent-config.ts            AgentConfig type — the thing you fill in to define an agent
 run-agent.ts                The generic ReAct loop every agent and adapter runs through
-load-agent.ts               Resolves AgentConfig.mcpServers into real tools (no-op without it)
-mcp-tools.ts                 Wraps one MCP server's tools as ToolDefinition[]
 vector-index.ts             Dependency-free embeddings + cosine-similarity search, for RAG
-agent-registry.ts          Maps agent name -> {config, createModelCall}, via load-agent.ts
+agent-registry.ts          Maps agent name -> {config, createModelCall}
 session-store.ts           SessionStore: FileSessionStore, RedisSessionStore, createSessionStore()
-anthropic-model-call.ts    createAnthropicModelCall — the one real ModelCall this repo ships
+anthropic-model-call.ts    createAnthropicModelCall — a real ModelCall this repo ships
+openai-model-call.ts        createOpenAIModelCall — same seam, OpenAI's Chat Completions API
 agents/file-agent.ts               Example agent: summarizes text files
-agents/customer-service-agent.ts  Example agent: order lookup / refund / email
-agents/mcp-filesystem-agent.ts    Example agent: every tool comes from a real MCP server, zero hand-written
+agents/customer-service-agent.ts  Example agent: order/shipment lookup, refund, email
 agents/rag-agent.ts                Example agent: retrieves from an in-memory vector index
 adapters/cli.ts             Channel adapter: command line
 adapters/http.ts            Channel adapter: HTTP API
-skills/                     SKILL.md files discoverable by agents
+skills/                     SKILL.md files discoverable by agents, scoped per agent subdirectory
 examples/file-agent/        Sample input files + generated output for the file-agent demo
 Dockerfile, docker-compose.yml   Container build + local Redis for testing
 ```

package/dist/agent-config.d.ts

@@ -1,6 +1,5 @@
 import type { Rule, Decision, Scope, Approver } from 'actauth';
 import type { SafetyClassifier } from 'toollane';
-import type { StdioServerParameters } from '@modelcontextprotocol/sdk/client/stdio.js';
 export interface ToolSchema {
     name: string;
     description: string;
@@ -14,16 +13,8 @@ export interface AgentConfig {
     /** Also doubles as the ActAuth scope.agent segment. */
     name: string;
     systemPrompt: string;
-    /** Hand-written tools. Default []  — an agent can run on mcpServers alone. */
+    /** Hand-written tools. Default []. */
     tools?: ToolDefinition[];
-    /** MCP servers to connect at load time (see load-agent.ts); their
-     * tools are discovered via listTools() and appended to `tools`. This
-     * is what makes adding an MCP-backed agent a config change — write
-     * rules for the tool names you expect it to expose (check its docs, or
-     * probe it once), same as for a hand-written tool. Anything it exposes
-     * that you didn't write a rule for still safely falls through to
-     * defaultDecision. */
-    mcpServers?: StdioServerParameters[];
     /** ActAuth rules, e.g. { scopePattern: 'default/production/customer-service', tool: 'issue_refund', decision: 'ask' } */
     rules: Rule[];
     /** Decision when no rule matches. Default 'ask' — new tools are opt-in, not silently allowed. */
@@ -37,4 +28,13 @@ export interface AgentConfig {
     contextBudgetTokens?: number;
     /** Which tools ToolLane may run in a parallel lane. Default: none (every tool runs solo). */
     isSafeTool?: SafetyClassifier;
+    /** How adapters/http.ts derives a session key from a request body — this
+     * is business logic ("what counts as one conversation" is agent-
+     * specific: a customer, a Slack channel, a ticket, ...), not a channel-
+     * adapter concern, so it lives here rather than being hardcoded in the
+     * adapter. Return undefined to signal "this body doesn't identify a
+     * session" (the adapter responds 400). Omit entirely to use the
+     * adapter's default — a client-supplied `sessionId` field, the same
+     * shape adapters/cli.ts's --session flag already uses. */
+    sessionIdFor?: (body: Record<string, unknown>) => string | undefined;
 }

package/dist/anthropic-model-call.js

@@ -1,20 +1,35 @@
 // The one real ModelCall implementation loopengine ships. Every example
-// agent (file-agent.ts, customer-service-agent.ts, mcp-filesystem-agent.ts)
-// still uses a canned, turn-counting fake so the whole loop is runnable
-// with no API key — swap that fake for createAnthropicModelCall(...) and
-// nothing in run-agent.ts, the adapters, or any AgentConfig changes.
-// ModelCall is the only seam this needed.
+// agent (file-agent.ts, customer-service-agent.ts, rag-agent.ts) still
+// uses a canned, turn-counting fake so the whole loop is runnable with no
+// API key — swap that fake for createAnthropicModelCall(...) and nothing
+// in run-agent.ts, the adapters, or any AgentConfig changes. ModelCall is
+// the only seam this needed.
 //
-// loopengine's Message type (contextclip) is deliberately generic —
-// {role, content: string} — so conversation history round-trips to the
-// API as plain user/assistant text turns, not Anthropic's native
-// tool_use/tool_result content blocks. Claude reads
-// "[lookup_order result] {...}" as plain text just fine and the
-// conversation still works correctly, but it's not the structured,
-// block-native history the API is built around. If you need that
-// fidelity later, it means changing what run-agent.ts stores in
-// `messages`, not this file.
+// loopengine's own Message type mirrors Anthropic's native shape closely
+// on purpose: `content` is either a plain string or a ModelContentBlock[]
+// carrying real tool_use/tool_result blocks with ids, the same identity
+// Anthropic's own API expects a tool_use to be answered by a matching
+// tool_result. This file's only job is translating between that shape and
+// the SDK's own param/response types — see message-to-param below.
 import Anthropic from '@anthropic-ai/sdk';
+function toContentBlockParam(block) {
+    if (block.type === 'tool_use') {
+        return { type: 'tool_use', id: block.id, name: block.name, input: block.input ?? {} };
+    }
+    if (block.type === 'tool_result') {
+        return { type: 'tool_result', tool_use_id: block.tool_use_id, content: block.content, is_error: block.is_error };
+    }
+    // text (and anything else this file doesn't specifically construct —
+    // in practice only text/tool_use/tool_result ever end up in a Message
+    // this framework builds).
+    return { type: 'text', text: block.text ?? '' };
+}
+function toMessageParam(message) {
+    return {
+        role: message.role === 'assistant' ? 'assistant' : 'user',
+        content: typeof message.content === 'string' ? message.content : message.content.map(toContentBlockParam),
+    };
+}
 export function createAnthropicModelCall(options = {}) {
     const client = options.client ?? new Anthropic({ apiKey: options.apiKey });
     const model = options.model ?? 'claude-sonnet-5';
@@ -24,10 +39,7 @@ export function createAnthropicModelCall(options = {}) {
             model,
             max_tokens: maxTokens,
             system,
-            messages: messages.map((m) => ({
-                role: m.role === 'assistant' ? 'assistant' : 'user',
-                content: m.content,
-            })),
+            messages: messages.map(toMessageParam),
             tools: tools.length
                 ? tools.map((t) => ({
                     name: t.name,

package/dist/index.d.ts

@@ -1,13 +1,11 @@
 export { runAgent } from './run-agent.js';
-export type { ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from './run-agent.js';
+export type { Message, ModelCall, ModelContentBlock, ModelResponse, RunAgentOptions, RunAgentResult, } from './run-agent.js';
 export type { AgentConfig, ToolSchema, ToolDefinition } from './agent-config.js';
-export { loadAgent } from './load-agent.js';
-export type { LoadedAgent } from './load-agent.js';
-export { connectMcpTools } from './mcp-tools.js';
-export type { McpConnection } from './mcp-tools.js';
 export { FileSessionStore, RedisSessionStore, createSessionStore } from './session-store.js';
-export type { SessionStore, SessionResult } from './session-store.js';
+export type { SessionStore, SessionResult, RedisSessionStoreOptions } from './session-store.js';
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
 export type { Document, ScoredDocument } from './vector-index.js';
 export { createAnthropicModelCall } from './anthropic-model-call.js';
 export type { AnthropicModelCallOptions } from './anthropic-model-call.js';
+export { createOpenAIModelCall } from './openai-model-call.js';
+export type { OpenAIModelCallOptions } from './openai-model-call.js';

package/dist/index.js

@@ -4,8 +4,7 @@
 // built on top of this surface, not part of it — see the README section
 // "Using loopengine as a library" for the boundary and why.
 export { runAgent } from './run-agent.js';
-export { loadAgent } from './load-agent.js';
-export { connectMcpTools } from './mcp-tools.js';
 export { FileSessionStore, RedisSessionStore, createSessionStore } from './session-store.js';
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
 export { createAnthropicModelCall } from './anthropic-model-call.js';
+export { createOpenAIModelCall } from './openai-model-call.js';

package/dist/openai-model-call.d.ts

@@ -0,0 +1,14 @@
+import OpenAI from 'openai';
+import type { ModelCall } from './run-agent.js';
+export interface OpenAIModelCallOptions {
+    /** Defaults to the OPENAI_API_KEY env var, same as the SDK itself. */
+    apiKey?: string;
+    /** No hardcoded default, unlike Anthropic's — OpenAI's current flagship
+     * model name changes too often to bake into this file safely. Pass the
+     * one you actually want. */
+    model: string;
+    maxTokens?: number;
+    /** Inject a pre-configured client instead of building one from apiKey — e.g. to pass a custom `fetch` in tests. */
+    client?: OpenAI;
+}
+export declare function createOpenAIModelCall(options: OpenAIModelCallOptions): ModelCall;

package/dist/openai-model-call.js

@@ -0,0 +1,101 @@
+// A second real ModelCall implementation, alongside anthropic-model-call.ts
+// — same seam, different provider. Swap createOpenAIModelCall(...) in for
+// the canned fake in any agent and nothing in run-agent.ts, the adapters,
+// or any AgentConfig changes.
+//
+// Structural mismatch worth knowing: loopengine's Message bundles every
+// tool_result from one turn into a single user-role message's content
+// array (mirroring Anthropic's own shape, which this framework's Message
+// type was modeled on). OpenAI's Chat Completions API has no equivalent —
+// each tool result is its own top-level message with role: 'tool'. So
+// unlike Anthropic's 1:1 toMessageParam, toMessageParams here is plural: one
+// loopengine Message can expand into several OpenAI messages, never fewer.
+//
+// stop_reason is normalized to the vocabulary anthropic-model-call.ts
+// already established ('end_turn' / 'tool_use' / 'max_tokens') rather than
+// passed through as OpenAI's own finish_reason strings — reflowkit's
+// defaultIsTruncated checks a translated ModelResponse for stop_reason ===
+// 'max_tokens', so a provider-agnostic caller wiring up onTruncated later
+// gets the same behavior regardless of which ModelCall is plugged in.
+import OpenAI from 'openai';
+function toMessageParams(message) {
+    if (typeof message.content === 'string') {
+        return [{ role: message.role === 'assistant' ? 'assistant' : 'user', content: message.content }];
+    }
+    if (message.role === 'assistant') {
+        const text = message.content
+            .filter((block) => block.type === 'text')
+            .map((block) => block.text ?? '')
+            .join('');
+        const toolUseBlocks = message.content.filter((block) => block.type === 'tool_use');
+        return [
+            {
+                role: 'assistant',
+                // Required unless tool_calls is set — an empty string here (no
+                // text, only tool calls) is rejected by the API, so this must be
+                // null, not ''.
+                content: text || null,
+                tool_calls: toolUseBlocks.length
+                    ? toolUseBlocks.map((block) => ({
+                        id: block.id,
+                        type: 'function',
+                        function: { name: block.name, arguments: JSON.stringify(block.input ?? {}) },
+                    }))
+                    : undefined,
+            },
+        ];
+    }
+    // Every non-assistant, block-structured Message this loop ever builds is
+    // one turn's tool_result blocks bundled together (see run-agent.ts's
+    // pushMessage calls) — expand each into its own `role: 'tool'` message.
+    return message.content.map((block) => ({
+        role: 'tool',
+        tool_call_id: block.tool_use_id,
+        content: block.content ?? '',
+    }));
+}
+function toStopReason(finishReason) {
+    if (finishReason === 'tool_calls' || finishReason === 'function_call')
+        return 'tool_use';
+    if (finishReason === 'length')
+        return 'max_tokens';
+    if (finishReason === 'stop')
+        return 'end_turn';
+    return finishReason;
+}
+export function createOpenAIModelCall(options) {
+    const client = options.client ?? new OpenAI({ apiKey: options.apiKey });
+    const maxTokens = options.maxTokens ?? 4096;
+    return async (messages, system, tools) => {
+        const response = await client.chat.completions.create({
+            model: options.model,
+            max_completion_tokens: maxTokens,
+            messages: [{ role: 'system', content: system }, ...messages.flatMap(toMessageParams)],
+            tools: tools.length
+                ? tools.map((t) => ({
+                    type: 'function',
+                    function: { name: t.name, description: t.description, parameters: t.input_schema },
+                }))
+                : undefined,
+        });
+        const choice = response.choices[0];
+        const content = [];
+        if (choice.message.content)
+            content.push({ type: 'text', text: choice.message.content });
+        for (const call of choice.message.tool_calls ?? []) {
+            // A 'custom' tool call is the freeform-text tool type OpenAI added
+            // alongside 'function' — this framework's ToolDefinition only ever
+            // declares 'function'-shaped tools, so a custom call can't have come
+            // from anything this loop offered the model.
+            if (call.type !== 'function')
+                continue;
+            content.push({
+                type: 'tool_use',
+                id: call.id,
+                name: call.function.name,
+                input: JSON.parse(call.function.arguments),
+            });
+        }
+        return { stop_reason: toStopReason(choice.finish_reason), content };
+    };
+}