@ziggs-ai/agent-sdk 0.15.0 → 0.17.0

package/dist/{server → platform}/ConnectionPool.js

@@ -1,7 +1,7 @@
 /**
  * ConnectionPool — the agents this launcher process hosts.
  *
- * Holds N `AgentHostOptions` configs and connects every one of them at boot
+ * Holds N `AgentOptions` configs and connects every one of them at boot
  *. Each host long-polls its own inbox for the life of the process —
  * there is no agent socket. There is no subset, no cap and no lifecycle policy:
  * a write releasing that poll is the only signal anything needs.
@@ -14,7 +14,7 @@
  * answer was "none of them".
  */
 import { ConnectionManager } from '@ziggs-ai/api-client';
-import { AgentHost } from '../AgentHost.js';
+import { createAgent } from '../Agent.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 export class ConnectionPool {
     manager = new ConnectionManager();
@@ -48,7 +48,7 @@ export class ConnectionPool {
                 const cfg = this.configs.get(agentId);
                 const originalTap = cfg.effectTap;
                 const pool = this;
-                const host = new AgentHost({
+                const host = createAgent({
                     ...cfg,
                     effectTap(effect, response) {
                         if (effect.kind === 'send-message') {
@@ -72,7 +72,11 @@ export class ConnectionPool {
     }
     /** Connect every registered agent. Reports the ones that could not come up. */
     async connectAll() {
-        return this.manager.connectAll();
+        await this.manager.connectAll();
+        const connected = this.listActive().length;
+        if (connected !== this.size) {
+            throw new Error(`Only ${connected}/${this.size} agents started; process must restart`);
+        }
     }
     /** The host for one agent, connecting it if it somehow is not up yet. */
     async startAgent(agentId) {
@@ -181,6 +185,14 @@ export class ConnectionPool {
     query(filter) { return this.manager.query(filter); }
     list() { return this.manager.list(); }
     listActive() { return this.manager.listActive(); }
+    /**
+     * Inbox liveness for every live agent in this process. The runner's health
+     * route answers from this rather than from "the HTTP server replied", which
+     * a wedged process does happily while none of its agents read anything.
+     */
+    liveness() {
+        return [...this.hosts.values()].map((host) => host.inboxLiveness());
+    }
     get size() { return this.manager.size; }
     getMeta(id) { return this.manager.getMeta(id); }
 }

package/dist/{server → platform}/EventQueue.d.ts

@@ -7,7 +7,7 @@ export interface EventQueueBusyLane {
     queued: number;
     processing: boolean;
 }
-/** Outcome of `waitForIdle` / `AgentHost.drain`. Timeout is data, not a throw. */
+/** Outcome of `waitForIdle` / `Agent.drain`. Timeout is data, not a throw. */
 export interface WaitForIdleResult {
     idle: boolean;
     timedOut: boolean;

package/dist/{server → platform}/StateTimers.d.ts

@@ -6,7 +6,7 @@ export interface StateTimeoutEvent {
 }
 /**
  * Per-lane liveness timers for parked states declaring timeoutMs. Owned by
- * AgentHost. A firing timer enqueues a state-timeout frame on the SAME lane
+ * Agent. A firing timer enqueues a state-timeout frame on the SAME lane
  * (caller-provided enqueue → EventQueue), so it serializes behind any real
  * event and can never race one. Epochs make stale frames identifiable: a
  * queued timeout frame whose epoch is not the lane's currently-armed epoch was

package/dist/{server → platform}/StateTimers.js

@@ -1,7 +1,7 @@
 import { runtimeLog } from '../shared/runtimeLog.js';
 /**
  * Per-lane liveness timers for parked states declaring timeoutMs. Owned by
- * AgentHost. A firing timer enqueues a state-timeout frame on the SAME lane
+ * Agent. A firing timer enqueues a state-timeout frame on the SAME lane
  * (caller-provided enqueue → EventQueue), so it serializes behind any real
  * event and can never race one. Epochs make stale frames identifiable: a
  * queued timeout frame whose epoch is not the lane's currently-armed epoch was

package/dist/{server → platform}/ZiggsEffectHandler.d.ts

@@ -1,14 +1,14 @@
 /**
  * Ziggs-flavored EffectHandler.
  *
- * Translates the Agent's pure Effect requests into concrete backend calls:
+ * Translates the brain's Effect requests into concrete backend calls:
  * reads go through the grant-fenced ContextReadClient snapshot, writes through
  * artifactsClient / taskService / agreementService / messageSender, and LLM
- * turns through the adapter. This is the only place where Agent intent meets
+ * turns through the adapter. This is the only place where brain intent meets
  * backend reality.
  *
- * Lives in agent-sdk for now alongside `Agent`; destined for a separate
- * `@ziggs-ai/agent-server` package once the SDK split is complete.
+ * Belongs to the SDK body. The operator runner owns process startup and
+ * health serving; it does not perform the brain’s effects.
  */
 import type { Effect, EffectHandler, LlmMessage, LlmResponse, LlmToolSchema, ToolCallResult } from '../types.js';
 /** Minimal LLM adapter contract — OpenAIAdapter satisfies this. */

package/dist/{server → platform}/ZiggsEffectHandler.js

@@ -115,7 +115,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     const argsPreview = previewToolArgs(args);
     // #6 — breadcrumbs are best-effort. Awaiting them bracketed every
     // tool call; a slow/wedged artifacts backend stalled the whole wake. Match
-    // ClaudeSdkAgent thought writes (fire-and-forget).
+    // ClaudeBrain thought writes (fire-and-forget).
     void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
         state: 'started',
         tool: effect.name,
@@ -230,7 +230,7 @@ export function createZiggsEffectHandler(deps) {
             case 'read-context': {
                 // Grant-fenced aggregate read: the backend composes the ContextSnapshot
                 // (GET /context/snapshot) through the same access + temporal fence as
-                // the per-type reads. Every producer — ClaudeSdkAgent.tick, runTurn,
+                // the per-type reads. Every producer — ClaudeBrain.tick, runTurn,
                 // and the on-demand context_snapshot tool — routes through here.
                 const snap = await buildSnapshot(deps, effect.sessionId, deps.agentId, {
                     limit: effect.opts?.maxMessages,

package/dist/{server → platform}/agreements/AgreementService.d.ts

@@ -1,4 +1,4 @@
-import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType } from '@ziggs-ai/api-client';
+import { type Agreement, type ClaimedKind, type ClaimOptions, type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput, type PublishOfferPayload, type UnifiedProposeInput, type ProposeShape, type DelegateAgreementData, type CounterAgreementData, type CreateLinkBody, type CreateLinkResult, type ListAgreementsFilters, type GetMyAgreementsFilters, type ChatLinkType, type ArtifactLinkType } from '@ziggs-ai/api-client';
 export declare class AgreementService {
     private creds;
     constructor(operatorKey: string, agentId: string);
@@ -12,6 +12,15 @@ export declare class AgreementService {
     proposeBroadcast(payload: ProposeBroadcastInput): Promise<Agreement>;
     /** @deprecated Alias for {@link proposeDirect}. */
     propose(payload: ProposeAgreementData): Promise<Agreement>;
+    /**
+     * One propose grammar (direct / request / standing offer). Fleet pricing
+     * and the wake idempotency key stay on the caller — this is the shared
+     * routing, not a second copy of it.
+     */
+    proposeUnified(input: UnifiedProposeInput): Promise<{
+        agreement: Agreement;
+        shape: ProposeShape;
+    }>;
     /**
      * Seller-broadcast marketplace offer. `payload.audience` sets the `payer`
      * sentinel: 'everyone' (default, public) or 'org' (your active org only).

package/dist/{server → platform}/agreements/AgreementService.js

@@ -1,4 +1,4 @@
-import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, } from '@ziggs-ai/api-client';
+import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, proposeUnified, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createLink, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, linkArtifactToAgreement, getArtifactsForAgreement, } from '@ziggs-ai/api-client';
 export class AgreementService {
     creds;
     constructor(operatorKey, agentId) {
@@ -24,6 +24,14 @@ export class AgreementService {
     propose(payload) {
         return proposeAgreement(payload, this.creds);
     }
+    /**
+     * One propose grammar (direct / request / standing offer). Fleet pricing
+     * and the wake idempotency key stay on the caller — this is the shared
+     * routing, not a second copy of it.
+     */
+    proposeUnified(input) {
+        return proposeUnified(input, this.creds);
+    }
     /**
      * Seller-broadcast marketplace offer. `payload.audience` sets the `payer`
      * sentinel: 'everyone' (default, public) or 'org' (your active org only).

package/dist/{server → platform}/inboxLoop.d.ts

@@ -1,4 +1,4 @@
-import { type InboxRequestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
+import { type InboxChatNews, type InboxRequestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
 import { SeenMessages } from './SeenMessages.js';
 /**
  * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
@@ -53,6 +53,19 @@ export interface InboxPassResult {
      */
     failures: number;
 }
+/**
+ * Store publish waits on a `probe_*` chat reply, not inbox ack. Act those
+ * rooms before leftover mail so a standing host answers the gate even when
+ * the envelope also carries older chats.
+ */
+export declare function chatsInWakeOrder(chats: InboxChatNews[]): InboxChatNews[];
+/**
+ * Store publish waits on a chat reply, not inbox ack. The ordinary pass can
+ * already be inside leftover mail when that room appears, so a side read
+ * answers `probe_*` chats without waiting for the current pass to finish.
+ * It never acks — the main pass still owns the watermark.
+ */
+export declare function answerPublishProbes(deps: InboxLoopDeps): Promise<number>;
 /**
  * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
  * the deltas, deliver them into the host, and ack. Returns what it delivered.
@@ -67,7 +80,26 @@ export interface InboxLoopHandle {
     stop(): Promise<void>;
     /** True while the loop is running. */
     readonly running: boolean;
+    /**
+     * When this loop last completed a pass against the server — the one true
+     * liveness signal for an agent, and the same fact the store shows as online.
+     * Null until the first pass returns.
+     */
+    readonly lastPassAt: number | null;
+    /**
+     * When this loop last STARTED an iteration, successful or not. Separate from
+     * `lastPassAt` on purpose: a backend outage stops passes while the loop is
+     * perfectly healthy, so a restart decision reads this one and a staleness
+     * report reads the other. `running` says the loop exists; this says it turns.
+     */
+    readonly lastAttemptAt: number | null;
 }
+/**
+ * How many consecutive passes have refused to advance the watermark.
+ * A capped envelope used to reset the counter (zero handover failures),
+ * so `forceAck` never fired on the one hold that lasts forever.
+ */
+export declare function heldPassAfter(prev: number, pass: Pick<InboxPassResult, 'acked' | 'failures' | 'truncated'>): number;
 /**
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
  * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
@@ -82,4 +114,5 @@ export interface InboxLoopHandle {
  */
 export declare function runInboxLoop(deps: InboxLoopDeps, opts?: {
     waitSeconds?: number;
+    probePollMs?: number;
 }): InboxLoopHandle;

package/dist/{server → platform}/inboxLoop.js

@@ -8,6 +8,62 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
+/**
+ * Store publish waits on a `probe_*` chat reply, not inbox ack. Act those
+ * rooms before leftover mail so a standing host answers the gate even when
+ * the envelope also carries older chats.
+ */
+export function chatsInWakeOrder(chats) {
+    return [...chats].sort((a, b) => {
+        const ap = isPublishProbeChat(a.chatId) ? 0 : 1;
+        const bp = isPublishProbeChat(b.chatId) ? 0 : 1;
+        if (ap !== bp)
+            return ap - bp;
+        return a.latestAt < b.latestAt ? 1 : -1;
+    });
+}
+function isPublishProbeChat(chatId) {
+    return chatId.startsWith('probe_');
+}
+/**
+ * Store publish waits on a chat reply, not inbox ack. The ordinary pass can
+ * already be inside leftover mail when that room appears, so a side read
+ * answers `probe_*` chats without waiting for the current pass to finish.
+ * It never acks — the main pass still owns the watermark.
+ */
+export async function answerPublishProbes(deps) {
+    const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+    const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+    const envelope = await inbox.getInbox({});
+    const probes = (envelope.chats ?? []).filter((c) => isPublishProbeChat(c.chatId));
+    if (probes.length === 0)
+        return 0;
+    const mine = (d) => d.assigneeId === deps.ownAgentId;
+    const earliestByChat = new Map();
+    for (const d of envelope.deliveries) {
+        if (!d.chatId || !mine(d) || !isPublishProbeChat(d.chatId))
+            continue;
+        const seen = earliestByChat.get(d.chatId);
+        if (!seen || d.ts < seen)
+            earliestByChat.set(d.chatId, d.ts);
+    }
+    const attempt = async (what, handover) => {
+        try {
+            await handover();
+            return true;
+        }
+        catch (err) {
+            warn(deps.label ?? 'inboxLoop', `publish-probe ${what} was not handled: ${err?.message ?? err}`);
+            return false;
+        }
+    };
+    let delivered = 0;
+    for (const news of probes) {
+        const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
+        delivered += await deliverMessagesForChat(deps, news, earliest, reader, attempt);
+    }
+    return delivered;
+}
 /**
  * Standing proposals share the merged inbox visibility model with deliveries,
  * but older envelopes predate an explicit assignee stamp. Prefer the server's
@@ -116,9 +172,9 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         }
     };
     if (envelope.deliveriesCapped) {
-        // Informational only — does NOT block acking what WAS handed over. The
-        // tail stays unacked and arrives on the next pass; never acking here would
-        // make a badly backed-up agent replay its whole backlog forever.
+        // The listed window is the oldest CAP. Acking it slides the cursor; the
+        // newer tail stays past ackTo and arrives on the next pass. Holding here
+        // was the wedge: the same over-cap window came back forever.
         warn(label, 'inbox deliveriesCapped (more mail than one envelope carries — the tail follows on the next pass)');
     }
     // The single-assign law: a row is MINE to act on iff it carries my stamp.
@@ -136,7 +192,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         if (!seen || d.ts < seen)
             earliestByChat.set(d.chatId, d.ts);
     }
-    for (const news of envelope.chats) {
+    for (const news of chatsInWakeOrder(envelope.chats ?? [])) {
         const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
         const n = await deliverMessagesForChat(deps, news, earliest, reader, attempt);
         messagesDelivered += n;
@@ -195,7 +251,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     }
     // request channel. Triage is the host's job (exact string compare);
     // a miss must still count as handled so the watermark can advance with 0 tokens.
-    for (const request of envelope.requestsAwaitingMe ?? []) {
+    for (const request of envelope.openRequestsAwaitingMe ?? []) {
         const key = `request:${request.agreementId}:${request.ts}`;
         if (deps.seen.has(key))
             continue;
@@ -245,12 +301,7 @@ 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;
-    // 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`);
-    }
-    else if (envelope.ackTo && (failures === 0 || opts.forceAck)) {
+    if (envelope.ackTo && (failures === 0 || opts.forceAck)) {
         if (failures > 0) {
             runtimeLog.error(label, `acking a window that failed ${failures} handover(s) — giving up on redelivery to keep the ` +
                 `agent alive; this mail is lost (ackTo=${envelope.ackTo})`);
@@ -261,7 +312,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         const handledResourceIds = [
             ...new Set([
                 ...envelope.deliveries.filter(mine).map((d) => d.resourceId),
-                ...(envelope.requestsAwaitingMe ?? []).map((q) => q.agreementId),
+                ...(envelope.openRequestsAwaitingMe ?? []).map((q) => q.agreementId),
             ]),
         ].filter((id) => typeof id === 'string' && id.length > 0);
         await inbox.ack(envelope.ackTo, { handledResourceIds });
@@ -289,6 +340,16 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
  * some defaults ship with. Lower it if your deployment sits behind a shorter one.
  */
 const DEFAULT_WAIT_SECONDS = 110;
+/**
+ * Side-poll interval for store-publish `probe_*` rooms.
+ *
+ * Default **off**. A second GET /inbox beside the main long-poll burned the
+ * shared poll ceiling: every hosted agent side-polled, probes got 429s, and
+ * Register saw ALB HTML 504s. Main pass + probe-first ordering + pinned
+ * `probe_*` deliveries are enough; set `probePollMs` only when you knowingly
+ * need the extra loop.
+ */
+const DEFAULT_PROBE_POLL_MS = 0;
 const ERROR_BACKOFF_BASE_MS = 1_000;
 const ERROR_BACKOFF_MAX_MS = 30_000;
 /**
@@ -299,6 +360,14 @@ const ERROR_BACKOFF_MAX_MS = 30_000;
  * rather than an unbounded loop.
  */
 const MAX_HELD_PASSES = 3;
+/**
+ * How many consecutive passes have refused to advance the watermark.
+ * A capped envelope used to reset the counter (zero handover failures),
+ * so `forceAck` never fired on the one hold that lasts forever.
+ */
+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));
 }
@@ -317,21 +386,28 @@ function sleep(ms) {
 export function runInboxLoop(deps, opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
+    const probePollMs = opts.probePollMs ?? DEFAULT_PROBE_POLL_MS;
     let running = true;
     let consecutiveErrors = 0;
     let heldPasses = 0;
+    let lastPassAt = null;
+    let lastAttemptAt = null;
     let first = true;
-    const done = (async () => {
+    const main = (async () => {
         while (running) {
             try {
+                lastAttemptAt = Date.now();
                 const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds, {
                     forceAck: heldPasses >= MAX_HELD_PASSES,
                 });
+                lastPassAt = Date.now();
                 first = false;
                 consecutiveErrors = 0;
                 // A held pass means the same window comes back; count how many times we
                 // have refused it so a permanently unhandleable frame cannot spin here.
-                heldPasses = pass.failures > 0 && !pass.acked ? heldPasses + 1 : 0;
+                // Capped holds used to reset this: failures === 0, so the poison
+                // escape never climbed. Count any pass that refused to advance.
+                heldPasses = heldPassAfter(heldPasses, pass);
             }
             catch (err) {
                 if (!running)
@@ -356,10 +432,42 @@ export function runInboxLoop(deps, opts = {}) {
             }
         }
     })();
+    const probes = (async () => {
+        if (probePollMs <= 0)
+            return;
+        while (running) {
+            const slice = 50;
+            let left = probePollMs;
+            while (left > 0 && running) {
+                const step = Math.min(slice, left);
+                await sleep(step);
+                left -= step;
+            }
+            if (!running)
+                break;
+            try {
+                const n = await answerPublishProbes(deps);
+                if (n > 0)
+                    log(label, `publish-probe side poll delivered ${n} message(s)`);
+            }
+            catch (err) {
+                if (!running)
+                    break;
+                warn(label, `publish-probe side poll failed: ${err?.message ?? err}`);
+            }
+        }
+    })();
+    const done = Promise.all([main, probes]);
     return {
         get running() {
             return running;
         },
+        get lastPassAt() {
+            return lastPassAt;
+        },
+        get lastAttemptAt() {
+            return lastAttemptAt;
+        },
         async stop() {
             running = false;
             await done.catch(() => { });

package/dist/{server → platform}/polls/PollKind.d.ts

@@ -5,12 +5,9 @@
  *
  *   polls: [{ kind: 'sente-email', identityId: 'idt_...' }]
  *
- * It declares; it does not execute. Execution belongs to PollRunner, which the
- * launcher runs once for the whole fleet — polling is a fleet concern the way
- * the health server is, not a per-host behaviour: one loop per (agent, binding)
- * with its own interval, backoff and backpressure, instead of every host
- * hand-rolling a timer inside its message loop. Declaration travels with the
- * agent; execution does not.
+ * The declaration and its PollRunner travel with the Agent. connectAsync starts
+ * both inbox delivery and external polls; disconnect stops both. The process
+ * runner does not own a second copy of the polling lifecycle.
  *
  * A poll answers ONE question: is there work for this agent right now. It never
  * returns the work itself. The agent reads that for itself once woken, through
@@ -26,7 +23,7 @@
  * Kind-specific config, verbatim from the agent's manifest.
  *
  * `chatId` is not kind-specific and is not optional in practice: a wake has to
- * resolve to a lane or AgentHost's session resolver returns null and drops it
+ * resolve to a lane or Agent's session resolver returns null and drops it
  * silently. A poll has no engagement behind it to derive one from, so the
  * binding names the chat the agent thinks in — which also puts its triage
  * somewhere a human can watch. PollRunner refuses to register a binding without

package/dist/{server → platform}/polls/PollKind.js

@@ -5,12 +5,9 @@
  *
  *   polls: [{ kind: 'sente-email', identityId: 'idt_...' }]
  *
- * It declares; it does not execute. Execution belongs to PollRunner, which the
- * launcher runs once for the whole fleet — polling is a fleet concern the way
- * the health server is, not a per-host behaviour: one loop per (agent, binding)
- * with its own interval, backoff and backpressure, instead of every host
- * hand-rolling a timer inside its message loop. Declaration travels with the
- * agent; execution does not.
+ * The declaration and its PollRunner travel with the Agent. connectAsync starts
+ * both inbox delivery and external polls; disconnect stops both. The process
+ * runner does not own a second copy of the polling lifecycle.
  *
  * A poll answers ONE question: is there work for this agent right now. It never
  * returns the work itself. The agent reads that for itself once woken, through

package/dist/{server → platform}/polls/PollRunner.d.ts

@@ -1,11 +1,9 @@
 /**
- * PollRunner — executes declared polls for a whole fleet, outside any host.
+ * PollRunner — executes declared external wake sources for agents.
  *
- * Every host already long-polls its own Ziggs inbox; this applies the same wake
- * discipline to the sources Ziggs cannot see — mailboxes, feeds, whatever a
- * PollKind can ask. It runs in the launcher rather than inside any AgentHost
- * because none of it belongs to a host's message loop: a poll is per
- * (agent, binding) and carries its own interval, backoff and backpressure.
+ * Each Agent owns its runner and starts it with its inbox loop. A poll is per
+ * (agent, binding), with its own interval, backoff and backpressure. This same
+ * lifecycle applies to fleet, MCP-tool, lab and evaluation agents.
  *
  * One loop per (agent, binding), and each loop AWAITS its own wake before
  * scheduling the next tick. That is the whole backpressure story: while an
@@ -73,6 +71,7 @@ export declare class PollRunner {
     private readonly wakeWindowMs;
     private readonly loops;
     private running;
+    private generation;
     constructor({ pool, registry, agents, operatorKey, defaultIntervalMs, maxBackoffMs, wakeTimeoutMs, maxWakesPerWindow, wakeWindowMs, label, }: PollRunnerOptions);
     get size(): number;
     start(): void;

package/dist/{server → platform}/polls/PollRunner.js

@@ -1,11 +1,9 @@
 /**
- * PollRunner — executes declared polls for a whole fleet, outside any host.
+ * PollRunner — executes declared external wake sources for agents.
  *
- * Every host already long-polls its own Ziggs inbox; this applies the same wake
- * discipline to the sources Ziggs cannot see — mailboxes, feeds, whatever a
- * PollKind can ask. It runs in the launcher rather than inside any AgentHost
- * because none of it belongs to a host's message loop: a poll is per
- * (agent, binding) and carries its own interval, backoff and backpressure.
+ * Each Agent owns its runner and starts it with its inbox loop. A poll is per
+ * (agent, binding), with its own interval, backoff and backpressure. This same
+ * lifecycle applies to fleet, MCP-tool, lab and evaluation agents.
  *
  * One loop per (agent, binding), and each loop AWAITS its own wake before
  * scheduling the next tick. That is the whole backpressure story: while an
@@ -30,6 +28,7 @@ export class PollRunner {
     wakeWindowMs;
     loops = [];
     running = false;
+    generation = 0;
     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;
@@ -65,6 +64,7 @@ export class PollRunner {
                     chatId: binding.chatId,
                     timer: null,
                     failures: 0,
+                    inFlight: false,
                     wakes: 0,
                     windowStartedAt: Date.now(),
                     capped: false,
@@ -79,14 +79,18 @@ export class PollRunner {
         if (this.running)
             return;
         this.running = true;
+        this.generation++;
         if (!this.loops.length)
             return;
-        for (const loop of this.loops)
-            this.schedule(loop, 0);
+        for (const loop of this.loops) {
+            if (!loop.inFlight)
+                this.schedule(loop, 0);
+        }
         runtimeLog.info(this.label, `started — ${this.loops.length} poll(s): ${this.loops.map((l) => `${l.agentId}:${l.kind.id}`).join(', ')}`);
     }
     stop() {
         this.running = false;
+        this.generation++;
         for (const loop of this.loops) {
             if (loop.timer)
                 clearTimeout(loop.timer);
@@ -97,7 +101,14 @@ export class PollRunner {
     schedule(loop, delayMs = this.nextDelay(loop)) {
         if (!this.running)
             return;
-        loop.timer = setTimeout(() => void this.tick(loop), delayMs);
+        loop.timer = setTimeout(() => {
+            loop.timer = null;
+            loop.inFlight = true;
+            void this.tick(loop, this.generation).finally(() => {
+                loop.inFlight = false;
+                this.schedule(loop);
+            });
+        }, delayMs);
     }
     /** Interval while healthy; doubling up to the ceiling while failing. */
     nextDelay(loop) {
@@ -105,7 +116,7 @@ export class PollRunner {
             return loop.intervalMs;
         return Math.min(loop.intervalMs * 2 ** loop.failures, this.maxBackoffMs);
     }
-    async tick(loop) {
+    async tick(loop, generation = this.generation) {
         if (!this.running)
             return;
         let result;
@@ -119,9 +130,11 @@ export class PollRunner {
         catch (err) {
             loop.failures += 1;
             runtimeLog.error(this.label, `${loop.agentId}:${loop.kind.id} source failed (${loop.failures}x, next in ${this.nextDelay(loop)}ms): ${err.message}`);
-            this.schedule(loop);
             return;
         }
+        // A source read may finish after disconnect or a new connection.
+        if (!this.running || generation !== this.generation)
+            return;
         if (result?.actionable && this.claimWake(loop)) {
             const hint = result.hint ?? `New work from ${loop.kind.id}. Check it.`;
             try {
@@ -140,7 +153,6 @@ export class PollRunner {
                 runtimeLog.error(this.label, `${loop.agentId} wake failed (${loop.failures}x, next in ${this.nextDelay(loop)}ms): ${err.message}`);
             }
         }
-        this.schedule(loop);
     }
     /**
      * Take one wake from this binding's budget, or refuse.

package/dist/platform/polls/declaredPollRunner.d.ts

@@ -0,0 +1,4 @@
+import type { AgentOptions } from '../../Agent.js';
+import { PollRunner, type WakeTarget } from './PollRunner.js';
+/** Validate before starting any work, so a declared wake source cannot vanish. */
+export declare function createDeclaredPollRunner(options: AgentOptions, target: WakeTarget): PollRunner | null;

package/dist/platform/polls/declaredPollRunner.js

@@ -0,0 +1,29 @@
+import { PollRegistry } from './PollKind.js';
+import { PollRunner } from './PollRunner.js';
+/** Validate before starting any work, so a declared wake source cannot vanish. */
+export function createDeclaredPollRunner(options, target) {
+    const registry = new PollRegistry();
+    for (const kind of options.pollKinds ?? [])
+        registry.register(kind);
+    if (options.polls === undefined)
+        return null;
+    if (!Array.isArray(options.polls))
+        throw new Error('Agent: polls must be an array');
+    for (const binding of options.polls) {
+        if (!binding || !registry.get(binding.kind)) {
+            throw new Error(`Agent ${options.agentId}: unknown poll kind "${binding?.kind}"; declare its implementation in pollKinds`);
+        }
+        if (typeof binding.chatId !== 'string' || !binding.chatId.trim()) {
+            throw new Error(`Agent ${options.agentId}: poll "${binding.kind}" requires a chatId`);
+        }
+    }
+    if (!options.polls.length)
+        return null;
+    return new PollRunner({
+        pool: target,
+        registry,
+        agents: [{ agentId: options.agentId, polls: options.polls }],
+        operatorKey: options.operatorKey,
+        label: `${options.name || options.agentId}-polls`,
+    });
+}