@apnex/network-adapter 0.1.1 → 0.1.5

package/dist/tool-manager/orchestrator/dispatcher.js

@@ -0,0 +1,559 @@
+/**
+ * dispatcher.ts — tool-manager handler factory (Layer 1c).
+ *
+ * Host-independent shared abstraction that owns the MCP server's
+ * Initialize / ListTools / CallTool handlers and the supporting
+ * pending-action-queueItemId tracking + tool-catalog cache fallback +
+ * clientInfo capture + error-envelope normalization.
+ *
+ * Mounted by per-host shims (Layer 3) which add host-specific transport
+ * plumbing (stdio / Bun-HTTP / future) and host-specific render-surface
+ * via the `notificationHooks` callback bag (Universal Adapter
+ * notification contract).
+ *
+ * This module is the "tool-manager" per Design v1.2 §4 naming discipline
+ * (Director-ratified rename from "MCP-boundary dispatcher" 2026-04-26)
+ * — distinct from the "Message-router" which is sovereign-package #6
+ * (`@apnex/message-router`) landing in M-Push-Foundation W4. Always
+ * qualify ("tool-manager" or "Message-router") in new code; avoid bare
+ * "dispatcher".
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, InitializeRequestSchema, McpError, ErrorCode, } from "@modelcontextprotocol/sdk/types.js";
+import { MessageRouter, SeenIdCache } from "@apnex/message-router";
+import { PollBackstop, resolveRole } from "../../kernel/poll-backstop.js";
+import { ClaimableDigestTracker } from "../work-protocol/claimable-digest-tracker.js";
+import { WorkLeaseTracker } from "../work-protocol/work-lease-tracker.js";
+import { TOOL_CALL_SIGNAL_SKIP, pendingKey, injectQueueItemId, } from "../dispatch/tool-call-policy.js";
+import { runToolDispatch } from "../dispatch/dispatch.js";
+// M-Tool-Manager Slice B: the pure OIS tool-call policy helpers
+// (TOOL_CALL_SIGNAL_SKIP / pendingKey / injectQueueItemId) moved to
+// `./tool-call-policy.js` so the dispatch authority (`./dispatch.js`) and this
+// god-object shell share them without a circular import. They are imported
+// above (used internally) and RE-EXPORTED here so existing consumers
+// (index.ts, tests) are unaffected.
+export { TOOL_CALL_SIGNAL_SKIP, pendingKey, injectQueueItemId };
+// idea-355 §4.3 (review fix) — tight timeout on the wake/stall reconcile's Hub
+// read. The liveness heartbeat now runs concurrently with the reconcile (see
+// PollBackstop.tickHeartbeat), but this still bounds how long the reconcile can
+// hold the heartbeat cadence (heartbeatInFlight) and resource use. On timeout
+// the read is treated as a failed read (AC3 — tracker skipped, no false replay).
+const WAKE_STALL_READ_TIMEOUT_MS = 10_000;
+function withTimeout(p, ms, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+export function createSharedDispatcher(opts) {
+    const log = opts.log ?? (() => { });
+    const serverName = opts.serverName ?? "proxy";
+    const serverCapabilities = opts.serverCapabilities ?? { tools: {}, logging: {} };
+    const pendingActionMap = new Map();
+    // idea-353 W1 idle-gate: count of host-driven CallTool requests currently in
+    // flight. The wake/stall reconciler reads this on the heartbeat tick to avoid
+    // interrupting a mid-task agent (AC4). The tick's own internal `agent.call`s
+    // (list_ready_work etc.) do NOT pass through this handler, so an idle poll
+    // never self-gates.
+    let activeCallCount = 0;
+    let capturedClientInfo = {
+        name: "unknown",
+        version: "0.0.0",
+    };
+    const getClientInfo = () => capturedClientInfo;
+    function isUsableAgent(agent) {
+        return !!agent && agent.isConnected !== false;
+    }
+    // bug-141 retry budget. Bootstrap-path ListTools races the Hub
+    // handshake on cold-start; this retry window absorbs the gap before
+    // raising a structured error. Worst-case latency:
+    // (LIST_TOOLS_RETRY_ATTEMPTS - 1) × LIST_TOOLS_RETRY_DELAY_MS
+    // (~2.8s) before the error surfaces. Probe path remains <50ms via
+    // cached catalog.
+    //
+    // Pass-1 (2026-05-26, bug-141 initial fix) set 4 × 200ms = 600ms
+    // budget. Pass-2 (2026-05-28) bumped to 15 × 200ms = 2.8s after
+    // observing greg-side cold-starts where the McpAgentClient reached
+    // `streaming` state (agent.isConnected=true) ~1.3s after
+    // identityReady resolved — 4 attempts wasn't enough to bridge the
+    // race. The architecturally-correct fix is for hosts to wire
+    // listToolsGate to syncReady instead of identityReady (claude-
+    // plugin shim does this); the wider retry budget defends opencode-
+    // plugin + any host that doesn't wire the gate, and is a belt-and-
+    // suspenders defense against future race-window widening.
+    const LIST_TOOLS_RETRY_ATTEMPTS = 15;
+    const LIST_TOOLS_RETRY_DELAY_MS = 200;
+    // ADR-017 Phase 1.1: SSE thread_message events carry queueItemId
+    // inline. Capture into pendingActionMap so the next settling
+    // create_thread_reply can auto-inject sourceQueueItemId — even if
+    // no drain ever populated the map. Eliminates the SSE-vs-drain race
+    // that caused false-positive escalations on early thread tests.
+    const captureQueueItemFromEvent = (event) => {
+        if (event.event !== "thread_message")
+            return;
+        const data = event.data;
+        const qid = data.queueItemId;
+        const threadId = data.threadId;
+        if (typeof qid === "string" && typeof threadId === "string") {
+            pendingActionMap.set(pendingKey("thread_message", threadId), qid);
+        }
+    };
+    // Mission-56 W2.2: Layer-2 routing. Every classified event goes
+    // through `@apnex/message-router` so Message-ID dedup (push+poll
+    // race) + kind→hook mapping live in one place. The host's
+    // `notificationHooks` bag is the router's hook surface — no
+    // shape adapter needed (the router's NotificationHooks interface
+    // mirrors DispatcherNotificationHooks exactly).
+    //
+    // The seen-id cache is shared across the construction-time router
+    // and any per-call routers minted by `makePendingActionItemHandler`,
+    // so a Message ID seen on the SSE inline path will dedup a later
+    // drain-path replay (and vice-versa).
+    const seenIdCache = new SeenIdCache();
+    const router = new MessageRouter({
+        hooks: opts.notificationHooks ?? {},
+        seenIdCache,
+    });
+    // Mission-56 W3.3: post-render claim. Extracts the Message ID from
+    // `message_arrived` events (W1a SSE shape: event.data.message.id)
+    // and fires `claim_message(id)` against the Hub via the agent. Per
+    // architect-issued W3 directive: claim happens AFTER the host hook
+    // renders (the ordering matches "shim calls after successful render
+    // to host" from Design v1.2 commitment #6). Errors are swallowed +
+    // logged — claim failure is non-fatal (the SSE path still rendered;
+    // the next poll-tick will pick up any unclaimed Message in the
+    // status === "new" set if needed).
+    //
+    // Multi-agent same-role: the Hub-side CAS enforces winner-takes-all
+    // (mission-56 W3.2). The wonClaim signal is informational; even if
+    // we lost, the host has already rendered (claim is post-render), so
+    // the loser still sees the Message — but only the winner's claim
+    // flips status to `received`, gating subsequent ack to a single
+    // canonical actor.
+    function fireClaimMessage(event) {
+        if (event.event !== "message_arrived")
+            return;
+        const data = event.data;
+        const message = data?.message;
+        const messageId = message?.id;
+        if (typeof messageId !== "string")
+            return;
+        const agent = opts.getAgent();
+        if (!agent || agent.state !== "streaming")
+            return;
+        void agent
+            .call("claim_message", { id: messageId })
+            .catch((err) => {
+            log(`[claim_message] non-fatal failure for ${messageId}: ${err?.message ?? String(err)}`);
+        });
+    }
+    // Phase-1.5 #1 (M-SSE-Filter-List-Adapter-Consumption Design v1.0
+    // §1.3): when Hub has set `payload.suppress_peek_line: true` (per
+    // §1.5 filter-list at sse-peek-line-render.ts), downgrade the event
+    // to informational routing — the host's onInformationalEvent hook
+    // logs but does NOT call pushChannelNotification (no LLM wake; no
+    // peek-line surface). State-machine consumption preserved via the
+    // log path. Operator-visible noise reduction for filter-listed
+    // events. Back-compat: undefined / false → current Phase-1 flow
+    // unchanged.
+    function isSuppressed(event) {
+        const data = event.data;
+        return data?.suppress_peek_line === true;
+    }
+    const callbacks = {
+        onActionableEvent: (event) => {
+            if (isSuppressed(event)) {
+                // Filter-listed event: route as informational; skip
+                // captureQueueItemFromEvent + fireClaimMessage (actionable-only
+                // side effects). State-machine consumption preserved via the
+                // informational hook's log path.
+                router.route({ kind: "notification.informational", event });
+                return;
+            }
+            captureQueueItemFromEvent(event);
+            router.route({ kind: "notification.actionable", event });
+            // Mission-56 W3.3: post-render claim (replaces W2.2 stub-claim TODO).
+            fireClaimMessage(event);
+        },
+        onInformationalEvent: (event) => {
+            router.route({ kind: "notification.informational", event });
+        },
+        onStateChange: (state, previous, reason) => {
+            log(`Connection: ${previous} → ${state}${reason ? ` (${reason})` : ""}`);
+            router.route({ kind: "state.change", state, previous, reason });
+            // bug-103: on every transition into `streaming` (first connect AND every
+            // reconnect), trigger an immediate poll-backstop catch-up tick — so
+            // role-targeted kind:note notifications missed while the adapter was
+            // disconnected are recovered promptly, not only on the next ≤cadence
+            // interval tick. No-op when the first-timer is disabled or already
+            // in-flight (tick() guards both).
+            if (state === "streaming")
+                void pollBackstop?.tick(opts.getAgent);
+        },
+    };
+    // idea-355 §4.3 — kernel-internal queue wake/stall reconcile. Hoisted from the
+    // claude shim so EVERY host gets it via the dispatcher heartbeat tick with ZERO
+    // shim wiring (the shim that wires none of these seams still emits via
+    // notificationHooks on a tick). The trackers are per-dispatcher-instance and
+    // persist ACROSS ticks — the level-triggered, ID-keyed dedup state must survive
+    // tick-to-tick or every tick re-emits (digest spam).
+    const claimableDigest = new ClaimableDigestTracker();
+    // Slice D: use the injected tracker when a native binding shares one (so its
+    // runToolDispatch observations land where the reconcile reads); else own it.
+    const workLeases = opts.sharedWorkLeases ?? new WorkLeaseTracker();
+    let wakeStallInFlight = false;
+    // The reconcile body. Drives W1 (inbound claimable digest), W2 (outbound
+    // stall-prompt), W3 (emit-only status log). Invoked from the heartbeat tick
+    // below (wrapped in its own try/catch alongside the host live-refresh hook).
+    async function runWakeStallReconcile() {
+        // Invariant: in-flight latch so overlapping ticks don't double-emit. The
+        // gates below run BEFORE the latch is taken, so an early return never needs
+        // to release it.
+        if (wakeStallInFlight)
+            return;
+        const agent = opts.getAgent();
+        // Gate on a live streaming agent (the call path requires it anyway).
+        if (!agent || agent.state !== "streaming")
+            return;
+        // Invariant: gate on identityReady — role + agentId come from the post-
+        // handshake identity; a pre-handshake tick would read an undefined identity
+        // and list_ready_work the wrong (or empty) set.
+        const agentId = agent.getMetrics?.().agentId;
+        if (!agentId)
+            return;
+        // bug-173 — resolve the role at USE-time (it may be a `() => string` thunk
+        // for hosts whose dispatcher is constructed before config.role loads), so the
+        // idea-353 wake/stall reconcile filters on the SAME configured role the
+        // PollBackstop tick uses — not a frozen module-init env default.
+        const roleOpt = opts.pollBackstop?.role;
+        const role = roleOpt === undefined ? undefined : resolveRole(roleOpt);
+        if (!role)
+            return;
+        wakeStallInFlight = true;
+        try {
+            // Slice D: a native host (pi) supplies its own idle probe because its tool
+            // calls bypass this dispatcher's CallTool handler (so activeCallCount is
+            // always 0 for it). MCP hosts leave externalIdle undefined → counter wins.
+            const idle = opts.externalIdle ? opts.externalIdle() : activeCallCount === 0;
+            const nowMs = Date.now();
+            let claimableCount = 0;
+            // W1 — inbound claimable digest. Read the CALLER-CLAIMABLE set via the
+            // stable list_ready_work contract with scopeToCaller (idea-353 WI-2.1 /
+            // audit-4265: the Hub applies claim_work's FULL predicate — deps + role +
+            // WIP-cap + quarantine — so the digest never over-reports what this agent
+            // can actually claim; AC5 strict parity). On a failed read, skip the
+            // tracker entirely so a transient empty/aborted read cannot manufacture a
+            // false 0→N replay (AC3).
+            try {
+                const raw = await withTimeout(agent.call("list_ready_work", { role, scopeToCaller: true }, { internal: true }), WAKE_STALL_READ_TIMEOUT_MS, "list_ready_work wake/stall read");
+                const items = raw?.items;
+                if (Array.isArray(items)) {
+                    const claimableIds = items
+                        .map((i) => i?.id)
+                        .filter((id) => typeof id === "string");
+                    claimableCount = claimableIds.length;
+                    const decision = claimableDigest.reconcile({ claimableIds, isIdle: idle });
+                    if (decision.emit) {
+                        router.route({
+                            kind: "notification.actionable",
+                            event: {
+                                event: "work_claimable_digest",
+                                data: { role, count: decision.count, newCount: decision.newCount },
+                            },
+                        });
+                        log(`[idea-353] inbound digest emitted — ${decision.count} claimable (${decision.newCount} new) for ${role}`);
+                    }
+                }
+            }
+            catch (err) {
+                log(`[idea-353] list_ready_work tick failed (non-fatal): ${err?.message ?? err}`);
+            }
+            // W2 — outbound stall-prompt. Idle-gated: never pester a visibly-
+            // progressing holder (an in-flight CallTool = active progress). A held
+            // lease past ~60% of its window without a renew gets ONE nudge.
+            if (idle) {
+                for (const due of workLeases.dueForStallPrompt(nowMs)) {
+                    router.route({
+                        kind: "notification.actionable",
+                        event: {
+                            event: "work_lease_stall",
+                            data: { workId: due.workId, msUntilExpiry: due.msUntilExpiry },
+                        },
+                    });
+                    workLeases.markPrompted(due.workId);
+                    log(`[idea-353] outbound stall-prompt emitted — ${due.workId} (~${Math.round(due.msUntilExpiry / 60000)}m left)`);
+                }
+            }
+            // W3 — emit-only Agent.status idle/stall telemetry seam. Thin + non-gating.
+            const heldLeases = workLeases.size();
+            const statusState = !idle ? "working" : heldLeases > 0 ? "holding" : "idle";
+            log(`[idea-353][agent-status] state=${statusState} idle=${idle} claimable=${claimableCount} heldLeases=${heldLeases}`);
+        }
+        finally {
+            // Invariant: release the latch on BOTH success and error — a thrown
+            // reconcile must not wedge the latch (that would silently disable the
+            // wake forever).
+            wakeStallInFlight = false;
+        }
+    }
+    // Mission-56 W3.3: PollBackstop construction (opt-in via opts.pollBackstop).
+    // The backstop fires `list_messages({status:"new", since:<lastSeen>})`
+    // periodically and routes each delta Message through the same
+    // MessageRouter as the SSE inline path so seen-id LRU dedup catches
+    // push+poll race overlap. Polled Messages also fire claim_message
+    // (the router invocation goes through onActionableEvent which
+    // already includes fireClaimMessage).
+    // idea-355 §4.3 — the kernel owns the heartbeat tick. The host's optional
+    // onHeartbeatTick (e.g. claude's bug-180 tool-surface live-refresh, which is
+    // host-coupled via mcpServer.sendToolListChanged) and the kernel wake/stall
+    // reconcile SHARE the tick; each runs in its OWN try/catch (invariant #5) so a
+    // failing or slow one cannot break or block the other.
+    const hostHeartbeatTick = opts.pollBackstop?.onHeartbeatTick;
+    const pollBackstop = opts.pollBackstop
+        ? new PollBackstop({
+            ...opts.pollBackstop,
+            log: opts.pollBackstop.log ?? log,
+            onPolledMessage: (event) => {
+                router.route({ kind: "notification.actionable", event });
+                fireClaimMessage(event);
+            },
+            onHeartbeatTick: async () => {
+                if (hostHeartbeatTick) {
+                    try {
+                        await hostHeartbeatTick();
+                    }
+                    catch (err) {
+                        log(`[tick] host heartbeat hook threw (non-fatal): ${err?.message ?? err}`);
+                    }
+                }
+                try {
+                    await runWakeStallReconcile();
+                }
+                catch (err) {
+                    log(`[tick] wake/stall reconcile threw (non-fatal): ${err?.message ?? err}`);
+                }
+            },
+        })
+        : undefined;
+    // Mission-56 W3.3: explicit-ack-on-action helper. Host shims wire
+    // this to fire when the LLM consumer has acted on (or actively
+    // deferred) a Message — per Option (i) ratified at thread-325 round-2,
+    // ack is tied to consumer-action, not auto-on-render.
+    async function ackMessage(messageId) {
+        const agent = opts.getAgent();
+        if (!agent || agent.state !== "streaming")
+            return;
+        try {
+            await agent.call("ack_message", { id: messageId });
+        }
+        catch (err) {
+            log(`[ack_message] non-fatal failure for ${messageId}: ${err?.message ?? String(err)}`);
+        }
+    }
+    const makePendingActionItemHandler = (hooks) => {
+        // Per-call hooks override the construction-time bag for the
+        // drain path (preserves the original makePendingActionItemHandler
+        // contract — claude-plugin shim uses this to bind a custom log
+        // sink). Share the seen-id cache so drain-path replays dedup
+        // against SSE-path inline deliveries.
+        const drainRouter = new MessageRouter({
+            hooks: hooks ?? {},
+            seenIdCache,
+        });
+        return (item) => {
+            pendingActionMap.set(pendingKey(item.dispatchType, item.entityRef), item.id);
+            drainRouter.route({ kind: "pending-action.dispatch", item });
+        };
+    };
+    function createMcpServer() {
+        const server = new Server({ name: serverName, version: opts.proxyVersion }, { capabilities: serverCapabilities });
+        // Initialize handler is intentionally NOT gated — host MCP clients
+        // (e.g. Claude Code) have a tight initialize timeout that's faster
+        // than a full Hub handshake. The Initialize handler captures
+        // clientInfo for downstream handshake passthrough.
+        server.setRequestHandler(InitializeRequestSchema, async (request) => {
+            try {
+                const ci = request.params
+                    .clientInfo;
+                if (ci &&
+                    typeof ci.name === "string" &&
+                    typeof ci.version === "string") {
+                    capturedClientInfo = { name: ci.name, version: ci.version };
+                    log(`[Handshake] Captured clientInfo: ${ci.name}@${ci.version}`);
+                }
+            }
+            catch (err) {
+                log(`[Handshake] clientInfo capture failed (non-fatal): ${err}`);
+            }
+            return {
+                protocolVersion: request.params.protocolVersion,
+                capabilities: serverCapabilities,
+                serverInfo: { name: serverName, version: opts.proxyVersion },
+            };
+        });
+        server.setRequestHandler(ListToolsRequestSchema, async () => {
+            // Probe-safe cache fallback. When identity hasn't yet resolved
+            // (e.g. `claude mcp list` spawned the adapter and will exit
+            // before the handshake completes), serve the persisted catalog
+            // if available + valid against the current Hub version. Probe
+            // returns in <50ms with zero Hub round-trips.
+            if (opts.getCachedCatalog &&
+                opts.getIsIdentityReady &&
+                !opts.getIsIdentityReady()) {
+                const cached = opts.getCachedCatalog();
+                if (cached) {
+                    const currentRevision = opts.getCurrentToolSurfaceRevision?.() ?? null;
+                    const valid = (opts.isCacheValid ?? (() => false))(cached, currentRevision);
+                    if (valid) {
+                        log(`[ListTools] served from cache (${cached.catalog.length} tools)`);
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        return { tools: cached.catalog };
+                    }
+                    log(`[ListTools] cache stale (cached.toolSurfaceRevision=${cached.toolSurfaceRevision}, current=${currentRevision ?? "unknown"}) — bootstrapping`);
+                }
+                else {
+                    log("[ListTools] no cache (bootstrapping cache from Hub)");
+                }
+            }
+            if (opts.listToolsGate)
+                await opts.listToolsGate;
+            // bug-114 fallback-gap fix (2026-05-26): on cold-start the
+            // bootstrap path can race the Hub transport's connection
+            // completion — `listToolsGate` is currently undefined in every
+            // host shim, so the await above is a no-op. Pre-fix the
+            // handler returned `{ tools: [] }` silently when
+            // `isUsableAgent(agent)` was false, and host MCP clients
+            // (Claude Code) cached the empty list as the authoritative
+            // tool surface for the session — invisible comms-loss across
+            // the agent population, especially after a
+            // CATALOG_SCHEMA_VERSION bump invalidated all on-disk caches.
+            //
+            // Post-fix: short bounded retry (LIST_TOOLS_RETRY_ATTEMPTS ×
+            // LIST_TOOLS_RETRY_DELAY_MS) to absorb the narrow handshake
+            // race, then raise a structured MCP error (-32603 InternalError)
+            // so the host surfaces an actionable failure instead of
+            // caching `{ tools: [] }`. Bootstrap-completed telemetry emits
+            // on every path exit so silent zero-returns are architecturally
+            // impossible.
+            let agent = null;
+            for (let attempt = 1; attempt <= LIST_TOOLS_RETRY_ATTEMPTS; attempt++) {
+                const candidate = opts.getAgent();
+                if (isUsableAgent(candidate)) {
+                    agent = candidate;
+                    break;
+                }
+                if (attempt < LIST_TOOLS_RETRY_ATTEMPTS) {
+                    log(`[ListTools] adapter not ready (attempt ${attempt}/${LIST_TOOLS_RETRY_ATTEMPTS}) — retrying in ${LIST_TOOLS_RETRY_DELAY_MS}ms`);
+                    await new Promise((resolve) => setTimeout(resolve, LIST_TOOLS_RETRY_DELAY_MS));
+                }
+            }
+            if (!agent) {
+                log(`[ListTools] bootstrap failed: adapter not ready after ${LIST_TOOLS_RETRY_ATTEMPTS} attempts — raising structured error`);
+                throw new McpError(ErrorCode.InternalError, "Adapter not ready: Hub transport has not connected yet. Retry the request.");
+            }
+            // Route through agent.listTools() so any configured cognitive
+            // pipeline's onListTools middleware (ToolDescriptionEnricher,
+            // ResponseSummarizer, etc.) observes and modifies the surface.
+            const tools = await agent.listTools();
+            // Best-effort cache write-back. Skip on empty results — never
+            // poison the cache with a zero-tool catalog (bug-114 hardening).
+            if (opts.persistCatalog && tools.length > 0) {
+                try {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    opts.persistCatalog(tools);
+                }
+                catch (err) {
+                    log(`[ListTools] persistCatalog hook threw (non-fatal): ${err.message ?? err}`);
+                }
+            }
+            else if (opts.persistCatalog && tools.length === 0) {
+                log("[ListTools] persistCatalog skipped (zero tools — refusing to poison cache)");
+            }
+            log(`[ListTools] bootstrap completed: ${tools.length} tools surfaced`);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return { tools: tools };
+        });
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            // M-Tool-Manager Slice B: the CallTool handler body is now the shared
+            // dispatch authority (`runToolDispatch`). This MCP handler is a thin
+            // caller that supplies the closure state as an explicit dispatch context
+            // and returns the (Slice-B faithful, still MCP-shaped) result. The
+            // per-call behavior — idle-gate, callToolGate+timeout, Hub-not-connected
+            // precheck, queueItemId injection, signal-FSM wrap, lease observe,
+            // onToolCallResult, error normalization — all lives in `dispatch.ts` and
+            // is shared byte-for-byte with any future host binding (pi native, ACP).
+            const dispatchCtx = {
+                getAgent: opts.getAgent,
+                pendingActionMap,
+                workLeases,
+                onCallStart: () => {
+                    activeCallCount++;
+                },
+                onCallEnd: () => {
+                    activeCallCount--;
+                },
+                callToolGate: opts.callToolGate,
+                callToolGateTimeoutMs: opts.callToolGateTimeoutMs,
+                onToolCallResult: opts.onToolCallResult,
+                log,
+            };
+            const incomingArgs = (request.params.arguments ?? {});
+            // The dispatch authority returns the Slice-B-faithful MCP-shaped result
+            // ({ content, isError }); the SDK's CallTool result type is broader
+            // (optional task/_meta fields the original literal also omitted). Cast at
+            // this MCP-binding boundary — MCP-shape concerns are the binding's job.
+            const dispatchResult = await runToolDispatch(dispatchCtx, request.params.name, incomingArgs);
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return dispatchResult;
+        });
+        return server;
+    }
+    return {
+        pendingActionMap,
+        createMcpServer,
+        callbacks,
+        getClientInfo,
+        makePendingActionItemHandler,
+        pollBackstop,
+        ackMessage,
+        getActiveCallCount: () => activeCallCount,
+        isIdle: () => activeCallCount === 0,
+        workLeases,
+    };
+}
+/**
+ * bug-53 boot-time fail-fast: assert host adapter has opted into
+ * pollBackstop wiring (transport_heartbeat periodic timer). Throws if
+ * `dispatcher.pollBackstop === undefined` UNLESS `TRANSPORT_HEARTBEAT_ENABLED=false`
+ * is set explicitly (opt-out path).
+ *
+ * Class: substrate-runtime-gap (sister to bug-49/50/51). Mission-75 §3.3
+ * substrate (PollBackstop heartbeat-second-timer) shipped at thread-472 with
+ * unit tests green, but the host integration was never written — both
+ * adapters call `createSharedDispatcher({...})` without supplying
+ * `opts.pollBackstop`, so the dispatcher's pollBackstop field stayed
+ * `undefined` and neither the poll-timer nor the heartbeat-timer ever
+ * scheduled. ZERO `transport_heartbeat` MCP tool calls fired in 96 minutes
+ * post Hub-restart (5127-line shim.log + 1789-event ndjson confirmed).
+ *
+ * This assertion is a §6.4-equivalent gate: each host MUST call
+ * `assertHostWiringComplete(dispatcher)` post-startup so the bug-53 class
+ * cannot recur silently. Misconfiguration fails fast at boot, not invisibly
+ * after 96 minutes of clinical observability degradation.
+ */
+export function assertHostWiringComplete(dispatcher, log = (m) => console.error(m)) {
+    if (dispatcher.pollBackstop !== undefined) {
+        return; // wiring complete
+    }
+    if (process.env.TRANSPORT_HEARTBEAT_ENABLED === "false") {
+        // Explicit opt-out path — log info-level so operators have forensics.
+        log("[adapter] pollBackstop intentionally disabled via TRANSPORT_HEARTBEAT_ENABLED=false");
+        return;
+    }
+    throw new Error("[adapter] HOST WIRING ERROR: pollBackstop not configured in createSharedDispatcher opts. " +
+        "Transport heartbeat will not fire (lastHeartbeatAt will stay frozen at adapter-startup). " +
+        "Per mission-75 §3.3 + bug-53 closure, host adapters MUST opt in to pollBackstop. " +
+        "Set TRANSPORT_HEARTBEAT_ENABLED=false to explicitly disable.");
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/tool-manager/orchestrator/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../../src/tool-manager/orchestrator/dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/tool-manager/work-protocol/claimable-digest-tracker.d.ts

@@ -0,0 +1,60 @@
+/**
+ * claimable-digest-tracker.ts — idea-353 W1 inbound wake (level-triggered,
+ * idle-gated, idempotent claimable-digest).
+ *
+ * The C1 work-queue is a pull model with no wake-on-ready signal: an idle
+ * eligible agent never learns that newly-claimable work appeared and sits
+ * unclaimed until someone manually nudges it (proven 3× in dogfood-1). This
+ * tracker is the **decision core** of the inbound wake — given the set of
+ * truly-claimable work ids for the agent's role (read via the stable
+ * `list_ready_work` contract) and whether the agent is idle, it decides whether
+ * to surface a digest ("N items claimable for your role").
+ *
+ * The design's ONE genuinely-new substrate is this **level-trigger / de-dup
+ * state** (the FR-22 storm-risk locus). The rules:
+ *
+ *   - **Idle-gated (AC4):** never surface while the agent is mid-task. A busy
+ *     tick neither emits NOR advances the baseline — so items that appeared
+ *     while the agent was working are surfaced on the FIRST idle tick, not
+ *     silently swallowed.
+ *   - **Level-triggered / idempotent (AC3):** emit ONLY on an upward edge —
+ *     0→N, or a genuinely-NEW claimable id appeared since the last surfaced
+ *     set. A steady N>0, a re-tick, or a Hub restart (the in-memory baseline
+ *     survives, since the adapter process does not restart) yields no new ids
+ *     → no emit. ID-keyed, not count-keyed, so a swap (one item claimed away,
+ *     another appearing at the same count) still edges.
+ *
+ * Pairs with the at-tick guard in the host: the tracker is only fed on a
+ * SUCCESSFUL `list_ready_work` read — a failed read (Hub mid-restart, agent not
+ * streaming) skips the tick entirely and leaves the baseline untouched, so a
+ * transient empty/aborted read cannot manufacture a false 0→N replay.
+ *
+ * Pure + synchronous: all I/O (the list_ready_work read, the host emit) lives
+ * in the host tick; this class holds only the de-dup state + the decision, so
+ * the storm-proof contract is unit-testable without a live Hub (AC3/AC4).
+ */
+export interface ClaimableDigestInput {
+    /** The truly-claimable work ids for the agent's role this tick (post-bug-181). */
+    claimableIds: string[];
+    /** The idle-gate: false = the agent is actively mid-task (never interrupt it). */
+    isIdle: boolean;
+}
+export interface ClaimableDigestDecision {
+    /** True iff an upward edge was detected while idle → surface the digest. */
+    emit: boolean;
+    /** Current claimable count (whether or not we emit). */
+    count: number;
+    /** Number of newly-appeared claimable ids since the last surfaced set. */
+    newCount: number;
+}
+export declare class ClaimableDigestTracker {
+    /** The claimable id set the agent was last woken about (the de-dup baseline). */
+    private lastSurfaced;
+    /**
+     * Decide whether this tick should surface a claimable-digest wake.
+     * @param input current claimable ids + idle state for this tick.
+     */
+    reconcile(input: ClaimableDigestInput): ClaimableDigestDecision;
+    /** Diagnostic/test accessor for the current de-dup baseline size. */
+    getSurfacedCount(): number;
+}