loopengine 0.0.3 → 0.0.6

package/README.md

@@ -74,17 +74,18 @@ console.log(result.text)
 
 The full exported surface: `runAgent`, `AgentConfig`/`ToolSchema`/`ToolDefinition`,
 `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.
+`embed`/`cosineSimilarity` (for RAG — see below), `discoverAgents` (see
+"Auto-discovered agent registry" below), and `createAnthropicModelCall`/
+`createOpenAIModelCall`/`createDeepSeekModelCall` (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
-own, same one-line-per-agent shape), `adapters/cli.ts`/`adapters/http.ts`
-(one specific CLI/HTTP wiring choice, not imposed on every consumer), and
-the `Dockerfile`. Everything below this point describes that reference app —
-read it as a worked example of what to build with the library, not as
-library API itself.
+`agent-registry.ts` (this repo's own name → config lookup table, built on
+`discoverAgents` — build your own the same way), `adapters/cli.ts`/
+`adapters/http.ts` (one specific CLI/HTTP wiring choice, not imposed on
+every consumer), and the `Dockerfile`. Everything below this point
+describes that reference app — read it as a worked example of what to
+build with the library, not as library API itself.
 
 ## Quick start
 
@@ -130,9 +131,47 @@ export const config: AgentConfig = {
 `agents/file-agent.ts` and `agents/customer-service-agent.ts` are two complete, working
 examples — same `runAgent` loop, entirely different personas and tools.
 
-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.
+A file exporting `config` and `createModelCall` and saved into `agents/` is
+runnable through both adapters immediately — `agent-registry.ts` discovers
+it automatically (by `AgentConfig.name`, not the filename) at startup.
+Nothing to edit, no import to add, no adapter change. See "Auto-discovered
+agent registry" below for how and why.
+
+## Auto-discovered agent registry
+
+`discoverAgents(dir)` — exported from the library, used by this repo's own
+`agent-registry.ts` — scans a directory's direct files (not
+subdirectories, so shared helper code has somewhere to live without being
+mistaken for an agent) for modules exporting `config`/`createModelCall`,
+and builds a `Map<name, {config, createModelCall}>` from them:
+
+```ts
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { discoverAgents } from 'loopengine'
+
+const agentsDir = join(dirname(fileURLToPath(import.meta.url)), 'agents')
+const entries = await discoverAgents(agentsDir) // top-level await — fine in ESM
+```
+
+Keyed by `AgentConfig.name`, not the filename — that's the identity
+ActAuth's `scope.agent` segment already uses, so this doesn't introduce a
+second naming scheme, and a rename is just editing `config.name`, not also
+a registry line and an import path. Two files that declared the same
+`config.name` would already silently collide in ActAuth's rules before
+this existed; `discoverAgents` throws loudly on that (and on a file
+missing either export) at startup instead, which is a real safety
+property this adds, not just less typing.
+
+`agent-registry.ts` is a ~15-line wrapper around this: resolve `agents/`
+relative to its own file, call `discoverAgents` once at module load behind
+a top-level `await`, and expose `listAgents()`/`getEntry(name)` as
+synchronous functions from the result — ESM guarantees an importer's own
+evaluation (`adapters/http.ts`, `adapters/cli.ts`) waits for that
+top-level await to settle first, so neither adapter needs to know
+discovery is async underneath. Verified live: dropped a new agent file
+into `agents/` with zero other changes and called it immediately through
+both `adapters/cli.ts` and `adapters/http.ts`.
 
 ## Retrieval (RAG)
 
@@ -385,6 +424,18 @@ const modelCall = createOpenAIModelCall({ model: 'gpt-4.1' })
 const result = await runAgent(config, modelCall, 'order A-1001 arrived broken', [])
 ```
 
+```ts
+import { createDeepSeekModelCall } from './deepseek-model-call.js'
+
+// model is required, same reasoning as OpenAI's; reads DEEPSEEK_API_KEY
+// from the env — throws immediately, with a DeepSeek-specific message, if
+// neither that nor apiKey is set, rather than the OpenAI SDK's own
+// constructor silently accepting OPENAI_API_KEY instead.
+const modelCall = createDeepSeekModelCall({ model: 'deepseek-chat' })
+
+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.
 
@@ -410,6 +461,15 @@ 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.
 
+`deepseek-model-call.ts` reuses `openai-model-call.ts`'s translation
+verbatim (exported, not duplicated) rather than reimplementing it —
+DeepSeek's Chat Completions API is wire-compatible with OpenAI's (verified
+against DeepSeek's own docs), down to the same `tool_calls` response
+shape. The one real difference: DeepSeek documents `max_tokens`, not the
+newer `max_completion_tokens` OpenAI's endpoint expects, so only the
+request-building call site differs, not the shared message/response
+translation functions.
+
 ## Skills
 
 Agents can discover and invoke `SKILL.md` files (see `skills/`), the same
@@ -446,10 +506,12 @@ 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
 vector-index.ts             Dependency-free embeddings + cosine-similarity search, for RAG
-agent-registry.ts          Maps agent name -> {config, createModelCall}
+discover-agents.ts          discoverAgents — scans a directory, builds {name -> {config, createModelCall}}
+agent-registry.ts          This repo's ~15-line wrapper: discoverAgents('agents/') + listAgents()/getEntry()
 session-store.ts           SessionStore: FileSessionStore, RedisSessionStore, createSessionStore()
 anthropic-model-call.ts    createAnthropicModelCall — a real ModelCall this repo ships
 openai-model-call.ts        createOpenAIModelCall — same seam, OpenAI's Chat Completions API
+deepseek-model-call.ts      createDeepSeekModelCall — same seam, reuses openai-model-call.ts's translation
 agents/file-agent.ts               Example agent: summarizes text files
 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

package/dist/agent-config.d.ts

@@ -26,6 +26,14 @@ export interface AgentConfig {
     skillsDirs?: string[];
     skillIndexBudgetTokens?: number;
     contextBudgetTokens?: number;
+    /** Hard cap on model calls in one runAgent() invocation — the only thing
+     * that stops a model stuck re-requesting the same (or ping-ponging)
+     * tool calls forever, which nothing else in this loop bounds. Default
+     * 25. Hitting it ends the turn the same way running out of tools to
+     * call does — a real result, not a thrown error — with
+     * RunAgentResult.stopReason set to 'max_turns' so a caller can tell the
+     * difference from a normal finish. */
+    maxTurns?: 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

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

@@ -0,0 +1,15 @@
+import OpenAI from 'openai';
+import type { ModelCall } from './run-agent.js';
+export interface DeepSeekModelCallOptions {
+    /** Defaults to the DEEPSEEK_API_KEY env var. */
+    apiKey?: string;
+    /** No hardcoded default — same reasoning as OpenAIModelCallOptions.model:
+     * pass the one you actually want. */
+    model: string;
+    maxTokens?: number;
+    /** Defaults to DeepSeek's own API — override to point at a proxy/mirror. */
+    baseURL?: string;
+    /** Inject a pre-configured client instead of building one from apiKey/baseURL — e.g. to pass a custom `fetch` in tests. */
+    client?: OpenAI;
+}
+export declare function createDeepSeekModelCall(options: DeepSeekModelCallOptions): ModelCall;

package/dist/deepseek-model-call.js

@@ -0,0 +1,53 @@
+// A third real ModelCall implementation. DeepSeek's Chat Completions API
+// is wire-compatible with OpenAI's — confirmed against DeepSeek's own docs
+// (api-docs.deepseek.com/api/create-chat-completion/): same messages/
+// tools/tool_choice request shape, same tool_calls response shape — so
+// this reuses openai-model-call.ts's message/response translation
+// verbatim via the real `openai` SDK client, just pointed at DeepSeek's
+// base URL, rather than duplicating that logic.
+//
+// The one real difference: DeepSeek's docs list `max_tokens` as the
+// token-limit field, not the newer `max_completion_tokens`
+// openai-model-call.ts uses (OpenAI deprecated max_tokens in favor of
+// max_completion_tokens; DeepSeek's endpoint doesn't document the newer
+// field at all) — decided at the request-building call site below, since
+// toMessageParams/toModelResponse don't touch that field either way.
+import OpenAI from 'openai';
+import { toMessageParams, toModelResponse } from './openai-model-call.js';
+export function createDeepSeekModelCall(options) {
+    if (!options.client && !options.apiKey && !process.env.DEEPSEEK_API_KEY) {
+        // Fails here, with a DeepSeek-specific message, rather than letting
+        // the OpenAI SDK's own constructor validation reject it — that error
+        // says "set OPENAI_API_KEY", which would send someone who never
+        // touched that variable chasing the wrong fix.
+        throw new Error('createDeepSeekModelCall: no apiKey given and DEEPSEEK_API_KEY is not set.');
+    }
+    const client = options.client ??
+        new OpenAI({
+            // Explicitly null, not undefined, if neither is set — the OpenAI
+            // SDK's own constructor falls back to reading OPENAI_API_KEY itself
+            // when apiKey is undefined (its normal, correct behavior for
+            // createOpenAIModelCall), which here would silently authenticate
+            // against DeepSeek with an OpenAI key if one happens to be set. The
+            // guard above already rules out reaching here with no key at all,
+            // but null (not undefined) is kept regardless so this line is
+            // correct on its own, not just because of the guard before it.
+            apiKey: options.apiKey ?? process.env.DEEPSEEK_API_KEY ?? null,
+            baseURL: options.baseURL ?? 'https://api.deepseek.com',
+        });
+    const maxTokens = options.maxTokens ?? 4096;
+    return async (messages, system, tools) => {
+        const response = await client.chat.completions.create({
+            model: options.model,
+            max_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,
+        });
+        return toModelResponse(response.choices[0]);
+    };
+}

package/dist/discover-agents.d.ts

@@ -0,0 +1,16 @@
+import type { AgentConfig } from './agent-config.js';
+import type { ModelCall } from './run-agent.js';
+export interface AgentModule {
+    config: AgentConfig;
+    /** Factory, not a shared instance — a fresh ModelCall per request/session. */
+    createModelCall: () => ModelCall;
+}
+/** Scans `dir`'s direct files only (not subdirectories — put shared,
+ * non-agent code in a subdirectory to keep it out of discovery, no
+ * separate exclude-list mechanism needed) for `.ts`/`.js` modules, each
+ * expected to export `config` and `createModelCall` — the same shape
+ * every agents/*.ts file in this repo's own reference app already
+ * exports. Throws, rather than skipping, on a file that doesn't match
+ * that shape or a duplicate AgentConfig.name — both are almost always a
+ * bug in the agent file, not something to silently ignore. */
+export declare function discoverAgents(dir: string): Promise<Map<string, AgentModule>>;

package/dist/discover-agents.js

@@ -0,0 +1,48 @@
+// Scans a directory for agent modules and builds a name -> module map from
+// it — the thing that makes "drop a new file in agents/" enough to
+// register an agent, no hand-written import-and-add-one-line edit needed
+// anywhere else. See agent-registry.ts for the one place this repo's own
+// reference app actually calls it.
+//
+// Keyed by AgentConfig.name, not the filename — that's the same identity
+// ActAuth's scope.agent segment already uses (see AgentConfig.name's own
+// doc comment), so this doesn't introduce a second naming scheme. Two
+// files that happened to declare the same config.name would already
+// silently collide in ActAuth's rules today regardless of this helper;
+// surfacing that collision loudly here, at discovery time, is a real
+// safety property this adds, not just convenience.
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+function isAgentModule(mod) {
+    return (typeof mod === 'object' &&
+        mod !== null &&
+        'config' in mod &&
+        'createModelCall' in mod &&
+        typeof mod.createModelCall === 'function');
+}
+/** Scans `dir`'s direct files only (not subdirectories — put shared,
+ * non-agent code in a subdirectory to keep it out of discovery, no
+ * separate exclude-list mechanism needed) for `.ts`/`.js` modules, each
+ * expected to export `config` and `createModelCall` — the same shape
+ * every agents/*.ts file in this repo's own reference app already
+ * exports. Throws, rather than skipping, on a file that doesn't match
+ * that shape or a duplicate AgentConfig.name — both are almost always a
+ * bug in the agent file, not something to silently ignore. */
+export async function discoverAgents(dir) {
+    const entries = new Map();
+    const files = readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile() && /\.(ts|js)$/.test(entry.name) && !entry.name.endsWith('.d.ts'));
+    for (const file of files) {
+        const modulePath = resolve(dir, file.name);
+        const mod = await import(pathToFileURL(modulePath).href);
+        if (!isAgentModule(mod)) {
+            throw new Error(`${file.name} in ${dir} does not export both 'config' and 'createModelCall' — every agent module must.`);
+        }
+        const name = mod.config.name;
+        if (entries.has(name)) {
+            throw new Error(`Duplicate agent name '${name}' — ${file.name} in ${dir} isn't the first file to declare AgentConfig.name '${name}'.`);
+        }
+        entries.set(name, mod);
+    }
+    return entries;
+}

package/dist/index.d.ts

@@ -9,3 +9,7 @@ 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';
+export { createDeepSeekModelCall } from './deepseek-model-call.js';
+export type { DeepSeekModelCallOptions } from './deepseek-model-call.js';
+export { discoverAgents } from './discover-agents.js';
+export type { AgentModule } from './discover-agents.js';

package/dist/index.js

@@ -8,3 +8,5 @@ export { FileSessionStore, RedisSessionStore, createSessionStore } from './sessi
 export { VectorIndex, embed, cosineSimilarity } from './vector-index.js';
 export { createAnthropicModelCall } from './anthropic-model-call.js';
 export { createOpenAIModelCall } from './openai-model-call.js';
+export { createDeepSeekModelCall } from './deepseek-model-call.js';
+export { discoverAgents } from './discover-agents.js';

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

@@ -1,5 +1,6 @@
 import OpenAI from 'openai';
-import type { ModelCall } from './run-agent.js';
+import type { Message, ModelCall, ModelResponse } from './run-agent.js';
+type ChatMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
 export interface OpenAIModelCallOptions {
     /** Defaults to the OPENAI_API_KEY env var, same as the SDK itself. */
     apiKey?: string;
@@ -11,4 +12,8 @@ export interface OpenAIModelCallOptions {
     /** 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 toMessageParams(message: Message): ChatMessage[];
+export declare function toStopReason(finishReason: string): string;
+export declare function toModelResponse(choice: OpenAI.Chat.Completions.ChatCompletion.Choice): ModelResponse;
 export declare function createOpenAIModelCall(options: OpenAIModelCallOptions): ModelCall;
+export {};

package/dist/openai-model-call.js

@@ -17,8 +17,15 @@
 // 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.
+//
+// toMessageParams/toStopReason/toModelResponse are exported for
+// deepseek-model-call.ts to reuse verbatim — DeepSeek's Chat Completions
+// API is wire-compatible with this same request/response shape (confirmed
+// against DeepSeek's own docs), the one real difference being the token-
+// limit field name, which is only decided at the request-building call
+// site below, not in these shared translation functions.
 import OpenAI from 'openai';
-function toMessageParams(message) {
+export function toMessageParams(message) {
     if (typeof message.content === 'string') {
         return [{ role: message.role === 'assistant' ? 'assistant' : 'user', content: message.content }];
     }
@@ -54,7 +61,7 @@ function toMessageParams(message) {
         content: block.content ?? '',
     }));
 }
-function toStopReason(finishReason) {
+export function toStopReason(finishReason) {
     if (finishReason === 'tool_calls' || finishReason === 'function_call')
         return 'tool_use';
     if (finishReason === 'length')
@@ -63,6 +70,26 @@ function toStopReason(finishReason) {
         return 'end_turn';
     return finishReason;
 }
+export function toModelResponse(choice) {
+    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 };
+}
 export function createOpenAIModelCall(options) {
     const client = options.client ?? new OpenAI({ apiKey: options.apiKey });
     const maxTokens = options.maxTokens ?? 4096;
@@ -78,24 +105,6 @@ export function createOpenAIModelCall(options) {
                 }))
                 : 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 };
+        return toModelResponse(response.choices[0]);
     };
 }

package/dist/run-agent.d.ts

@@ -53,5 +53,10 @@ export interface RunAgentResult {
      * only works if `history` only ever grows, which stops being true the
      * moment recovery can shrink/rewrite it, not just extend it. */
     newMessages: Message[];
+    /** Set to 'max_turns' if the loop stopped because it hit
+     * config.maxTurns, not because the model produced a final answer with
+     * no more tool_use blocks — `text` in that case is a synthetic notice,
+     * not something the model said. Absent on a normal finish. */
+    stopReason?: 'max_turns';
 }
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;

package/dist/run-agent.js

@@ -128,7 +128,19 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
     const systemPrompt = skillIndex.length
         ? `${config.systemPrompt}\n\nAvailable skills:\n${skillIndex.map((s) => `- ${s.name}: ${s.description}`).join('\n')}`
         : config.systemPrompt;
+    // Nothing else in this loop bounds a model stuck re-requesting the same
+    // (or ping-ponging) tool calls forever — checked before spending a model
+    // call on the (maxTurns + 1)-th turn, not after.
+    const maxTurns = config.maxTurns ?? 25;
+    let turn = 0;
     for (;;) {
+        turn++;
+        if (turn > maxTurns) {
+            const text = `Stopped after ${maxTurns} turns without a final answer — the agent may be stuck in a loop.`;
+            pushMessage({ role: 'assistant', content: text });
+            log('loop:max_turns', { maxTurns });
+            return { text, history: messages, newMessages, stopReason: 'max_turns' };
+        }
         const budget = contextClip.check(messages.map(flattenForContextClip));
         log('contextclip:check', budget);
         if (budget.action === 'nudge' && budget.nudge)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.3",
+  "version": "0.0.6",
   "type": "module",
   "description": "A minimal framework for defining and running tool-using AI agents over CLI, HTTP, or both.",
   "license": "MIT",
@@ -25,6 +25,10 @@
     "dist/anthropic-model-call.d.ts",
     "dist/openai-model-call.js",
     "dist/openai-model-call.d.ts",
+    "dist/deepseek-model-call.js",
+    "dist/deepseek-model-call.d.ts",
+    "dist/discover-agents.js",
+    "dist/discover-agents.d.ts",
     "LICENSE"
   ],
   "scripts": {