@apnex/network-adapter 0.1.0

package/dist/tool-manager/dispatcher.d.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 type { AgentClientCallbacks, AgentEvent, SessionState, SessionReconnectReason } from "../kernel/agent-client.js";
+import type { McpAgentClient } from "../kernel/mcp-agent-client.js";
+import { PollBackstop, type PollBackstopOptions } from "../kernel/poll-backstop.js";
+import type { DrainedPendingAction } from "../kernel/state-sync.js";
+import type { CachedCatalog } from "./tool-catalog-cache.js";
+export interface DispatcherClientInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Universal Adapter notification contract — generic shim-injection
+ * callback bag. Layer 3 (per-host shim) implements these to bind
+ * dispatcher events into host-specific render-surfaces (claude
+ * `<channel>` / opencode `promptAsync` / future hosts).
+ *
+ * Spec: docs/specs/universal-adapter-notification-contract.md
+ */
+export interface DispatcherNotificationHooks {
+    onActionableEvent?: (event: AgentEvent) => void;
+    onInformationalEvent?: (event: AgentEvent) => void;
+    onStateChange?: (state: SessionState, previous: SessionState, reason?: SessionReconnectReason) => void;
+    onPendingActionItem?: (item: DrainedPendingAction) => void;
+}
+export interface SharedDispatcherOptions {
+    /**
+     * Late-binding agent accessor. Some hosts (opencode) construct the
+     * dispatcher before the McpAgentClient connection is established.
+     * Returning `null` means "not connected yet" — the dispatcher
+     * surfaces a "Hub not connected" error envelope on CallTool and an
+     * empty tool-list on ListTools.
+     */
+    getAgent: () => McpAgentClient | null;
+    /** Adapter version reported in MCP serverInfo. */
+    proxyVersion: string;
+    /** MCP server name. Default: "proxy". */
+    serverName?: string;
+    /**
+     * MCP server capabilities advertised at Initialize. Default:
+     * `{ tools: {}, logging: {} }`. Hosts with extra capabilities
+     * (e.g. claude `experimental.claude/channel`) override.
+     */
+    serverCapabilities?: Record<string, unknown>;
+    /** Diagnostic logger. No-op default. */
+    log?: (msg: string) => void;
+    /**
+     * Resolves when the underlying McpAgentClient handshake completes
+     * (transport connected + identity asserted). Gates the ListTools
+     * handler so the host's catalog fetch doesn't block on the slow
+     * full-sync phase. Omit when no gating is needed (tests).
+     *
+     * Was: `handshakeComplete` (per-plugin dispatchers). Renamed in
+     * mission-55 cleanup per Design v1.2 Q5: name what is gated, not
+     * what is complete.
+     */
+    listToolsGate?: Promise<void>;
+    /**
+     * Resolves when the McpAgentClient session is claim-eligible
+     * (eager mode: claim_session returned; lazy mode: identity ready).
+     * Gates the CallTool handler so tool dispatch waits until the
+     * Hub will accept it. Omit when no gating is needed.
+     *
+     * Was: `agentReady` (per-plugin dispatchers). Renamed in mission-55
+     * cleanup per Design v1.2 Q5.
+     */
+    callToolGate?: Promise<void>;
+    getCachedCatalog?: () => CachedCatalog | null;
+    getIsIdentityReady?: () => boolean;
+    getCurrentHubVersion?: () => string | null;
+    persistCatalog?: (catalog: unknown[]) => void;
+    /**
+     * Optional cache-validity check. When omitted, cache-fallback
+     * conservatively treats every cached entry as invalid (live-fetch
+     * dominates). Wire `isCacheValid` from `./tool-catalog-cache.js`
+     * to enable Hub-version-keyed validity.
+     */
+    isCacheValid?: (cached: CachedCatalog, currentHubVersion: string | null | undefined) => boolean;
+    /**
+     * Universal Adapter notification contract. Host shim attaches its
+     * render-surface bindings here.
+     */
+    notificationHooks?: DispatcherNotificationHooks;
+    /**
+     * Mission-56 W3.3: opt-in adapter-side hybrid poll backstop. When
+     * supplied, the dispatcher constructs a PollBackstop (Design v1.2
+     * commitment #5) that periodically calls `list_messages` with a
+     * `since` cursor + `status: "new"` filter and surfaces each delta
+     * Message via the same MessageRouter as the SSE inline path
+     * (preserving seen-id LRU dedup across both paths).
+     *
+     * Pass `{ role: "engineer" | "architect" }` minimum; cadence
+     * defaults to 5min (`OIS_ADAPTER_POLL_BACKSTOP_S` env override).
+     * Omit to disable polling (push-only mode).
+     */
+    pollBackstop?: Omit<PollBackstopOptions, "onPolledMessage">;
+}
+export interface SharedDispatcher {
+    /** ADR-017 queueItemId tracking map. Keyed by `${dispatchType}:${entityRef}`. */
+    pendingActionMap: Map<string, string>;
+    /**
+     * Lazy MCP server factory. Hosts call this to obtain a fresh Server
+     * instance for each host transport (stdio: once at startup;
+     * Bun-HTTP: once per HTTP session).
+     */
+    createMcpServer: () => Server;
+    /**
+     * AgentClientCallbacks suitable for `agent.setCallbacks(...)`. Wires
+     * pendingActionMap-population + propagates to notificationHooks for
+     * host-specific render-surface.
+     */
+    callbacks: AgentClientCallbacks;
+    /** Returns last-captured Initialize-time clientInfo. */
+    getClientInfo: () => DispatcherClientInfo;
+    /**
+     * Builds an `onPendingActionItem` handshake callback that populates
+     * pendingActionMap (drain-path parity with the SSE inline-queueItemId
+     * path) and forwards to the supplied hooks.
+     */
+    makePendingActionItemHandler: (hooks?: DispatcherNotificationHooks) => (item: DrainedPendingAction) => void;
+    /**
+     * Mission-56 W3.3: PollBackstop instance, present iff `opts.pollBackstop`
+     * was supplied. Hosts MAY call `pollBackstop.start(getAgent)` at the
+     * appropriate lifecycle moment (typically post-handshake, when the
+     * agent reaches `streaming`). Hosts MUST call `pollBackstop.stop()`
+     * on shutdown to clear the timer. Omitted (`undefined`) when polling
+     * is disabled (push-only mode).
+     */
+    pollBackstop?: PollBackstop;
+    /**
+     * Mission-56 W3.3: explicit-ack-on-action surface. Host shims call
+     * this when the consumer (LLM) has acted on or actively-deferred a
+     * Message that was previously claimed (per Option (i) ratified at
+     * thread-325 round-2). Idempotent: re-acks on already-acked Messages
+     * are no-ops. Errors swallowed (logged, non-fatal) — a missed ack
+     * leaves the Message at status `received`, which the next poll-tick
+     * naturally excludes from `status: "new"` so the consumer doesn't
+     * re-render it.
+     */
+    ackMessage: (messageId: string) => Promise<void>;
+}
+/** Compose the pendingActionMap key. Pure helper; exported for tests. */
+/**
+ * Mission-62 W3: tools that should NOT trigger signal_working_*
+ * wrapping. The signal_* tools themselves would recurse infinitely;
+ * register_role + claim_session + drain_pending_actions are lifecycle
+ * tools, not semantic tool-call-work.
+ */
+export declare const TOOL_CALL_SIGNAL_SKIP: ReadonlySet<string>;
+export declare function pendingKey(dispatchType: string, entityRef: string): string;
+/**
+ * Inject `sourceQueueItemId` into a settling tool call's arguments
+ * when a pendingActionMap entry is registered for the call's target.
+ * Currently only `create_thread_reply` settles a thread_message
+ * dispatch; extend this set as new auto-injection rules are ratified.
+ *
+ * Side effect: deletes the consumed map entry. Explicit
+ * sourceQueueItemId in the args wins over the map (no rewrite).
+ */
+export declare function injectQueueItemId(name: string, args: Record<string, unknown>, pendingActionMap: Map<string, string>): Record<string, unknown>;
+export declare function createSharedDispatcher(opts: SharedDispatcherOptions): SharedDispatcher;

package/dist/tool-manager/dispatcher.js

@@ -0,0 +1,379 @@
+/**
+ * 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, } from "@modelcontextprotocol/sdk/types.js";
+import { MessageRouter, SeenIdCache } from "@apnex/message-router";
+import { PollBackstop } from "../kernel/poll-backstop.js";
+/** Compose the pendingActionMap key. Pure helper; exported for tests. */
+/**
+ * Mission-62 W3: tools that should NOT trigger signal_working_*
+ * wrapping. The signal_* tools themselves would recurse infinitely;
+ * register_role + claim_session + drain_pending_actions are lifecycle
+ * tools, not semantic tool-call-work.
+ */
+export const TOOL_CALL_SIGNAL_SKIP = new Set([
+    "signal_working_started",
+    "signal_working_completed",
+    "signal_quota_blocked",
+    "signal_quota_recovered",
+    "register_role",
+    "claim_session",
+    "drain_pending_actions",
+]);
+export function pendingKey(dispatchType, entityRef) {
+    return `${dispatchType}:${entityRef}`;
+}
+/**
+ * Inject `sourceQueueItemId` into a settling tool call's arguments
+ * when a pendingActionMap entry is registered for the call's target.
+ * Currently only `create_thread_reply` settles a thread_message
+ * dispatch; extend this set as new auto-injection rules are ratified.
+ *
+ * Side effect: deletes the consumed map entry. Explicit
+ * sourceQueueItemId in the args wins over the map (no rewrite).
+ */
+export function injectQueueItemId(name, args, pendingActionMap) {
+    if (name !== "create_thread_reply")
+        return args;
+    const threadId = args.threadId;
+    if (typeof threadId !== "string")
+        return args;
+    if ("sourceQueueItemId" in args)
+        return args;
+    const queueItemId = pendingActionMap.get(pendingKey("thread_message", threadId));
+    if (!queueItemId)
+        return args;
+    pendingActionMap.delete(pendingKey("thread_message", threadId));
+    return { ...args, sourceQueueItemId: queueItemId };
+}
+export function createSharedDispatcher(opts) {
+    const log = opts.log ?? (() => { });
+    const serverName = opts.serverName ?? "proxy";
+    const serverCapabilities = opts.serverCapabilities ?? { tools: {}, logging: {} };
+    const pendingActionMap = new Map();
+    let capturedClientInfo = {
+        name: "unknown",
+        version: "0.0.0",
+    };
+    const getClientInfo = () => capturedClientInfo;
+    function isUsableAgent(agent) {
+        return !!agent && agent.isConnected !== false;
+    }
+    // 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)}`);
+        });
+    }
+    const callbacks = {
+        onActionableEvent: (event) => {
+            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 });
+        },
+    };
+    // 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).
+    const pollBackstop = opts.pollBackstop
+        ? new PollBackstop({
+            ...opts.pollBackstop,
+            log: opts.pollBackstop.log ?? log,
+            onPolledMessage: (event) => {
+                router.route({ kind: "notification.actionable", event });
+                fireClaimMessage(event);
+            },
+        })
+        : 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 currentVersion = opts.getCurrentHubVersion?.() ?? null;
+                    const valid = (opts.isCacheValid ?? (() => false))(cached, currentVersion);
+                    if (valid) {
+                        log("[ListTools] served from cache");
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        return { tools: cached.catalog };
+                    }
+                    log(`[ListTools] cache stale (cached.hubVersion=${cached.hubVersion}, current=${currentVersion ?? "unknown"}) — bootstrapping`);
+                }
+                else {
+                    log("[ListTools] no cache (bootstrapping cache from Hub)");
+                }
+            }
+            if (opts.listToolsGate)
+                await opts.listToolsGate;
+            const agent = opts.getAgent();
+            if (!isUsableAgent(agent))
+                return { tools: [] };
+            // 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. Failures log + continue; the
+            // primary response is already on its way to the host.
+            if (opts.persistCatalog) {
+                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}`);
+                }
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return { tools: tools };
+        });
+        server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const callStartedAt = Date.now();
+            const requestedTool = request.params.name;
+            log(`[CallTool] ${requestedTool} entered`);
+            try {
+                if (opts.callToolGate) {
+                    log(`[CallTool] ${requestedTool} awaiting callToolGate`);
+                    await opts.callToolGate;
+                    log(`[CallTool] ${requestedTool} gate passed (+${Date.now() - callStartedAt}ms)`);
+                }
+                const agent = opts.getAgent();
+                if (!isUsableAgent(agent)) {
+                    log(`[CallTool] ${requestedTool} aborted — Hub not connected`);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: "Hub not connected",
+                                    message: "The Hub adapter is not currently connected.",
+                                }),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const { name } = request.params;
+                const incomingArgs = (request.params.arguments ?? {});
+                const outgoingArgs = injectQueueItemId(name, incomingArgs, pendingActionMap);
+                // ── Mission-62 W3 — activity FSM signal wrapping ─────────────
+                //
+                // Wrap each LLM-driven tool call with signal_working_started +
+                // signal_working_completed RPCs (fire-and-forget; eventual-
+                // consistency on Hub-side activity FSM). Per Design v1.0 §5.2:
+                // implicit-only inference infeasible (LLM-to-MCP-tool-call
+                // path doesn't enqueue items per ADR-017 §M1-M2); explicit
+                // signaling required for routing peers to see this agent's
+                // working state.
+                //
+                // Skip-list prevents infinite recursion (signal_* calls would
+                // wrap themselves) + handshake/lifecycle tools that are not
+                // semantically tool-call-work (register_role, claim_session,
+                // drain_pending_actions).
+                const wrapWithSignal = !TOOL_CALL_SIGNAL_SKIP.has(name);
+                if (wrapWithSignal) {
+                    // Fire-and-forget: don't await; Hub-side eventual-consistency
+                    // is acceptable for v1.0 routing-cache use case.
+                    agent.call("signal_working_started", { toolName: name }).catch((err) => {
+                        log(`[mission-62] signal_working_started fire-and-forget failed (non-fatal): ${err?.message ?? err}`);
+                    });
+                }
+                let result;
+                const agentCallStart = Date.now();
+                log(`[CallTool] ${name} dispatching to agent.call (wrapWithSignal=${wrapWithSignal})`);
+                try {
+                    result = await agent.call(name, outgoingArgs);
+                    log(`[CallTool] ${name} agent.call returned in ${Date.now() - agentCallStart}ms`);
+                }
+                finally {
+                    if (wrapWithSignal) {
+                        agent.call("signal_working_completed", {}).catch((err) => {
+                            log(`[mission-62] signal_working_completed fire-and-forget failed (non-fatal): ${err?.message ?? err}`);
+                        });
+                    }
+                }
+                log(`[CallTool] ${name} completed in ${Date.now() - callStartedAt}ms total`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: typeof result === "string"
+                                ? result
+                                : JSON.stringify(result, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                log(`[CallTool] ${requestedTool} threw after ${Date.now() - callStartedAt}ms: ${message}`);
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ error: message }) },
+                    ],
+                    isError: true,
+                };
+            }
+        });
+        return server;
+    }
+    return {
+        pendingActionMap,
+        createMcpServer,
+        callbacks,
+        getClientInfo,
+        makePendingActionItemHandler,
+        pollBackstop,
+        ackMessage,
+    };
+}
+//# sourceMappingURL=dispatcher.js.map

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

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

package/dist/tool-manager/tool-catalog-cache.d.ts

@@ -0,0 +1,85 @@
+/**
+ * tool-catalog-cache.ts — per-WORK_DIR Hub tool catalog cache.
+ *
+ * Probe-safe ListTools support: when the host calls tools/list before
+ * the adapter's identityReady has resolved (e.g. `claude mcp list`
+ * spawning the adapter just to enumerate available tools), the
+ * dispatcher serves the catalog from a persisted cache without
+ * touching the Hub. Together with the lazy session-claim path this
+ * makes probes fully Hub-free against a warm cache.
+ *
+ * Storage: $WORK_DIR/.ois/tool-catalog.json
+ *   {
+ *     schemaVersion: 1,
+ *     hubVersion: "1.0.0",
+ *     fetchedAt: "2026-04-22T...Z",
+ *     catalog: [...]
+ *   }
+ *
+ * Invalidation: Hub-version mismatch only. No TTL — the catalog is
+ * static between Hub deploys; TTL would add noise without correctness
+ * value. Schema-version mismatch on read returns null (cache treated
+ * as invalid; future schema evolution bumps CATALOG_SCHEMA_VERSION).
+ *
+ * Atomicity: writeCache uses tmp-file + rename so partial writes on
+ * crash don't corrupt the cache. Parse errors on read also return
+ * null — the cache self-heals on next bootstrap.
+ *
+ * Failure modes (best-effort; readCache + writeCache never throw on
+ * the primary flow):
+ *   - missing file:           readCache returns null
+ *   - parse error:            readCache returns null + logs
+ *   - schema-version mismatch: readCache returns null
+ *   - $WORK_DIR readonly:     writeCache logs + no-ops
+ *   - disk full:              writeCache logs + no-ops
+ */
+/**
+ * Bumping CATALOG_SCHEMA_VERSION forces all existing cache files to
+ * be treated as invalid + re-bootstrapped. Use when changing the
+ * cache file shape.
+ */
+export declare const CATALOG_SCHEMA_VERSION = 1;
+/**
+ * MCP tool catalog entry shape. Kept loose (`unknown[]`) since the
+ * cache is opaque storage; the dispatcher hands the catalog back to
+ * the host without re-shaping.
+ */
+export type ToolCatalog = unknown[];
+export interface CachedCatalog {
+    schemaVersion: number;
+    hubVersion: string;
+    fetchedAt: string;
+    catalog: ToolCatalog;
+}
+/** Compute the canonical cache path for a given WORK_DIR. */
+export declare function cachePathFor(workDir: string): string;
+/**
+ * Read the cache file. Returns null on missing file, parse error,
+ * schema-version mismatch, or shape mismatch. Never throws — the
+ * primary ListTools flow always falls through to a live Hub fetch
+ * when readCache returns null.
+ */
+export declare function readCache(workDir: string, log?: (msg: string) => void): CachedCatalog | null;
+/**
+ * Persist the catalog atomically. Writes a sibling tmp file then
+ * renames — so a crash mid-write leaves either the previous cache
+ * intact OR the new cache fully landed. Best-effort: failures log
+ * and return; the caller's primary flow continues.
+ */
+export declare function writeCache(workDir: string, catalog: ToolCatalog, hubVersion: string, log?: (msg: string) => void): void;
+/**
+ * Check cache validity against the current Hub version.
+ *
+ * Two semantics:
+ *   - currentHubVersion is a non-empty string: strict equality vs
+ *     cached.hubVersion. Mismatch → invalid → caller re-bootstraps.
+ *   - currentHubVersion is null/undefined/empty: caller doesn't know
+ *     the current Hub version yet (e.g. /health fetch in flight at
+ *     startup). Trust the cache (probe-friendly default) — worst
+ *     case is serving a stale catalog ONCE until the next /health
+ *     fetch completes and a real session refreshes the cache.
+ *
+ * Schema-version check is enforced inside readCache, so isCacheValid
+ * never sees a wrong-schema cached object.
+ */
+export declare function isCacheValid(cached: CachedCatalog, currentHubVersion: string | null | undefined): boolean;