@ziggs-ai/agent-sdk 0.33.1 → 0.34.0

package/CHANGELOG.md

@@ -15,7 +15,14 @@
 ### Fixed
 
 - Hosted Claude agents can discover and invoke the access explanation tool named by their recovery instructions.
-- Shutdown stops new inbox work, acknowledges the current pass, and then releases its lease. Bounded draining includes inbox shutdown, while idle long-polls are cancelled promptly.
+- `disconnect(timeoutMs)` is bounded and resolves once the inbox host lease is
+  released: an idle long-poll is cancelled at once, a pass in flight gets up to
+  the bound to acknowledge what it finished, and a pass that outlasts the bound
+  loses the lease anyway so the next host is handed what was not acknowledged.
+  `drain()` waits on the event queue only. A pool no longer refuses to start a
+  replacement host with "retry after its current delivery completes": the
+  replacement starts once the previous host's lease is released, and
+  `shutdown(timeoutMs)` spends one budget across stopping intake and draining.
 
 - `agreement_subcontract` sends the terms the model stated. With no end date
   and no task count the server writes a standing sub-agreement, as it does

package/README.md

@@ -47,14 +47,18 @@ const agent = createAgent({
 await agent.connectAsync();
 
 // When your process shuts down:
-// agent.disconnect();
+// await agent.disconnect();
 // await agent.drain();
 ```
 
 The identity must already exist on Ziggs and the operator key must authorize it.
 `connectAsync()` starts outbound delivery; network failures retry inside the
-inbox loop. It is safe to call again while connected. `disconnect()` stops new
-polling and clears state timers; `drain()` waits for queued and active wakes.
+inbox loop. It is safe to call again while connected. `disconnect(timeoutMs)`
+stops new polling and clears state timers, lets the inbox pass in flight
+acknowledge what it finished, then releases the inbox host lease; a pass that
+outlasts the bound (30 s by default) loses the lease anyway, and the next host
+is handed what was not acknowledged. `drain()` waits for queued and active
+wakes.
 
 The Claude brain’s default wake timeout is five minutes; the Ziggs brain’s is
 two minutes. `tickTimeoutMs` overrides either. Legacy `cognition: 'fsm' |

package/dist/Agent.d.ts

@@ -256,7 +256,6 @@ export declare class Agent {
     private stateTimers;
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     private inboxLoop;
-    private inboxStopping;
     private inboxLoopEnabled;
     private started;
     private pollRunner;
@@ -419,7 +418,16 @@ export declare class Agent {
     wakeTaskAssignment(taskId: string, options?: {
         fromInbox?: boolean;
     }): Promise<void>;
-    disconnect(): Promise<void>;
+    /**
+     * Stop taking work. Timers and polls stop at once; the inbox loop cancels
+     * an idle long-poll and lets a pass already handed to this host finish and
+     * acknowledge, then releases the host lease — within `timeoutMs`. A pass
+     * that outlasts the bound does not keep the lease: it is released anyway
+     * and the next host is handed what was not acknowledged. Resolves once the
+     * lease is released either way. In-flight wakes keep running in the event
+     * queue; `drain()` is what waits for those.
+     */
+    disconnect(timeoutMs?: number): Promise<void>;
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.
      * A timeout is returned, not thrown — the caller names it (lab verdict, fleet

package/dist/Agent.js

@@ -33,7 +33,7 @@ import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient,
 import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 import { TaskService } from './platform/tasks/TaskService.js';
 import { AgreementService } from './platform/agreements/AgreementService.js';
-import { runInboxLoop } from './platform/inboxLoop.js';
+import { INBOX_STOP_TIMEOUT_MS, runInboxLoop } from './platform/inboxLoop.js';
 import { requestExactMatch } from './platform/requestMatch.js';
 import { SeenMessages } from './platform/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
@@ -219,7 +219,6 @@ export class Agent {
     stateTimers;
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     inboxLoop = null;
-    inboxStopping = null;
     inboxLoopEnabled;
     started = false;
     pollRunner;
@@ -1446,16 +1445,6 @@ export class Agent {
         return this.options.agentId || null;
     }
     async connectAsync(_timeout) {
-        if (this.started)
-            return this;
-        // Reconnecting must not race the previous loop's final lease release.
-        if (this.inboxStopping) {
-            await this.inboxStopping;
-            this.inboxStopping = null;
-        }
-        // Another reconnect may have resumed from the same retirement promise.
-        // Everything below starts synchronously, so rechecking prevents a second
-        // inbox loop from replacing the handle of the one that just started.
         if (this.started)
             return this;
         // Start the per-agent inbox long-poll loop — the agent's sole wake source.
@@ -1556,40 +1545,30 @@ export class Agent {
             chatId: sessionId,
         }, laneKey);
     }
-    disconnect() {
+    /**
+     * Stop taking work. Timers and polls stop at once; the inbox loop cancels
+     * an idle long-poll and lets a pass already handed to this host finish and
+     * acknowledge, then releases the host lease — within `timeoutMs`. A pass
+     * that outlasts the bound does not keep the lease: it is released anyway
+     * and the next host is handed what was not acknowledged. Resolves once the
+     * lease is released either way. In-flight wakes keep running in the event
+     * queue; `drain()` is what waits for those.
+     */
+    async disconnect(timeoutMs = INBOX_STOP_TIMEOUT_MS) {
         this.started = false;
         this.pollRunner?.stop();
         this.stateTimers.clearAll();
-        if (this.inboxLoop)
-            this.inboxStopping = this.inboxLoop.stop();
+        const loop = this.inboxLoop;
         this.inboxLoop = null;
-        // Draining is separately bounded by the caller. Waiting here could hang
-        // shutdown on a slow wake before that timeout even starts.
-        return Promise.resolve();
+        if (loop)
+            await loop.stop(timeoutMs);
     }
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.
      * A timeout is returned, not thrown — the caller names it (lab verdict, fleet
      * shutdown log) instead of EventQueue printing a stray warning.
      */
-    async drain(timeoutMs = 30_000) {
-        const deadline = Date.now() + Math.max(0, timeoutMs);
-        if (this.inboxStopping) {
-            let timer;
-            const stopped = await Promise.race([
-                this.inboxStopping.then(() => true),
-                new Promise((resolve) => { timer = setTimeout(() => resolve(false), Math.max(0, timeoutMs)); }),
-            ]).finally(() => clearTimeout(timer));
-            if (!stopped) {
-                const queue = await this.eventQueue.waitForIdle(0);
-                return { ...queue, idle: false, timedOut: true, timeoutMs,
-                    busyLanes: [...queue.busyLanes, { laneKey: 'inbox-shutdown', queued: 0, processing: true }] };
-            }
-            this.inboxStopping = null;
-        }
-        const result = await this.eventQueue.waitForIdle(Math.max(0, deadline - Date.now()));
-        return { ...result, timeoutMs };
-    }
+    drain(timeoutMs = 30_000) { return this.eventQueue.waitForIdle(timeoutMs); }
     registerTool(tool) { return this.toolManager.register(tool); }
     isConnected() { return this.started && (!this.inboxLoopEnabled || (this.inboxLoop?.running ?? false)); }
     /**

package/dist/platform/ConnectionPool.d.ts

@@ -17,8 +17,7 @@ export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
     private readonly hosts;
-    private readonly retiringHosts;
-    private shutdownGeneration;
+    private stopTimeoutMs;
     private readonly responseListeners;
     /**
      * Register N agent configs. Nothing connects until `connectAll()`. A config
@@ -47,12 +46,15 @@ export declare class ConnectionPool {
      * is already live and polling the same inboxes, so that window is where one
      * delivery gets handled twice: two hosts, one request, two answers.
      *
-     * `disconnect()` only stops the inbox loop and timers; in-flight ticks live in
-     * each host's event queue, which is what `drain()` waits on. So stopping
-     * intake first costs nothing that is already running.
+     * `disconnect()` stops the inbox loop and timers, lets the pass in flight
+     * acknowledge what it finished, and releases the host lease — all inside
+     * the bound; in-flight ticks live in each host's event queue, which is what
+     * `drain()` waits on. One budget covers both, so a fleet on a 120s stop
+     * clock is not asked to wait twice.
      *
      * A host that cannot finish inside `timeoutMs` is left behind rather than
-     * holding up the rest — the caller is on a shutdown clock of its own.
+     * holding up the rest — the caller is on a shutdown clock of its own. Its
+     * lease is released regardless, so the replacement can host at once.
      */
     shutdown(timeoutMs?: number): Promise<void>;
     /**

package/dist/platform/ConnectionPool.js

@@ -15,6 +15,7 @@
  */
 import { ConnectionManager } from '@ziggs-ai/api-client';
 import { createAgent } from '../Agent.js';
+import { INBOX_STOP_TIMEOUT_MS } from './inboxLoop.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 export class ConnectionPool {
     manager = new ConnectionManager();
@@ -23,12 +24,9 @@ export class ConnectionPool {
     // open/close callbacks and does not expose them, and re-reading one through
     // `startAgent` after a stop would reconnect the agent we are shutting down.
     hosts = new Map();
-    // A stopped host can still be acknowledging its last delivery. Its
-    // replacement shares this process's lease identity, so it must wait.
-    retiringHosts = new Map();
-    // Invalidate replacements already waiting on a retiring host when shutdown
-    // starts. They are not in the manager's active set yet, so stopAll misses them.
-    shutdownGeneration = 0;
+    // How long a stopping host may spend acknowledging its pass in flight before
+    // its lease is released anyway. `shutdown()` sets it to the caller's budget.
+    stopTimeoutMs = INBOX_STOP_TIMEOUT_MS;
     // Listeners enqueued by requestFrom — drained on outbound send-message effects.
     responseListeners = new Map();
     /**
@@ -51,17 +49,6 @@ export class ConnectionPool {
             }
             this.configs.set(agentId, config);
             this.manager.register(agentId, async () => {
-                const generation = this.shutdownGeneration;
-                const retiring = this.retiringHosts.get(agentId);
-                if (retiring) {
-                    const result = await retiring.drain();
-                    if (generation !== this.shutdownGeneration) {
-                        throw new Error(`Pool shut down while agent "${agentId}" was waiting for its previous host`);
-                    }
-                    if (!result.idle)
-                        throw new Error(`Agent "${agentId}" is still finishing shutdown; retry after its current delivery completes`);
-                    this.retiringHosts.delete(agentId);
-                }
                 const cfg = this.configs.get(agentId);
                 const originalTap = cfg.effectTap;
                 const pool = this;
@@ -81,8 +68,9 @@ export class ConnectionPool {
                 runtimeLog.debug('ConnectionPool', `connected "${agentId}"`);
                 return host;
             }, async (host) => {
-                this.retiringHosts.set(agentId, host);
-                await host.disconnect();
+                // Resolves once the host's lease is released, so a replacement
+                // started next cannot share the inbox with a host still acking.
+                await host.disconnect(this.stopTimeoutMs);
                 this.hosts.delete(agentId);
                 runtimeLog.debug('ConnectionPool', `disconnected "${agentId}"`);
             }, metaByAgentId.get(agentId));
@@ -126,26 +114,24 @@ export class ConnectionPool {
      * is already live and polling the same inboxes, so that window is where one
      * delivery gets handled twice: two hosts, one request, two answers.
      *
-     * `disconnect()` only stops the inbox loop and timers; in-flight ticks live in
-     * each host's event queue, which is what `drain()` waits on. So stopping
-     * intake first costs nothing that is already running.
+     * `disconnect()` stops the inbox loop and timers, lets the pass in flight
+     * acknowledge what it finished, and releases the host lease — all inside
+     * the bound; in-flight ticks live in each host's event queue, which is what
+     * `drain()` waits on. One budget covers both, so a fleet on a 120s stop
+     * clock is not asked to wait twice.
      *
      * A host that cannot finish inside `timeoutMs` is left behind rather than
-     * holding up the rest — the caller is on a shutdown clock of its own.
+     * holding up the rest — the caller is on a shutdown clock of its own. Its
+     * lease is released regardless, so the replacement can host at once.
      */
     async shutdown(timeoutMs = 30_000) {
-        this.shutdownGeneration++;
-        const hosts = [...new Set([...this.hosts.values(), ...this.retiringHosts.values()])];
+        const deadline = Date.now() + timeoutMs;
+        const hosts = [...this.hosts.values()];
+        this.stopTimeoutMs = timeoutMs;
         await this.manager.stopAll();
         await Promise.all(hosts.map(async (host) => {
             try {
-                const result = await host.drain(timeoutMs);
-                if (result?.idle) {
-                    for (const [id, retiring] of this.retiringHosts) {
-                        if (retiring === host)
-                            this.retiringHosts.delete(id);
-                    }
-                }
+                const result = await host.drain(Math.max(0, deadline - Date.now()));
                 if (result?.timedOut) {
                     runtimeLog.warn('ConnectionPool', `drain timed out after ${timeoutMs}ms: ${result.queuedEvents} event(s) queued, ${result.busyLanes.length} busy lane(s)`);
                 }

package/dist/platform/inboxLoop.d.ts

@@ -71,8 +71,16 @@ export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number,
     signal?: AbortSignal;
 }): Promise<InboxPassResult>;
 export interface InboxLoopHandle {
-    /** Stop the loop after the current pass; resolves when it has fully exited. */
-    stop(): Promise<void>;
+    /**
+     * Stop reading. An idle long-poll is cancelled at once; a pass already
+     * handed to the host runs on so it can acknowledge what it finished, and
+     * the host lease is released after that. A pass still running when
+     * `timeoutMs` is up does not hold the lease: it is released anyway, and the
+     * next host is handed whatever was not acknowledged. Resolves `true` when
+     * the pass finished inside the bound, `false` when the lease was released
+     * out from under it.
+     */
+    stop(timeoutMs?: number): Promise<boolean>;
     /** True while the loop is running. */
     readonly running: boolean;
     /**
@@ -91,6 +99,8 @@ export interface InboxLoopHandle {
 }
 /** Count held windows so retries can back off without discarding mail. */
 export declare function heldPassAfter(prev: number, pass: Pick<InboxPassResult, 'acked' | 'failures' | 'truncated'>): number;
+/** How long `stop()` waits for a pass in flight before releasing the lease anyway. */
+export declare const INBOX_STOP_TIMEOUT_MS = 30000;
 /**
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
  * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.

package/dist/platform/inboxLoop.js

@@ -390,6 +390,18 @@ function sleep(ms, signal) {
             signal?.addEventListener('abort', finish, { once: true });
     });
 }
+/** How long `stop()` waits for a pass in flight before releasing the lease anyway. */
+export const INBOX_STOP_TIMEOUT_MS = 30_000;
+/** Resolves `true` when `promise` settles within `ms`, `false` otherwise. The timer never outlives the answer. */
+function withinMs(promise, ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), Math.max(0, ms));
+        promise.then(() => true, () => true).then((settled) => {
+            clearTimeout(timer);
+            resolve(settled);
+        });
+    });
+}
 /**
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
  * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
@@ -412,6 +424,10 @@ export function runInboxLoop(deps, opts = {}) {
     let lastAttemptAt = null;
     let first = true;
     const shutdown = new AbortController();
+    // One DELETE, whichever gets there first: the loop's own exit, or a stop
+    // that ran out of patience with the pass in flight.
+    let released = null;
+    const releaseOnce = () => (released ??= releaseInboxHostBestEffort(deps));
     const main = (async () => {
         while (running) {
             try {
@@ -447,7 +463,7 @@ export function runInboxLoop(deps, opts = {}) {
             }
         }
     })();
-    const done = main.finally(() => releaseInboxHostBestEffort(deps));
+    const done = main.finally(releaseOnce);
     return {
         get running() {
             return running;
@@ -458,12 +474,17 @@ export function runInboxLoop(deps, opts = {}) {
         get lastAttemptAt() {
             return lastAttemptAt;
         },
-        async stop() {
+        async stop(timeoutMs = INBOX_STOP_TIMEOUT_MS) {
             running = false;
-            // Cancel an idle long-poll, but let work already handed to the host
-            // finish and acknowledge before releasing its lease.
+            // Cancel an idle long-poll; a pass already handed to the host keeps
+            // going so it can acknowledge what it finished before the lease goes.
             shutdown.abort();
-            await done;
+            const finished = await withinMs(done, timeoutMs);
+            if (!finished) {
+                warn(label, `inbox pass still running after ${timeoutMs}ms — releasing the host lease now; what it has not acknowledged is redelivered to the next host`);
+                await releaseOnce();
+            }
+            return finished;
         },
     };
 }

package/dist/pricing/fleetEvalFree.js

@@ -6,7 +6,6 @@ export const EVAL_HARNESS_AGENT_IDS = new Set([
     'minimal-context-agent',
     'forwarding-agent',
     'failing-agent',
-    'messaging-only-agent',
     'principal-agent',
     'capability-probe-agent',
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.32.1",
+    "@ziggs-ai/api-client": "0.33.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",