loopengine 0.0.1 → 0.0.2

package/dist/run-agent.d.ts

@@ -1,16 +1,38 @@
-import { type Message } from 'contextclip';
 import type { AgentConfig, ToolSchema } from './agent-config.js';
 export interface ModelContentBlock {
     type: string;
+    /** text blocks. */
     text?: string;
+    /** tool_use blocks: this call's own id (referenced by a later tool_result). */
     id?: string;
+    /** tool_use blocks. */
     name?: string;
+    /** tool_use blocks. */
     input?: Record<string, unknown>;
+    /** tool_result blocks: id of the tool_use block this result answers. */
+    tool_use_id?: string;
+    /** tool_result blocks: the tool's output (or denial/error message). */
+    content?: string;
+    /** tool_result blocks: true if the tool call failed or was denied. */
+    is_error?: boolean;
 }
 export interface ModelResponse {
     stop_reason: string;
     content: ModelContentBlock[];
 }
+/** loopengine's own conversation-message type — a superset of
+ * ContextClip's `{role, content: string}`: `content` can also be a
+ * `ModelContentBlock[]`, the same block shape `ModelResponse.content`
+ * already used, so a model's tool_use requests and this loop's
+ * tool_result replies round-trip with real per-call identity
+ * (`tool_use_id`) instead of being flattened into prose. Plain-string
+ * content (a user's message, a skill's injected body, a synthetic
+ * compaction note) is just as valid — nothing requires every message to
+ * be block-structured. */
+export interface Message {
+    role: string;
+    content: string | ModelContentBlock[];
+}
 /** Swap the Anthropic SDK in here — this is the only seam a real API call needs. */
 export type ModelCall = (messages: Message[], system: string, tools: ToolSchema[]) => Promise<ModelResponse>;
 export interface RunAgentOptions {
@@ -24,5 +46,12 @@ export interface RunAgentResult {
      * `history` on the next call to continue the conversation. Opaque to
      * the caller: store/transmit it, don't inspect or mutate it. */
     history: Message[];
+    /** Exactly what this turn added — safe to durably append regardless of
+     * whether ContextClip recovery reshaped `history` mid-turn. A caller
+     * that persists conversations (see session-store.ts) should use this
+     * instead of diffing `history` by length against what it loaded: that
+     * only works if `history` only ever grows, which stops being true the
+     * moment recovery can shrink/rewrite it, not just extend it. */
+    newMessages: Message[];
 }
 export declare function runAgent(config: AgentConfig, modelCall: ModelCall, userMessage: string, history?: Message[], options?: RunAgentOptions): Promise<RunAgentResult>;

package/dist/run-agent.js

@@ -8,6 +8,27 @@ import { SkillGarden } from 'skillgarden';
 import { ContextClipper } from 'contextclip';
 import { ToolLane } from 'toollane';
 import { Reflow } from 'reflowkit';
+/** ContextClip only ever needs a flat string per message to estimate
+ * token usage — it doesn't need to understand tool_use/tool_result
+ * structure, so this is a one-way, read-only projection, never something
+ * that needs to be un-projected back. */
+function flattenForContextClip(message) {
+    if (typeof message.content === 'string')
+        return { role: message.role, content: message.content };
+    const text = message.content
+        .map((block) => {
+        if (block.type === 'text')
+            return block.text ?? '';
+        if (block.type === 'tool_use')
+            return `[tool_use ${block.name}(${JSON.stringify(block.input)})]`;
+        if (block.type === 'tool_result') {
+            return `[tool_result for ${block.tool_use_id}]${block.is_error ? ' ERROR' : ''}: ${block.content ?? ''}`;
+        }
+        return `[${block.type}]`;
+    })
+        .join('\n');
+    return { role: message.role, content: text };
+}
 export async function runAgent(config, modelCall, userMessage, history = [], options = {}) {
     const log = options.onEvent ?? (() => { });
     const scope = { tenant: 'default', environment: 'production', ...config.scope, agent: config.name };
@@ -15,20 +36,64 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         ? new SkillGarden({ dirs: config.skillsDirs, indexBudgetTokens: config.skillIndexBudgetTokens ?? 200 })
         : null;
     const skillIndex = skillGarden?.buildIndex().included ?? [];
-    const contextClip = new ContextClipper({ budgetTokens: config.contextBudgetTokens ?? 8000, tailMessages: 4 });
+    // Also the tail-preservation window recover() below relies on — kept as
+    // one named constant so the two can never drift out of sync.
+    const tailMessages = 4;
+    const contextClip = new ContextClipper({ budgetTokens: config.contextBudgetTokens ?? 8000, tailMessages });
     const rules = new RuleSet(config.rules, config.defaultDecision ?? 'ask');
     const gate = new Gate(rules, config.approver ?? new ConsoleApprover());
     const toolLane = new ToolLane({ isSafe: config.isSafeTool ?? (() => false) });
+    let messages = [...history, { role: 'user', content: userMessage }];
+    // Tracked in parallel with `messages`, but never rewritten wholesale by
+    // recovery the way `messages` is — this is the actual, authoritative
+    // answer to "what did this turn add," independent of how many times (if
+    // any) the head of `messages` got drained/summarized along the way. See
+    // pushMessage() below and the reconciliation inside onPromptTooLong.
+    let newMessages = [{ role: 'user', content: userMessage }];
+    function pushMessage(message) {
+        messages.push(message);
+        newMessages.push(message);
+    }
     const reflow = new Reflow({
-        onPromptTooLong: async (messages) => {
-            const result = await contextClip.recover(messages);
-            log('reflow:recover', { from: messages.length, to: result.messages.length });
-            return result.messages;
+        onPromptTooLong: async (currentMessages) => {
+            // newMessages (this turn's own content — not durably stored
+            // anywhere else yet) must never be handed to ContextClip at all.
+            // An earlier version of this reconciliation tried to recover
+            // newMessages *after* compaction by reusing whatever ContextClip's
+            // synthetic head contained — that's unsound: ContextClip's cheap
+            // "drain" stage doesn't produce a head at all, it just deletes old
+            // messages outright, trusting there's a durable copy elsewhere.
+            // That trust is only valid for the *prior* portion; only that
+            // portion is safe to compact at all.
+            const priorCount = currentMessages.length - newMessages.length;
+            const priorPortion = currentMessages.slice(0, priorCount);
+            const result = await contextClip.recover(priorPortion.map(flattenForContextClip));
+            log('reflow:recover', { from: currentMessages.length, to: result.messages.length + newMessages.length });
+            if (result.action === 'unchanged')
+                return currentMessages;
+            // Same tail-preservation reuse as before, just scoped to
+            // priorPortion alone now — newMessages is appended back whole,
+            // always, regardless of how large it's grown this turn.
+            const preservedTailCount = Math.min(tailMessages, priorPortion.length);
+            const structuredTail = priorPortion.slice(priorPortion.length - preservedTailCount);
+            const newHead = result.messages.slice(0, result.messages.length - preservedTailCount);
+            const recovered = [...newHead, ...structuredTail, ...newMessages];
+            // Reflow.call() only ever returns {value, recoveries, truncated} —
+            // it never hands back whatever `currentMessages` became after a
+            // retry, so recovery would otherwise only ever affect the one
+            // retried call. Reassigning the outer `messages` binding here (this
+            // hook is the only place that has both the recovered array and a
+            // reason to persist it) is what makes recovery durable: every
+            // subsequent contextClip.check() in this loop, and the `history`
+            // this function eventually returns, both see the compacted
+            // conversation from this point on — not the original, ever-growing
+            // one. newMessages itself needs no reconciliation at all — it was
+            // never part of what could be compacted away.
+            messages = recovered;
+            return recovered;
         },
     });
-    // Optional on AgentConfig — an MCP-only agent's tools are populated by
-    // load-agent.ts before this ever runs, but default defensively here too
-    // in case a config reaches runAgent without going through it.
+    // Optional on AgentConfig — an agent can have zero tools.
     const tools = config.tools ?? [];
     const toolsByName = new Map(tools.map((t) => [t.name, t]));
     const toolSchemas = tools.map(({ name, description, input_schema }) => ({
@@ -36,65 +101,104 @@ export async function runAgent(config, modelCall, userMessage, history = [], opt
         description,
         input_schema,
     }));
+    // The system prompt below only ever listed skill names/descriptions as
+    // prose — nothing told a real model it could actually call a tool named
+    // "Skill" to invoke one, so it never would have. One shared schema, not
+    // one per skill: the skill's own name is an *input*, exactly what keeps
+    // the tool list cheap regardless of how many skills exist — the whole
+    // point of SkillGarden's index-now-load-later design. See the
+    // toolUseBlocks loop below for where this is actually answered.
+    if (skillIndex.length) {
+        toolSchemas.push({
+            name: 'Skill',
+            description: 'Invoke one of the available skills listed in the system prompt, by name.',
+            input_schema: {
+                type: 'object',
+                properties: {
+                    skill: { type: 'string', description: 'Name of the skill to invoke, exactly as listed.' },
+                    args: {
+                        type: 'string',
+                        description: 'Optional arguments for the skill body — substituted for $ARGUMENTS/$1/$2 placeholders.',
+                    },
+                },
+                required: ['skill'],
+            },
+        });
+    }
     const systemPrompt = skillIndex.length
         ? `${config.systemPrompt}\n\nAvailable skills:\n${skillIndex.map((s) => `- ${s.name}: ${s.description}`).join('\n')}`
         : config.systemPrompt;
-    let messages = [...history, { role: 'user', content: userMessage }];
     for (;;) {
-        const budget = contextClip.check(messages);
+        const budget = contextClip.check(messages.map(flattenForContextClip));
         log('contextclip:check', budget);
         if (budget.action === 'nudge' && budget.nudge)
-            messages.push(budget.nudge);
+            pushMessage(budget.nudge);
         const { value: response, recoveries } = await reflow.call((msgs) => modelCall(msgs, systemPrompt, toolSchemas), messages);
         if (recoveries.length > 0)
             log('reflow:recoveries', recoveries);
+        // The model's full response — text and tool_use blocks alike, with
+        // real ids — becomes this turn's assistant message verbatim. Every
+        // tool_use block emitted here gets a matching tool_result pushed
+        // below before the loop continues; a real model API expects exactly
+        // that pairing on the next request, not a prose summary of it.
+        pushMessage({ role: 'assistant', content: response.content });
         const toolUseBlocks = response.content.filter((b) => b.type === 'tool_use');
         if (toolUseBlocks.length === 0) {
             const text = response.content.find((b) => b.type === 'text')?.text ?? '';
             log('loop:done', text);
-            messages.push({ role: 'assistant', content: text });
-            return { text, history: messages };
-        }
-        // Skill invocation injects instructions into context; it isn't a tool
-        // that needs ActAuth gating or ToolLane scheduling.
-        const skillCall = toolUseBlocks.find((b) => b.name === 'Skill');
-        if (skillCall && skillGarden) {
-            const body = skillGarden.invoke(skillCall.input.skill);
-            log('skillgarden:invoke', skillCall.input.skill);
-            messages.push({ role: 'assistant', content: `[called Skill: ${skillCall.input.skill}]` });
-            messages.push({ role: 'user', content: body });
-            continue;
+            return { text, history: messages, newMessages };
         }
-        const approved = [];
-        const denied = [];
-        const reasons = new Map();
+        const resultBlocks = [];
+        const approvedCalls = [];
         for (const block of toolUseBlocks) {
+            // Skill invocation injects instructions into context; it isn't a
+            // real tool call and doesn't need ActAuth gating or ToolLane
+            // scheduling — but it's still a tool_use block the model emitted,
+            // so it still needs a tool_result to answer it, same as any other.
+            if (block.name === 'Skill' && skillGarden) {
+                const body = skillGarden.invoke(block.input.skill, block.input?.args);
+                log('skillgarden:invoke', block.input.skill);
+                resultBlocks.push({ type: 'tool_result', tool_use_id: block.id, content: body });
+                continue;
+            }
             const decision = await gate.evaluate(block.name, block.input ?? {}, scope);
             log('actauth:decision', { tool: block.name, decision: decision.decision, reason: decision.reason });
             if (decision.decision === 'allow') {
-                approved.push(block);
+                approvedCalls.push({
+                    id: block.id,
+                    name: block.name,
+                    execute: () => toolsByName.get(block.name).execute(block.input ?? {}),
+                });
             }
             else {
-                denied.push(block);
-                reasons.set(block.id, decision.reason);
+                // Every requested tool gets exactly one tool_result back — a
+                // denied call is not simply dropped, or the model has no way to
+                // tell "denied" apart from "hasn't run yet" and may just
+                // re-request it forever.
+                resultBlocks.push({
+                    type: 'tool_result',
+                    tool_use_id: block.id,
+                    content: `denied: ${decision.reason}`,
+                    is_error: true,
+                });
             }
         }
-        messages.push({ role: 'assistant', content: `[requested: ${toolUseBlocks.map((b) => b.name).join(', ')}]` });
-        // Every requested tool gets exactly one result message back — a denied
-        // call is not simply dropped, or the model has no way to tell "denied"
-        // apart from "hasn't run yet" and may just re-request it forever.
-        for (const block of denied) {
-            messages.push({ role: 'user', content: `[${block.name} result] denied: ${reasons.get(block.id)}` });
-        }
-        const calls = approved.map((b) => ({
-            id: b.id,
-            name: b.name,
-            execute: () => toolsByName.get(b.name).execute(b.input ?? {}),
-        }));
-        for await (const result of toolLane.run(calls)) {
+        // result.id is the same id LaneCall.id was given above — the exact
+        // per-call identity that makes it possible to link a result back to
+        // the specific tool_use block that requested it, even when several
+        // calls ran in the same parallel lane. The old flattened-text design
+        // could only link by tool *name*, ambiguous the moment two calls to
+        // the same tool ran in one turn.
+        for await (const result of toolLane.run(approvedCalls)) {
             const summary = result.status === 'fulfilled' ? JSON.stringify(result.value) : `ERROR: ${result.error}`;
             log('toollane:result', { name: result.name, summary });
-            messages.push({ role: 'user', content: `[${result.name} result] ${summary}` });
+            resultBlocks.push({
+                type: 'tool_result',
+                tool_use_id: result.id,
+                content: summary,
+                is_error: result.status === 'rejected',
+            });
         }
+        pushMessage({ role: 'user', content: resultBlocks });
     }
 }

package/dist/session-store.d.ts

@@ -1,17 +1,36 @@
+import { Redis } from 'ioredis';
 import { type Storage } from 'sessionknit';
-import type { Message } from 'contextclip';
+import type { Message } from './run-agent.js';
 export interface SessionResult<T> {
-    history: Message[];
+    /** Exactly what this turn added — durably appended as-is, in order.
+     * This has to come from the caller explicitly (runAgent's own
+     * RunAgentResult.newMessages) rather than being inferred by diffing a
+     * returned `history` against what withSession loaded: that only works
+     * if history only ever grows, which isn't true once ContextClip
+     * recovery can shrink/rewrite it mid-turn — see RunAgentResult's own
+     * doc comment for the full reasoning. */
+    newMessages: Message[];
     result: T;
 }
 export interface SessionStore {
     /** Loads history for sessionId, runs fn exclusively — no other
      * withSession call for the same sessionId runs concurrently, in this
-     * process or (for RedisSessionStore) any other — appends the new
-     * messages fn's result adds, and resolves with fn's result. */
+     * process or (for RedisSessionStore) any other — durably appends
+     * fn's result.newMessages in order, and resolves with fn's result. */
     withSession<T>(sessionId: string, fn: (history: Message[]) => Promise<SessionResult<T>>): Promise<T>;
     close(): Promise<void>;
 }
+/** Serializes async work per key within this process. Good enough for
+ * FileSessionStore (single process); RedisSessionStore needs a real
+ * distributed lock instead since multiple server instances share it. */
+export declare class KeyedMutex {
+    private tails;
+    run<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /** Test-only: how many keys currently have an in-flight or
+     * about-to-be-cleaned-up chain — should return to 0 once all queued
+     * work across all keys has settled. */
+    size(): number;
+}
 /** Wraps a SessionKnit log behind the flat load/run/append contract
  * runAgent's callers use. Shared by both the file- and Redis-backed
  * stores below — only the Storage and the lock differ. */
@@ -29,20 +48,34 @@ declare class SessionKnitStore implements SessionStore {
 export declare class FileSessionStore extends SessionKnitStore {
     constructor(dir: string);
 }
+export interface RedisSessionStoreOptions {
+    lockTtlMs?: number;
+    lockRetryDelayMs?: number;
+    lockMaxWaitMs?: number;
+    /** Inject a pre-built client instead of connecting from redisUrl — e.g. to pass a fake in tests. */
+    client?: Redis;
+}
 /** Redis-backed store for multi-instance deployments. Locking is a
  * single-instance-Redis lock (SET NX PX + a compare-and-delete unlock
  * script) — good enough as long as session state lives in one Redis; true
  * multi-node Redlock is overkill until it doesn't. This lock is what keeps
  * two concurrent turns for the same session from interleaving appends
- * across instances — SessionKnit's own topology repair handles branching
- * *within* one resumed chain, not that. */
+ * across instances — SessionKnit's own topology repair (reattaching
+ * sibling branches within one resumed chain) is a defensive read-side
+ * repair for crash recovery, not a substitute for that. */
 export declare class RedisSessionStore extends SessionKnitStore {
+    private readonly redis;
     private readonly lockTtlMs;
     private readonly lockRetryDelayMs;
     private readonly lockMaxWaitMs;
-    private readonly redis;
-    constructor(redisUrl: string, lockTtlMs?: number, lockRetryDelayMs?: number, lockMaxWaitMs?: number);
+    constructor(redisUrl: string, options?: RedisSessionStoreOptions);
     private lockKeyFor;
+    /** True if we still (or again) hold the lock after this call — false
+     * means someone else's SET NX PX has already replaced ours. A thrown
+     * error here doesn't mean that on its own; it's treated as "try again
+     * next tick" by the caller, since a transient network blip renewing the
+     * TTL isn't proof the lock is actually gone. */
+    private renewLock;
     private withLock;
 }
 /** Picks the store from environment so adapters don't hardcode a backend:

package/dist/session-store.js

@@ -10,17 +10,22 @@
 //   - non-blocking, debounced writes instead of a full read-modify-write
 //     of the entire session on every turn
 //   - interruption detection — if the process dies between requesting
-//     tools and recording their results (run-agent.ts pushes an
-//     "[requested: ...]" message before any tool runs, then one
-//     "[... result]" message per completed tool), the next resume() sees
-//     an unresolved request and injects a note into context saying so,
-//     instead of silently resending an incomplete turn as if it were
+//     tools and recording their results (run-agent.ts pushes the
+//     assistant's tool_use blocks as one message before any tool runs,
+//     then one message bundling every tool_result once they've all
+//     settled), the next resume() sees an assistant message with an
+//     unanswered tool_use block and injects a note into context saying
+//     so, instead of silently resending an incomplete turn as if it were
 //     clean.
-// SessionKnit's own topology repair is for branches *within* one resumed
-// chain (parallel tool calls, crash recovery) — it isn't a substitute for
-// turn-level exclusivity, so this module still serializes concurrent
-// withSession calls for the same sessionId itself (KeyedMutex / a Redis
-// lock), same as before.
+// SessionKnit's own topology repair (reattaching sibling branches under a
+// shared parentId) is a defensive read-side repair for crash/corruption
+// recovery, not something normal operation exercises — run-agent.ts
+// bundles a whole turn's tool_use/tool_result blocks into one message
+// each, and withSession below appends newMessages sequentially, so a
+// turn's own appends are always a linear chain, siblings or not. It isn't
+// a substitute for turn-level exclusivity either way, so this module
+// still serializes concurrent withSession calls for the same sessionId
+// itself (KeyedMutex / a Redis lock), same as before.
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { Redis } from 'ioredis';
@@ -28,23 +33,47 @@ import { SessionKnit, FileStorage } from 'sessionknit';
 /** Serializes async work per key within this process. Good enough for
  * FileSessionStore (single process); RedisSessionStore needs a real
  * distributed lock instead since multiple server instances share it. */
-class KeyedMutex {
+export class KeyedMutex {
     tails = new Map();
     run(key, fn) {
         const prevTail = this.tails.get(key) ?? Promise.resolve();
         const result = prevTail.then(fn, fn);
-        this.tails.set(key, result.catch(() => { }));
+        const settled = result.catch(() => { });
+        this.tails.set(key, settled);
+        // Self-cleaning: once nothing is queued behind this key anymore,
+        // drop it instead of leaking one Map entry per distinct key forever.
+        // Every anonymous, auto-generated session id (see adapters/http.ts,
+        // adapters/cli.ts) creates a brand-new key that would otherwise
+        // never be visited again — an unbounded, permanent leak in a
+        // long-running process. Identity-checked against the Map's *current*
+        // value for this key, not just "did settled resolve" — a call queued
+        // behind this one already replaced the entry with its own tail by
+        // the time this fires, and deleting then would orphan that chain
+        // instead of leaving it for its own turn to clean up.
+        settled.then(() => {
+            if (this.tails.get(key) === settled)
+                this.tails.delete(key);
+        });
         return result;
     }
+    /** Test-only: how many keys currently have an in-flight or
+     * about-to-be-cleaned-up chain — should return to 0 once all queued
+     * work across all keys has settled. */
+    size() {
+        return this.tails.size;
+    }
 }
-// run-agent.ts pushes exactly one "[requested: tool_a, tool_b]" assistant
-// message before any tool executes, then one "[tool result]" user message
-// per completed tool as they finish (adapters/http.ts, adapters/cli.ts
-// never see this — it lives entirely inside the messages array runAgent
-// returns). If the process dies in that window, the request message is the
-// last thing on disk with no result behind it.
+// run-agent.ts pushes the model's full response — tool_use blocks
+// included — as one assistant message before any tool executes, then one
+// user message bundling every tool_result once they've all settled
+// (adapters/http.ts, adapters/cli.ts never see this — it lives entirely
+// inside the messages array runAgent returns). If the process dies in
+// that window, the assistant message with its unanswered tool_use
+// block(s) is the last thing on disk.
 function hasUnresolvedToolCall(message) {
-    return message.role === 'assistant' && message.content.startsWith('[requested:');
+    return (message.role === 'assistant' &&
+        Array.isArray(message.content) &&
+        message.content.some((block) => block.type === 'tool_use'));
 }
 function buildContinuation() {
     return {
@@ -67,13 +96,9 @@ class SessionKnitStore {
     async withSession(sessionId, fn) {
         return this.lock(sessionId, async () => {
             const { messages, leafId } = await this.knit.resume(sessionId);
-            const { history: nextHistory, result } = await fn(messages);
-            // Everything fn's history grew by beyond what resume() handed it —
-            // this naturally excludes the synthetic continuation message too
-            // (it's already counted in messages.length), which is exactly right:
-            // it's a resend-only hint, never meant to be durably stored.
+            const { newMessages, result } = await fn(messages);
             let parentId = leafId;
-            for (const message of nextHistory.slice(messages.length)) {
+            for (const message of newMessages) {
                 const id = randomUUID();
                 await this.knit.append(sessionId, { id, parentId, message });
                 parentId = id;
@@ -115,29 +140,41 @@ class RedisEntryStorage {
         return raw.map((line) => JSON.parse(line));
     }
 }
+const UNLOCK_IF_OWNER_SCRIPT = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`;
+const RENEW_IF_OWNER_SCRIPT = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("pexpire", KEYS[1], ARGV[2]) else return 0 end`;
 /** Redis-backed store for multi-instance deployments. Locking is a
  * single-instance-Redis lock (SET NX PX + a compare-and-delete unlock
  * script) — good enough as long as session state lives in one Redis; true
  * multi-node Redlock is overkill until it doesn't. This lock is what keeps
  * two concurrent turns for the same session from interleaving appends
- * across instances — SessionKnit's own topology repair handles branching
- * *within* one resumed chain, not that. */
+ * across instances — SessionKnit's own topology repair (reattaching
+ * sibling branches within one resumed chain) is a defensive read-side
+ * repair for crash recovery, not a substitute for that. */
 export class RedisSessionStore extends SessionKnitStore {
+    redis;
     lockTtlMs;
     lockRetryDelayMs;
     lockMaxWaitMs;
-    redis;
-    constructor(redisUrl, lockTtlMs = 30_000, lockRetryDelayMs = 50, lockMaxWaitMs = 15_000) {
-        const redis = new Redis(redisUrl);
+    constructor(redisUrl, options = {}) {
+        const redis = options.client ?? new Redis(redisUrl);
         super(new RedisEntryStorage(redis), (sessionId, fn) => this.withLock(sessionId, fn), () => redis.quit().then(() => { }));
-        this.lockTtlMs = lockTtlMs;
-        this.lockRetryDelayMs = lockRetryDelayMs;
-        this.lockMaxWaitMs = lockMaxWaitMs;
         this.redis = redis;
+        this.lockTtlMs = options.lockTtlMs ?? 30_000;
+        this.lockRetryDelayMs = options.lockRetryDelayMs ?? 50;
+        this.lockMaxWaitMs = options.lockMaxWaitMs ?? 15_000;
     }
     lockKeyFor(sessionId) {
         return `session-lock:${sessionId}`;
     }
+    /** True if we still (or again) hold the lock after this call — false
+     * means someone else's SET NX PX has already replaced ours. A thrown
+     * error here doesn't mean that on its own; it's treated as "try again
+     * next tick" by the caller, since a transient network blip renewing the
+     * TTL isn't proof the lock is actually gone. */
+    async renewLock(lockKey, token) {
+        const result = await this.redis.eval(RENEW_IF_OWNER_SCRIPT, 1, lockKey, token, this.lockTtlMs);
+        return result === 1;
+    }
     async withLock(sessionId, fn) {
         const lockKey = this.lockKeyFor(sessionId);
         const token = randomUUID();
@@ -150,14 +187,54 @@ export class RedisSessionStore extends SessionKnitStore {
                 throw new Error(`timed out waiting for lock on session '${sessionId}'`);
             await new Promise((resolve) => setTimeout(resolve, this.lockRetryDelayMs));
         }
+        // Without renewal, a turn that runs longer than lockTtlMs (a real
+        // model call plus several tool round-trips easily can) would
+        // silently lose the lock mid-flight — a second concurrent request
+        // for the same session could then acquire it and run concurrently,
+        // interleaving appends into the same durable log. Renewing at a
+        // fraction of the TTL (not waiting until right before expiry) leaves
+        // real margin for a slow renewal call itself to still land in time.
+        // Recursive setTimeout, not setInterval, so a slow renewal can never
+        // overlap with the next one — each renewal only schedules the next
+        // after the previous has settled.
+        let lockLost = false;
+        let renewTimer;
+        const scheduleRenewal = () => {
+            renewTimer = setTimeout(async () => {
+                try {
+                    if (!(await this.renewLock(lockKey, token))) {
+                        lockLost = true;
+                        return; // confirmed gone — no point scheduling further renewals
+                    }
+                }
+                catch {
+                    // Renewal call itself failed (network blip, etc.) — not proof
+                    // the lock is lost, only a confirmed token mismatch is. Try
+                    // again next tick; the TTL still bounds how long we can be
+                    // wrong about still holding it.
+                }
+                scheduleRenewal();
+            }, Math.floor(this.lockTtlMs / 3));
+        };
+        scheduleRenewal();
         try {
-            return await fn();
+            const result = await fn();
+            if (lockLost) {
+                // fn() already ran to completion — there's no way to undo or
+                // cancel work already in flight, only to make the failure loud
+                // instead of silently returning as if mutual exclusion held the
+                // whole time. Whatever this turn wrote may be interleaved with a
+                // concurrent request's writes.
+                throw new Error(`lock for session '${sessionId}' was lost mid-turn — a concurrent request may have run ` +
+                    'against the same session; this turn\'s result should not be trusted');
+            }
+            return result;
         }
         finally {
+            clearTimeout(renewTimer);
             // Only delete if we still hold it — otherwise we'd release a lock our
             // TTL already expired and a different request has since acquired.
-            const script = `if redis.call("get", KEYS[1]) == ARGV[1] then return redis.call("del", KEYS[1]) else return 0 end`;
-            await this.redis.eval(script, 1, lockKey, token);
+            await this.redis.eval(UNLOCK_IF_OWNER_SCRIPT, 1, lockKey, token);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopengine",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "description": "A minimal framework for defining and running tool-using AI agents over CLI, HTTP, or both.",
   "license": "MIT",
@@ -17,16 +17,14 @@
     "dist/run-agent.d.ts",
     "dist/agent-config.js",
     "dist/agent-config.d.ts",
-    "dist/load-agent.js",
-    "dist/load-agent.d.ts",
-    "dist/mcp-tools.js",
-    "dist/mcp-tools.d.ts",
     "dist/session-store.js",
     "dist/session-store.d.ts",
     "dist/vector-index.js",
     "dist/vector-index.d.ts",
     "dist/anthropic-model-call.js",
     "dist/anthropic-model-call.d.ts",
+    "dist/openai-model-call.js",
+    "dist/openai-model-call.d.ts",
     "LICENSE"
   ],
   "scripts": {
@@ -37,17 +35,17 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.116.0",
-    "@modelcontextprotocol/sdk": "^1.30.0",
     "actauth": "^0.0.2",
     "contextclip": "^0.0.1",
     "ioredis": "^6.0.0",
+    "mcpplug": "^0.0.1",
+    "openai": "^7.4.0",
     "reflowkit": "^0.0.1",
     "sessionknit": "^0.0.2",
-    "skillgarden": "^0.0.1",
+    "skillgarden": "^0.0.4",
     "toollane": "^0.0.1"
   },
   "devDependencies": {
-    "@modelcontextprotocol/server-filesystem": "^2026.7.10",
     "@types/node": "^26.2.0",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0",

package/dist/load-agent.d.ts

@@ -1,8 +0,0 @@
-import type { AgentConfig } from './agent-config.js';
-export interface LoadedAgent {
-    /** Same config, with tools = hand-written tools + everything discovered from mcpServers. */
-    config: AgentConfig;
-    /** Closes every MCP connection this load opened. No-op if the config had no mcpServers. */
-    close: () => Promise<void>;
-}
-export declare function loadAgent(config: AgentConfig): Promise<LoadedAgent>;