@aragon-agent/core 0.2.14 → 0.2.16

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/dist/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { AssistantMessage, Message, StreamEvent, TokenUsage } from './llm/types.js';
 import type { ToolResult } from './tools/types.js';
+import type { CompactionTrigger } from './engine/context-manager.js';
 export interface AgentStartEvent {
     type: 'agent_start';
 }
@@ -50,7 +51,62 @@ export interface CodeExecutionEndEvent {
     error?: string;
     duration: number;
 }
+/**
+ * Context compaction is about to run (context-auto-compaction §5.1).
+ *
+ * IT PAUSES THE IDLE WATCHDOG (`agent.ts::applyWatchdogPolicy`), because a
+ * summarization is a normal LLM call and can exceed `DEFAULT_IDLE_TIMEOUT`.
+ */
+export interface CompactionStartEvent {
+    type: 'compaction_start';
+    trigger: CompactionTrigger;
+    messageCount: number;
+}
+/**
+ * Context compaction finished, applied or not (context-auto-compaction §5.1).
+ *
+ * EMITTED FROM A `finally`, ON EVERY EXIT PATH. It is what RESUMES the watchdog,
+ * so a compaction that failed to emit its `end` would leave the run permanently
+ * deaf (P1-3).
+ */
+export interface CompactionEndEvent {
+    type: 'compaction_end';
+    applied: boolean;
+    mode: 'summarized' | 'truncated' | 'none';
+    /** Set whenever `applied` is false, and on any degraded splice. */
+    reason?: string;
+    messagesBefore: number;
+    messagesAfter: number;
+    droppedMessages: number;
+    /**
+     * Core's own `estimatePromptTokens`, BOTH SIDES — comparable by construction.
+     *
+     * A "before" from provider usage and an "after" from an estimate are two
+     * different units, and the card's headline claim ("118k -> 23k") would be
+     * comparing a measurement to a guess (§5.1).
+     */
+    estimatedTokensBefore: number;
+    estimatedTokensAfter: number;
+    /** The summary body, so the host needs no second channel to render its card. */
+    summary?: string;
+    /**
+     * Set only when the host clipped oversized `tool_result` bodies inside the
+     * RETAINED tail because the tail alone did not fit
+     * (context-auto-compaction-hardening §3.3.4 / W2).
+     *
+     * OPTIONAL, SO NO EXISTING SUBSCRIBER CHANGES. It is here rather than on
+     * `CompactionOutcome` because the engine has no use for the distinction — it
+     * validates and adopts a history like any other — while `aragon exec`'s JSON
+     * stream and the headless stderr line report a bounded, announced data loss
+     * the user is entitled to know about.
+     */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    durationMs: number;
+}
 /** Union of all events emitted by the Agent engine. */
-export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent;
+export type AgentEvent = AgentStartEvent | AgentEndEvent | TurnStartEvent | TurnEndEvent | MessageUpdateEvent | ToolExecutionStartEvent | ToolExecutionEndEvent | CodeExecutionStartEvent | CodeExecutionEndEvent | CompactionStartEvent | CompactionEndEvent;
 /** Callback signature for Agent event listeners. */
 export type AgentEventListener = (event: AgentEvent) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aragon-agent/core",
-  "version": "0.2.14",
+  "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",