@ziggs-ai/agent-sdk 0.11.0 → 0.11.1

package/dist/agent/ClaudeSdkAgent.js

@@ -35,26 +35,30 @@ export function isNoticeOnlyWake(event, ownAgentId) {
 }
 const DEFAULT_STATE = 'ready';
 /**
- * Per-task turn cap. A wake drives one `query()` that may loop up to this many
- * internal turns; the tool schema + system prompt ride every turn, so this is
- * the direct multiplier on a task's token spend. 30 let a confused MCP agent
- * burn schema×30 per wake; brokered tasks (fetch → record → done) converge in a
- * handful of turns, so 12 is ample. Env-overridable (raise for genuinely long
- * agents). */
-const DEFAULT_MAX_TURNS = Number(process.env.CLAUDE_SDK_MAX_TURNS ?? 12);
+ * Per-wake turn cap — a runaway backstop, NOT a budget.
+ *
+ * Cost is bounded by the priced spend guard below, so this only has to sit above
+ * the longest honest job, with room for a retry inside it. A job that gathers
+ * before it works — reading the engagement, listing grants, discovering a
+ * connection's tools, pulling the data — spends around ten turns before it
+ * starts on the work it was hired for, then needs several more to draft, record
+ * the artifact and close the task. Set below that, the cap ends wakes with the
+ * gathering done and nothing filed.
+ */
+const DEFAULT_MAX_TURNS = Number(process.env.CLAUDE_SDK_MAX_TURNS ?? 30);
 /**
  * Hard ceiling on billable input tokens (incl. cache read/write) a single wake
- * may spend before we abort the query. Defense-in-depth on the shared fleet key
+ * may spend before we abort the query. Defense-in-depth on the host's LLM key
  * against a runaway loop; set high enough that normal tasks never trip it. The
  * task ends unfinished (and logs loudly) rather than burning unbounded. */
 const MAX_TASK_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_INPUT_TOKENS ?? 500_000);
 /**
  * Per-lane wake-rate circuit breaker. The per-wake caps above bound one wake;
- * nothing bounded the NUMBER of wakes — the agent-private artifact echo drove
- * one wake per wake, forever. The echo is fixed at the source (backend
- * targeting never routes an agent its own writes), so this is a backstop for
- * any future echo path: a lane waking faster than real traffic plausibly drives it
- * skips the LLM (and logs loudly) instead of draining the fleet key. */
+ * nothing bounds the NUMBER of wakes. An echo path — anything that turns an
+ * agent's own write back into a delivery addressed to it — drives one wake per
+ * wake, forever. Targeting never routes an agent its own writes, so this is a
+ * backstop: a lane waking faster than real traffic plausibly drives it skips the
+ * LLM (and logs loudly) instead of draining the key. */
 const WAKE_WINDOW_MS = 10 * 60_000;
 const MAX_WAKES_PER_WINDOW = Number(process.env.CLAUDE_SDK_MAX_WAKES_PER_WINDOW ?? 40);
 /**
@@ -77,6 +81,19 @@ const MAX_SESSION_RESUME_INPUT_TOKENS = Number(process.env.CLAUDE_SDK_MAX_SESSIO
  * 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 function isMaxTurnsError(err) {
+    const message = err?.message;
+    return (typeof message === 'string' &&
+        /reached maximum number of turns/i.test(message));
+}
 export function isMissingSessionError(err) {
     const message = err?.message;
     return (typeof message === 'string' &&
@@ -90,6 +107,32 @@ function billableInput(usage) {
         (usage.cache_read_input_tokens ?? 0) +
         (usage.cache_creation_input_tokens ?? 0));
 }
+/**
+ * The same tokens, priced.
+ *
+ * A cache READ bills at ~0.1x base input and a cache WRITE at ~1.25x. The spend
+ * guard below exists to stop a runaway from draining the key, so it has to count
+ * what the key is actually charged — and counting a cache read as a full input
+ * token makes every multi-turn wake look like a runaway. The transcript replays
+ * on every turn, so a 40k context over ten turns reads as 400k of "spend" while
+ * costing about a tenth of that: unpriced, the guard fires on ordinary work long
+ * before any runaway would, and it fires mid-job — right after the gathering
+ * calls and before the deliverable, which is the whole of "the wake ends before
+ * it files anything".
+ *
+ * Weights, not prices: the ratio between the three input kinds is stable across
+ * Claude models even as the per-million rates change, so this stays right
+ * without tracking a price table.
+ */
+const CACHE_READ_WEIGHT = 0.1;
+const CACHE_WRITE_WEIGHT = 1.25;
+function costWeightedInput(usage) {
+    if (!usage)
+        return 0;
+    return ((usage.input_tokens ?? 0) +
+        (usage.cache_read_input_tokens ?? 0) * CACHE_READ_WEIGHT +
+        (usage.cache_creation_input_tokens ?? 0) * CACHE_WRITE_WEIGHT);
+}
 /**
  * Per-API-call usage. Only assistant turns carry it — the result message's
  * usage is the CUMULATIVE total of the whole query, so adding it on top of
@@ -106,8 +149,8 @@ function extractMetrics(message) {
         return null;
     const usage = message.usage;
     // Billable input includes cache reads/writes — that is what the Anthropic
-    // console counts and what the fleet key pays for. Reporting only the
-    // uncached slice made our telemetry read ~10-20x under the real usage.
+    // console counts and what the key is charged for. Reporting only the uncached
+    // slice understates real usage by more than an order of magnitude.
     const input = billableInput(usage);
     const output = usage?.output_tokens ?? 0;
     // Cache read/write are already folded into `input` above; surfaced separately
@@ -351,7 +394,16 @@ export class ClaudeSdkAgent {
         });
         let metrics = { llmCalls: 0, tokens: { total: 0, input: 0, output: 0, cacheRead: 0, cacheCreation: 0 } };
         let sessionId = nextCtx.claudeSessionId;
+        // Cost-weighted, cumulative: what this wake has charged the key so far.
         let spentInput = 0;
+        // The transcript's SIZE, which is a different question from spend and needs
+        // a different measure: the largest single turn's input, unweighted. On the
+        // cumulative sum a lane with a modest transcript crosses the resume ceiling
+        // simply by taking enough turns, and forgets its session after every wake —
+        // so each wake re-gathers from zero and stalls at the same step.
+        let peakTurnInput = 0;
+        // Why the wake stopped, when it stopped on a guard rather than on its own.
+        let abortedBy = null;
         // stateless-per-wake never resumes — each wake is a fresh
         // transcript, so per-wake input stays flat instead of replaying the whole
         // lane history every turn.
@@ -408,11 +460,22 @@ export class ClaudeSdkAgent {
                         runtimeLog.warn('ClaudeSdkAgent', `query ended without success subtype=${message.subtype} session=${identity.sessionId}`);
                     }
                     // Runaway guard: abort before an unbounded loop drains the
-                    // shared fleet key. Breaking the for-await calls the generator's return(),
+                    // key. Breaking the for-await calls the generator's return(),
                     // which terminates the underlying query.
-                    spentInput += billableInput(usageOf(message));
+                    const turnUsage = usageOf(message);
+                    spentInput += costWeightedInput(turnUsage);
+                    peakTurnInput = Math.max(peakTurnInput, billableInput(turnUsage));
+                    // A wake that produced no per-turn usage still reports a cumulative
+                    // total on the result message. Divided by the turns it covers, that is
+                    // the average context per turn — a coarser read of the same transcript,
+                    // used only when the precise one is unavailable.
+                    if (message.type === 'result') {
+                        const turns = Math.max(1, message.num_turns ?? 1);
+                        peakTurnInput = Math.max(peakTurnInput, billableInput(message.usage) / turns);
+                    }
                     if (spentInput > MAX_TASK_INPUT_TOKENS) {
-                        runtimeLog.warn('ClaudeSdkAgent', `input-token budget exceeded (~${spentInput} > ${MAX_TASK_INPUT_TOKENS}) session=${identity.sessionId} agent=${this.agentId} — aborting query to cap spend`);
+                        abortedBy = 'input-budget';
+                        runtimeLog.warn('ClaudeSdkAgent', `input-token budget exceeded (~${Math.round(spentInput)} cost-weighted > ${MAX_TASK_INPUT_TOKENS}) session=${identity.sessionId} agent=${this.agentId} — aborting query to cap spend`);
                         break;
                     }
                 }
@@ -421,10 +484,34 @@ export class ClaudeSdkAgent {
                 signal?.removeEventListener('abort', onAbort);
             }
         };
+        /**
+         * Say, on the agent's own reasoning channel, that this wake stopped before
+         * it finished. Without the note a wake cut off by a guard is
+         * indistinguishable from one that delivered: the task stays `active` with
+         * `processing: false`, no artifact, no result, and nothing anywhere says
+         * why. The lane's history carries the reason instead, so a wedged-task
+         * detector has something to read.
+         */
+        const noteWakeCutShort = async (reason) => {
+            const text = `Wake stopped early: ${reason}. Work in progress was NOT filed — no ` +
+                `artifact was recorded and no task was closed by this wake.`;
+            await eff({
+                kind: 'record-event',
+                sessionId: identity.sessionId,
+                entry: { kind: 'thought', text },
+                idempotencyKey: writeKeys.artifactKey({ kind: 'thought', text }),
+            }).catch((err) => runtimeLog.warn('ClaudeSdkAgent', `record abort note failed session=${identity.sessionId}: ${err.message}`));
+        };
         try {
             await consumeQuery(resumeId);
         }
         catch (err) {
+            // Turn exhaustion arrives as a thrown error result, not a break, so it
+            // needs its own note before the throw propagates.
+            if (isMaxTurnsError(err)) {
+                abortedBy = 'max-turns';
+                await noteWakeCutShort(`the turn cap (${this.maxTurns}) was reached`);
+            }
             // the resumed transcript is gone. Claude Code stores transcripts
             // on the container's own disk while the session id outlives it — persisted
             // per lane in the session store with a 24h TTL — so a redeployed agents
@@ -445,6 +532,12 @@ export class ClaudeSdkAgent {
                 `session=${identity.sessionId} agent=${this.agentId} — retrying once on a fresh session`);
             nextCtx.claudeSessionId = undefined;
             sessionId = undefined;
+            // The first attempt failed before any turn ran, so it spent nothing and
+            // left no transcript. Carrying its counters into the retry would halve the
+            // budget the real attempt gets to work with.
+            spentInput = 0;
+            peakTurnInput = 0;
+            abortedBy = null;
             try {
                 await consumeQuery(undefined);
             }
@@ -460,17 +553,25 @@ export class ClaudeSdkAgent {
             nextCtx.claudeSessionId = undefined;
         else if (sessionId)
             nextCtx.claudeSessionId = sessionId;
-        // bound resumed-transcript growth. `metrics.tokens.input` is the
-        // wake's billable input off the result message (dominated by the resumed
-        // transcript's cache reads); `spentInput` covers an aborted wake that never
-        // produced a result. Past the ceiling, forget the session so the next wake
-        // starts fresh rather than paying an ever-larger replay.
-        const wakeInput = Math.max(metrics.tokens.input, spentInput);
-        if (nextCtx.claudeSessionId && wakeInput > MAX_SESSION_RESUME_INPUT_TOKENS) {
-            runtimeLog.info('ClaudeSdkAgent', `resetting Claude session (wake input ~${wakeInput} > ${MAX_SESSION_RESUME_INPUT_TOKENS}) ` +
+        // bound resumed-transcript growth. Past the ceiling, forget the session so
+        // the next wake starts fresh rather than paying an ever-larger replay.
+        //
+        // Measured as the largest SINGLE turn's input — that is the transcript,
+        // since every turn re-reads the whole thing. Summing the wake's turns
+        // instead measures how much WORK a wake did, not how much it carries: a lane
+        // whose transcript never leaves ~40k crosses the ceiling on turn five and
+        // drops its session on every wake. Resuming then never happens, so each wake
+        // re-reads the world from scratch and runs out of budget at the same step,
+        // and a standing job cannot advance.
+        if (nextCtx.claudeSessionId && peakTurnInput > MAX_SESSION_RESUME_INPUT_TOKENS) {
+            runtimeLog.info('ClaudeSdkAgent', `resetting Claude session (transcript ~${peakTurnInput} > ${MAX_SESSION_RESUME_INPUT_TOKENS}) ` +
                 `session=${identity.sessionId} agent=${this.agentId} — next wake starts fresh`);
             nextCtx.claudeSessionId = undefined;
         }
+        if (abortedBy === 'input-budget') {
+            await noteWakeCutShort(`the per-wake spend guard cut this run off (~${Math.round(spentInput)} ` +
+                `cost-weighted input tokens > ${MAX_TASK_INPUT_TOKENS})`);
+        }
         return {
             ctx: nextCtx,
             state: state ?? DEFAULT_STATE,

package/dist/agent/claudeSdkTools.js

@@ -25,16 +25,33 @@ function firstFilled(...candidates) {
     }
     return undefined;
 }
+/**
+ * Accept the agreement id an agent was woken on where a chat id is wanted.
+ *
+ * An agent woken on an agreement reaches for its context with the only id that
+ * wake gave it — the agreement's. That is not a chat id, so the snapshot came
+ * back empty: no history, no agreements, the agent itself as the only participant,
+ * and a bare `chatMissing`. Observed on the FIRST wake of every two-agent run,
+ * and once it sent the provider off to chat instead of to its own task.
+ *
+ * An agreement's implicit notification chat is `agrn-<agreementId>` — the lane
+ * the backend itself routes agreement traffic through — so the id the agent has
+ * does name a readable room, one prefix away. Mapping it is the difference
+ * between a wasted turn and an answer.
+ */
+function asChatLane(id) {
+    return id?.startsWith('agr_') ? `agrn-${id}` : id;
+}
 // Named distinctly from ziggs-mcp's per-type `ziggs_context_read`: this is the
 // one-shot aggregate snapshot (grant-fenced server-side), not a cursored read.
 export const contextSnapshotTool = defineTool('context_snapshot', {
-    chatId: { type: 'string', description: 'Omit this to snapshot the chat you were woken in — that is the usual case, and you do not need to know its id. Only pass a chatId to snapshot a DIFFERENT chat.' },
+    chatId: { type: 'string', description: 'Omit this to snapshot the chat you were woken in — that is the usual case, and you do not need to know its id. Only pass a chatId to snapshot a DIFFERENT chat. An agreement id is accepted too, and reads that agreement\'s lane.' },
     maxMessages: { type: 'number', description: `Message history cap (default ${DEFAULT_SNAPSHOT_MAX_MESSAGES}). Pass a larger value when you need deeper history.` },
 }, async (args, ctx) => {
     const c = ctx;
     if (!c.eff)
         throw new Error('context_snapshot requires eff in tool context');
-    const sessionId = firstFilled(args.chatId, c.chatId, c.sessionId);
+    const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
     if (!sessionId) {
         throw new Error('context_snapshot: this wake carries no chat to snapshot. Call it with no arguments ' +
             'to read the chat you were woken in; if this wake is on an agreement lane with no ' +
@@ -57,7 +74,9 @@ export const chatSendTool = defineTool('chat_send', {
     const c = ctx;
     if (!c.eff)
         throw new Error('chat_send requires eff in tool context');
-    const sessionId = firstFilled(args.chatId, c.chatId, c.sessionId);
+    // Same agreement-id-where-a-chat-id-goes slip as context_snapshot, and the
+    // same mapping: an agreement's traffic lane is `agrn-<agreementId>`.
+    const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
     if (!sessionId) {
         throw new Error('chat_send: this wake carries no chat to send in. Call it with no chatId to reply in ' +
             'the chat you were woken in, or pass the chatId of the chat you mean.');
@@ -92,9 +111,9 @@ export const chatSendTool = defineTool('chat_send', {
 // and a per-turn inbox poll fed the tool-operation echo loop.
 //
 // grant_list IS here: the hosted agent must always be able to answer
-// "what grants of mine do you hold?" across every rail — the 2026-07-20 incident
-// was a hosted agent with no grant-read tool telling its principal that lookup
-// doesn't exist. It reads operatorKey/agentId straight off the tool context.
+// "what grants of mine do you hold?" across every rail. Without the tool an
+// agent tells its principal the lookup does not exist. It reads
+// operatorKey/agentId straight off the tool context.
 //
 // task_list IS here: MCP delegates have ziggs_task_list; the hosted
 // Claude surface previously had no way to enumerate its own open tasks (reads

package/dist/defineAgent.js

@@ -3,6 +3,8 @@ import { injectKickoffDefault } from './runtime/kickoff.js';
 import { injectTaskIntakeDefault } from './runtime/taskIntake.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 import { DEFAULT_MODEL } from './AgentHost.js';
+import { normalizeNeeds, toolsForNeeds } from './tools/needs.js';
+import { toolName } from './tools/defineTool.js';
 /**
  * Validates the workflow synchronously, resolves merged tools and model, and
  * returns a frozen AgentConfig. Never mutates the input. `wait` defaults remain
@@ -44,10 +46,34 @@ export function defineAgent(input) {
     const { warnings } = validateWorkflow(workflow);
     for (const w of warnings)
         runtimeLog.warn('defineAgent', w);
-    const tools = [
+    // Tools the DECLARATION produces, not the author. An agent that says
+    // it needs a connection gets the tools to see and use one, so the prompt and
+    // the toolset cannot describe different worlds. Author tools come last and win
+    // on name, so hand-listing a derived tool is a no-op rather than a duplicate.
+    const needs = normalizeNeeds(input.needs);
+    const tools = [];
+    const positionByName = new Map();
+    for (const tool of [
+        ...toolsForNeeds(needs),
         ...(Array.isArray(input.tools) ? input.tools : []),
         ...(Array.isArray(input.services?.tools) ? input.services.tools : []),
-    ];
+    ]) {
+        const name = toolName(tool);
+        // A nameless entry cannot be deduped — keep it and let ToolManager reject
+        // it the way it always has, rather than silently dropping it here.
+        if (!name) {
+            tools.push(tool);
+            continue;
+        }
+        const at = positionByName.get(name);
+        if (at === undefined) {
+            positionByName.set(name, tools.length);
+            tools.push(tool);
+        }
+        else {
+            tools[at] = tool;
+        }
+    }
     // Model resolution, most-specific-first: a per-agent pin, then the
     // fleet-wide `LLM_MODEL` lever, then the single `DEFAULT_MODEL` fallback (the
     // ONE place the default lives — see AgentHost). The id also picks the provider
@@ -76,6 +102,9 @@ export function defineAgent(input) {
         ...(input.services ? { services: input.services } : {}),
         ...(taskTools !== undefined ? { taskTools } : {}),
         ...rest,
+        // After `rest`, so the config carries the NORMALIZED needs — AgentHost
+        // enforces these at task start and should not have to re-parse the raw field.
+        ...(needs.length ? { needs } : {}),
     };
     return Object.freeze(config);
 }

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export type { CognitionKind } from './agent/ClaudeSdkAgent.js';
 export { ziggsBrain, claudeBrain, isBrainSelection, isClaudeCognition } from './brain/index.js';
 export type { Brain, BrainSelection, ZiggsBrainConfig, ClaudeBrainConfig, } from './brain/index.js';
 export type { TickInput, TickOutput, AgentOptions } from './agent/Agent.js';
-export type { SessionResolver, AgentHostOptions } from './AgentHost.js';
+export type { SessionResolver, AgentHostOptions, WakeRecord } from './AgentHost.js';
 export { createZiggsEffectHandler } from './server/ZiggsEffectHandler.js';
 export type { ZiggsEffectDeps } from './server/ZiggsEffectHandler.js';
 export { EventQueue } from './server/EventQueue.js';
@@ -52,6 +52,8 @@ export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
 export { recordReport } from './tools/recordReport.js';
 export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
+export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
+export type { AgentNeed, ConnectionNeed } from './tools/needs.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';

package/dist/index.js

@@ -48,6 +48,9 @@ export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
 export { recordReport } from './tools/recordReport.js';
+// An agent declares the access it cannot work without, and the declaration
+// produces the tools for it.
+export { MCP_PROVIDER, describeNeed, normalizeNeeds, toolsForNeed, toolsForNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';

package/dist/pricing/fleetTierByAgentId.gen.d.ts

@@ -1,7 +1,7 @@
 /**
  * AUTO-GENERATED by scripts/build-fleet-tier-map.mjs — do not edit by hand.
- * agent-sdk local default pricing (backend uses agent.pricingTier).
+ * Local default pricing; the server resolves an agent's own pricing tier.
  */
 export type FleetPricingTier = 'A' | 'B' | 'C' | 'D';
 export declare const FLEET_TIER_BY_AGENT_ID: Record<string, FleetPricingTier>;
-export declare const FLEET_TIER_MAP_SIZE = 765;
+export declare const FLEET_TIER_MAP_SIZE = 772;

package/dist/pricing/fleetTierByAgentId.gen.js

@@ -11,11 +11,18 @@ export const FLEET_TIER_BY_AGENT_ID = {
     "shopper-agent": "D",
     "hire-agent": "B",
     "ziggs-docs-agent": "B",
+    "agent-definer": "B",
+    "linear-janitor": "B",
+    "shipped-digest": "B",
+    "docs-reviewer": "B",
+    "email-agent": "B",
     "relay-coordinator": "D",
+    "retry-coordinator": "D",
+    "scatter-coordinator": "D",
+    "race-coordinator": "D",
     "relay-intake-worker": "D",
     "relay-work-worker": "D",
     "relay-deliver-worker": "D",
-    "retry-coordinator": "D",
     "retry-fail-worker": "D",
     "retry-ok-worker": "D",
     "weather-forecaster": "A",
@@ -765,4 +772,4 @@ export const FLEET_TIER_BY_AGENT_ID = {
     "polar-researcher": "B",
     "death-studies-scholar": "B"
 };
-export const FLEET_TIER_MAP_SIZE = 765;
+export const FLEET_TIER_MAP_SIZE = 772;

package/dist/server/ZiggsEffectHandler.js

@@ -331,7 +331,16 @@ export function createZiggsEffectHandler(deps) {
     };
     const handler = async (effect) => {
         const response = await dispatch(effect);
-        deps.effectTap?.(effect, response);
+        // A tap observes; it must never decide the effect's fate. This call was bare,
+        // so a tap that threw took the effect down with it — and taps stringify
+        // arbitrary tool results, which throws on a circular value or a BigInt. The
+        // other two taps (metrics, wake) are already guarded; this is the last one.
+        try {
+            deps.effectTap?.(effect, response);
+        }
+        catch (err) {
+            runtimeLog.warn('ZiggsEffectHandler', `effectTap failed: ${err?.message || err}`);
+        }
         return response;
     };
     return handler;

package/dist/server/inboxLoop.js

@@ -216,10 +216,10 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     // this window has failed too many times in a row and is now poison, in which
     // case it is dropped loudly rather than wedging the agent forever.
     let acked = false;
-    // ZIG-1305 — a capped envelope has unlisted older deliveries behind ackTo;
+    // A capped envelope has unlisted older deliveries behind ackTo;
     // acking would refuse or bury them. Hold until a later uncapped pass.
     if (envelope.deliveriesCapped && envelope.ackTo) {
-        warn(label, `holding the watermark at ${envelope.ackTo} — deliveriesCapped; ack would not cover the unlisted tail (ZIG-1305)`);
+        warn(label, `holding the watermark at ${envelope.ackTo} — deliveriesCapped; ack would not cover the unlisted tail`);
     }
     else if (envelope.ackTo && (failures === 0 || opts.forceAck)) {
         if (failures > 0) {
@@ -251,7 +251,12 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         failures,
     };
 }
-const DEFAULT_WAIT_SECONDS = 25;
+/**
+ * Default long-poll hold for hosted agents. Matches the server's own ceiling,
+ * and assumes a proxy idle timeout comfortably above it rather than the 25s
+ * some defaults ship with. Lower it if your deployment sits behind a shorter one.
+ */
+const DEFAULT_WAIT_SECONDS = 110;
 const ERROR_BACKOFF_BASE_MS = 1_000;
 const ERROR_BACKOFF_MAX_MS = 30_000;
 /**

package/dist/server/polls/PollRunner.d.ts

@@ -41,6 +41,26 @@ export interface PollRunnerOptions {
      * through every single time.
      */
     wakeTimeoutMs?: number;
+    /**
+     * Most actionable wakes one binding may cause per {@link wakeWindowMs}.
+     * Default 20.
+     *
+     * A poll wakes its agent whenever the source says `actionable`, and each wake
+     * is a real model run. Nothing else bounds that: the agent polls the outside
+     * world and triggers itself, so the backend never sees it and the agreement
+     * wake ceiling never gets a chance to fire. A mailbox that stops being
+     * archived keeps answering "yes, there is unhandled mail" forever, at one wake
+     * per interval, indefinitely.
+     *
+     * 20 an hour is far above any healthy agent and roughly 20 minutes of a
+     * runaway at the 60s default interval.
+     *
+     * Deliberately a runner option and NOT read from the PollKind or the binding:
+     * a bound that the bounded thing can raise is not a bound.
+     */
+    maxWakesPerWindow?: number;
+    /** Window the wake cap is measured over. Default 1 hour. */
+    wakeWindowMs?: number;
     label?: string;
 }
 export declare class PollRunner {
@@ -49,9 +69,11 @@ export declare class PollRunner {
     private readonly label;
     private readonly maxBackoffMs;
     private readonly wakeTimeoutMs;
+    private readonly maxWakesPerWindow;
+    private readonly wakeWindowMs;
     private readonly loops;
     private running;
-    constructor({ pool, registry, agents, operatorKey, defaultIntervalMs, maxBackoffMs, wakeTimeoutMs, label, }: PollRunnerOptions);
+    constructor({ pool, registry, agents, operatorKey, defaultIntervalMs, maxBackoffMs, wakeTimeoutMs, maxWakesPerWindow, wakeWindowMs, label, }: PollRunnerOptions);
     get size(): number;
     start(): void;
     stop(): void;
@@ -59,4 +81,17 @@ export declare class PollRunner {
     /** Interval while healthy; doubling up to the ceiling while failing. */
     private nextDelay;
     private tick;
+    /**
+     * Take one wake from this binding's budget, or refuse.
+     *
+     * Refusing is announced once per window, at error level, and resuming is
+     * announced too. A poll that simply goes quiet is worse than one that wakes
+     * too much: from the outside it is indistinguishable from a mailbox that is
+     * genuinely empty, so nobody looks.
+     *
+     * The source keeps being polled while capped. Stopping the poll as well would
+     * mean the first tick after the window rolls is the one that discovers the
+     * backlog, and a source that recovered would go unnoticed for a whole window.
+     */
+    private claimWake;
 }

package/dist/server/polls/PollRunner.js

@@ -26,14 +26,18 @@ export class PollRunner {
     label;
     maxBackoffMs;
     wakeTimeoutMs;
+    maxWakesPerWindow;
+    wakeWindowMs;
     loops = [];
     running = false;
-    constructor({ pool, registry, agents, operatorKey, defaultIntervalMs = 60_000, maxBackoffMs = 15 * 60_000, wakeTimeoutMs = Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000), label = 'PollRunner', }) {
+    constructor({ pool, registry, agents, operatorKey, defaultIntervalMs = 60_000, maxBackoffMs = 15 * 60_000, wakeTimeoutMs = Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000), maxWakesPerWindow = 20, wakeWindowMs = 60 * 60_000, label = 'PollRunner', }) {
         this.pool = pool;
         this.operatorKey = operatorKey;
         this.label = label;
         this.maxBackoffMs = maxBackoffMs;
         this.wakeTimeoutMs = wakeTimeoutMs;
+        this.maxWakesPerWindow = maxWakesPerWindow;
+        this.wakeWindowMs = wakeWindowMs;
         for (const config of agents) {
             const agentId = config['agentId'];
             if (typeof agentId !== 'string' || !agentId)
@@ -61,6 +65,9 @@ export class PollRunner {
                     chatId: binding.chatId,
                     timer: null,
                     failures: 0,
+                    wakes: 0,
+                    windowStartedAt: Date.now(),
+                    capped: false,
                 });
             }
         }
@@ -115,7 +122,7 @@ export class PollRunner {
             this.schedule(loop);
             return;
         }
-        if (result?.actionable) {
+        if (result?.actionable && this.claimWake(loop)) {
             const hint = result.hint ?? `New work from ${loop.kind.id}. Check it.`;
             try {
                 // Awaited on purpose — see the header. The next tick waits for the
@@ -135,4 +142,37 @@ export class PollRunner {
         }
         this.schedule(loop);
     }
+    /**
+     * Take one wake from this binding's budget, or refuse.
+     *
+     * Refusing is announced once per window, at error level, and resuming is
+     * announced too. A poll that simply goes quiet is worse than one that wakes
+     * too much: from the outside it is indistinguishable from a mailbox that is
+     * genuinely empty, so nobody looks.
+     *
+     * The source keeps being polled while capped. Stopping the poll as well would
+     * mean the first tick after the window rolls is the one that discovers the
+     * backlog, and a source that recovered would go unnoticed for a whole window.
+     */
+    claimWake(loop) {
+        const now = Date.now();
+        if (now - loop.windowStartedAt >= this.wakeWindowMs) {
+            if (loop.capped) {
+                runtimeLog.info(this.label, `${loop.agentId}:${loop.kind.id} wake budget reset — waking again (cap ${this.maxWakesPerWindow}/${this.wakeWindowMs}ms)`);
+            }
+            loop.windowStartedAt = now;
+            loop.wakes = 0;
+            loop.capped = false;
+        }
+        if (loop.wakes >= this.maxWakesPerWindow) {
+            if (!loop.capped) {
+                loop.capped = true;
+                runtimeLog.error(this.label, `${loop.agentId}:${loop.kind.id} hit the wake cap (${this.maxWakesPerWindow} in ${this.wakeWindowMs}ms) and will NOT be woken again until the window rolls. ` +
+                    `The source keeps reporting actionable, so either it is genuinely that busy or something downstream stopped clearing it.`);
+            }
+            return false;
+        }
+        loop.wakes += 1;
+        return true;
+    }
 }

package/dist/server/tasks/TaskService.d.ts

@@ -8,10 +8,10 @@ export declare class TaskService {
     getActiveTasksForChat(chatId: string): Promise<Task[]>;
     getSubtasks(parentTaskId: string): Promise<Task[]>;
     spawnUnderAgreement(agreementId: string, taskData: Omit<CreateTaskData, 'agreementId'>): Promise<Task>;
-    updateState(taskId: string, state: TaskState, result?: unknown, idempotencyKey?: string): Promise<Task>;
-    updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task>;
-    cancel(taskId: string): Promise<Task>;
-    report(taskId: string, message?: string): Promise<Task>;
-    setSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<Task>;
+    updateState(taskId: string, state: TaskState, result?: unknown, idempotencyKey?: string): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
+    updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
+    cancel(taskId: string): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
+    report(taskId: string, message?: string): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
+    setSatisfaction(taskId: string, satisfaction: 'positive' | 'negative'): Promise<import("@ziggs-ai/api-client").TaskWriteConfirm>;
     count(filters?: CountTasksFilters): Promise<number>;
 }

package/dist/server/tools/tier2/mcpConnectionTools.js

@@ -4,7 +4,7 @@ import { ConnectionsClient } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
 import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
 /**
- * ZIG-1104 — calling a tool on a connected MCP server, one shot.
+ * Calling a tool on a connected MCP server, one shot.
  *
  * `connection_proxy` cannot do this. That path resolves a NAMED connector from
  * `connection.provider` and checks the action against its fixed action list; a

package/dist/tools/ToolManager.d.ts

@@ -1,5 +1,5 @@
 import { ToolProvider } from './ToolProvider.js';
-import type { ToolDefinition } from './defineTool.js';
+import { type ToolDefinition } from './defineTool.js';
 export declare class ToolManager extends ToolProvider {
     private tools;
     constructor();