@ziggs-ai/agent-sdk 0.24.1 → 0.26.0

package/dist/brain/hostedToolSurface.js

@@ -0,0 +1,207 @@
+/**
+ * What the hosted Claude brain mounts into the model.
+ *
+ * The MCP door already lists only the everyday set plus a catalog. This is
+ * that same cut for the in-process brain: everyday SDK tools stay loaded by
+ * name, agent-owned tools stay loaded by name, and every other Ziggs platform
+ * tool is named by `tools` and called through `tool_read` or `tool_write`.
+ * The tools stay registered on the ToolManager — the FSM brain and the
+ * dispatcher both call them — they just stop riding every wake as schemas.
+ */
+import { EVERYDAY_SDK_TOOLS, annotationForSdkTool } from '@ziggs-ai/api-client';
+import { defineTool, toolName } from '../tools/defineTool.js';
+/**
+ * Platform tools written by hand, not as a shared capability. Their lane is
+ * what the dispatcher uses; a name here is also a platform name, so it leaves
+ * the model block unless it is in the everyday set.
+ */
+const HAND_LANE = {
+    context_snapshot: 'read-only',
+    chat_send: 'write',
+    wake_at: 'write',
+    agreement_propose: 'write',
+    agreement_subcontract: 'write',
+    agreement_respond: 'write',
+    agreement_counter: 'write',
+    agreement_get: 'read-only',
+    agreement_revoke: 'destructive',
+    agreement_fulfill: 'write',
+    task_set_result: 'write',
+    task_update_plan_step: 'write',
+    task_create: 'write',
+    task_replace_plan: 'write',
+    mcp_tools_list: 'read-only',
+    mcp_tool_call: 'write',
+    connection_list_grants: 'read-only',
+};
+const EVERYDAY = new Set(EVERYDAY_SDK_TOOLS);
+const CATALOG_NAMES = ['tools', 'tool_read', 'tool_write'];
+const CATALOG = new Set(CATALOG_NAMES);
+export function hostedToolLane(name) {
+    const hand = HAND_LANE[name];
+    if (hand)
+        return hand;
+    const annotation = annotationForSdkTool(name);
+    if (annotation === 'read-only' || annotation === 'destructive')
+        return annotation;
+    return 'write';
+}
+function isPlatform(name) {
+    return name in HAND_LANE || annotationForSdkTool(name) !== undefined;
+}
+/** A Ziggs platform tool the model reaches through the catalog, not by schema. */
+export function isHostedCatalogOnly(name) {
+    return isPlatform(name) && !EVERYDAY.has(name);
+}
+function oneLine(description, name) {
+    const text = String(description ?? name).replace(/\s+/g, ' ').trim();
+    const sentence = text.split(/(?<=\.)\s/)[0] ?? text;
+    return sentence.length > 180 ? `${sentence.slice(0, 177)}...` : sentence;
+}
+function callLine(name, lane, native) {
+    if (lane === 'destructive') {
+        return `call it by name only: ${name}; the dispatchers refuse it`;
+    }
+    const dispatcher = lane === 'read-only' ? 'tool_read' : 'tool_write';
+    if (native) {
+        return `call it by name: ${name}; ${dispatcher} { tool: "${name}", args } also works`;
+    }
+    return `call via ${dispatcher} { tool, args }`;
+}
+function rowFor(tool) {
+    const name = toolName(tool) ?? '';
+    const lane = hostedToolLane(name);
+    const native = !isHostedCatalogOnly(name);
+    return {
+        name,
+        line: oneLine(tool.schema.function['description'], name),
+        readOnly: lane === 'read-only',
+        native,
+        call: callLine(name, lane, native),
+    };
+}
+function refuseWrongLane(name, lane, via) {
+    if (lane === 'destructive') {
+        throw new Error(`${name} cannot be called through ${via}: it is irreversible, and it is loaded directly so the call names what it does. Call ${name} by name.`);
+    }
+    const readOnly = lane === 'read-only';
+    const askedRead = via === 'tool_read';
+    if (readOnly === askedRead)
+        return;
+    throw new Error(readOnly
+        ? `${name} is read-only: call it with tool_read { tool, args }, not tool_write.`
+        : `${name} changes state: call it with tool_write { tool, args }, not tool_read.`);
+}
+/**
+ * The Claude bridge does not call a tool's handler. It emits `tool-call`, and
+ * the effect handler looks the name up on the ToolManager. A catalog call has
+ * to go back through that same effect so the target still gets the timeline,
+ * the write keys, and the wake scope. A direct executor is only for a caller
+ * that has no effect handler (a schema probe, a unit test).
+ */
+async function callCatalogTarget(name, payload, ctx, execute) {
+    const eff = ctx.eff;
+    const sessionId = typeof ctx.chatId === 'string' ? ctx.chatId
+        : typeof ctx.sessionId === 'string' ? ctx.sessionId
+            : undefined;
+    if (typeof eff === 'function' && sessionId) {
+        const result = await eff({
+            kind: 'tool-call',
+            sessionId,
+            name,
+            args: payload,
+            senderId: typeof ctx.senderId === 'string' ? ctx.senderId : undefined,
+            senderType: typeof ctx.senderType === 'string' ? ctx.senderType : undefined,
+            onBehalfOfAgreementId: typeof ctx.onBehalfOfAgreementId === 'string' ? ctx.onBehalfOfAgreementId : undefined,
+            serviceAgreementId: typeof ctx.serviceAgreementId === 'string' ? ctx.serviceAgreementId : undefined,
+            runId: typeof ctx.runId === 'string' ? ctx.runId : undefined,
+            writeKeys: ctx.writeKeys,
+            memory: ctx.memory,
+        });
+        const settled = result;
+        if (settled && settled.ok === false)
+            throw new Error(settled.error ?? `${name} failed`);
+        if (settled && 'ok' in settled)
+            return settled.result;
+        return result;
+    }
+    if (!execute)
+        throw new Error('hosted catalog has no executor');
+    return execute(name, payload, ctx);
+}
+function catalogTools(present, execute) {
+    const list = () => [...present.values()].map(rowFor).sort((a, b) => a.name.localeCompare(b.name));
+    const toolsTool = defineTool('tools', {
+        search: {
+            type: 'string',
+            description: 'Filter by name or the one-line description. Omit to list every tool.',
+        },
+        describe: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Tool names whose full schema you want before calling them.',
+        },
+    }, async (args) => {
+        const describe = Array.isArray(args.describe) ? args.describe.map(String) : [];
+        if (describe.length > 0) {
+            return describe.map((name) => {
+                const tool = present.get(name);
+                if (!tool) {
+                    return { name, error: `No such tool: ${name}. Call tools for the full list of names.` };
+                }
+                return { ...rowFor(tool), schema: tool.schema.function };
+            });
+        }
+        const q = typeof args.search === 'string' ? args.search.toLowerCase() : '';
+        return list().filter((row) => !q || row.name.includes(q) || row.line.toLowerCase().includes(q));
+    }, {
+        description: 'Every Ziggs tool that exists: name plus one line. A handful are already loaded by name; the rest are called through tool_read or tool_write. Pass describe with tool names to get their full schemas. Nothing is hidden.',
+    });
+    const dispatch = (via) => async (args, ctx) => {
+        const name = typeof args.tool === 'string' ? args.tool : '';
+        if (!name || !present.has(name)) {
+            throw new Error(`No such tool: ${name || '(missing)'}. Call tools for the full list of names.`);
+        }
+        refuseWrongLane(name, hostedToolLane(name), via);
+        const payload = args.args && typeof args.args === 'object' && !Array.isArray(args.args)
+            ? args.args
+            : {};
+        return callCatalogTarget(name, payload, ctx, execute);
+    };
+    const toolRead = defineTool('tool_read', {
+        tool: { type: 'string', required: true, description: 'Read-only tool name from tools.' },
+        args: { type: 'object', description: 'Arguments for that tool, as its schema defines them.' },
+    }, dispatch('tool_read'), {
+        description: 'Call a read-only Ziggs tool by name. A tool that writes is refused here and pointed at tool_write. Look it up with tools describe=[name] first when you do not already know its parameters. The result is exactly what the tool itself returns.',
+    });
+    const toolWrite = defineTool('tool_write', {
+        tool: { type: 'string', required: true, description: 'Writing tool name from tools.' },
+        args: { type: 'object', description: 'Arguments for that tool, as its schema defines them.' },
+    }, dispatch('tool_write'), {
+        description: 'Call a Ziggs tool that creates or changes something, by name. Read-only tools are refused here and pointed at tool_read. Irreversible tools (agreement_revoke) are called by their own name only — this dispatcher refuses them. Look the tool up with tools describe=[name] first when you do not already know its parameters.',
+    });
+    return [toolsTool, toolRead, toolWrite];
+}
+/**
+ * The tool block the hosted model is shown.
+ *
+ * `execute` runs a catalog call through the ToolManager. Omit it when only
+ * the schemas are being priced — the dispatchers then refuse to run.
+ */
+export function hostedModelTools(all, execute) {
+    const present = new Map();
+    for (const tool of all) {
+        const name = toolName(tool);
+        if (!name || CATALOG.has(name))
+            continue;
+        present.set(name, tool);
+    }
+    const visible = [];
+    for (const [name, tool] of present) {
+        if (isHostedCatalogOnly(name))
+            continue;
+        visible.push(tool);
+    }
+    visible.push(...catalogTools(present, execute));
+    return visible;
+}

package/dist/brain/wakeGate.d.ts

@@ -0,0 +1,48 @@
+import type { RawEvent } from '../runtime/buildOutcome.js';
+/**
+ * The wake gate: ask the backend whether chat messages need a
+ * model turn before the Claude brain starts one.
+ *
+ * The backend asks Jev (TypeSafe's System One model) one Choice — "asks this
+ * agent to act now" or "context to read later" — and answers `wake: false`
+ * only on a confident "context". The key lives there, not here: hosts run on
+ * customers' machines.
+ */
+export interface WakeGateMessage {
+    text: string;
+    senderId?: string;
+}
+export interface WakeGateRequest {
+    messages: WakeGateMessage[];
+    agreementId?: string;
+    chatId?: string;
+}
+export interface WakeGateAnswer {
+    wake: boolean;
+    /** `act` | `context` | `unsure` | `off`, as the backend decided. */
+    how?: string;
+    confidence?: number;
+}
+/** Null means "no answer": the caller wakes as it always has. */
+export type AskWakeGate = (req: WakeGateRequest) => Promise<WakeGateAnswer | null>;
+/**
+ * The messages this wake may ask about, or null when it may not ask at all.
+ *
+ * Only a wake made entirely of chat speech with text is asked about. Anything
+ * else in the batch — a task result, an agreement lifecycle event, a notice —
+ * wakes as today, decided here in code before Jev is involved: an assigned
+ * task, a control request (pause, stop) and a proposal naming this agent must
+ * never be skipped, and none of them is a `message`.
+ */
+export declare function gateableMessages(event: RawEvent | undefined): WakeGateMessage[] | null;
+/** The agreement the wake names, for the cost record. First one wins. */
+export declare function wakeAgreementId(event: RawEvent | undefined): string | undefined;
+/**
+ * The default gate: `POST /internal/wake-gate` with the agent's operator key.
+ * Any failure — network, timeout, a refusal, a body without `wake` — is null,
+ * so a backend that predates the route costs one 404 and changes nothing.
+ */
+export declare function backendWakeGate(creds: {
+    operatorKey: string;
+    agentId: string;
+}): AskWakeGate;

package/dist/brain/wakeGate.js

@@ -0,0 +1,76 @@
+import { buildOperatorHeaders, getBackendUrl } from '@ziggs-ai/api-client';
+import { getBatchEvents } from '../context/batch.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+/** Longer than Jev's own 4s budget on the server, shorter than a turn is worth waiting for. */
+const TIMEOUT_MS = 6000;
+/**
+ * The messages this wake may ask about, or null when it may not ask at all.
+ *
+ * Only a wake made entirely of chat speech with text is asked about. Anything
+ * else in the batch — a task result, an agreement lifecycle event, a notice —
+ * wakes as today, decided here in code before Jev is involved: an assigned
+ * task, a control request (pause, stop) and a proposal naming this agent must
+ * never be skipped, and none of them is a `message`.
+ */
+export function gateableMessages(event) {
+    const events = getBatchEvents(event);
+    if (events.length === 0)
+        return null;
+    const out = [];
+    for (const ev of events) {
+        if (!ev || ev.type !== 'message')
+            return null;
+        const text = typeof ev.text === 'string' ? ev.text.trim() : '';
+        if (!text)
+            return null;
+        out.push({
+            text,
+            ...(typeof ev.senderId === 'string' && ev.senderId ? { senderId: ev.senderId } : {}),
+        });
+    }
+    return out;
+}
+/** The agreement the wake names, for the cost record. First one wins. */
+export function wakeAgreementId(event) {
+    for (const ev of getBatchEvents(event)) {
+        const id = ev?.agreementId;
+        if (typeof id === 'string' && id)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * The default gate: `POST /internal/wake-gate` with the agent's operator key.
+ * Any failure — network, timeout, a refusal, a body without `wake` — is null,
+ * so a backend that predates the route costs one 404 and changes nothing.
+ */
+export function backendWakeGate(creds) {
+    return async (req) => {
+        if (!creds.operatorKey)
+            return null;
+        try {
+            const res = await fetch(`${getBackendUrl()}/internal/wake-gate`, {
+                method: 'POST',
+                headers: {
+                    ...buildOperatorHeaders(creds.operatorKey, creds.agentId),
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(req),
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                await res.body?.cancel().catch(() => undefined);
+                runtimeLog.warn('wakeGate', `wake gate answered ${res.status} — waking as usual`);
+                return null;
+            }
+            const data = (await res.json().catch(() => null));
+            if (!data || typeof data.wake !== 'boolean')
+                return null;
+            return data;
+        }
+        catch (err) {
+            runtimeLog.warn('wakeGate', `wake gate unreachable (${err?.name ?? 'error'}) — waking as usual`);
+            return null;
+        }
+    };
+}

package/dist/index.d.ts

@@ -67,8 +67,10 @@ export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormat
 export { ProactiveTrigger } from './platform/proactive/ProactiveTrigger.js';
 export { PollRegistry, declaredPolls, type PollBinding, type PollContext, type PollKind, type PollResult, } from './platform/polls/PollKind.js';
 export { PollRunner, type PollRunnerOptions, type WakeTarget } from './platform/polls/PollRunner.js';
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
 export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
+export { hostedModelTools, isHostedCatalogOnly, hostedToolLane } from './brain/hostedToolSurface.js';
+export type { HostedToolExecute } from './brain/hostedToolSurface.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
 export type { MemoryStore } from './memory/MemoryStore.js';

package/dist/index.js

@@ -79,10 +79,11 @@ export {
 // Tier 1 — protocol grammar (framework-managed via taskTools).
 PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, 
 // Tier 2 — opt-in capability bundles (spread into `tools:`).
-PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
+PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
 // The always-on toolset for the hosted Claude cognition (parity guard
 // reads this as part of the real SDK registry).
 export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
+export { hostedModelTools, isHostedCatalogOnly, hostedToolLane } from './brain/hostedToolSurface.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
 export { InMemoryStore, FileMemoryStore } from './memory/MemoryStore.js';
 export { classifyIncomingEvent } from './context/classifyEnvelope.js';

package/dist/ingress/normalizeIncoming.d.ts

@@ -5,6 +5,7 @@ export interface NormalizedEvent {
         senderId?: string;
         senderType?: string;
         receiverId?: string;
+        assigneeId?: string;
         /**
          * Backend per-delivery id of the chat row this event came from. The one
          * field of the event that is identical on live push and on catch-up
@@ -58,6 +59,7 @@ interface WireMetadata {
     };
     /** Inbox rewrite: assigned mail is this agent's even when the chat row names a human. */
     receiverId?: string;
+    assigneeId?: string;
     task?: WireTask;
     service?: {
         conversationAgreementId?: string;

package/dist/ingress/normalizeIncoming.js

@@ -113,6 +113,7 @@ export function normalizeIncomingEvent({ text, metadata = {} }) {
         senderId: metadata.sender?.id,
         senderType,
         receiverId: receiverId || undefined,
+        assigneeId: typeof metadata.assigneeId === 'string' ? metadata.assigneeId : undefined,
         messageId: typeof metadata.messageId === 'string' && metadata.messageId ? metadata.messageId : undefined,
         timestamp: Date.now(),
         ...(entryType ? { entryType } : {}),

package/dist/platform/ZiggsEffectHandler.d.ts

@@ -36,7 +36,7 @@ export interface ZiggsEffectDeps {
     contextReadClient: ContextReadClient;
     taskService: TaskService;
     agreementService: AgreementService;
-    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string, conversationAgreementId?: string) => Promise<unknown>;
+    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string, conversationAgreementId?: string, underAgreementId?: string, taskId?: string) => Promise<unknown>;
     /** Sends a streaming chunk to a client. Called per-token during stream-text effects. */
     chunkSender?: (sessionId: string, receiverId: string, text: string, messageId: string) => void;
     toolManager: ToolManager;

package/dist/platform/ZiggsEffectHandler.js

@@ -313,7 +313,7 @@ export function createZiggsEffectHandler(deps) {
                 });
             }
             case 'send-message': {
-                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId);
+                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId, effect.underAgreementId, effect.taskId);
                 outbox.track(effect.sessionId, { text: effect.text, receiverId: effect.receiverId });
                 // Carry the send's own report back to whoever asked for the send. A
                 // sender that cannot see where its message went cannot tell a delivered

package/dist/platform/inboxLoop.d.ts

@@ -1,4 +1,4 @@
-import { type InboxChatNews, type InboxDeliveryRef, 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
@@ -60,19 +60,13 @@ export interface InboxPassResult {
  * the wake — it does not buy a canned answer.
  */
 export declare function chatsInWakeOrder(chats: InboxChatNews[]): InboxChatNews[];
-/**
- * The one hire a chat's assigned deliveries name, or null when the room
- * has none or more than one. Memory (and acting-for) treat "several
- * customers in one room" as the shared section.
- */
-export declare function soleHireAgreementIdForChat(deliveries: readonly Pick<InboxDeliveryRef, 'chatId' | 'agreementId' | 'assigneeId'>[], chatId: string, ownAgentId: string): string | null;
 /**
  * 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.
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, opts?: {
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, _opts?: {
     forceAck?: boolean;
 }): Promise<InboxPassResult>;
 export interface InboxLoopHandle {
@@ -94,11 +88,7 @@ export interface InboxLoopHandle {
      */
     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.
- */
+/** Count held windows so retries can back off without discarding mail. */
 export declare function heldPassAfter(prev: number, pass: Pick<InboxPassResult, 'acked' | 'failures' | 'truncated'>): number;
 /**
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls