@apnex/network-adapter 0.1.1 → 0.1.5

package/dist/tool-manager/{dispatcher.d.ts → orchestrator/dispatcher.d.ts}

@@ -19,11 +19,13 @@
  * "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";
+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 "../catalog/tool-catalog-cache.js";
+import { WorkLeaseTracker } from "../work-protocol/work-lease-tracker.js";
+import { TOOL_CALL_SIGNAL_SKIP, pendingKey, injectQueueItemId } from "../dispatch/tool-call-policy.js";
 export interface DispatcherClientInfo {
     name: string;
     version: string;
@@ -47,8 +49,11 @@ 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.
+     * surfaces a "Hub not connected" error envelope on CallTool and a
+     * structured MCP error on ListTools after a bounded retry window
+     * (bug-114 fallback-gap fix). Silent empty-tool-list response was
+     * retired 2026-05-26 — host MCP clients (e.g. Claude Code) cached
+     * the empty list as the authoritative surface, masking comms-loss.
      */
     getAgent: () => McpAgentClient | null;
     /** Adapter version reported in MCP serverInfo. */
@@ -64,10 +69,19 @@ export interface SharedDispatcherOptions {
     /** 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).
+     * Resolves when the underlying McpAgentClient is fully usable
+     * (transport connected + identity asserted + streaming-state
+     * reached, i.e. `agent.start()` returned). Gates the ListTools
+     * handler's bootstrap path; on probe-path (`!identityReady`) the
+     * cache fallback runs without awaiting this gate.
+     *
+     * bug-141 pass-2 (2026-05-28): docs updated from "handshake
+     * completes" → "fully usable". The earlier wording prompted host
+     * shims to gate on `identityReady`, which opened the gate ~1.3s
+     * before `agent.isConnected` flipped true (during the synchronizing
+     * → streaming transition) — surfacing the bug-141 race. Hosts MUST
+     * gate on a Promise that resolves only after the agent is in
+     * streaming state (claude-plugin: `syncReady`).
      *
      * Was: `handshakeComplete` (per-plugin dispatchers). Renamed in
      * mission-55 cleanup per Design v1.2 Q5: name what is gated, not
@@ -84,22 +98,47 @@ export interface SharedDispatcherOptions {
      * cleanup per Design v1.2 Q5.
      */
     callToolGate?: Promise<void>;
+    /**
+     * mission-88 W10 (bug-126 fix): timeout in ms for `await callToolGate`.
+     * If the gate Promise neither resolves nor rejects within this budget,
+     * the dispatcher emits a structured `gate-timeout` log line + returns
+     * isError to host (instead of hanging indefinitely as the bug-126
+     * incident exhibited). Default 30000ms; set to 0 to disable.
+     *
+     * Defense against pending-forever sessionReady Promises (W10 Design §3
+     * H1+H3 hypotheses). The timeout is a fail-safe — production-correct
+     * handshake flow should never hit it.
+     */
+    callToolGateTimeoutMs?: number;
     getCachedCatalog?: () => CachedCatalog | null;
     getIsIdentityReady?: () => boolean;
-    getCurrentHubVersion?: () => string | null;
+    /**
+     * bug-114 — current Hub tool-surface revision (`/health`
+     * `toolSurfaceRevision`). The cache-validity key; `null` when the
+     * /health fetch hasn't resolved yet (probe-friendly trust-cache).
+     */
+    getCurrentToolSurfaceRevision?: () => 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.
+     * to enable tool-surface-revision-keyed validity.
      */
-    isCacheValid?: (cached: CachedCatalog, currentHubVersion: string | null | undefined) => boolean;
+    isCacheValid?: (cached: CachedCatalog, currentRevision: string | null | undefined) => boolean;
     /**
      * Universal Adapter notification contract. Host shim attaches its
      * render-surface bindings here.
      */
     notificationHooks?: DispatcherNotificationHooks;
+    /**
+     * idea-353 W2: observe each host-driven CallTool's (method, args, result)
+     * after it returns. The host wires this to a WorkLeaseTracker so the
+     * outbound stall-prompt can track this agent's own held leases locally
+     * (claim/renew/complete/abandon) with no Hub round-trip. Best-effort —
+     * a throw is caught + logged and never affects the tool-call return.
+     */
+    onToolCallResult?: (method: string, args: Record<string, unknown>, result: unknown) => void;
     /**
      * Mission-56 W3.3: opt-in adapter-side hybrid poll backstop. When
      * supplied, the dispatcher constructs a PollBackstop (Design v1.2
@@ -113,6 +152,24 @@ export interface SharedDispatcherOptions {
      * Omit to disable polling (push-only mode).
      */
     pollBackstop?: Omit<PollBackstopOptions, "onPolledMessage">;
+    /**
+     * Slice D (pi native binding) — external idle probe. A NATIVE host (pi) drives
+     * tool calls through `runToolDispatch` directly, NOT through this dispatcher's
+     * MCP `CallTool` handler, so the internal `activeCallCount` never sees them.
+     * Supply the host's own idle signal (e.g. pi's `ctx.isIdle()`) and the
+     * wake/stall reconcile gates on THAT instead of the (always-zero) internal
+     * counter. When omitted, the internal `activeCallCount` is authoritative
+     * (MCP hosts — unchanged).
+     */
+    externalIdle?: () => boolean;
+    /**
+     * Slice D (pi native binding) — shared WorkLeaseTracker. A native host's
+     * `ToolDispatchContext.workLeases` must be the SAME tracker the reconcile
+     * reads for stall-prompts. Inject it here so the native binding's
+     * `workLeases.observe(...)` populates the tracker the heartbeat tick consumes.
+     * When omitted, the dispatcher constructs its own (MCP hosts — unchanged).
+     */
+    sharedWorkLeases?: WorkLeaseTracker;
 }
 export interface SharedDispatcher {
     /** ADR-017 queueItemId tracking map. Keyed by `${dispatchType}:${entityRef}`. */
@@ -157,24 +214,46 @@ export interface SharedDispatcher {
      * re-render it.
      */
     ackMessage: (messageId: string) => Promise<void>;
+    /**
+     * idea-353 W1 idle-gate: number of host-driven CallTool requests currently
+     * in flight. The wake/stall reconciler reads this on the heartbeat tick to
+     * skip surfacing while the agent is mid-task (AC4). The tick's own internal
+     * `agent.call`s do not pass through the CallTool handler, so they are not
+     * counted (an idle poll never self-gates).
+     */
+    getActiveCallCount: () => number;
+    /** idea-353 W1 idle-gate convenience: `getActiveCallCount() === 0`. */
+    isIdle: () => boolean;
+    /**
+     * Slice D (pi native binding) — the WorkLeaseTracker the reconcile reads. A
+     * native host builds its `ToolDispatchContext.workLeases` from THIS instance
+     * so its `runToolDispatch` lease observations feed the stall-prompt path.
+     * (Same object as `opts.sharedWorkLeases` when injected.)
+     */
+    workLeases: WorkLeaseTracker;
 }
-/** 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;
+export { TOOL_CALL_SIGNAL_SKIP, pendingKey, injectQueueItemId };
+export declare function createSharedDispatcher(opts: SharedDispatcherOptions): SharedDispatcher;
 /**
- * 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.
+ * 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).
  *
- * Side effect: deletes the consumed map entry. Explicit
- * sourceQueueItemId in the args wins over the map (no rewrite).
+ * 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 declare function injectQueueItemId(name: string, args: Record<string, unknown>, pendingActionMap: Map<string, string>): Record<string, unknown>;
-export declare function createSharedDispatcher(opts: SharedDispatcherOptions): SharedDispatcher;
+export declare function assertHostWiringComplete(dispatcher: {
+    pollBackstop?: PollBackstop;
+}, log?: (msg: string) => void): void;