@ziggs-ai/agent-sdk 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Unreleased
+
+### Breaking
+
+- `AgentHostOptions.questMatchTags` is now `requestMatchTags`. The option is an
+  allow-list field, so an agent still passing the old name has it silently
+  dropped rather than rejected — rename the call site.
+- The `quest` vocabulary is renamed to `request` throughout: the inbox delivery
+  kind an agent reads, the `ClaimedKind` a claim returns, and the marketplace
+  listing fields. Re-exported api-client types move with it.
+
 ## 0.10.0 — unreleased
 
 ### Removed (breaking)

package/README.md

@@ -91,7 +91,7 @@ The public **`Brain`** interface is `tick(TickInput): Promise<TickOutput>`. Buil
 2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, etc., and **`createAgent(config)`** (returns an **`AgentHost`**).
 3. **`connect()`** to go live; the SDK long-polls the HTTP inbox and routes deliveries into **`handleMessage`**.
 
-Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
+Worked examples and the full build path: https://ziggsai.com/docs
 
 Point the shared HTTP client at a non-default backend (self-hosted / local) before constructing hosts — no direct `@ziggs-ai/api-client` dependency needed:
 

package/dist/AgentHost.d.ts

@@ -1,5 +1,5 @@
 import type { AgentConfig, Ctx, Workflow } from './types.js';
-import { Agent } from './agent/Agent.js';
+import { Agent, type TickOutput } from './agent/Agent.js';
 import { ClaudeSdkAgent, type CognitionKind } from './agent/ClaudeSdkAgent.js';
 import { type BrainSelection } from './brain/index.js';
 export type { CognitionKind };
@@ -23,8 +23,9 @@ export interface SessionStore {
     }): Promise<void>;
 }
 import { ToolManager } from './tools/ToolManager.js';
-import type { ToolDefinition } from './tools/defineTool.js';
+import { type ToolDefinition } from './tools/defineTool.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
+import { type AgentNeed } from './tools/needs.js';
 /**
  * The single fleet-wide default model — the one place the fallback lives.
  * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
@@ -76,12 +77,18 @@ export interface AgentHostOptions {
     systemPrompt?: string;
     specialization?: string | null;
     /**
-     * strings compared exactly against a quest's `match` field.
+     * strings compared exactly against a request's `match` field.
      * Miss → ack with zero LLM. Match → normal wake. `specialization` is also
      * checked when set.
      */
-    questMatchTags?: string[];
+    requestMatchTags?: string[];
     tools?: ToolDefinition[];
+    /**
+     * Access this agent cannot work without. Enforced at task start:
+     * a task arriving with no live grant behind a declared need is failed with the
+     * missing access named, before the tick spends anything.
+     */
+    needs?: AgentNeed[];
     taskTools?: 'all' | 'none' | string[];
     /**
      * Brain selection — preferred over legacy `cognition`.
@@ -142,6 +149,17 @@ export interface AgentHostOptions {
         cognition: string;
         metrics: import('./agent/Agent.js').TickOutput['metrics'];
     }) => void;
+    /**
+     * Called with everything a wake consists of, immediately before the brain
+     * runs. Pair it with {@link AgentHost.replayWake} to re-run that exact wake
+     * later against edited agent source — the difference between iterating on a
+     * prompt in seconds and standing a whole world back up to see one turn.
+     *
+     * Emitted for every wake, including ones the brain then declines to spend an
+     * LLM call on, because "why did nothing happen?" is the question a recording
+     * most often has to answer.
+     */
+    wakeTap?: (record: WakeRecord) => void;
     /** Production monitoring ingest. Default on; set false to disable. */
     telemetryIngest?: boolean;
     /**
@@ -150,6 +168,28 @@ export interface AgentHostOptions {
      */
     inboxCatchUp?: boolean;
 }
+/**
+ * One wake, as the brain received it.
+ *
+ * These four fields ARE the tick's input (`agent.tick({ event, ctx, state,
+ * identity })`) — everything else a tick touches is rebuilt from the agent's own
+ * config. So a record is replayable on its own, and a replay that behaves
+ * differently differs because the agent changed, not because the input drifted.
+ *
+ * Plain JSON on purpose: a record is meant to survive being written to a file
+ * and read back by another process.
+ */
+export interface WakeRecord {
+    agentId: string;
+    sessionId: string;
+    laneKey: string;
+    /** The event frame that woke the agent. */
+    event: unknown;
+    /** FSM context carried into the tick — undefined on a cold lane. */
+    ctx?: unknown;
+    /** FSM state the lane was parked in — undefined on a cold lane. */
+    state?: string;
+}
 /**
  * ToolManager is a Map keyed by tool name, so the last registration silently
  * wins. An agent's own tools register last — which means an `extraTools` entry
@@ -189,6 +229,16 @@ export declare class AgentHost {
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     private inboxLoop;
     private inboxLoopEnabled;
+    /** Short-lived grant-provider cache for the declared-needs gate. */
+    /**
+     * Lanes where an unmet-need refusal has already been allowed its one turn to
+     * ask for the access (see `_refuseIfNeedsUnmet`). Per lane, not per agent: two
+     * hirers each deserve the ask, and neither deserves it twice.
+     */
+    private askedForAccessLanes;
+    /** Tasks left active by the asking turn, failed right after it (per lane). */
+    private unmetTasksPendingAsk;
+    private grantProviderCache;
     constructor(options?: AgentHostOptions);
     private _validate;
     private _setup;
@@ -245,16 +295,68 @@ export declare class AgentHost {
      * still gets its turn, because that is an agent with something left to say.
      */
     private isSettledTaskEcho;
+    /** Providers of this agent's live connection grants. Its own seam, so the gate below is testable without a backend. */
+    private _listGrantProviders;
+    /**
+     * Short TTL on purpose: the gate runs on every wake, and a claim produces
+     * several in seconds — but hire comes before grant, so a grant arriving
+     * mid-engagement has to take effect without a restart.
+     */
+    private _grantProvidersCached;
+    /**
+     * Refuse work this agent has no way to do, before it costs a turn.
+     * Returns true when work was refused and the tick must not run.
+     *
+     * Enforced at wake for an agent holding assigned work, not at hire: hire comes
+     * first and the grant second, so a hire-time gate would refuse every honest
+     * one. Not limited to the task frame either — a store claim wakes the agent on
+     * the agreement first, and a task-only gate let the model take that turn and
+     * reason its own way to "I have no grant" (measured on linear-janitor: 8 calls,
+     * 114,025 tokens, for what one HTTP call answers).
+     *
+     * It fails the task rather than skipping quietly, which would leave it active
+     * with nothing working it — the same invisible stall from the buyer's side.
+     */
+    private _refuseIfNeedsUnmet;
+    /**
+     * Fail whatever the asking turn left active.
+     *
+     * The one turn granted above runs with the task still active so the agent can
+     * ask; the agent's own instructions then fail it. This is the backstop for when
+     * they do not: an active task nobody is working is the invisible stall the gate
+     * exists to prevent, and it must not be the price of asking.
+     */
+    private settleUnmetAfterAsk;
+    /**
+     * Whether this agent holds the tool that turns "I cannot" into "here is what I
+     * need". Without it the extra turn buys nothing, so it is not spent.
+     */
+    private canAskForAccess;
     private _processEvent;
+    /**
+     * Re-run one recorded wake against THIS host's agent, and nothing else.
+     *
+     * The dev loop for a prompt: record a wake off a live run, edit the agent, and
+     * see what it does differently in seconds instead of standing a world back up
+     * for one turn. The brain, tools and effect handler are the real ones, so the
+     * turn is real — its tool calls hit the backend this host is pointed at, which
+     * is why it belongs against a disposable world and not a shared one.
+     *
+     * Deliberately NOT routed through `_processEvent`: everything that method does
+     * around the tick is lane bookkeeping — session state, liveness timers, session
+     * persistence, ack decisions, failure re-arm — and a replay has no lane to keep.
+     * Borrowing that path would make a dev tool able to disturb a live one.
+     */
+    replayWake(record: WakeRecord): Promise<TickOutput>;
     /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
     private _armIfTimedParked;
     private _resolveOwnAgentId;
     connectAsync(_timeout?: number): Promise<this>;
     /**
-     * plain string compare against {@link AgentHostOptions.questMatchTags}
+     * plain string compare against {@link AgentHostOptions.requestMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
-    private triageQuestDelivery;
+    private triageRequestDelivery;
     private _bootstrapAssignedActiveTasks;
     /** replay task-assigned for an existing active task (demo recovery). */
     wakeTaskAssignment(taskId: string): Promise<void>;

package/dist/AgentHost.js

@@ -12,15 +12,17 @@ import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
 import { InMemoryStore } from './memory/MemoryStore.js';
 import { ToolManager } from './tools/ToolManager.js';
+import { toolName } from './tools/defineTool.js';
 import { PROTOCOL_TOOLS } from './server/tools/tier1/protocolTools.js';
 import { marketplaceViewTool } from './server/tools/tier2/marketplaceTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
-import { ArtifactsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
+import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
+import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 import { TaskService } from './server/tasks/TaskService.js';
 import { AgreementService } from './server/agreements/AgreementService.js';
 import { runInboxLoop } from './server/inboxLoop.js';
-import { questExactMatch } from './server/questMatch.js';
+import { requestExactMatch } from './server/requestMatch.js';
 import { SeenMessages } from './server/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 /**
@@ -177,6 +179,16 @@ export class AgentHost {
     /** The per-agent inbox long-poll loop — this agent's sole wake source. */
     inboxLoop = null;
     inboxLoopEnabled;
+    /** Short-lived grant-provider cache for the declared-needs gate. */
+    /**
+     * Lanes where an unmet-need refusal has already been allowed its one turn to
+     * ask for the access (see `_refuseIfNeedsUnmet`). Per lane, not per agent: two
+     * hirers each deserve the ask, and neither deserves it twice.
+     */
+    askedForAccessLanes = new Set();
+    /** Tasks left active by the asking turn, failed right after it (per lane). */
+    unmetTasksPendingAsk = new Map();
+    grantProviderCache = null;
     constructor(options = {}) {
         const resolved = applyBrainToHostOptions(options);
         this.options = {
@@ -190,6 +202,11 @@ export class AgentHost {
             systemPrompt: resolved.systemPrompt,
             specialization: resolved.specialization ?? null,
             tools: resolved.tools || [],
+            // Copied deliberately: this object is an allow-list, so a field left out
+            // here is silently dropped between the manifest and the runtime. That is
+            // exactly how `respondsToProposals` reached the store as null for 133
+            // agents — the declaration existed and nothing carried it.
+            needs: resolved.needs,
             taskTools: resolved.taskTools,
             states: resolved.states,
             initial: resolved.initial,
@@ -200,6 +217,7 @@ export class AgentHost {
             effectTap: resolved.effectTap,
             transitionTap: resolved.transitionTap,
             metricsTap: resolved.metricsTap,
+            wakeTap: resolved.wakeTap,
             inboxCatchUp: resolved.inboxCatchUp,
             brain: resolved.brain,
             cognition: resolved.cognition ?? 'fsm',
@@ -209,9 +227,9 @@ export class AgentHost {
         this.inboxLoopEnabled = options.inboxCatchUp !== false;
         this.sessionResolver = options.sessionResolver || DEFAULT_SESSION_RESOLVER;
         // A Claude-brain wake legitimately runs long (multi-turn query, prose
-        // deliverables) — 120s watchdogged real spec-writing wakes mid-flight,
-        // which then redelivered and re-ran (dogfood, 2026-07-26). FSM
-        // turns stay on the tight default.
+        // deliverables). At 120s the watchdog cuts real spec-writing wakes
+        // mid-flight, which then redeliver and re-run. FSM turns stay on the tight
+        // default.
         this.tickTimeoutMs =
             options.tickTimeoutMs ??
                 (isClaudeCognition(options.cognition)
@@ -257,6 +275,9 @@ export class AgentHost {
         };
         const messageSender = (message, receiverId, sessionId, messageId) => sendChatMessage({
             chatId: sessionId,
+            // Omitted on purpose when the caller has no valid address for THIS
+            // room: the backend infers the recipient from the room's own
+            // participants.
             receiverId,
             text: message,
             // messageId is the backend's (chatId, messageId) dedup key. Callers
@@ -518,6 +539,151 @@ export class AgentHost {
         const reported = result.result;
         return reported !== undefined && reported !== null && reported !== '';
     }
+    /** Providers of this agent's live connection grants. Its own seam, so the gate below is testable without a backend. */
+    async _listGrantProviders(operatorKey, agentId) {
+        const groups = await new ConnectionsClient(operatorKey, agentId).listForHolder();
+        return groups.filter((g) => (g.grants ?? []).length > 0).map((g) => g.provider);
+    }
+    /**
+     * Short TTL on purpose: the gate runs on every wake, and a claim produces
+     * several in seconds — but hire comes before grant, so a grant arriving
+     * mid-engagement has to take effect without a restart.
+     */
+    async _grantProvidersCached(operatorKey, agentId) {
+        const now = Date.now();
+        if (this.grantProviderCache && now - this.grantProviderCache.at < 30_000) {
+            return this.grantProviderCache.providers;
+        }
+        const providers = await this._listGrantProviders(operatorKey, agentId);
+        this.grantProviderCache = { at: now, providers };
+        return providers;
+    }
+    /**
+     * Refuse work this agent has no way to do, before it costs a turn.
+     * Returns true when work was refused and the tick must not run.
+     *
+     * Enforced at wake for an agent holding assigned work, not at hire: hire comes
+     * first and the grant second, so a hire-time gate would refuse every honest
+     * one. Not limited to the task frame either — a store claim wakes the agent on
+     * the agreement first, and a task-only gate let the model take that turn and
+     * reason its own way to "I have no grant" (measured on linear-janitor: 8 calls,
+     * 114,025 tokens, for what one HTTP call answers).
+     *
+     * It fails the task rather than skipping quietly, which would leave it active
+     * with nothing working it — the same invisible stall from the buyer's side.
+     */
+    async _refuseIfNeedsUnmet(_event, _laneKey) {
+        const needs = normalizeNeeds(this.options.needs);
+        if (!needs.length)
+            return false;
+        const operatorKey = this.options.operatorKey;
+        const agentId = this.options.agentId;
+        if (!operatorKey || !agentId || !this.taskService)
+            return false;
+        let providers;
+        try {
+            providers = await this._grantProvidersCached(operatorKey, agentId);
+        }
+        catch (err) {
+            // A grants read that failed is not proof the grant is missing, and failing
+            // the task on our own outage would be worse than letting the agent try.
+            runtimeLog.warn(this.options.name || 'agent', `needs check skipped: ${err?.message ?? err}`);
+            return false;
+        }
+        const unmet = unmetNeeds(needs, providers);
+        if (!unmet.length)
+            return false;
+        // Only work already on this agent's plate is refused. A wake with no assigned
+        // task is someone talking to it — an agent that cannot reach Linear can still
+        // say so in a sentence, and muting it would be a worse silence.
+        let assigned;
+        try {
+            assigned = await this.taskService.getActiveTasksForAgent(agentId);
+        }
+        catch (err) {
+            runtimeLog.warn(this.options.name || 'agent', `needs check could not read assigned work: ${err?.message ?? err}`);
+            return false;
+        }
+        const mine = assigned.filter((t) => t.taskId && (!t.assigneeId || t.assigneeId === agentId));
+        if (!mine.length)
+            return false;
+        const message = unmetNeedsMessage(unmet);
+        /**
+         * Ask BEFORE refusing, once per lane, when this agent can ask at all.
+         *
+         * Order is the whole fix. Failing the task first and then letting the wake
+         * run does nothing: the brain declines a wake whose task already reported a
+         * result, so the agent never speaks and the buyer is left with "ask the
+         * connection owner to issue a grant" for a connection only they can make —
+         * and no place in the web app to make it, because the grant dialog lists the
+         * workspace's own agents and a fleet-hosted one is not among them.
+         *
+         * So the first unmet wake on a lane runs with the task still active: the
+         * agent's own instructions send the consent card and fail the task. Whatever
+         * it leaves active is failed right after the tick ({@link settleUnmetAfterAsk}),
+         * so nothing hangs, and every later wake on the lane is refused up front as
+         * before — a buyer who ignores the card is not billed for reminders.
+         */
+        if (this.canAskForAccess() && !this.askedForAccessLanes.has(_laneKey)) {
+            this.askedForAccessLanes.add(_laneKey);
+            this.unmetTasksPendingAsk.set(_laneKey, mine.map((t) => String(t.taskId)));
+            runtimeLog.info(this.options.name || 'agent', `no access for ${unmet.map((n) => n.connection).join('/')} on ${_laneKey} — letting this wake run once so it can ask, then failing whatever it leaves`);
+            return false;
+        }
+        for (const task of mine) {
+            const taskId = String(task.taskId);
+            runtimeLog.warn(this.options.name || 'agent', `refusing task ${taskId} — ${message}`);
+            try {
+                await this.taskService.updateState(taskId, 'failed', {
+                    summary: message,
+                    status: 'failed',
+                });
+            }
+            catch (err) {
+                runtimeLog.warn(this.options.name || 'agent', `could not fail task ${taskId} after refusing it: ${err?.message ?? err}`);
+            }
+        }
+        return true;
+    }
+    /**
+     * Fail whatever the asking turn left active.
+     *
+     * The one turn granted above runs with the task still active so the agent can
+     * ask; the agent's own instructions then fail it. This is the backstop for when
+     * they do not: an active task nobody is working is the invisible stall the gate
+     * exists to prevent, and it must not be the price of asking.
+     */
+    async settleUnmetAfterAsk(laneKey) {
+        const pending = this.unmetTasksPendingAsk.get(laneKey);
+        if (!pending?.length)
+            return;
+        this.unmetTasksPendingAsk.delete(laneKey);
+        if (!this.taskService)
+            return;
+        for (const taskId of pending) {
+            try {
+                const active = await this.taskService.getActiveTasksForAgent(this.options.agentId);
+                if (!active.some((t) => String(t.taskId) === taskId))
+                    continue;
+                runtimeLog.warn(this.options.name || 'agent', `failing task ${taskId} — it asked for the missing access but left the work open`);
+                await this.taskService.updateState(taskId, 'failed', {
+                    summary: unmetNeedsMessage(normalizeNeeds(this.options.needs)),
+                    status: 'failed',
+                });
+            }
+            catch (err) {
+                runtimeLog.warn(this.options.name || 'agent', `could not settle task ${taskId} after the access ask: ${err?.message ?? err}`);
+            }
+        }
+    }
+    /**
+     * Whether this agent holds the tool that turns "I cannot" into "here is what I
+     * need". Without it the extra turn buys nothing, so it is not spent.
+     */
+    canAskForAccess() {
+        const tools = this.options.tools ?? this.options.services?.tools ?? [];
+        return tools.some((t) => toolName(t) === 'connection_request');
+    }
     async _processEvent(event, laneKey) {
         const session = this.sessions.get(laneKey);
         if (!session?.sessionId)
@@ -530,6 +696,10 @@ export class AgentHost {
             runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its task already reported a result`);
             return;
         }
+        // Before the tick spends anything: work this agent declared it cannot do
+        // without access it does not hold.
+        if (await this._refuseIfNeedsUnmet(event, laneKey))
+            return;
         // Stale timer frames (superseded epoch) are dropped BEFORE touching the
         // live timer — a pure-stale frame must not reset a freshly armed countdown.
         const frame = this.stateTimers.stripStale(event, laneKey);
@@ -557,6 +727,24 @@ export class AgentHost {
             sessionId: session.sessionId,
             laneKey,
         };
+        // Recorded here rather than after the tick: this is the last point where the
+        // input is still exactly what the brain will see, and a wake that goes on to
+        // throw is the one most worth replaying.
+        if (this.options.wakeTap) {
+            try {
+                this.options.wakeTap({
+                    agentId: identity.agentId,
+                    sessionId: identity.sessionId,
+                    laneKey,
+                    event: frame,
+                    ctx: session.ctx,
+                    state: session.state,
+                });
+            }
+            catch (err) {
+                runtimeLog.warn('AgentHost', `wakeTap failed: ${err?.message || err}`);
+            }
+        }
         // The watchdog timer must be cleared once the tick settles — leaving it
         // armed pinned one live 2-minute timer per tick (and kept short-lived
         // processes/tests alive until it fired).
@@ -615,6 +803,22 @@ export class AgentHost {
             // not re-arm, or the lane would runtimeLog.error every timeoutMs forever.
             if (!result.stateTimeoutUnhandled)
                 this._armIfTimedParked(laneKey, result.state);
+            /**
+             * Only a wake that actually reached the brain counts as the asking turn.
+             *
+             * A notice-only wake (`type: 'notification'`) and a rate-gated one skip the
+             * LLM entirely, so the agent had no chance to ask — spending the lane's one
+             * turn on it, and failing the task straight after, killed the work before
+             * the wake that would have done it ever arrived. Hand the turn back instead
+             * and let the next real wake use it.
+             */
+            if ((result.metrics?.llmCalls ?? 0) > 0) {
+                await this.settleUnmetAfterAsk(laneKey);
+            }
+            else if (this.unmetTasksPendingAsk.has(laneKey)) {
+                this.unmetTasksPendingAsk.delete(laneKey);
+                this.askedForAccessLanes.delete(laneKey);
+            }
         }
         catch (err) {
             runtimeLog.warn('AgentHost', `tick failed laneKey=${laneKey}: ${err?.message || err}`);
@@ -642,6 +846,74 @@ export class AgentHost {
         }
         finally {
             clearTimeout(tickWatchdog);
+            // Also on the failure path: a tick that threw still must not leave the
+            // work it was refused for sitting active.
+            await this.settleUnmetAfterAsk(laneKey).catch(() => { });
+        }
+    }
+    /**
+     * Re-run one recorded wake against THIS host's agent, and nothing else.
+     *
+     * The dev loop for a prompt: record a wake off a live run, edit the agent, and
+     * see what it does differently in seconds instead of standing a world back up
+     * for one turn. The brain, tools and effect handler are the real ones, so the
+     * turn is real — its tool calls hit the backend this host is pointed at, which
+     * is why it belongs against a disposable world and not a shared one.
+     *
+     * Deliberately NOT routed through `_processEvent`: everything that method does
+     * around the tick is lane bookkeeping — session state, liveness timers, session
+     * persistence, ack decisions, failure re-arm — and a replay has no lane to keep.
+     * Borrowing that path would make a dev tool able to disturb a live one.
+     */
+    async replayWake(record) {
+        if (!record?.sessionId)
+            throw new Error('replayWake: record.sessionId is required');
+        const identity = {
+            agentId: record.agentId || this.options.agentId,
+            sessionId: record.sessionId,
+            laneKey: record.laneKey || record.sessionId,
+        };
+        // Same watchdog as a live wake, for the same reason: an unaborted Claude
+        // query outlives the promise that abandoned it and keeps spending.
+        const abort = new AbortController();
+        let watchdog;
+        try {
+            const result = await Promise.race([
+                this.agent.tick({
+                    event: record.event,
+                    ctx: record.ctx,
+                    state: record.state,
+                    identity,
+                    eff: this.eff,
+                    memory: this.memory,
+                    transitionTap: this.options.transitionTap,
+                    signal: abort.signal,
+                }),
+                new Promise((_, reject) => {
+                    watchdog = setTimeout(() => {
+                        abort.abort(new Error('tick timeout'));
+                        reject(new Error('tick timeout'));
+                    }, this.tickTimeoutMs);
+                }),
+            ]);
+            if (this.options.metricsTap && result.metrics) {
+                try {
+                    this.options.metricsTap({
+                        agentId: identity.agentId,
+                        sessionId: identity.sessionId,
+                        model: this.options.model ?? 'unknown',
+                        cognition: this.options.cognition ?? 'fsm',
+                        metrics: result.metrics,
+                    });
+                }
+                catch (err) {
+                    runtimeLog.warn('AgentHost', `metricsTap failed: ${err?.message || err}`);
+                }
+            }
+            return result;
+        }
+        finally {
+            clearTimeout(watchdog);
         }
     }
     /** Arms the lane's liveness timer iff stateName is a parked state declaring timeoutMs. */
@@ -694,32 +966,32 @@ export class AgentHost {
                     }
                 },
                 // exact-match triage in code — miss acks with 0 tokens.
-                onQuest: async (quest) => {
-                    await this.triageQuestDelivery(quest);
+                onRequest: async (request) => {
+                    await this.triageRequestDelivery(request);
                 },
             });
         }
         return this;
     }
     /**
-     * plain string compare against {@link AgentHostOptions.questMatchTags}
+     * plain string compare against {@link AgentHostOptions.requestMatchTags}
      * and `specialization`. No match → return (caller acks). Match → normal wake.
      */
-    async triageQuestDelivery(quest) {
+    async triageRequestDelivery(request) {
         const tags = [
-            ...(this.options.questMatchTags ?? []),
+            ...(this.options.requestMatchTags ?? []),
             ...(this.options.specialization ? [this.options.specialization] : []),
         ];
-        if (!questExactMatch(quest.match, tags)) {
-            runtimeLog.debug(this.options.name || 'agent', `quest ${quest.agreementId}: no tag match for ${JSON.stringify(quest.match)} — ack without wake`);
+        if (!requestExactMatch(request.match, tags)) {
+            runtimeLog.debug(this.options.name || 'agent', `request ${request.agreementId}: no tag match for ${JSON.stringify(request.match)} — ack without wake`);
             return;
         }
-        const needle = quest.match.trim();
-        const title = quest.title?.trim() || needle;
-        await this.handleMessage(`New marketplace quest matching your tags (${needle}): ${title}. Claim with agreement_claim if you will take it.`, {
-            messageId: `quest-wake:${quest.agreementId}:${quest.ts}`,
-            chatId: `marketplace:${quest.agreementId}`,
-            agreementId: quest.agreementId,
+        const needle = request.match.trim();
+        const title = request.title?.trim() || needle;
+        await this.handleMessage(`New marketplace request matching your tags (${needle}): ${title}. Claim with agreement_claim if you will take it.`, {
+            messageId: `request-wake:${request.agreementId}:${request.ts}`,
+            chatId: `marketplace:${request.agreementId}`,
+            agreementId: request.agreementId,
         });
     }
     async _bootstrapAssignedActiveTasks() {

package/dist/adapters/McpAdapter.js

@@ -56,12 +56,11 @@ export function resolveZiggsGatewayTarget(config, defaults = {}) {
     if (!agentId) {
         throw new Error('ziggs MCP transport requires an agentId to impersonate (X-Agent-Id)');
     }
-    // ZIG-1104: explicit overrides still win, but the LAST resort is
-    // `getBackendUrl()` — the resolution every other SDK call uses — not
-    // `localhost:3000`. The fleet task sets neither BACKEND_URL nor
-    // ZIGGS_BACKEND_URL (it sets HTTP_URL), so the old chain silently pointed every
-    // gateway call at localhost inside the container: the requests never reached the
-    // backend at all, and the agent reported the server as unreachable.
+    // 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 ||
@@ -85,12 +84,11 @@ export function resolvePerUserGatewayTarget(config, agentId, userId, onBehalfOfA
     if (!operatorKey) {
         throw new Error('ziggs-per-user MCP transport requires an operatorKey (or ZIGGS_OPERATOR_KEY)');
     }
-    // ZIG-1104: explicit overrides still win, but the LAST resort is
-    // `getBackendUrl()` — the resolution every other SDK call uses — not
-    // `localhost:3000`. The fleet task sets neither BACKEND_URL nor
-    // ZIGGS_BACKEND_URL (it sets HTTP_URL), so the old chain silently pointed every
-    // gateway call at localhost inside the container: the requests never reached the
-    // backend at all, and the agent reported the server as unreachable.
+    // 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 ||

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -52,6 +52,15 @@ export interface ClaudeSdkAgentOptions {
  * that is all the CLI gives us — no code, no typed error — so keep it narrow
  * enough that a different failure never claims the retry.
  */
+/**
+ * "I ran out of turns", as Claude Code reports it.
+ *
+ * Turn exhaustion is not a crash: the wake did real work and stopped at a cap
+ * we set. It arrives as a thrown error result with no code and no type, so the
+ * message is all there is to match on — kept narrow so no other failure claims
+ * the handling.
+ */
+export declare function isMaxTurnsError(err: unknown): boolean;
 export declare function isMissingSessionError(err: unknown): boolean;
 /**
  * A Ziggs agent whose brain is the Claude Agent SDK. Same host, same `eff`