@ziggs-ai/agent-sdk 0.33.0 → 0.33.1

package/CHANGELOG.md

@@ -12,6 +12,23 @@
 
 ## Unreleased
 
+### 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.
+
+- `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/dist/Agent.d.ts

@@ -256,6 +256,7 @@ 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;

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';
@@ -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);
@@ -218,6 +219,7 @@ 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;
@@ -1444,6 +1446,16 @@ 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.
@@ -1548,16 +1560,36 @@ export class Agent {
         this.started = false;
         this.pollRunner?.stop();
         this.stateTimers.clearAll();
-        const stopping = this.inboxLoop?.stop() ?? Promise.resolve();
+        if (this.inboxLoop)
+            this.inboxStopping = this.inboxLoop.stop();
         this.inboxLoop = null;
-        return stopping;
+        // Draining is separately bounded by the caller. Waiting here could hang
+        // shutdown on a slow wake before that timeout even starts.
+        return Promise.resolve();
     }
     /**
      * 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.
      */
-    drain(timeoutMs = 30_000) { return this.eventQueue.waitForIdle(timeoutMs); }
+    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 };
+    }
     registerTool(tool) { return this.toolManager.register(tool); }
     isConnected() { return this.started && (!this.inboxLoopEnabled || (this.inboxLoop?.running ?? false)); }
     /**

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,8 @@ export declare class ConnectionPool {
     private readonly manager;
     private readonly configs;
     private readonly hosts;
+    private readonly retiringHosts;
+    private shutdownGeneration;
     private readonly responseListeners;
     /**
      * Register N agent configs. Nothing connects until `connectAll()`. A config

package/dist/platform/ConnectionPool.js

@@ -23,6 +23,12 @@ 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;
     // Listeners enqueued by requestFrom — drained on outbound send-message effects.
     responseListeners = new Map();
     /**
@@ -45,6 +51,17 @@ 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;
@@ -64,6 +81,7 @@ export class ConnectionPool {
                 runtimeLog.debug('ConnectionPool', `connected "${agentId}"`);
                 return host;
             }, async (host) => {
+                this.retiringHosts.set(agentId, host);
                 await host.disconnect();
                 this.hosts.delete(agentId);
                 runtimeLog.debug('ConnectionPool', `disconnected "${agentId}"`);
@@ -116,11 +134,18 @@ export class ConnectionPool {
      * holding up the rest — the caller is on a shutdown clock of its own.
      */
     async shutdown(timeoutMs = 30_000) {
-        const hosts = [...this.hosts.values()];
+        this.shutdownGeneration++;
+        const hosts = [...new Set([...this.hosts.values(), ...this.retiringHosts.values()])];
         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);
+                    }
+                }
                 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,8 +66,9 @@ 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. */

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,19 @@ 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 });
+    });
 }
 /**
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
@@ -394,17 +411,18 @@ export function runInboxLoop(deps, opts = {}) {
     let lastPassAt = null;
     let lastAttemptAt = null;
     let first = true;
+    const shutdown = new AbortController();
     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 +437,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(() => releaseInboxHostBestEffort(deps));
     return {
         get running() {
             return running;
@@ -442,10 +460,10 @@ export function runInboxLoop(deps, opts = {}) {
         },
         async stop() {
             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, but let work already handed to the host
+            // finish and acknowledge before releasing its lease.
+            shutdown.abort();
+            await done;
         },
     };
 }

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.1",
   "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",