toolnexus 0.19.0 → 0.20.0

package/dist/client.js

@@ -349,7 +349,7 @@ export class Client {
         if (req.maxTokens)
             body.max_tokens = req.maxTokens;
         const signal = this.makeSignal(req.signal);
-        {
+        try {
             const data = await this.llmCallJson(`${this.opts.baseUrl.replace(/\/$/, "")}/chat/completions`, {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${key}`, ...this.opts.headers },
@@ -374,6 +374,9 @@ export class Client {
                 raw: data,
             };
         }
+        finally {
+            this.releaseSignal(signal);
+        }
     }
     /** Anthropic-style upstream: the real translation. */
     async translateAnthropic(req) {
@@ -407,7 +410,7 @@ export class Client {
         if (tc)
             body.tool_choice = tc;
         const signal = this.makeSignal(req.signal);
-        {
+        try {
             const data = await this.llmCallJson(endpoint, {
                 method: "POST",
                 headers: {
@@ -444,6 +447,9 @@ export class Client {
                 raw: data,
             };
         }
+        finally {
+            this.releaseSignal(signal);
+        }
     }
     /**
      * Renders a translate result's tool calls as an OpenAI `tool_calls` array, ready to put
@@ -508,12 +514,28 @@ export class Client {
     system(toolkit) {
         return [this.opts.systemPrompt ?? "", toolkit?.skillsPrompt() ?? ""].filter(Boolean).join("\n\n");
     }
-    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal. */
+    /** Run-scoped timeout timers, cleared by `releaseSignal` when the run settles. */
+    runTimers = new WeakMap();
+    /** Drop a run's timeout timer. Idempotent, and safe on a signal that never had one. */
+    releaseSignal(signal) {
+        const t = this.runTimers.get(signal);
+        if (t !== undefined) {
+            clearTimeout(t);
+            this.runTimers.delete(signal);
+        }
+    }
+    /** Build a run-scoped abort signal from the optional run-level timeout + an external signal.
+     *
+     * The timer is deliberately NOT `unref()`d. An unref'd timer cannot keep the event loop
+     * alive, so a run whose only pending work is a request that never settles — an injected
+     * `fetch`, an in-process transport, a stalled stream — drains the loop and the timeout never
+     * fires at all, which is the one case `timeoutMs` exists for. It is RELEASED instead: the
+     * caller clears it however the run leaves, so a finished run holds nothing open. */
     makeSignal(external) {
         const ctrl = new AbortController();
         if (this.opts.timeoutMs) {
             const t = setTimeout(() => ctrl.abort(new Error(`run timeout after ${this.opts.timeoutMs}ms`)), this.opts.timeoutMs);
-            t.unref?.();
+            this.runTimers.set(ctrl.signal, t);
         }
         if (external) {
             if (external.aborted)
@@ -612,10 +634,47 @@ export class Client {
             throw e;
         }
     }
-    // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
+    // The run-scoped timeout timer is owned by these four wrappers, so it is cleared however the
+    // run leaves: return, throw, or a consumer abandoning the stream half-way.
     async runOpenAI(prompt, toolkit, external, history) {
-        const key = resolveKey(this.opts);
         const signal = this.makeSignal(external);
+        try {
+            return await this.runOpenAIWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async runAnthropic(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            return await this.runAnthropicWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async *streamOpenAI(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            yield* this.streamOpenAIWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    async *streamAnthropic(prompt, toolkit, external, history) {
+        const signal = this.makeSignal(external);
+        try {
+            yield* this.streamAnthropicWithSignal(signal, prompt, toolkit, history);
+        }
+        finally {
+            this.releaseSignal(signal);
+        }
+    }
+    // ---- OpenAI-style: POST {baseUrl}/chat/completions ----
+    async runOpenAIWithSignal(signal, prompt, toolkit, history) {
+        const key = resolveKey(this.opts);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
         if (!messages.length) {
@@ -718,9 +777,8 @@ export class Client {
         return { result };
     }
     // ---- Anthropic-style: POST {baseUrl}/messages ----
-    async runAnthropic(prompt, toolkit, external, history) {
+    async runAnthropicWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;
         const system = this.system(toolkit);
@@ -796,9 +854,8 @@ export class Client {
         }
     }
     // ---- Streaming: OpenAI-style ----
-    async *streamOpenAI(prompt, toolkit, external, history) {
+    async *streamOpenAIWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const runStart = Date.now();
         let messages = history && history.length ? [...history] : [];
         if (!messages.length) {
@@ -906,9 +963,8 @@ export class Client {
         }
     }
     // ---- Streaming: Anthropic-style ----
-    async *streamAnthropic(prompt, toolkit, external, history) {
+    async *streamAnthropicWithSignal(signal, prompt, toolkit, history) {
         const key = resolveKey(this.opts);
-        const signal = this.makeSignal(external);
         const runStart = Date.now();
         const base = this.opts.baseUrl.replace(/\/$/, "");
         const endpoint = base.endsWith("/v1") ? `${base}/messages` : `${base}/v1/messages`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolnexus",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Dynamic MCP servers + agent skills as uniform tools for any LLM (opencode-style).",
   "type": "module",
   "main": "./dist/index.js",
@@ -17,7 +17,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/issues.test.ts",
+    "test": "npm run build && node --experimental-strip-types --test test/unit.test.ts test/agents.test.ts test/agent-hooks.test.ts test/agent-inprocess.test.ts test/home.test.ts test/compaction.test.ts test/loop.test.ts test/in-process.test.ts test/translate.test.ts test/multimodal.test.ts test/classifier.test.ts test/acp.test.ts test/issues.test.ts test/host-boundary.test.ts",
     "example": "node --experimental-strip-types examples/basic.ts",
     "example:judge": "node --experimental-strip-types examples/judge.ts",
     "example:multimodal": "node --experimental-strip-types examples/multimodal.ts"

package/src/agents/home.ts

@@ -234,9 +234,11 @@ export function startAgent(a: Agent, run: AgentRunOptions, hb: HeartbeatOptions)
         })
       }
     }
-    cancel = runtime.clock.setTimeout(beat, hb.everyMs) // self-reschedule → one live timer
+    // keepAlive:false — a heartbeat is housekeeping and must never be the reason
+    // a host process stays up.
+    cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false }) // self-reschedule → one live timer
   }
-  cancel = runtime.clock.setTimeout(beat, hb.everyMs)
+  cancel = runtime.clock.setTimeout(beat, hb.everyMs, { keepAlive: false })
 
   return {
     runtime,

package/src/agents/runtime.ts

@@ -39,16 +39,23 @@ import type { Answer, Request, Tool, ToolResult } from "../types.js"
 export interface Clock {
   /** Current time in ms (epoch or virtual). */
   now(): number
-  /** Schedule `fn` after `ms`; returns a cancel function. */
-  setTimeout(fn: () => void, ms: number): () => void
+  /** Schedule `fn` after `ms`; returns a cancel function.
+   *
+   * `keepAlive` defaults to TRUE, and the default is the important half: a timer
+   * that cannot hold the event loop open never fires when it is the only thing
+   * left to do — which is precisely a deadline whose promise nothing else will
+   * settle. Background housekeeping that should never hold a process open (a
+   * heartbeat) passes `false` explicitly. A host's own Clock may ignore the
+   * option; it then behaves as that host's timers always have. */
+  setTimeout(fn: () => void, ms: number, opts?: { keepAlive?: boolean }): () => void
 }
 
-/** The real clock (default). Timers are unref'd so they never hold the process open. */
+/** The real clock (default). See `Clock.setTimeout` for why `keepAlive` defaults to true. */
 export const systemClock: Clock = {
   now: () => Date.now(),
-  setTimeout(fn, ms) {
+  setTimeout(fn, ms, opts) {
     const t = setTimeout(fn, ms)
-    ;(t as { unref?: () => void }).unref?.()
+    if (opts?.keepAlive === false) (t as { unref?: () => void }).unref?.()
     return () => clearTimeout(t)
   },
 }