@ziggs-ai/agent-sdk 0.10.0 → 0.10.2

package/dist/server/EventQueue.js

@@ -4,6 +4,12 @@ import { runtimeLog } from '../shared/runtimeLog.js';
  * batch dispatch. The runtime sees at most one in-flight processEvent call
  * per laneKey at a time; multiple events arriving while busy are merged
  * into a single { type: 'batch', events: [...] } frame on the next pass.
+ *
+ * ZIG-1191: `enqueue` REJECTS when the dispatch failed. It used to log the error
+ * and resolve, which made every caller — including the inbox loop, whose next
+ * statement is the ack — unable to tell a handled event from a lost one. A
+ * caller that has nothing to do with a failure should say so with `.catch()`;
+ * the one holding a delivery must not have that decision made for it.
  */
 export class EventQueue {
     _processEvent;
@@ -28,9 +34,12 @@ export class EventQueue {
             state = { events: [], processing: false };
             this._state.set(laneKey, state);
         }
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
             this._metrics.enqueued += 1;
-            state.events.push({ event, resolve });
+            state.events.push({
+                event,
+                settle: (err) => (err === undefined ? resolve() : reject(err)),
+            });
             this._trimQueueIfNeeded(state, laneKey);
             this._processIfNeeded(laneKey);
         });
@@ -49,21 +58,25 @@ export class EventQueue {
         while (state.events.length > 0) {
             const batch = state.events.splice(0, state.events.length);
             const events = batch.map(e => e.event);
-            const resolvers = batch.map(e => e.resolve);
+            const settlers = batch.map(e => e.settle);
             const coalesced = events.length === 1
                 ? events[0]
                 : { type: 'batch', events };
+            // Coalescing makes the batch the unit of success: the lane ran one tick
+            // for all of it, so a failure belongs to every event that was merged in.
+            let failure;
             try {
                 await this._processEvent(coalesced, laneKey);
             }
             catch (error) {
+                failure = error ?? new Error('processEvent failed');
                 this._metrics.errors += 1;
                 runtimeLog.error('EventQueue', `processEvent error for laneKey=${laneKey}: ${error?.message || error}`);
             }
             this._metrics.processedBatches += 1;
             this._metrics.processedEvents += events.length;
-            for (const r of resolvers)
-                r();
+            for (const settle of settlers)
+                settle(failure);
         }
         state.processing = false;
     }
@@ -71,7 +84,9 @@ export class EventQueue {
         while (state.events.length > this._maxQueueLengthPerLane) {
             const dropped = state.events.shift();
             this._metrics.dropped += 1;
-            dropped?.resolve();
+            // A dropped event was never handled, so its caller hears about it — the
+            // inbox loop holds the ack instead of acking work that fell off the queue.
+            dropped?.settle(new Error(`EventQueue dropped an event on laneKey=${laneKey} (queue over ${this._maxQueueLengthPerLane})`));
             runtimeLog.warn('EventQueue', `dropped oldest event laneKey=${laneKey} max=${this._maxQueueLengthPerLane}`);
         }
     }

package/dist/server/SeenMessages.d.ts

@@ -10,4 +10,11 @@ export declare class SeenMessages {
     constructor(maxSize?: number);
     has(messageId: string | null | undefined): boolean;
     mark(messageId: string | null | undefined): void;
+    /**
+     * Forget a mark, so the next delivery of the same id is processed rather than
+     * skipped. ZIG-1191: marking happens BEFORE the work, to hold the door against
+     * a concurrent duplicate — which means a failure has to take the mark back, or
+     * the redelivery that a held ack buys is silently dropped as a duplicate.
+     */
+    unmark(messageId: string | null | undefined): void;
 }

package/dist/server/SeenMessages.js

@@ -28,4 +28,19 @@ export class SeenMessages {
                 this.seen.delete(oldest);
         }
     }
+    /**
+     * Forget a mark, so the next delivery of the same id is processed rather than
+     * skipped. ZIG-1191: marking happens BEFORE the work, to hold the door against
+     * a concurrent duplicate — which means a failure has to take the mark back, or
+     * the redelivery that a held ack buys is silently dropped as a duplicate.
+     */
+    unmark(messageId) {
+        if (!messageId || typeof messageId !== 'string')
+            return;
+        if (!this.seen.delete(messageId))
+            return;
+        const at = this.order.indexOf(messageId);
+        if (at !== -1)
+            this.order.splice(at, 1);
+    }
 }

package/dist/server/ZiggsEffectHandler.d.ts

@@ -67,6 +67,7 @@ export declare function executeToolWithSideEffects(deps: Pick<ZiggsEffectDeps, '
 }>, roster: {
     agents: unknown[];
     users: unknown[];
+    agreements?: unknown[];
 }): Promise<ToolCallResult>;
 /**
  * Build a single shared EffectHandler. The handler is stateful — it caches

package/dist/server/ZiggsEffectHandler.js

@@ -109,11 +109,14 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     const toolT0 = Date.now();
     const args = effect.args || {};
     const argsPreview = previewToolArgs(args);
-    await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
+    // ZIG-1120 #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).
+    void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
         state: 'started',
         tool: effect.name,
         ...(argsPreview ? { args: argsPreview } : {}),
-    }, effect.wakeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }));
+    }, effect.writeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }));
     try {
         const lastUser = roster.users.find((u) => u.userId || u.id);
         // Accumulate token usage from any nested LLM call the tool makes (llmTool),
@@ -142,22 +145,25 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             eff,
             agents: roster.agents,
             users: roster.users,
+            // ZIG-1120 #8 — session snapshot already has agreements; protocolRunner
+            // used to re-fetch them over HTTP on every spawn/subcontract.
+            agreements: roster.agreements ?? [],
             senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
             senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
             onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
             memory: effect.memory,
-            wakeKeys: effect.wakeKeys,
+            writeKeys: effect.writeKeys,
             reportUsage,
             turnScratch: {},
         });
         // One clip per tool call: this is a full JSON.stringify of the untruncated
         // result, and the artifact body and the idempotency key want the same string.
         const clipped = clipForOperationArtifact(result);
-        await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
+        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
             state: 'completed',
             tool: effect.name,
             result: clipped,
-        }, effect.wakeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }));
+        }, effect.writeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }));
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -171,11 +177,11 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     catch (error) {
         const errMsg = error?.message ?? String(error);
         runtimeLog.warn('ZiggsEffectHandler', `tool-call "${effect.name}" failed: ${errMsg}`);
-        await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
+        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
-        }, effect.wakeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }));
+        }, effect.writeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }));
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -277,14 +283,15 @@ export function createZiggsEffectHandler(deps) {
                 return { text, usage };
             }
             case 'tool-call': {
-                // Roster comes from the cached snapshot (populated by read-context). Both
-                // cognitions land here — the FSM via runTurn's executeTool, the Claude
-                // Agent SDK via the toolManagerToSdkMcp bridge — so tool side effects are
-                // emitted exactly once, in one place (ZIG-775).
+                // Roster + agreements come from the cached snapshot (populated by
+                // read-context). Both cognitions land here — the FSM via runTurn's
+                // executeTool, the Claude Agent SDK via the toolManagerToSdkMcp bridge —
+                // so tool side effects are emitted exactly once, in one place (ZIG-775).
                 const cached = cacheGet(effect.sessionId);
                 return executeToolWithSideEffects(deps, handler, effect, {
                     agents: cached?.agents || [],
                     users: cached?.users || [],
+                    agreements: cached?.agreements || [],
                 });
             }
             case 'send-message': {

package/dist/server/createHealthServer.js

@@ -19,7 +19,7 @@ function readJsonBody(req) {
 export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents', pool, } = {}) {
     const server = createServer(async (req, res) => {
         const url = req.url ?? '/';
-        const startMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
+        const startMatch = url.match(/^\/fleet-start\/([^/?]+)/);
         if (req.method === 'POST' && startMatch && pool) {
             const agentId = decodeURIComponent(startMatch[1]);
             try {

package/dist/server/inboxLoop.d.ts

@@ -1,4 +1,4 @@
-import { type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
+import { type InboxQuestRef, 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
@@ -26,6 +26,12 @@ export interface InboxLoopDeps {
      * for it (chat-less agreement, self-assigned task).
      */
     onTask?: (task: InboxTaskRef) => Promise<void>;
+    /**
+     * A marketplace quest doorbell (ZIG-1185). The host MUST triage with a plain
+     * string compare and return without an LLM wake on miss — otherwise every
+     * public quest burns a full Claude turn per published supplier.
+     */
+    onQuest?: (quest: InboxQuestRef) => Promise<void>;
     label?: string;
 }
 export interface InboxPassResult {
@@ -35,10 +41,17 @@ export interface InboxPassResult {
     resourceEvents: number;
     /** Assigned open tasks delivered this pass (ZIG-973). */
     tasksDelivered: number;
+    /** Quest refs triaged this pass (ZIG-1185) — includes misses that only ack. */
+    questsTriaged: number;
     /** True when the watermark advanced this pass. */
     acked: boolean;
     /** True when there was more mail than one envelope carries. */
     truncated: boolean;
+    /**
+     * Handovers into the host that failed this pass (ZIG-1191). Non-zero means the
+     * watermark was deliberately held, so the same window arrives again.
+     */
+    failures: number;
 }
 /**
  * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
@@ -46,7 +59,9 @@ export interface InboxPassResult {
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number): Promise<InboxPassResult>;
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, opts?: {
+    forceAck?: boolean;
+}): Promise<InboxPassResult>;
 export interface InboxLoopHandle {
     /** Stop the loop after the current pass; resolves when it has fully exited. */
     stop(): Promise<void>;

package/dist/server/inboxLoop.js

@@ -15,7 +15,7 @@ function warn(label, msg) {
  * reads through `/context/read`, where the agent's own grants fence what it is
  * allowed to see. A delivery reference is an address, never an authorisation.
  */
-async function deliverMessagesForChat(deps, news, earliestTs, reader) {
+async function deliverMessagesForChat(deps, news, earliestTs, reader, attempt) {
     let delivered = 0;
     let remaining = news.count;
     // `after` is exclusive, so step back a millisecond to include the oldest
@@ -55,8 +55,11 @@ async function deliverMessagesForChat(deps, news, earliestTs, reader) {
             const text = typeof row.text === 'string' ? row.text : '';
             if (!text.trim())
                 continue;
-            await deps.onMessage(text, { ...row, chatId: news.chatId });
-            delivered++;
+            // The host un-marks its own `seen` entry when a message fails, so there is
+            // nothing to forget here — but the failure still holds the watermark.
+            const handled = await attempt(`chat ${news.chatId} message ${messageId}`, () => deps.onMessage(text, { ...row, chatId: news.chatId }));
+            if (handled)
+                delivered++;
             remaining--;
         }
         if (!page.hasMore || !page.latestSequence)
@@ -72,7 +75,7 @@ async function deliverMessagesForChat(deps, news, earliestTs, reader) {
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export async function pollInboxOnce(deps, waitSeconds = 0) {
+export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
     const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
@@ -80,6 +83,24 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
     let messagesDelivered = 0;
     let resourceEvents = 0;
     let tasksDelivered = 0;
+    let questsTriaged = 0;
+    let failures = 0;
+    // ZIG-1191: a handover that failed must not be acked, and must not be
+    // remembered as seen — otherwise the redelivery the held watermark buys is
+    // dropped as a duplicate. One failure does not abandon the rest of the
+    // envelope: the others are still delivered, and the watermark waits for all.
+    const attempt = async (what, handover, forget) => {
+        try {
+            await handover();
+            return true;
+        }
+        catch (err) {
+            failures++;
+            forget?.();
+            warn(label, `${what} was not handled: ${err?.message ?? err} — holding the ack`);
+            return false;
+        }
+    };
     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
@@ -97,7 +118,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
     }
     for (const news of envelope.chats) {
         const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
-        const n = await deliverMessagesForChat(deps, news, earliest, reader);
+        const n = await deliverMessagesForChat(deps, news, earliest, reader, attempt);
         messagesDelivered += n;
         if (n > 0)
             log(label, `chat ${news.chatId} delivered ${n} message(s)`);
@@ -105,14 +126,16 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
     // Everything that is not chat text is handed over as a resource event, from
     // the delivery itself — the reference already carries the ids the host needs,
     // so nothing has to be re-derived to name what changed.
+    // Quests must never take this path (ZIG-1185) — even if a pre-cut server
+    // left them in `deliveries`, skip so they cannot wake the LLM before triage.
     for (const d of envelope.deliveries) {
-        if (d.kind === 'message')
+        if (d.kind === 'message' || d.kind === 'quest')
             continue;
         const key = `delivery:${d.kind}:${d.resourceId}:${d.ts}`;
         if (deps.seen.has(key))
             continue;
         deps.seen.mark(key);
-        await deps.onResourceEvent({
+        const handled = await attempt(`${d.kind} ${d.resourceId}`, () => deps.onResourceEvent({
             kind: d.kind,
             ts: d.ts,
             resourceId: d.resourceId,
@@ -120,8 +143,9 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
             ...(d.agreementId ? { agreementId: d.agreementId } : {}),
             ...(d.taskId ? { taskId: d.taskId } : {}),
             change: 'created',
-        });
-        resourceEvents++;
+        }), () => deps.seen.unmark(key));
+        if (handled)
+            resourceEvents++;
     }
     // ZIG-973: the work channel. An open assigned task is redelivered on every
     // pass until it closes (that IS the durable-wait contract), so dedup on
@@ -133,13 +157,35 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
             continue;
         deps.seen.mark(key);
         if (deps.onTask) {
-            await deps.onTask(task);
-            tasksDelivered++;
+            const handled = await attempt(`task ${task.taskId}`, () => deps.onTask(task), () => deps.seen.unmark(key));
+            if (handled)
+                tasksDelivered++;
         }
     }
     if (envelope.truncatedTasks) {
         warn(label, `inbox truncatedTasks=${envelope.truncatedTasks} (more assigned tasks than one pass surfaces — they appear as earlier ones close)`);
     }
+    // ZIG-1185: quest 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 quest of envelope.questsAwaitingMe ?? []) {
+        const key = `quest:${quest.agreementId}:${quest.ts}`;
+        if (deps.seen.has(key))
+            continue;
+        deps.seen.mark(key);
+        if (deps.onQuest) {
+            const handled = await attempt(`quest ${quest.agreementId}`, () => deps.onQuest(quest), () => deps.seen.unmark(key));
+            if (handled)
+                questsTriaged++;
+        }
+        else {
+            // No handler → still count as handled (ack) so an old host cannot wedge
+            // forever on quest mail it does not understand.
+            questsTriaged++;
+        }
+    }
+    if (envelope.truncatedQuests) {
+        warn(label, `inbox truncatedQuests=${envelope.truncatedQuests} (more quests than one pass surfaces — the tail follows on the next pass)`);
+    }
     // Pending decisions are standing state, not deliveries: they keep appearing
     // until answered, so dedup them the same way tasks are deduped.
     for (const proposal of envelope.proposalsAwaitingMe) {
@@ -147,36 +193,60 @@ export async function pollInboxOnce(deps, waitSeconds = 0) {
         if (deps.seen.has(key))
             continue;
         deps.seen.mark(key);
-        await deps.onResourceEvent({
+        const handled = await attempt(`pending proposal ${proposal.agreementId}`, () => deps.onResourceEvent({
             kind: 'agreement',
             ts: proposal.proposedAt ?? new Date().toISOString(),
             resourceId: proposal.agreementId,
             agreementId: proposal.agreementId,
             change: 'created',
             reason: 'proposal_pending',
-        });
-        resourceEvents++;
+        }), () => deps.seen.unmark(key));
+        if (handled)
+            resourceEvents++;
     }
     // Act, then ack: everything above has been handed to the host, so the
     // watermark may now move past it. A crash before this point redelivers.
+    //
+    // ZIG-1191: "act" now means acted, not attempted. A pass with failures holds
+    // the watermark so the server redelivers the window — unless `forceAck` says
+    // 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;
-    if (envelope.ackTo) {
+    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})`);
+        }
         await inbox.ack(envelope.ackTo);
         acked = true;
         log(label, `acked up to ${envelope.ackTo}`);
     }
+    else if (envelope.ackTo) {
+        warn(label, `holding the watermark at ${envelope.ackTo} — ${failures} handover(s) failed this pass, so the ` +
+            'window will be redelivered');
+    }
     return {
         deliveries: envelope.deliveries.length,
         messagesDelivered,
         resourceEvents,
         tasksDelivered,
+        questsTriaged,
         acked,
         truncated: envelope.deliveriesCapped,
+        failures,
     };
 }
 const DEFAULT_WAIT_SECONDS = 25;
 const ERROR_BACKOFF_BASE_MS = 1_000;
 const ERROR_BACKOFF_MAX_MS = 30_000;
+/**
+ * How many passes in a row may hold the watermark before the window is treated
+ * as poison and acked away (ZIG-1191). Three is enough for the failures we have
+ * actually seen — a redeployed container, a wedged backend, a transient throw —
+ * and short enough that a frame the host can never handle costs three wakes
+ * rather than an unbounded loop.
+ */
+const MAX_HELD_PASSES = 3;
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -197,13 +267,19 @@ export function runInboxLoop(deps, opts = {}) {
     const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
     let running = true;
     let consecutiveErrors = 0;
+    let heldPasses = 0;
     let first = true;
     const done = (async () => {
         while (running) {
             try {
-                await pollInboxOnce(deps, first ? 0 : waitSeconds);
+                const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds, {
+                    forceAck: heldPasses >= MAX_HELD_PASSES,
+                });
                 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;
             }
             catch (err) {
                 if (!running)

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

@@ -0,0 +1,72 @@
+/**
+ * PollKind — polling as a declared, pluggable thing, the way tools are.
+ *
+ * An agent lists the polls it depends on the same way it lists tools:
+ *
+ *   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.
+ *
+ * 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
+ * its own tools, so it cannot end up with a second, differently-shaped copy of
+ * its input and no way to tell which is current.
+ *
+ * WHERE THE CURSOR LIVES: in the source, whenever the source has one. Sente
+ * has `archived` on a message, so "already handled" is a fact about the
+ * mailbox, not something we mirror. A kind whose source has no such notion has
+ * to keep a cursor, and then it is the kind's business — never the agent's.
+ */
+/**
+ * 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
+ * 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
+ * one rather than let the wake evaporate at runtime.
+ */
+export interface PollBinding {
+    kind: string;
+    /** Chat the poll wake is delivered into. Required; see above. */
+    chatId?: string;
+    [key: string]: unknown;
+}
+export interface PollContext {
+    agentId: string;
+    operatorKey?: string;
+}
+export interface PollResult {
+    /** Whether the agent should be woken now. */
+    actionable: boolean;
+    /**
+     * One line telling the agent why it woke. Carries no payload — see above.
+     * Omit and the runner sends the kind's default.
+     */
+    hint?: string;
+}
+export interface PollKind {
+    id: string;
+    /** How often to run this kind. The runner's default applies when omitted. */
+    intervalMs?: number;
+    poll(binding: PollBinding, ctx: PollContext): Promise<PollResult>;
+}
+/**
+ * Kinds register here rather than being imported by the runner, so a
+ * source-specific kind ships with the agent that needs it and the SDK stays
+ * free of third-party dependencies.
+ */
+export declare class PollRegistry {
+    private readonly kinds;
+    register(kind: PollKind): this;
+    get(id: string): PollKind | undefined;
+    get ids(): string[];
+}
+/** Read an agent's declared polls off its config. Absent or malformed → none. */
+export declare function declaredPolls(config: Record<string, unknown>): PollBinding[];

package/dist/server/polls/PollKind.js

@@ -0,0 +1,53 @@
+/**
+ * PollKind — polling as a declared, pluggable thing, the way tools are.
+ *
+ * An agent lists the polls it depends on the same way it lists tools:
+ *
+ *   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.
+ *
+ * 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
+ * its own tools, so it cannot end up with a second, differently-shaped copy of
+ * its input and no way to tell which is current.
+ *
+ * WHERE THE CURSOR LIVES: in the source, whenever the source has one. Sente
+ * has `archived` on a message, so "already handled" is a fact about the
+ * mailbox, not something we mirror. A kind whose source has no such notion has
+ * to keep a cursor, and then it is the kind's business — never the agent's.
+ */
+/**
+ * Kinds register here rather than being imported by the runner, so a
+ * source-specific kind ships with the agent that needs it and the SDK stays
+ * free of third-party dependencies.
+ */
+export class PollRegistry {
+    kinds = new Map();
+    register(kind) {
+        if (!kind?.id)
+            throw new Error('PollRegistry: a poll kind needs an id');
+        if (this.kinds.has(kind.id))
+            throw new Error(`PollRegistry: duplicate poll kind "${kind.id}"`);
+        this.kinds.set(kind.id, kind);
+        return this;
+    }
+    get(id) {
+        return this.kinds.get(id);
+    }
+    get ids() {
+        return [...this.kinds.keys()];
+    }
+}
+/** Read an agent's declared polls off its config. Absent or malformed → none. */
+export function declaredPolls(config) {
+    const raw = config['polls'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((b) => !!b && typeof b === 'object' && typeof b.kind === 'string');
+}

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

@@ -0,0 +1,62 @@
+/**
+ * PollRunner — executes declared polls for a whole fleet, outside any host.
+ *
+ * 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.
+ *
+ * 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
+ * agent is still dealing with what it was woken for, its next poll has not
+ * happened yet, so it cannot be woken twice for the same thing. No in-flight
+ * bookkeeping, no dedup table — the source is authoritative and a poll that
+ * has not run yet cannot report anything stale.
+ *
+ * A failing source backs off exponentially and recovers on the first success.
+ * Without it a source that is down is hit at full rate indefinitely, which is
+ * how you get rate-limited by the thing you were trying to read.
+ */
+import { type PollRegistry } from './PollKind.js';
+/** The slice of ConnectionPool this needs. Kept narrow to avoid a cycle. */
+export interface WakeTarget {
+    sendTo(agentId: string, text: string, metadata?: Record<string, unknown>, opts?: {
+        timeoutMs?: number;
+    }): Promise<unknown>;
+}
+export interface PollRunnerOptions {
+    pool: WakeTarget;
+    registry: PollRegistry;
+    /** Registered agent configs — anything carrying `agentId` and maybe `polls`. */
+    agents: Record<string, unknown>[];
+    operatorKey?: string;
+    defaultIntervalMs?: number;
+    /** Ceiling on the failure backoff. Default 15 minutes. */
+    maxBackoffMs?: number;
+    /**
+     * How long a woken agent may take before the wake is treated as hung.
+     * Defaults to 5 minutes, matching the Claude-brain tick timeout — the pool's
+     * own `sendTo` default is 30s, which a legitimate multi-turn wake blows
+     * through every single time.
+     */
+    wakeTimeoutMs?: number;
+    label?: string;
+}
+export declare class PollRunner {
+    private readonly pool;
+    private readonly operatorKey?;
+    private readonly label;
+    private readonly maxBackoffMs;
+    private readonly wakeTimeoutMs;
+    private readonly loops;
+    private running;
+    constructor({ pool, registry, agents, operatorKey, defaultIntervalMs, maxBackoffMs, wakeTimeoutMs, label, }: PollRunnerOptions);
+    get size(): number;
+    start(): void;
+    stop(): void;
+    private schedule;
+    /** Interval while healthy; doubling up to the ceiling while failing. */
+    private nextDelay;
+    private tick;
+}