@aragon-agent/core 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to `@aragon-agent/core` are documented here. Entries at
 — those releases really were published under that name, so they are left as they
 were written.
 
+## 0.3.0
+
+### Added
+
+- **`Agent.pauseIdleWatchdog()` / `Agent.resumeIdleWatchdog()`** — suspend and
+  restart the idle watchdog around a tool that blocks on a human. Both are
+  idempotent, and a paused watchdog also swallows `kick()`, so an event arriving
+  mid-wait cannot silently re-arm it. Always pair them in a `try/finally`: a
+  throw inside the wait must not leave the watchdog disarmed for the rest of the
+  run. The host is the only party that can know a person is being waited on —
+  from inside the loop that call is indistinguishable from a wedged network
+  request.
+
+- **`AgentConfig.timeouts.toolTimeoutOverrides?: Record<string, number>`** —
+  per-tool ceilings keyed by tool name, forwarded to `ToolExecutor`'s existing
+  `timeoutOverrides`. This is pure wiring of a capability the executor already
+  had and that was unreachable through `Agent`.
+
+  Read this before relying on it: `ToolExecutor` expresses a timeout by aborting
+  `context.signal` and then *continuing to await* the tool's promise — there is
+  no `Promise.race`. A tool that never observes `context.signal` is therefore
+  never timed out, and the number set here is inert for it, with no error
+  anywhere. See *Blocking on a human* in `API.md`.
+
+### Fixed
+
+- `IdleWatchdog.stop()` now clears the paused flag. Without it a run aborted
+  while paused would leave the watchdog deaf for every subsequent run, because
+  `start()` goes through `kick()` and `kick()` returns early while paused.
+
+### Notes
+
+- **No change to the export surface.** The two new members are instance methods
+  and the third is a config field, so `src/index.ts` and the `EXPECTED` list in
+  `public-api.test.ts` are untouched.
+
 ## 0.2.0
 
 ### Breaking

package/dist/engine/agent.d.ts

@@ -37,6 +37,18 @@ export interface AgentConfig {
         toolTimeout?: number;
         /** Code execution timeout (ms). Default: 30_000 (30 s). */
         codeTimeout?: number;
+        /**
+         * Per-tool ceilings keyed by tool name, overriding `toolTimeout`.
+         *
+         * READ THIS BEFORE RELYING ON IT: `ToolExecutor` expresses a timeout by
+         * calling `controller.abort(...)` on the context signal and then continuing
+         * to `await` the tool's promise — there is no `Promise.race`. A tool that
+         * never observes `context.signal` is therefore never timed out, and any
+         * number set here is inert for it. Tools that must honour a ceiling have to
+         * subscribe to `context.signal` explicitly (see `bash-tool.ts` in the CLI
+         * package for the house pattern).
+         */
+        toolTimeoutOverrides?: Record<string, number>;
     };
 }
 export interface AgentState {
@@ -110,6 +122,10 @@ export declare class Agent {
     replaceMessages(messages: Message[]): void;
     /** Clear both steering and follow-up message queues. */
     clearAllQueues(): void;
+    /** Suspend the idle watchdog (e.g. while a tool waits on a human). Idempotent. */
+    pauseIdleWatchdog(): void;
+    /** Resume the idle watchdog and restart its window from now. Idempotent. */
+    resumeIdleWatchdog(): void;
     /**
      * Emit an event to all listeners and kick the watchdog.
      * Listener errors are caught and logged to prevent crashing the loop.

package/dist/engine/agent.js

@@ -67,6 +67,9 @@ export class Agent {
         // Tool executor
         this.toolExecutor = new ToolExecutor(this.toolRegistry, {
             defaultTimeout: this.toolTimeout,
+            ...(config.timeouts?.toolTimeoutOverrides
+                ? { timeoutOverrides: config.timeouts.toolTimeoutOverrides }
+                : {}),
         });
         // Watchdog — on timeout, abort the agent
         this.watchdog = new IdleWatchdog(this.idleTimeout, () => {
@@ -192,6 +195,22 @@ export class Agent {
         this.messageQueueManager.clearAll();
     }
     // =========================================================================
+    // Idle watchdog control
+    //
+    // Public because only the HOST knows that a tool is blocked on a human. The
+    // engine sees an ordinary long-running tool call and would abort the run
+    // after `idleTimeout` — which is right for a wedged network call and wrong
+    // for a person reading a plan. Always pair these in a `try/finally`.
+    // =========================================================================
+    /** Suspend the idle watchdog (e.g. while a tool waits on a human). Idempotent. */
+    pauseIdleWatchdog() {
+        this.watchdog.pause();
+    }
+    /** Resume the idle watchdog and restart its window from now. Idempotent. */
+    resumeIdleWatchdog() {
+        this.watchdog.resume();
+    }
+    // =========================================================================
     // Internal
     // =========================================================================
     /**

package/dist/engine/watchdog.d.ts

@@ -11,12 +11,28 @@ export declare class IdleWatchdog {
     private readonly onTimeout;
     private timerId;
     private running;
+    private paused;
     constructor(timeoutMs: number, onTimeout: () => void);
     /** Reset the idle timer.  Must be called on every Agent event. */
     kick(): void;
     /** Start the watchdog.  Begins (or restarts) the idle timer. */
     start(): void;
-    /** Stop the watchdog and cancel any pending timer. */
+    /**
+     * Suspend the idle timer — e.g. while a tool blocks on a human answer.
+     * Idempotent.  A paused watchdog swallows `kick()`, so an event arriving
+     * mid-wait cannot silently re-arm it.
+     */
+    pause(): void;
+    /** Resume and restart the idle window from now.  Idempotent. */
+    resume(): void;
+    /**
+     * Stop the watchdog and cancel any pending timer.
+     *
+     * Clearing `paused` here is load-bearing: a run aborted while paused would
+     * otherwise leave the watchdog deaf for the NEXT run — `start()` calls
+     * `kick()`, and `kick()` returns early while paused — and nothing anywhere
+     * would report it.
+     */
     stop(): void;
     /** Update the timeout duration.  Takes effect on the next `kick()`. */
     setTimeout(ms: number): void;

package/dist/engine/watchdog.js

@@ -11,13 +11,14 @@ export class IdleWatchdog {
     onTimeout;
     timerId = null;
     running = false;
+    paused = false;
     constructor(timeoutMs, onTimeout) {
         this.timeoutMs = timeoutMs;
         this.onTimeout = onTimeout;
     }
     /** Reset the idle timer.  Must be called on every Agent event. */
     kick() {
-        if (!this.running)
+        if (!this.running || this.paused)
             return;
         this.clearTimer();
         this.timerId = setTimeout(() => {
@@ -29,9 +30,31 @@ export class IdleWatchdog {
         this.running = true;
         this.kick();
     }
-    /** Stop the watchdog and cancel any pending timer. */
+    /**
+     * Suspend the idle timer — e.g. while a tool blocks on a human answer.
+     * Idempotent.  A paused watchdog swallows `kick()`, so an event arriving
+     * mid-wait cannot silently re-arm it.
+     */
+    pause() {
+        this.paused = true;
+        this.clearTimer();
+    }
+    /** Resume and restart the idle window from now.  Idempotent. */
+    resume() {
+        this.paused = false;
+        this.kick();
+    }
+    /**
+     * Stop the watchdog and cancel any pending timer.
+     *
+     * Clearing `paused` here is load-bearing: a run aborted while paused would
+     * otherwise leave the watchdog deaf for the NEXT run — `start()` calls
+     * `kick()`, and `kick()` returns early while paused — and nothing anywhere
+     * would report it.
+     */
     stop() {
         this.running = false;
+        this.paused = false;
         this.clearTimer();
     }
     /** Update the timeout duration.  Takes effect on the next `kick()`. */

package/package.json

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