loopengine 0.0.2 → 0.0.4

package/README.md

@@ -1,5 +1,7 @@
 # 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
 it through one generic ReAct loop over the CLI, an HTTP API, or both. No
@@ -37,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'
 

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/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.2",
+  "version": "0.0.4",
   "type": "module",
   "description": "A minimal framework for defining and running tool-using AI agents over CLI, HTTP, or both.",
   "license": "MIT",