loopengine 0.0.4 → 0.0.7

package/README.md

@@ -32,6 +32,28 @@ one layer further out still: it's not part of the loop either, just a
 its output merges straight in with no adapter code. See "External tool
 gateways" below.
 
+## Creating a new project
+
+The fastest way to get a running agent server, in your own repo, is
+[`create-loopengine`](https://www.npmjs.com/package/create-loopengine):
+
+```bash
+npx create-loopengine@latest my-agents
+cd my-agents
+npm install
+cp .env.example .env   # fill in ANTHROPIC_API_KEY
+npm run dev             # HTTP server on :8787
+```
+
+That scaffolds a real, standalone project — its own `package.json`
+depending on `loopengine` (not a clone of this repo), an HTTP + CLI
+adapter, and one starter agent — rather than a bare library import. `npm
+install loopengine` alone (below) only gets you the library; the server,
+adapters, and a runnable example are deliberately not part of that
+package, which is the gap `create-loopengine` fills. See
+[`create-loopengine`'s own README](https://github.com/evanyan22/create-loopengine)
+for what the generated project looks like.
+
 ## Using loopengine as a library
 
 This repo is two things in one: a small library (the loop itself) and a
@@ -74,17 +96,20 @@ 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` (scans a
+directory for `config`/`createModelCall` modules and builds a name → entry
+map, keyed by `AgentConfig.name` — see `agent-registry.ts` for the ~15-line
+wrapper this repo's own adapters use), 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 +155,10 @@ 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` finds it
+automatically (by `AgentConfig.name`, not the filename) at startup.
+Nothing to edit, no import to add, no adapter change.
 
 ## Retrieval (RAG)
 
@@ -235,7 +261,7 @@ 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."}'
+  -d '{"message":"Summarize a.txt and b.txt into summary.txt."}'
 ```
 
 `customer-service` is the exception here too — a request with no
@@ -385,6 +411,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 +448,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 +493,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/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/package.json

@@ -1,9 +1,10 @@
 {
   "name": "loopengine",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "type": "module",
   "description": "A minimal framework for defining and running tool-using AI agents over CLI, HTTP, or both.",
   "license": "MIT",
+  "homepage": "https://loopengine.co",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/evanyan22/loopengine.git"
@@ -25,6 +26,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": {