loopengine 0.1.12 → 0.1.13

package/dist/core/agent-config.d.ts

@@ -1,6 +1,7 @@
 import type { Rule, Decision, Scope } from 'actauth';
 import type { Redis } from 'ioredis';
 import type { SafetyClassifier } from 'toollane';
+import type { Summarizer } from './compaction.js';
 /** Which channel a runAgent() call is on — the value RunAgentOptions.channel
  * carries, checked against directly by AgentConfig.httpNotifier's own
  * resolution (see its own doc comment for why it only ever matches
@@ -443,6 +444,21 @@ export interface AgentConfig {
     skillsDirs?: string[];
     skillIndexBudgetTokens?: number;
     contextBudgetTokens?: number;
+    /** How compaction.ts's Compactor compresses old history once a turn
+     * goes over contextBudgetTokens. Omitted entirely defaults to
+     * TruncatingSummarizer — a real, dependency-free fallback that just
+     * concatenates and cuts text, with no model call and no added latency
+     * or cost. Pass `new LLMSummarizer({ modelCall })` (llm-summarizer.js)
+     * to compact with a real model call instead — genuinely worth it for
+     * an agent whose sessions run long enough to hit compaction at all,
+     * since a fact stated once early on (an order number, an id) tends to
+     * survive a structured LLM summary but not a hard character cutoff.
+     * Not defaulted to LLMSummarizer automatically: that would add a
+     * hidden extra model call — cost, latency, and a new failure mode —
+     * to every agent, including ones that never expected compaction to do
+     * anything but this repo's own tests, which assert exact modelCall
+     * call counts. */
+    summarizer?: Summarizer;
     /** 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

package/dist/core/llm-summarizer.d.ts

@@ -0,0 +1,24 @@
+import type { Message } from './budget.js';
+import type { ModelCall } from './run-agent.js';
+import { type Summarizer } from './compaction.js';
+export interface LLMSummarizerOptions {
+    modelCall: ModelCall;
+    /** Replaces the default instructions entirely — not appended to them. */
+    systemPrompt?: string;
+}
+/** Calls modelCall with no tools and asks it to compact `messages` per
+ * DEFAULT_SYSTEM_PROMPT's own structure (see that constant's own doc
+ * comment for why "facts established" is its own named section rather
+ * than left to a generic "summarize this" prompt — a fact mentioned once
+ * early in a long conversation is exactly what a free-form summary tends
+ * to paraphrase away). Falls back to TruncatingSummarizer — rather than
+ * throwing, which would surface as a whole turn failing — if the call
+ * itself throws (rate limit, network) or comes back with no usable text
+ * (a model that only ever returns tool_use has nothing this can use). */
+export declare class LLMSummarizer implements Summarizer {
+    private readonly modelCall;
+    private readonly systemPrompt;
+    private readonly fallback;
+    constructor(options: LLMSummarizerOptions);
+    summarize(messages: Message[]): Promise<Message>;
+}

package/dist/core/llm-summarizer.js

@@ -0,0 +1,42 @@
+import { TruncatingSummarizer } from './compaction.js';
+const DEFAULT_SYSTEM_PROMPT = `You are compacting an in-progress agent conversation to free up context window. You will be given a segment of older messages (the most recent messages are kept verbatim elsewhere and are not shown to you). Write a dense summary that lets the agent continue this task without having seen the original messages.
+
+Structure your summary with these sections, using only the ones that have content:
+- Facts established: concrete values stated even once — ids, numbers, names, dates, amounts, decisions — verbatim, not paraphrased. A fact that only appears here and gets paraphrased or dropped is lost for good.
+- Actions taken: tool calls made and their outcomes, briefly.
+- Open question / next step: what's still unresolved, if anything.
+
+Output only the summary itself — no preamble, no "here is a summary".`;
+/** Calls modelCall with no tools and asks it to compact `messages` per
+ * DEFAULT_SYSTEM_PROMPT's own structure (see that constant's own doc
+ * comment for why "facts established" is its own named section rather
+ * than left to a generic "summarize this" prompt — a fact mentioned once
+ * early in a long conversation is exactly what a free-form summary tends
+ * to paraphrase away). Falls back to TruncatingSummarizer — rather than
+ * throwing, which would surface as a whole turn failing — if the call
+ * itself throws (rate limit, network) or comes back with no usable text
+ * (a model that only ever returns tool_use has nothing this can use). */
+export class LLMSummarizer {
+    modelCall;
+    systemPrompt;
+    fallback = new TruncatingSummarizer();
+    constructor(options) {
+        this.modelCall = options.modelCall;
+        this.systemPrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    }
+    async summarize(messages) {
+        const transcript = messages.map((m) => `[${m.role}] ${m.content}`).join('\n');
+        let text;
+        try {
+            const response = await this.modelCall([{ role: 'user', content: transcript }], this.systemPrompt, []);
+            text = response.content.find((block) => block.type === 'text')?.text?.trim();
+        }
+        catch {
+            // modelCall threw — fall through to the truncating fallback below,
+            // same as text staying undefined.
+        }
+        if (!text)
+            return this.fallback.summarize(messages);
+        return { role: 'system', content: `[compacted ${messages.length} earlier message(s)]\n${text}` };
+    }
+}

package/dist/core/run-agent.js

@@ -336,7 +336,12 @@ async function buildTurnContext(config, modelCall, options) {
     // 70000-token nudge point) and hardThreshold's 0.92 still leave real
     // margin before hitting it.
     const budgetTracker = new BudgetTracker({ budgetTokens: config.contextBudgetTokens ?? 100000 });
-    const compactor = new Compactor({ budgetTokens: config.contextBudgetTokens ?? 100000, softThreshold: budgetTracker.softThreshold, tailMessages });
+    const compactor = new Compactor({
+        budgetTokens: config.contextBudgetTokens ?? 100000,
+        softThreshold: budgetTracker.softThreshold,
+        tailMessages,
+        summarizer: config.summarizer,
+    });
     const rules = loadRules(config);
     // AgentConfig.httpNotifier only ever stands in for the http channel —
     // see its own doc comment for why cli/http_stream never consult it at

package/dist/index.d.ts

@@ -24,6 +24,10 @@ export { discoverAgents, loadAgentModule, synthesizeCreateModelCall } from './co
 export type { AgentModule } from './core/discover-agents.js';
 export { agentAsTool } from './core/agent-as-tool.js';
 export { resumeAgent, loadRules, loadDefaultTools, loadSubagentAsTools, systemTools, systemSkillsDir } from './core/run-agent.js';
+export { Compactor, TruncatingSummarizer } from './core/compaction.js';
+export type { Summarizer, RecoverResult, RecoverAction } from './core/compaction.js';
+export { LLMSummarizer } from './core/llm-summarizer.js';
+export type { LLMSummarizerOptions } from './core/llm-summarizer.js';
 export { createCheckpointStore } from './core/durable-approvals.js';
 export type { TurnCheckpoint, CheckpointStore, OutstandingItem } from './core/durable-approvals.js';
 export { addGatewayTool, agentDir, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';

package/dist/index.js

@@ -29,6 +29,8 @@ export { agentAsTool } from './core/agent-as-tool.js';
 // copy of adapters/http.ts (which, like agent-registry.ts, is meant to be
 // owned/edited, not imported — see this file's own header comment).
 export { resumeAgent, loadRules, loadDefaultTools, loadSubagentAsTools, systemTools, systemSkillsDir } from './core/run-agent.js';
+export { Compactor, TruncatingSummarizer } from './core/compaction.js';
+export { LLMSummarizer } from './core/llm-summarizer.js';
 export { createCheckpointStore } from './core/durable-approvals.js';
 export { addGatewayTool, agentDir, disconnectComposioAccount, describeGatewayTools, listComposioConnections, listComposioTools, loadGatewayToolsFromDir, removeGatewayTool, removeGatewayToolSlug, GatewayToolExistsError, GatewayToolNotFoundError, } from './core/gateway-tools.js';
 export { WebhookNotifier } from './core/http-notify-triggers/webhook.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "type": "module",
   "description": "Runtime for tool-using AI agents with a transparent ReAct loop.",
   "license": "MIT",
@@ -59,6 +59,8 @@
     "dist/core/budget.d.ts",
     "dist/core/compaction.js",
     "dist/core/compaction.d.ts",
+    "dist/core/llm-summarizer.js",
+    "dist/core/llm-summarizer.d.ts",
     "dist/core/recovery.js",
     "dist/core/recovery.d.ts",
     "dist/core/http-notifier.js",