loopengine 0.1.12 → 0.1.14

package/dist/bin/package-manager.d.ts

@@ -29,6 +29,14 @@ export interface PackageManifest {
  * same role .create-loopengine.json already plays for template files. */
 export interface InstalledPackageRecord {
     version: string;
+    /** The exact spec (bare registry name, "name@version", a git+ssh/
+     * git+https URL with a #committish, a file: path, ...) last used to
+     * successfully install or upgrade this package — see
+     * oldContentSpec's own doc comment for why upgradePackage needs this
+     * stored verbatim rather than reconstructed from `packageName`.
+     * Optional only because a package installed before this field existed
+     * has no recorded value — see oldContentSpec's own fallback. */
+    spec?: string;
     tools: string[];
     skills: string[];
     actauthRules: string[];
@@ -99,14 +107,14 @@ export interface UpgradeFileResult {
  * to `packageName`, i.e. "latest") currently resolves to. Tool and skill
  * files get a real three-way merge (mine = current file, possibly
  * hand-edited since install; base = the version recorded at
- * install/last-upgrade, refetched via `<spec>@<oldVersion>`; theirs =
- * newly fetched) — identical technique to `create-loopengine upgrade`,
- * just applied to package-managed files instead of template files.
- * actauth rules upgrade per-rule instead: the target actauth.yml holds
- * rules from other packages and hand-written ones too, so there's no
- * coherent "whole file" base/theirs to merge — a rule unchanged since
- * install updates cleanly; a hand-edited one is left alone and reported
- * as a conflict rather than overwritten. */
+ * install/last-upgrade, refetched via oldContentSpec; theirs = newly
+ * fetched) — identical technique to `create-loopengine upgrade`, just
+ * applied to package-managed files instead of template files. actauth
+ * rules upgrade per-rule instead: the target actauth.yml holds rules
+ * from other packages and hand-written ones too, so there's no coherent
+ * "whole file" base/theirs to merge — a rule unchanged since install
+ * updates cleanly; a hand-edited one is left alone and reported as a
+ * conflict rather than overwritten. */
 export declare function upgradePackage(agentName: string, packageName: string, options?: FetchOptions & {
     spec?: string;
 }): Promise<{

package/dist/bin/package-manager.js

@@ -283,6 +283,7 @@ export async function installPackage(agentName, spec, options = {}) {
     }
     provenance[manifest.name] = {
         version: manifest.version,
+        spec,
         tools: toolNames,
         skills: skillIds,
         actauthRules: rules.map((r) => r.name),
@@ -321,18 +322,53 @@ function mergeFile(mine, base, theirs) {
     rmSync(scratchDir, { recursive: true, force: true });
     return { merged, conflicted };
 }
+// A git+ssh/git+https/git: URL, a plain https: tarball URL, or a local
+// file:/relative/absolute path all already pin to exact, immutable
+// content on their own (a #committish, or the file/tarball's own
+// content) — appending "@version" to one of these doesn't select an
+// older version the way it does for a registry specifier, it corrupts
+// the spec. Confirmed live: `npm pack 'git+file://...#v1.0.0@1.0.0'`
+// fails outright ("The git reference could not be found... pathspec
+// 'v1.0.0@1.0.0'"), it doesn't fall back to resolving just the tag.
+const PINNED_SPEC = /^(git\+|git:|https?:|file:|\.\.?\/|\/)/;
+/** What to fetch to reconstruct the exact content that was installed or
+ * last upgraded to, for use as the three-way merge's `base` — as
+ * distinct from `spec`, which is what the *new* content resolves to.
+ * A plain registry specifier (bare or scoped name, with or without its
+ * own "@version") is repinned to `version` — the manifest's own
+ * declared version at that install/upgrade, which is what actually got
+ * written to disk, regardless of whether the range originally given
+ * would still resolve there today. A git/file/URL spec is returned
+ * as-is — see PINNED_SPEC's own doc comment for why appending "@version"
+ * to one of those breaks instead of pinning. `recordedSpec` is only
+ * absent for a package installed before InstalledPackageRecord.spec
+ * existed; falling back to `packageName` there reproduces this
+ * function's own old (buggy for a git/file install) behavior exactly —
+ * no worse than before, and only for a package that hasn't upgraded
+ * since. */
+function oldContentSpec(recordedSpec, packageName, version) {
+    const base = recordedSpec ?? packageName;
+    if (PINNED_SPEC.test(base))
+        return base;
+    // Strip any version/tag the spec already carries (a scoped name's own
+    // leading '@' isn't this — only a second '@' after the name is) before
+    // repinning, so re-upgrading an already-version-pinned install doesn't
+    // produce a doubled-up "name@1.0.0@1.0.0".
+    const bareName = base.startsWith('@') ? `@${base.slice(1).split('@')[0]}` : base.split('@')[0];
+    return `${bareName}@${version}`;
+}
 /** Upgrades an already-installed package to whatever `spec` (defaulting
  * to `packageName`, i.e. "latest") currently resolves to. Tool and skill
  * files get a real three-way merge (mine = current file, possibly
  * hand-edited since install; base = the version recorded at
- * install/last-upgrade, refetched via `<spec>@<oldVersion>`; theirs =
- * newly fetched) — identical technique to `create-loopengine upgrade`,
- * just applied to package-managed files instead of template files.
- * actauth rules upgrade per-rule instead: the target actauth.yml holds
- * rules from other packages and hand-written ones too, so there's no
- * coherent "whole file" base/theirs to merge — a rule unchanged since
- * install updates cleanly; a hand-edited one is left alone and reported
- * as a conflict rather than overwritten. */
+ * install/last-upgrade, refetched via oldContentSpec; theirs = newly
+ * fetched) — identical technique to `create-loopengine upgrade`, just
+ * applied to package-managed files instead of template files. actauth
+ * rules upgrade per-rule instead: the target actauth.yml holds rules
+ * from other packages and hand-written ones too, so there's no coherent
+ * "whole file" base/theirs to merge — a rule unchanged since install
+ * updates cleanly; a hand-edited one is left alone and reported as a
+ * conflict rather than overwritten. */
 export async function upgradePackage(agentName, packageName, options = {}) {
     const fetch = options.fetchPackageDir ?? fetchPackageDir;
     const provenance = readProvenance(agentName);
@@ -341,7 +377,7 @@ export async function upgradePackage(agentName, packageName, options = {}) {
         throw new PackageNotInstalledError(`Package '${packageName}' isn't installed for '${agentName}'.`);
     }
     const spec = options.spec ?? packageName;
-    const oldDir = fetch(`${spec}@${record.version}`);
+    const oldDir = fetch(oldContentSpec(record.spec, packageName, record.version));
     const newDir = fetch(spec);
     const oldManifest = readManifest(oldDir);
     const newManifest = readManifest(newDir);
@@ -416,7 +452,7 @@ export async function upgradePackage(agentName, packageName, options = {}) {
         updateActauthRule(agentName, ruleName, { scope: newRule.scope, tool: newRule.tool, decision: newRule.decision });
         results.push({ path, status: 'updated' });
     }
-    provenance[packageName] = { ...record, version: newManifest.version, contentHashes: newContentHashes, env: newManifest.env ?? record.env };
+    provenance[packageName] = { ...record, version: newManifest.version, spec, contentHashes: newContentHashes, env: newManifest.env ?? record.env };
     writeProvenance(agentName, provenance);
     return { files: results };
 }

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.14",
   "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",