@ziggs-ai/agent-sdk 0.33.0 → 0.33.2

package/CHANGELOG.md

@@ -12,6 +12,30 @@
 
 ## Unreleased
 
+### Fixed
+
+- Hosted Claude agents can discover and invoke the access explanation tool named by their recovery instructions.
+- `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
+  over MCP; the SDK used to turn that into one count-bound task, and to reuse
+  an open sub-agreement for the same worker instead of creating one.
+- The backend address is read one way across the SDK: explicit config, then
+  `ZIGGS_BACKEND_URL`, then `BACKEND_URL`, then what `configureApiClient` set.
+  `createMcpAgent`'s per-user connect request no longer falls back to
+  `http://localhost:3000` when only `configureApiClient` is set.
+- A tool (mechanical) state whose tool throws, with no transition for the
+  error, now returns the agent to its initial state, as a thinking state
+  already did. `validateWorkflow` warns a tool state with no error transition.
+
 ### Added
 
 - The Claude brain asks the backend's wake gate before spending a turn on chat

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

@@ -418,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

@@ -12,7 +12,7 @@ import { applyBrainToAgentOptions, isClaudeCognition, } from './brain/index.js';
 import { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
 import { resolveClaudeModel } from './brain/claudeCognition.js';
 import { CHAT_TOOLS } from './platform/tools/tier2/chatTools.js';
-import { contextReadTool, openTool } from './platform/tools/tier2/contextTools.js';
+import { contextReadTool, openTool, accessExplainTool } from './platform/tools/tier2/contextTools.js';
 import { hostedModelTools } from './brain/hostedToolSurface.js';
 import { EventQueue } from './platform/EventQueue.js';
 import { StateTimers } from './platform/StateTimers.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';
@@ -99,12 +99,13 @@ function createToolManager(options) {
     // model reaches it through tool_write; an agent that can be handed a task
     // with a check-back rule but cannot arm a wake would have to busy-wait, and
     // there is nothing to busy-wait with.
-    // open / context_read are the hosted twins of the MCP everyday set. Skip
+    // open / context_read are the hosted twins of the MCP everyday set.
+    // access_explain must also be available for protocol and artifact recovery calls. Skip
     // them when the agent already brought the same tools, so the shadow warning
     // does not fire on a duplicate registration.
     const ownNames = new Set(ownTools.map((t) => toolName(t)));
     const everydayContext = isClaudeCognition(options.cognition)
-        ? [contextReadTool, openTool].filter((t) => !ownNames.has(toolName(t)))
+        ? [contextReadTool, openTool, accessExplainTool].filter((t) => !ownNames.has(toolName(t)))
         : [];
     const platformTools = [...taskTools, ...CHAT_TOOLS, ...browseTools, ...claudeSdkTools, ...everydayContext, ...WAKE_TOOLS];
     warnOnShadowedPlatformTools(platformTools, ownTools, options.agentId);
@@ -1544,13 +1545,23 @@ 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();
-        const stopping = this.inboxLoop?.stop() ?? Promise.resolve();
+        const loop = this.inboxLoop;
         this.inboxLoop = null;
-        return stopping;
+        if (loop)
+            await loop.stop(timeoutMs);
     }
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.

package/dist/mcp/createMcpAgent.js

@@ -2,7 +2,8 @@ import { resolveWebAppOrigin, connectionsSettingsAppUrl, laneHeader } from '@zig
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
-import { ConnectionsClient, getBackendUrl } from '@ziggs-ai/api-client';
+import { ConnectionsClient } from '@ziggs-ai/api-client';
+import { resolveBackendUrl } from '../shared/backendUrl.js';
 import { createAgent } from '../Agent.js';
 import { laneFromToolContext } from '../tools/toolCreds.js';
 import { thinkingDefaults } from '../runtime/defaults.js';
@@ -58,15 +59,7 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     if (!agentId) {
         throw new Error('ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)');
     }
-    // Explicit overrides still win, but the LAST resort is `getBackendUrl()` —
-    // the resolution every other SDK call uses — not `localhost:3000`. A deployment
-    // that sets none of BACKEND_URL / ZIGGS_BACKEND_URL would otherwise have every
-    // gateway call silently point at localhost inside its own container: the
-    // requests never reach the backend, and the agent reports it as unreachable.
-    const baseUrl = (config.baseUrl ||
-        process.env.ZIGGS_BACKEND_URL ||
-        process.env.BACKEND_URL ||
-        getBackendUrl()).replace(/\/$/, '');
+    const baseUrl = resolveBackendUrl(config.baseUrl);
     return {
         url: new URL(`${baseUrl}/connections/${encodeURIComponent(config.connectionId)}/mcp`),
         headers: {
@@ -92,15 +85,7 @@ export function resolvePerUserGatewayTarget(config, agentId, userId, onBehalfOfA
     if (!operatorKey) {
         throw new Error('ziggs-per-user MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
     }
-    // Explicit overrides still win, but the LAST resort is `getBackendUrl()` —
-    // the resolution every other SDK call uses — not `localhost:3000`. A deployment
-    // that sets none of BACKEND_URL / ZIGGS_BACKEND_URL would otherwise have every
-    // gateway call silently point at localhost inside its own container: the
-    // requests never reach the backend, and the agent reports it as unreachable.
-    const baseUrl = (config.baseUrl ||
-        process.env.ZIGGS_BACKEND_URL ||
-        process.env.BACKEND_URL ||
-        getBackendUrl()).replace(/\/$/, '');
+    const baseUrl = resolveBackendUrl(config.baseUrl);
     return {
         url: new URL(`${baseUrl}/connections/mcp/relay`),
         headers: {
@@ -384,10 +369,7 @@ export async function createMcpAgent(options) {
         // request targeting THEM (X-On-Behalf-Of-User) so the consent prompt lands
         // in their inbox. The backend dedups pending requests, so retrying every
         // turn is safe.
-        const backendBase = (transportConfig.baseUrl ||
-            process.env.BACKEND_URL ||
-            process.env.ZIGGS_BACKEND_URL ||
-            'http://localhost:3000').replace(/\/$/, '');
+        const backendBase = resolveBackendUrl(transportConfig.baseUrl);
         // App URL for the user-facing connect link: api.ziggsai.com → ziggsai.com.
         const appUrl = resolveWebAppOrigin(undefined, backendBase);
         const serverLabel = transportConfig.serverUrl

package/dist/platform/ConnectionPool.d.ts

@@ -17,6 +17,7 @@ export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
     private readonly hosts;
+    private stopTimeoutMs;
     private readonly responseListeners;
     /**
      * Register N agent configs. Nothing connects until `connectAll()`. A config
@@ -45,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,6 +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();
+    // 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();
     /**
@@ -64,7 +68,9 @@ export class ConnectionPool {
                 runtimeLog.debug('ConnectionPool', `connected "${agentId}"`);
                 return host;
             }, async (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));
@@ -108,19 +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) {
+        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);
+                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

@@ -66,12 +66,21 @@ export declare function chatsInWakeOrder(chats: InboxChatNews[]): InboxChatNews[
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, _opts?: {
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, opts?: {
     forceAck?: boolean;
+    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;
     /**
@@ -90,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

@@ -130,11 +130,17 @@ async function deliverMessagesForChat(deps, news, refs, reader, attempt, handled
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export async function pollInboxOnce(deps, waitSeconds = 0, _opts = {}) {
+export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const inbox = inboxClient(deps);
     const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
-    const envelope = await inbox.getInbox(waitSeconds > 0 ? { waitSeconds } : {});
+    const envelope = await inbox.getInbox({
+        ...(waitSeconds > 0 ? { waitSeconds } : {}),
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    // A response may race shutdown. Do not enqueue another wake after stopping;
+    // an already-running pass keeps its lease through its final acknowledgement.
+    opts.signal?.throwIfAborted();
     let messagesDelivered = 0;
     let resourceEvents = 0;
     let tasksDelivered = 0;
@@ -370,8 +376,31 @@ const ERROR_BACKOFF_MAX_MS = 30_000;
 export function heldPassAfter(prev, pass) {
     return !pass.acked && (pass.failures > 0 || pass.truncated) ? prev + 1 : 0;
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const finish = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, ms);
+        if (signal?.aborted)
+            finish();
+        else
+            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
@@ -394,17 +423,22 @@ export function runInboxLoop(deps, opts = {}) {
     let lastPassAt = null;
     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 {
                 lastAttemptAt = Date.now();
-                const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds);
+                const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds, { signal: shutdown.signal });
                 lastPassAt = Date.now();
                 first = false;
                 consecutiveErrors = 0;
                 heldPasses = heldPassAfter(heldPasses, pass);
                 if (heldPasses)
-                    await sleep(Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** Math.min(heldPasses - 1, 5)));
+                    await sleep(Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** Math.min(heldPasses - 1, 5)), shutdown.signal);
             }
             catch (err) {
                 if (!running)
@@ -419,17 +453,17 @@ export function runInboxLoop(deps, opts = {}) {
                 if (throttleMs !== null) {
                     consecutiveErrors = 0;
                     warn(label, `inbox loop throttled: ${err?.message ?? err} — waiting ${Math.round(throttleMs)}ms as instructed`);
-                    await sleep(throttleMs);
+                    await sleep(throttleMs, shutdown.signal);
                     continue;
                 }
                 const backoff = Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** (consecutiveErrors - 1));
                 const jitter = backoff * (0.5 + (consecutiveErrors % 7) / 14); // deterministic-ish, no Math.random
                 warn(label, `inbox loop pass failed (#${consecutiveErrors}): ${err?.message ?? err} — retrying in ~${Math.round(jitter)}ms`);
-                await sleep(jitter);
+                await sleep(jitter, shutdown.signal);
             }
         }
     })();
-    const done = main;
+    const done = main.finally(releaseOnce);
     return {
         get running() {
             return running;
@@ -440,12 +474,17 @@ export function runInboxLoop(deps, opts = {}) {
         get lastAttemptAt() {
             return lastAttemptAt;
         },
-        async stop() {
+        async stop(timeoutMs = INBOX_STOP_TIMEOUT_MS) {
             running = false;
-            // Drop the lease immediately. Do not wait out a held poll — SIGTERM
-            // then process.exit cannot sit on the 110s wait.
-            await releaseInboxHostBestEffort(deps);
-            void done.catch(() => { });
+            // 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();
+            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/platform/tools/tier1/protocolRunner.js

@@ -57,7 +57,7 @@ cachedAgreements) {
         case 'agreement-propose':
             return proposeAgreement(services, payload, chatId, agents, actorId, writeKeys);
         case 'agreement-subcontract':
-            return subcontractAgreement(services, payload, namedSubcontractChat(payload, chatId), agents, actorId, writeKeys, cachedAgreements);
+            return subcontractAgreement(services, payload, namedSubcontractChat(payload, chatId), actorId, writeKeys);
         case 'agreement-respond':
             if (!payload.agreementId || !payload.action)
                 return null;
@@ -322,9 +322,6 @@ function agIsProvider(a, agentId) {
 function agIsParty(a, agentId) {
     return partyActorIds(a.parties).includes(agentId);
 }
-function agActive(a) {
-    return !a.status || !TERMINAL_STATUS.has(String(a.status));
-}
 // Spawnable = actually ACTIVE. A freshly-subcontracted sub is `draft` until its
 // counterparty auto-approves; spawning under a draft (or citing an agreement the
 // assignee isn't a party on) 400s and cascades into a bogus worker "connection
@@ -339,66 +336,25 @@ function namedSubcontractChat(payload, wakeChatId) {
         return named.trim();
     return wakeChatId;
 }
-async function subcontractAgreement(services, payload, chatId, _agents, actingAgentId, writeKeys = null, cachedAgreements) {
+/**
+ * A sub-agreement under the agreement this wake works for, with exactly the
+ * terms the model stated. When it states neither an end date nor a task count
+ * the server writes a standing sub-agreement, the same as over MCP — the
+ * shared tool description says so.
+ *
+ * This used to rewrite such terms to one count-bound task, and to reuse any
+ * open sub-agreement for the same worker. Both served a backend rule that
+ * closed a parent once every child had finished; that rule is gone (a parent
+ * now closes only by its own quota, expiry or an explicit close), so the
+ * rewrite only made a hosted agent's sub-deal end after one task where the same
+ * request over MCP stays open. A crash replay is still covered by the
+ * wake-derived idempotency key.
+ */
+async function subcontractAgreement(services, payload, chatId, actingAgentId, writeKeys = null) {
     if (!payload.description || !payload.executorId)
         return null;
-    // b1: idempotent subcontract — if a non-terminal sub-agreement for
-    // this executor already exists under the same parent, reuse it instead of
-    // creating a duplicate (which bloats the chain and blocks the fulfill cascade).
-    if (chatId) {
-        const parent = payload.parentAgreementId;
-        const existing = (await agreementsInChat(services, chatId, cachedAgreements)).find((a) => agActive(a) && agIsProvider(a, payload.executorId) &&
-            (!parent || a.parentAgreementId === parent || a.rootAgreementId === parent));
-        if (existing?.agreementId)
-            return existing;
-    }
     const priced = applyFleetPricingForProtocol('agreement-subcontract', payload, actingAgentId);
     const { operation: _op, ...fields } = priced;
-    // a subcontract must carry a working close condition, or it hangs
-    // 'active' forever — and because the backend only auto-fulfills a parent hire
-    // once every child sub-agreement is terminal (the fulfill cascade), one
-    // never-closing child leaves the whole engagement open. Deciding lifecycle is
-    // left to the model, which under load (context bloat, competing wakes) emits
-    // incomplete terms — e.g. time-bound with no expiresAt and no maxExecutions —
-    // that never reach fulfillment. Make the common single-delegated-task case
-    // deterministic: if the caller gave neither a real quota nor a real deadline,
-    // treat it as one count-bound execution so completing that task closes the
-    // sub — which then cascades the parent closed. A genuinely durable subcontract
-    // still opts out by setting maxExecutions>1 or a time-bound expiresAt.
-    const f = fields;
-    // repair incomplete terms instead of clobbering them. The model
-    // often emits a real quota or deadline but gets the envelope wrong — a
-    // numeric-string maxExecutions, or a quota/deadline with the lifecycle field
-    // missing or mismatched. The old check treated all of those as "no close
-    // condition" and forced count-bound/1, silently discarding the stated intent
-    // (e.g. maxExecutions=2 → 1, so the sub fulfills one task early and the next
-    // spawn under it fails).
-    if (typeof f.maxExecutions === 'string' && f.maxExecutions.trim() !== '' && Number.isFinite(Number(f.maxExecutions))) {
-        f.maxExecutions = Number(f.maxExecutions);
-    }
-    const hasQuota = typeof f.maxExecutions === 'number' && f.maxExecutions > 0;
-    const hasDeadline = typeof f.expiresAt === 'string' && f.expiresAt.length > 0;
-    if (f.lifecycle === 'count-bound' && hasQuota) {
-        // coherent as stated
-    }
-    else if (f.lifecycle === 'time-bound' && hasDeadline) {
-        // coherent as stated
-    }
-    else if (hasQuota) {
-        f.lifecycle = 'count-bound'; // quota given, lifecycle missing/mismatched — keep the quota
-    }
-    else if (hasDeadline) {
-        f.lifecycle = 'time-bound'; // deadline given, lifecycle missing/mismatched — keep the deadline
-    }
-    else {
-        // no usable close condition at all — the deterministic single-task default
-        f.lifecycle = 'count-bound';
-        f.maxExecutions = 1;
-    }
-    // Wake-derived idempotency key (delivery law): a crash-replay that slips past
-    // the b1 reuse check above (e.g. no chatId, or the sub not yet visible in the
-    // snapshot) resolves to the already-created sub-agreement server-side instead
-    // of minting a duplicate.
     const idempotencyKey = writeKeys?.agreementSubcontractKey({
         executorId: payload.executorId,
         description: payload.description,

package/dist/platform/tools/tier2/connectionTools.js

@@ -1,6 +1,7 @@
 import { connectionProxyCapability, requestConnectionCapability, ConnectionsClient, } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
 import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
+import { resolveBackendUrl } from '../../../shared/backendUrl.js';
 // connection_proxy / connection_request are shared capability
 // definitions (api-client). connection_list_grants stays SDK-only: the MCP
 // surface folds connection listing into ziggs_connection_list (
@@ -19,7 +20,7 @@ export const connectionListGrantsTool = defineTool('connection_list_grants', {
     const operatorKey = ctx?.['operatorKey'];
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    const baseUrl = process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined;
+    const baseUrl = resolveBackendUrl();
     const client = new ConnectionsClient(operatorKey, ctx?.['agentId'] || undefined, baseUrl);
     try {
         const grants = await client.listGrants({ connectionId: args['connectionId'] });

package/dist/runtime/AgentMachine.d.ts

@@ -159,6 +159,16 @@ export declare class AgentMachine {
      */
     private _parkAtInitial;
     _step(outcome: Outcome, depth?: number): Promise<void>;
+    /**
+     * A turn threw. Route the error through the state's transitions; if none
+     * takes it, recover to workflow.initial so the next event is not judged by
+     * transitions written for this state.
+     *
+     * One method for thinking and tool (mechanical) states. The recovery used to
+     * live only in the thinking copy, so a tool state that threw with no error
+     * route stayed put and judged the next event as itself.
+     */
+    _recoverFromTurnError(error: unknown, kind: 'thinking' | 'mechanical'): Promise<void>;
     /**
      * Unmatched thinking outcome: go back to workflow.initial when that state is
      * parked. Used to require an error outcome, so a tool-result /

package/dist/runtime/AgentMachine.js

@@ -243,24 +243,7 @@ export class AgentMachine {
                 await this._step(turnOutcome, depth + 1);
             }
             catch (error) {
-                runtimeLog.error('AgentMachine', `mechanical state=${this.state} error: ${error?.message || error}`);
-                const errOutcome = {
-                    kind: 'error',
-                    source: 'unknown',
-                    cause: error?.message || String(error),
-                    retryable: false,
-                };
-                applyOutcomeToCtx(this.ctx, errOutcome);
-                this._running = false;
-                this._notify();
-                const fallback = this._evaluateTransitions(errOutcome);
-                if (fallback && fallback !== this.state) {
-                    this.state = fallback;
-                    this._notify();
-                }
-                else {
-                    await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
-                }
+                await this._recoverFromTurnError(error, 'mechanical');
             }
             return;
         }
@@ -346,27 +329,37 @@ export class AgentMachine {
             await this._step(turnOutcome, depth + 1);
         }
         catch (error) {
-            runtimeLog.error('AgentMachine', `state=${this.state} error: ${error?.message || error}`);
-            const errOutcome = {
-                kind: 'error',
-                source: 'unknown',
-                cause: error?.message || String(error),
-                retryable: false,
-            };
-            applyOutcomeToCtx(this.ctx, errOutcome);
-            this._running = false;
+            await this._recoverFromTurnError(error, 'thinking');
+        }
+    }
+    /**
+     * A turn threw. Route the error through the state's transitions; if none
+     * takes it, recover to workflow.initial so the next event is not judged by
+     * transitions written for this state.
+     *
+     * One method for thinking and tool (mechanical) states. The recovery used to
+     * live only in the thinking copy, so a tool state that threw with no error
+     * route stayed put and judged the next event as itself.
+     */
+    async _recoverFromTurnError(error, kind) {
+        runtimeLog.error('AgentMachine', `${kind === 'mechanical' ? 'mechanical ' : ''}state=${this.state} error: ${error?.message || error}`);
+        const errOutcome = {
+            kind: 'error',
+            source: 'unknown',
+            cause: error?.message || String(error),
+            retryable: false,
+        };
+        applyOutcomeToCtx(this.ctx, errOutcome);
+        this._running = false;
+        this._notify();
+        const fallback = this._evaluateTransitions(errOutcome);
+        if (fallback && fallback !== this.state) {
+            this.state = fallback;
             this._notify();
-            // Try to fall through using current state's transitions; if none match,
-            // recover to workflow.initial so the next event is not judged here.
-            const fallback = this._evaluateTransitions(errOutcome);
-            if (fallback && fallback !== this.state) {
-                this.state = fallback;
-                this._notify();
-            }
-            else {
-                await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
-                this._parkAtInitial();
-            }
+        }
+        else {
+            await this._sendFallbackIfUserWaiting('Something went wrong. Please try again.');
+            this._parkAtInitial();
         }
     }
     /**

package/dist/runtime/validateWorkflow.js

@@ -125,6 +125,11 @@ export function validateWorkflow(workflow) {
             else if (typeof p !== 'function') {
                 errors.push(`mechanical state "${name}" requires produces (OutcomeKind or fn)`);
             }
+            // The same soft check thinking states get. A tool that throws
+            // with no error route sends the agent back to its initial state.
+            if (!hasErrorTransition(mech.transitions ?? [])) {
+                warnings.push(`mechanical state "${name}" has no transition for { kind: 'error' } — a failed tool call sends the agent back to "${workflow.initial}". Add an error transition if it should go elsewhere.`);
+            }
         }
         if (!Array.isArray(state.transitions)) {
             errors.push(`state "${name}" requires a transitions array`);
@@ -189,17 +194,7 @@ export function validateWorkflow(workflow) {
                 if (!hasWaitFallthrough) {
                     warnings.push(`thinking state "${name}" has no fallthrough for { kind: 'wait' } — agent may stall when LLM picks wait. Spread thinkingDefaults().transitions or add explicitly.`);
                 }
-                const hasErrorFallthrough = state.transitions.some(t => {
-                    if (!t.when)
-                        return true;
-                    try {
-                        return t.when({ kind: 'error', source: 'unknown', cause: 'probe', retryable: false }, PROBE_CTX);
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-                if (!hasErrorFallthrough) {
+                if (!hasErrorTransition(state.transitions)) {
                     warnings.push(`thinking state "${name}" has no fallthrough for { kind: 'error' } — empty/failed turns may silently recurse until the depth guard. Add an error transition or spread thinkingDefaults().transitions.`);
                 }
             }
@@ -209,3 +204,16 @@ export function validateWorkflow(workflow) {
         throw new WorkflowValidationError(errors);
     return { errors, warnings };
 }
+/** Does some transition take an error outcome? A guard that throws counts as no. */
+function hasErrorTransition(transitions) {
+    return transitions.some((t) => {
+        if (!t.when)
+            return true;
+        try {
+            return t.when({ kind: 'error', source: 'unknown', cause: 'probe', retryable: false }, PROBE_CTX);
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/shared/backendUrl.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The backend address, read one way everywhere in the SDK.
+ *
+ * Explicit config wins, then the runner's overrides (`ZIGGS_BACKEND_URL`,
+ * `BACKEND_URL`), then `getBackendUrl()` — what `configureApiClient` set, else
+ * production. There were five copies with three different orders, and the one
+ * in the per-user connect path fell back to `http://localhost:3000`, so an
+ * outside developer who configured the client and nothing else had connection
+ * requests posted to their own machine.
+ */
+export declare function resolveBackendUrl(explicit?: string | null): string;

package/dist/shared/backendUrl.js

@@ -0,0 +1,17 @@
+import { getBackendUrl } from '@ziggs-ai/api-client';
+/**
+ * The backend address, read one way everywhere in the SDK.
+ *
+ * Explicit config wins, then the runner's overrides (`ZIGGS_BACKEND_URL`,
+ * `BACKEND_URL`), then `getBackendUrl()` — what `configureApiClient` set, else
+ * production. There were five copies with three different orders, and the one
+ * in the per-user connect path fell back to `http://localhost:3000`, so an
+ * outside developer who configured the client and nothing else had connection
+ * requests posted to their own machine.
+ */
+export function resolveBackendUrl(explicit) {
+    return (explicit ||
+        process.env.ZIGGS_BACKEND_URL ||
+        process.env.BACKEND_URL ||
+        getBackendUrl()).replace(/\/$/, '');
+}

package/dist/tools/capabilityAdapter.js

@@ -1,5 +1,6 @@
 import { defineTool } from './defineTool.js';
 import { laneFromToolContext } from './toolCreds.js';
+import { resolveBackendUrl } from '../shared/backendUrl.js';
 /**
  * the SDK surface adapter for shared capability definitions
  * (api-client `capabilities/`). One capability (schema + handler + guidance)
@@ -30,9 +31,7 @@ export function toolFromCapability(cap) {
                 ...(agentId ? { agentId } : {}),
                 ...(laneId ? { laneId } : {}),
             },
-            // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the
-            // shared clients default to HTTP_URL (api-client convention) otherwise.
-            baseUrl: process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined,
+            baseUrl: resolveBackendUrl(),
             webUrl: process.env.ZIGGS_WEB_URL,
             surface: 'sdk',
             serviceAgreementId: typeof ctx.serviceAgreementId === 'string' ? ctx.serviceAgreementId : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.33.0",
+  "version": "0.33.2",
   "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.0",
+    "@ziggs-ai/api-client": "0.32.1",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",