@aragon-agent/core 0.2.15 → 0.2.16

package/dist/tools/executor.d.ts

@@ -19,6 +19,20 @@ export interface ToolExecutorOptions {
     timeoutOverrides?: Record<string, number>;
     /** Maximum size (in bytes) of combined text output before truncation. Defaults to 100_000 (100 KB). */
     maxOutputSize?: number;
+    /**
+     * How long, after an abort is signalled, a tool has to settle before its
+     * promise is ABANDONED and an error result is returned in its place.
+     * Defaults to 5000.
+     *
+     * THE INVARIANT BEING PROTECTED IS "AN ABORT IS ALWAYS ANSWERABLE", AND AN
+     * INVARIANT THAT DEPENDS ON EVERY TOOL AUTHOR REMEMBERING IS NOT AN
+     * INVARIANT. Step 5 below used to be a bare `await tool.execute(...)`: the
+     * signal was delivered, the tool was free to ignore it, and the loop waited
+     * forever — so the host's "press Esc to stop" did nothing at all in exactly
+     * the situation where a user most needs it. Racing here makes the guarantee a
+     * property of the executor rather than of the toolset it happens to be given.
+     */
+    abortGraceMs?: number;
 }
 /**
  * Executes tool calls with validation, timeout management,
@@ -30,6 +44,7 @@ export declare class ToolExecutor {
     private readonly defaultTimeout;
     private readonly timeoutOverrides;
     private readonly maxOutputSize;
+    private readonly abortGraceMs;
     constructor(registry: ToolRegistry, options?: ToolExecutorOptions);
     /**
      * Execute a tool call end-to-end.

package/dist/tools/executor.js

@@ -19,6 +19,13 @@ const DEFAULT_MAX_OUTPUT_SIZE = 100_000;
 const TRUNCATION_SUFFIX = '\n... [truncated]';
 /** Sentinel symbol used to identify timeout aborts vs external aborts. */
 const TIMEOUT_REASON = Symbol('tool-timeout');
+/** Grace after an abort before a tool's promise is abandoned. */
+const DEFAULT_ABORT_GRACE_MS = 5_000;
+/**
+ * The race's losing branch. A unique object rather than a string or `null`, so
+ * it can never collide with something a tool legitimately resolves with.
+ */
+const ABANDON = Symbol('tool-abandoned');
 // ---------------------------------------------------------------------------
 // ToolExecutor
 // ---------------------------------------------------------------------------
@@ -32,11 +39,13 @@ export class ToolExecutor {
     defaultTimeout;
     timeoutOverrides;
     maxOutputSize;
+    abortGraceMs;
     constructor(registry, options = {}) {
         this.registry = registry;
         this.defaultTimeout = options.defaultTimeout ?? DEFAULT_TIMEOUT_MS;
         this.timeoutOverrides = options.timeoutOverrides ?? {};
         this.maxOutputSize = options.maxOutputSize ?? DEFAULT_MAX_OUTPUT_SIZE;
+        this.abortGraceMs = options.abortGraceMs ?? DEFAULT_ABORT_GRACE_MS;
     }
     /**
      * Execute a tool call end-to-end.
@@ -88,14 +97,67 @@ export class ToolExecutor {
             }
             signal.addEventListener('abort', externalAbortHandler, { once: true });
         }
-        // 5. Execute the tool.
+        // 5. Execute the tool, RACED AGAINST THE ABORT (+ grace).
+        //
+        // The race is the whole of the hardening: `tool.execute` may never settle —
+        // a child process whose grandchild holds the stdout pipe open is the shipped
+        // example — and without a second branch the loop waits on it forever while
+        // the user's abort has already been delivered and acted on.
+        //
+        // CLEANED UP IN A `finally`, NOT LEFT TO `{ once: true }`. The listener is
+        // one-shot, but the GRACE TIMER it arms is not: a tool that wins the race
+        // after an abort would leave a timer to fire `abortGraceMs` later, harmless
+        // today only because it is `unref`'d — a property of the timer rather than
+        // of the design. `agent-loop.ts`'s compaction race is the in-repo precedent
+        // and does exactly this.
         let result;
+        let graceTimer;
+        let onAbandonAbort;
         try {
             const context = {
                 signal: controller.signal,
                 onProgress,
             };
-            result = await tool.execute(toolCallId, validatedParams, context);
+            const abandoned = new Promise((resolveAbandon) => {
+                const arm = () => {
+                    // WRITTEN ON THE CONTEXT OBJECT THE TOOL ALREADY HOLDS, before its own
+                    // abort listener runs, so a tool can tell "the ceiling killed me" from
+                    // "the user pressed Esc" and say so in its result.
+                    context.abortCause =
+                        controller.signal.reason === TIMEOUT_REASON ? 'timeout' : 'external';
+                    graceTimer = setTimeout(() => resolveAbandon(ABANDON), this.abortGraceMs);
+                    graceTimer.unref?.();
+                };
+                if (controller.signal.aborted) {
+                    arm();
+                    return;
+                }
+                onAbandonAbort = arm;
+                controller.signal.addEventListener('abort', arm, { once: true });
+            });
+            const outcome = await Promise.race([
+                // Mapped to a VALUE on both settlements, so a rejecting tool does not
+                // reject the race itself and skip the `finally` below; the throw is
+                // re-thrown one line later into the existing catch, unchanged.
+                tool.execute(toolCallId, validatedParams, context).then((r) => r, (e) => ({ __thrown: e })),
+                abandoned,
+            ]);
+            if (outcome === ABANDON) {
+                // The orphan is DISCARDED. Its rejection is already absorbed by the
+                // `.then(onFulfilled, onRejected)` above rather than by a later
+                // `.catch()`, which is why that mapping is written as a two-argument
+                // `then` and not as `await`: a rejection arriving after we stopped
+                // listening would otherwise be an `unhandledRejection`, and in a host
+                // that routes those to a fatal handler a successfully-abandoned tool
+                // would become a process exit.
+                result = errorResult(`Tool "${toolName}" did not stop within ${this.abortGraceMs}ms of abort; abandoned.`);
+            }
+            else if (typeof outcome === 'object' && outcome !== null && '__thrown' in outcome) {
+                throw outcome.__thrown;
+            }
+            else {
+                result = outcome;
+            }
         }
         catch (err) {
             if (isAbortError(err) || controller.signal.aborted) {
@@ -111,6 +173,11 @@ export class ToolExecutor {
         }
         finally {
             clearTimeout(timeoutId);
+            if (graceTimer)
+                clearTimeout(graceTimer);
+            if (onAbandonAbort) {
+                controller.signal.removeEventListener('abort', onAbandonAbort);
+            }
             if (signal) {
                 signal.removeEventListener('abort', externalAbortHandler);
             }

package/dist/tools/types.d.ts

@@ -67,6 +67,23 @@ export interface ToolExecutionContext {
     signal?: AbortSignal;
     /** Optional callback for reporting incremental progress. */
     onProgress?: (update: ToolProgressUpdate) => void;
+    /**
+     * WHY the signal fired, set by `ToolExecutor` on THIS object at abort time,
+     * before the tool's own `abort` listener runs.
+     *
+     * The executor already distinguishes the two — its `TIMEOUT_REASON` symbol is
+     * module-private and carried on `controller.signal.reason` — but a tool cannot
+     * read it, because the symbol is not exported and must not be (the runtime
+     * export surface is frozen by `public-api.test.ts`). Publishing the CAUSE
+     * rather than the symbol keeps that surface unchanged while letting a tool
+     * write an honest footer: a command killed by the 180 s ceiling and one the
+     * user interrupted with Esc want different words, and only one of them should
+     * be advised to retry with a background launch.
+     *
+     * A FIELD ON AN EXISTING INTERFACE, so no new exported name appears. A tool
+     * that ignores it behaves exactly as it does today.
+     */
+    abortCause?: 'timeout' | 'external';
 }
 /**
  * The function signature every tool must implement.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.15",
+  "version": "0.2.16",
   "description": "AragonAgent core engine — LLM provider adapters, streaming, tool registry/execution, steering, idle watchdog, and an optional isolated-vm sandbox.",
   "license": "MIT",
   "author": "AragonAgent contributors",