@apnex/network-adapter 0.1.2 → 0.1.6

package/dist/tool-manager/catalog/tool-surface-reconciler.js

@@ -0,0 +1,101 @@
+/**
+ * tool-surface-reconciler.ts — declared-vs-applied reconcile for the Hub
+ * MCP tool surface (bug-180 / FR-21).
+ *
+ * Problem this closes: the host (e.g. Claude Code) enumerates `tools/list`
+ * ONCE at startup. On the pre-identity probe path the dispatcher serves the
+ * persisted on-disk catalog (tool-catalog-cache). When a Hub redeploy changes
+ * the tool surface, the in-memory catalog the host holds goes stale and
+ * nothing re-enumerates it — neither a client hard-reset nor /reload-plugins,
+ * because the long-lived proxy process never re-fetches and the redeploy emits
+ * no in-life `notifications/tools/list_changed` to already-connected hosts.
+ *
+ * The fix treats tool-surface delivery as a reconcile, mirroring the storage
+ * substrate's SchemaDef-reconciler:
+ *   - desired-state  = the Hub's tool surface, versioned by `toolSurfaceRevision`
+ *                      (a deterministic hash of the registered tool set, served
+ *                      on /health; Hub-side since bug-114).
+ *   - applied-state  = the revision the host most recently enumerated.
+ *   - watch/notify   = MCP `notifications/tools/list_changed` (the Hub already
+ *                      advertises `tools.listChanged: true`).
+ *
+ * On drift between applied and desired, emit `list_changed`; the host re-calls
+ * `tools/list` and — identity now resolved — the dispatcher serves the live
+ * surface (it skips the probe-cache path once identityReady is true).
+ *
+ * This class owns ONLY the reconcile decision + the applied-revision marker.
+ * All I/O is injected so it is unit-testable without a live Hub:
+ *   - fetchLiveRevision: resolve the Hub's current /health `toolSurfaceRevision`
+ *     (null on fetch failure / a Hub that doesn't return the field).
+ *   - readServedRevision: the revision the host's startup enumeration was
+ *     served from — the on-disk cache's `toolSurfaceRevision` (null when no
+ *     cache exists, i.e. a fresh install that bootstrapped live).
+ *   - emitListChanged: emit `notifications/tools/list_changed` to the host.
+ *
+ * Two trigger points share one `reconcile()`:
+ *   - L1 (primary): on the shim's `identityReady` event — catches the
+ *     redeploy-then-reconnect case that caused bug-180.
+ *   - L2 (backstop): on the existing PollBackstop heartbeat cadence — catches
+ *     a redeploy WHILE a session stays connected (no reconnect, so no fresh
+ *     identityReady).
+ *
+ * The applied-revision baseline is established on the first successful
+ * reconcile (whichever trigger fires first), seeded from the on-disk cache so
+ * a stale-cache-vs-live delta is detected even if L2 races ahead of L1.
+ */
+export class ToolSurfaceReconciler {
+    deps;
+    /**
+     * The revision the host is believed to currently have applied. null until
+     * the first successful reconcile establishes the baseline.
+     */
+    appliedRevision = null;
+    log;
+    constructor(deps) {
+        this.deps = deps;
+        this.log = deps.log ?? (() => { });
+    }
+    /** Test/diagnostic accessor for the current applied-state marker. */
+    getAppliedRevision() {
+        return this.appliedRevision;
+    }
+    /**
+     * One reconcile pass. Idempotent and safe to call from either trigger:
+     *   1. Resolve the live revision; no-op on unknown (fetch failed).
+     *   2. On first pass, seed the applied baseline from the on-disk cache
+     *      (what the host's startup probe served) — or from live if no cache.
+     *   3. On applied-vs-live drift, emit `list_changed` + advance the baseline.
+     *
+     * @param reason short label for logs (e.g. "identityReady", "heartbeat").
+     */
+    async reconcile(reason = "reconcile") {
+        const live = await this.deps.fetchLiveRevision();
+        if (live === null) {
+            this.log(`[tool-surface-reconcile] ${reason}: live revision unknown — skipping (cache trusted)`);
+            return { emitted: false, live: null };
+        }
+        // Establish the applied-state baseline on the first successful pass. Prefer
+        // the on-disk cache revision (the surface the pre-identity probe served);
+        // fall back to live when no cache exists (fresh install already enumerated
+        // live, so there is nothing to reconcile against).
+        if (this.appliedRevision === null) {
+            const served = this.deps.readServedRevision();
+            this.appliedRevision = served ?? live;
+            this.log(`[tool-surface-reconcile] ${reason}: baseline applied=${this.appliedRevision} (served=${served ?? "none"}, live=${live})`);
+        }
+        if (live !== this.appliedRevision) {
+            this.log(`[tool-surface-reconcile] ${reason}: drift applied=${this.appliedRevision} → live=${live} — emitting tools/list_changed`);
+            try {
+                this.deps.emitListChanged();
+            }
+            catch (err) {
+                // Never let a host-emit failure escape the reconcile loop.
+                this.log(`[tool-surface-reconcile] ${reason}: emitListChanged threw (non-fatal): ${err?.message ?? String(err)}`);
+            }
+            this.appliedRevision = live;
+            return { emitted: true, live };
+        }
+        return { emitted: false, live };
+    }
+}
+//# sourceMappingURL=tool-surface-reconciler.js.map

package/dist/tool-manager/catalog/tool-surface-reconciler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-surface-reconciler.js","sourceRoot":"","sources":["../../../src/tool-manager/catalog/tool-surface-reconciler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAiCH,MAAM,OAAO,qBAAqB;IAQH;IAP7B;;;OAGG;IACK,eAAe,GAAkB,IAAI,CAAC;IAC7B,GAAG,CAAwB;IAE5C,YAA6B,IAA+B;QAA/B,SAAI,GAAJ,IAAI,CAA2B;QAC1D,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACpC,CAAC;IAED,qEAAqE;IACrE,kBAAkB;QAChB,OAAO,IAAI,CAAC,eAAe,CAAC;IAC9B,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,SAAS,CAAC,MAAM,GAAG,WAAW;QAClC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACjD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,IAAI,CAAC,GAAG,CACN,4BAA4B,MAAM,oDAAoD,CACvF,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACxC,CAAC;QAED,4EAA4E;QAC5E,0EAA0E;QAC1E,2EAA2E;QAC3E,mDAAmD;QACnD,IAAI,IAAI,CAAC,eAAe,KAAK,IAAI,EAAE,CAAC;YAClC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC9C,IAAI,CAAC,eAAe,GAAG,MAAM,IAAI,IAAI,CAAC;YACtC,IAAI,CAAC,GAAG,CACN,4BAA4B,MAAM,sBAAsB,IAAI,CAAC,eAAe,YAAY,MAAM,IAAI,MAAM,UAAU,IAAI,GAAG,CAC1H,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,KAAK,IAAI,CAAC,eAAe,EAAE,CAAC;YAClC,IAAI,CAAC,GAAG,CACN,4BAA4B,MAAM,mBAAmB,IAAI,CAAC,eAAe,WAAW,IAAI,gCAAgC,CACzH,CAAC;YACF,IAAI,CAAC;gBACH,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YAC9B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,2DAA2D;gBAC3D,IAAI,CAAC,GAAG,CACN,4BAA4B,MAAM,wCAAyC,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,CACnH,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;YAC5B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QACjC,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClC,CAAC;CACF"}

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

@@ -0,0 +1,91 @@
+/**
+ * contracts.ts — the agnostic Tool-Manager contract (Slice A).
+ *
+ * The internal-sovereign-module boundary for tool catalog + dispatch. These
+ * interfaces are host- AND transport-agnostic BY CONSTRUCTION: nothing here
+ * imports `@modelcontextprotocol/sdk`, `McpAgentClient`, or any binding. A
+ * consumer (the MCP binding, pi's native binding, a future ACP binding) depends
+ * ONLY on these types — never on the concrete kernel classes (A3 Air-Gap).
+ *
+ * Design: docs/designs/m-sovereign-tool-manager-design.md
+ * Axioms:  A3 Sovereign Composition (Law of One, Air-Gap, Semantic Bit-Masking,
+ *          Earned Exposure — this is an INTERNAL module, not a published package).
+ *
+ * SLICE A INVARIANT: purely additive. `McpAgentClient` (via `IAgentClient`)
+ * structurally satisfies `IToolDispatchAgent` today with zero changes — this
+ * file only NAMES the subset the tool-manager actually needs, so the dispatch
+ * authority (Slice B) can depend on the interface instead of the class.
+ */
+/**
+ * Neutral tool descriptor — MCP-shaped fields (name / description / JSON-Schema
+ * inputSchema) but NOT an MCP SDK type. Every binding materializes its own host
+ * representation from this (MCP `Tool`, pi typebox `parameters`, …). This is the
+ * bit-perfect interface both sides agree on (A3 Semantic Bit-Masking).
+ *
+ * Structurally identical to `@apnex/cognitive-layer`'s `Tool`, deliberately
+ * re-declared here so the contract owns its own shape and carries no dependency
+ * on the cognitive layer.
+ */
+export interface ToolDescriptor {
+    name: string;
+    description?: string;
+    inputSchema?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * Options forwarded to a dispatch-time agent call. Mirrors the kernel's
+ * `AgentCallOptions` subset the tool-manager relies on.
+ */
+export interface ToolDispatchCallOptions {
+    /** Mark this call internal-machinery — skip LLM-facing result transforms. */
+    internal?: boolean;
+}
+/**
+ * The minimal agent surface the Tool-Manager needs. `McpAgentClient` /
+ * `IAgentClient` satisfy this structurally — the tool-manager imports THIS,
+ * never the class, which is what keeps the module carve-able and breaks the
+ * would-be circular dependency (tool-manager → kernel).
+ *
+ * `listTools()` already returns the tier-filtered, cognitively-enriched surface
+ * (the kernel owns that filtering) — the tool-manager consumes the finished
+ * descriptor and does not re-derive it.
+ */
+export interface IToolDispatchAgent {
+    readonly state: string;
+    readonly isConnected: boolean;
+    call(method: string, params: Record<string, unknown>, opts?: ToolDispatchCallOptions): Promise<unknown>;
+    listTools(): Promise<ToolDescriptor[]>;
+    getMetrics?(): {
+        agentId?: string;
+    };
+}
+/**
+ * Neutral dispatch result. Bindings format this into their host shape (MCP
+ * `content[]` + `isError`, pi `ToolResult`, …). NOT an MCP `CallToolResult`.
+ */
+export interface ToolDispatchResult {
+    /** Raw dispatch return — a string, or a JSON-serializable value. */
+    value: unknown;
+    isError: boolean;
+    /** Present when `isError` — the normalized failure message. */
+    errorMessage?: string;
+}
+/**
+ * The Tool-Manager authority (Slice B fills the impl). Owns exactly two
+ * concerns (A3 Law of One): the tool CATALOG (what tools exist, projected for a
+ * host) and tool DISPATCH (the per-call behavior wrapper currently trapped in
+ * the MCP `CallTool` handler body). Every binding terminates in `dispatch()`.
+ */
+export interface IToolManager {
+    /** Catalog authority — the derive-from-one-walk surface (A2). */
+    listTools(agent: IToolDispatchAgent): Promise<ToolDescriptor[]>;
+    /**
+     * Dispatch authority — the per-call behavior wrapper. Owns signal-FSM
+     * wrapping, queueItemId injection, active-call idle-gate bookkeeping, work-
+     * lease observation, and error normalization. (Slice B.)
+     */
+    dispatch(agent: IToolDispatchAgent, name: string, args: Record<string, unknown>): Promise<ToolDispatchResult>;
+    /** idle-gate reads (the wake/stall reconciler consumes these). */
+    getActiveCallCount(): number;
+    isIdle(): boolean;
+}

package/dist/tool-manager/contracts.js

@@ -0,0 +1,20 @@
+/**
+ * contracts.ts — the agnostic Tool-Manager contract (Slice A).
+ *
+ * The internal-sovereign-module boundary for tool catalog + dispatch. These
+ * interfaces are host- AND transport-agnostic BY CONSTRUCTION: nothing here
+ * imports `@modelcontextprotocol/sdk`, `McpAgentClient`, or any binding. A
+ * consumer (the MCP binding, pi's native binding, a future ACP binding) depends
+ * ONLY on these types — never on the concrete kernel classes (A3 Air-Gap).
+ *
+ * Design: docs/designs/m-sovereign-tool-manager-design.md
+ * Axioms:  A3 Sovereign Composition (Law of One, Air-Gap, Semantic Bit-Masking,
+ *          Earned Exposure — this is an INTERNAL module, not a published package).
+ *
+ * SLICE A INVARIANT: purely additive. `McpAgentClient` (via `IAgentClient`)
+ * structurally satisfies `IToolDispatchAgent` today with zero changes — this
+ * file only NAMES the subset the tool-manager actually needs, so the dispatch
+ * authority (Slice B) can depend on the interface instead of the class.
+ */
+export {};
+//# sourceMappingURL=contracts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/tool-manager/contracts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

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

@@ -0,0 +1,77 @@
+/**
+ * dispatch.ts — the tool DISPATCH authority (Slice B).
+ *
+ * This is the per-call behavior wrapper extracted VERBATIM from the MCP
+ * `CallTool` handler body in `dispatcher.ts` (the god-object). It owns the
+ * OIS-Hub dispatch policy that EVERY host binding must share:
+ *   - idle-gate bookkeeping (activeCallCount) for the wake/stall reconciler
+ *   - callToolGate wait + bug-126 timeout
+ *   - "Hub not connected" pre-check
+ *   - injectQueueItemId (ADR-017)
+ *   - signal_working_* FSM wrapping (mission-62)
+ *   - workLeases.observe (idea-353)
+ *   - onToolCallResult host hook
+ *   - error normalization + W10 terminal-log discipline
+ *
+ * SLICE B DISCIPLINE: this is a faithful EXTRACT-AND-DELEGATE. The logic, its
+ * order, the log lines, and the return shape are preserved byte-for-byte from
+ * the original handler so the 272-test regression suite certifies behavioral
+ * identity. The MCP `CallTool` handler in `dispatcher.ts` now calls
+ * `runToolDispatch(...)` and returns its result directly.
+ *
+ * Deliberately NOT done here (deferred to Slice C, per the two-phase rule):
+ *   - converting the MCP-shaped return to the neutral `ToolDispatchResult`
+ *   - relocating callToolGate / "Hub not connected" to the MCP binding
+ *   - collapsing the closure / renaming
+ * Faithful move first; structural cleanup when files move.
+ *
+ * Design: docs/designs/m-sovereign-tool-manager-design.md (Slice B)
+ * Axioms: A3 (Air-Gap — depends on injected deps, not the closure), A8 (certify
+ *         before ascending — regression parity is the gate).
+ */
+import type { IToolDispatchAgent } from "../contracts.js";
+import { WorkLeaseTracker } from "../work-protocol/work-lease-tracker.js";
+/**
+ * The MCP-shaped result the CallTool handler returns today. Preserved verbatim
+ * in Slice B (the neutral `ToolDispatchResult` conversion is a Slice-C concern).
+ */
+export interface McpToolCallResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * Explicit dependency context for a single tool dispatch. In the god-object
+ * these were closure variables; making them injected params is the A3 Air-Gap
+ * boundary being realized — `runToolDispatch` is now understandable and testable
+ * from its inputs alone (A3 Local Reasoning), with no hidden closure state.
+ */
+export interface ToolDispatchContext {
+    /** Late-bound agent accessor (null = not connected yet). */
+    getAgent: () => IToolDispatchAgent | null;
+    /** ADR-017 queueItemId tracking map (shared with the notification path). */
+    pendingActionMap: Map<string, string>;
+    /** idea-353 lease tracker (shared with the wake/stall reconciler). */
+    workLeases: WorkLeaseTracker;
+    /** Increment on dispatch entry (idle-gate); returns nothing. */
+    onCallStart: () => void;
+    /** Decrement on dispatch exit (idle-gate). */
+    onCallEnd: () => void;
+    /** Optional gate the dispatch awaits before touching the Hub. */
+    callToolGate?: Promise<void>;
+    /** bug-126 gate timeout (ms). Default 30000; 0 disables. */
+    callToolGateTimeoutMs?: number;
+    /** idea-353 W2 host observation hook (best-effort). */
+    onToolCallResult?: (method: string, args: Record<string, unknown>, result: unknown) => void;
+    /** Diagnostic logger. */
+    log: (msg: string) => void;
+}
+/**
+ * Execute one host-driven tool call through the full OIS dispatch policy.
+ *
+ * Extracted verbatim from the CallTool handler; `ctx` supplies what were closure
+ * variables. Returns the same MCP-shaped result the handler returned.
+ */
+export declare function runToolDispatch(ctx: ToolDispatchContext, requestedTool: string, incomingArgs: Record<string, unknown>): Promise<McpToolCallResult>;

package/dist/tool-manager/dispatch/dispatch.js

@@ -0,0 +1,170 @@
+/**
+ * dispatch.ts — the tool DISPATCH authority (Slice B).
+ *
+ * This is the per-call behavior wrapper extracted VERBATIM from the MCP
+ * `CallTool` handler body in `dispatcher.ts` (the god-object). It owns the
+ * OIS-Hub dispatch policy that EVERY host binding must share:
+ *   - idle-gate bookkeeping (activeCallCount) for the wake/stall reconciler
+ *   - callToolGate wait + bug-126 timeout
+ *   - "Hub not connected" pre-check
+ *   - injectQueueItemId (ADR-017)
+ *   - signal_working_* FSM wrapping (mission-62)
+ *   - workLeases.observe (idea-353)
+ *   - onToolCallResult host hook
+ *   - error normalization + W10 terminal-log discipline
+ *
+ * SLICE B DISCIPLINE: this is a faithful EXTRACT-AND-DELEGATE. The logic, its
+ * order, the log lines, and the return shape are preserved byte-for-byte from
+ * the original handler so the 272-test regression suite certifies behavioral
+ * identity. The MCP `CallTool` handler in `dispatcher.ts` now calls
+ * `runToolDispatch(...)` and returns its result directly.
+ *
+ * Deliberately NOT done here (deferred to Slice C, per the two-phase rule):
+ *   - converting the MCP-shaped return to the neutral `ToolDispatchResult`
+ *   - relocating callToolGate / "Hub not connected" to the MCP binding
+ *   - collapsing the closure / renaming
+ * Faithful move first; structural cleanup when files move.
+ *
+ * Design: docs/designs/m-sovereign-tool-manager-design.md (Slice B)
+ * Axioms: A3 (Air-Gap — depends on injected deps, not the closure), A8 (certify
+ *         before ascending — regression parity is the gate).
+ */
+import { injectQueueItemId, TOOL_CALL_SIGNAL_SKIP } from "./tool-call-policy.js";
+/** True when the agent is present and not explicitly disconnected. */
+function isUsableAgent(agent) {
+    return !!agent && agent.isConnected !== false;
+}
+/**
+ * Execute one host-driven tool call through the full OIS dispatch policy.
+ *
+ * Extracted verbatim from the CallTool handler; `ctx` supplies what were closure
+ * variables. Returns the same MCP-shaped result the handler returned.
+ */
+export async function runToolDispatch(ctx, requestedTool, incomingArgs) {
+    const { log } = ctx;
+    const callStartedAt = Date.now();
+    log(`[CallTool] ${requestedTool} entered`);
+    // idea-353 W1 idle-gate: mark the agent busy for the full lifespan of this
+    // host CallTool (gate-wait included), cleared in the finally below.
+    ctx.onCallStart();
+    try {
+        if (ctx.callToolGate) {
+            log(`[CallTool] ${requestedTool} awaiting callToolGate`);
+            // mission-88 W10 (bug-126 fix): timeout the gate await to prevent
+            // indefinite hang on pending-forever sessionReady. Default 30s; set
+            // callToolGateTimeoutMs=0 to disable (test-only). Structured
+            // `gate-timeout` log emitted on timeout; isError response returned.
+            const timeoutMs = ctx.callToolGateTimeoutMs ?? 30000;
+            if (timeoutMs > 0) {
+                let timeoutHandle;
+                const timeoutPromise = new Promise((_resolve, reject) => {
+                    timeoutHandle = setTimeout(() => {
+                        reject(new Error(`callToolGate timeout after ${timeoutMs}ms`));
+                    }, timeoutMs);
+                });
+                try {
+                    await Promise.race([ctx.callToolGate, timeoutPromise]);
+                }
+                finally {
+                    if (timeoutHandle)
+                        clearTimeout(timeoutHandle);
+                }
+            }
+            else {
+                await ctx.callToolGate;
+            }
+            log(`[CallTool] ${requestedTool} gate passed (+${Date.now() - callStartedAt}ms)`);
+        }
+        const agent = ctx.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 = requestedTool;
+        const outgoingArgs = injectQueueItemId(name, incomingArgs, ctx.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). Skip-list prevents
+        // recursion + handshake/lifecycle tools.
+        const wrapWithSignal = !TOOL_CALL_SIGNAL_SKIP.has(name);
+        if (wrapWithSignal) {
+            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`);
+            // idea-355 §4.3 (invariant #3) — kernel-side W2 observer. Feed this
+            // agent's own work-verb results to the lease tracker so the heartbeat
+            // tick's stall-prompt has a populated lease map. Best-effort.
+            try {
+                ctx.workLeases.observe(name, outgoingArgs, result, Date.now());
+            }
+            catch (obsErr) {
+                log(`[idea-353] kernel lease observe threw (non-fatal): ${obsErr?.message ?? obsErr}`);
+            }
+            // idea-353 W2: optional host hook for host-specific observation.
+            if (ctx.onToolCallResult) {
+                try {
+                    ctx.onToolCallResult(name, outgoingArgs, result);
+                }
+                catch (hookErr) {
+                    log(`[idea-353] onToolCallResult hook threw (non-fatal): ${hookErr?.message ?? hookErr}`);
+                }
+            }
+        }
+        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);
+        // mission-88 W10 (bug-126 fix): post-condition logging discipline — every
+        // CallTool entry MUST emit exactly one terminal log line.
+        const outcome = message.startsWith("callToolGate timeout")
+            ? "gate-timeout"
+            : "error-response";
+        log(`[CallTool] ${requestedTool} terminal: outcome=${outcome} elapsed=${Date.now() - callStartedAt}ms message="${message}"`);
+        return {
+            content: [
+                { type: "text", text: JSON.stringify({ error: message, w10_outcome: outcome }) },
+            ],
+            isError: true,
+        };
+    }
+    finally {
+        // idea-353 W1 idle-gate: this CallTool is no longer in flight.
+        ctx.onCallEnd();
+    }
+}
+//# sourceMappingURL=dispatch.js.map

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

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

package/dist/tool-manager/dispatch/tool-call-policy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * tool-call-policy.ts — pure OIS-Hub tool-call policy helpers (Slice B).
+ *
+ * Extracted VERBATIM from `dispatcher.ts` so both the dispatch authority
+ * (`dispatch.ts`) and the god-object shell can share them without a circular
+ * import. Pure functions + one constant; no closure, no MCP, no kernel.
+ *
+ * These encode OIS-Hub-specific dispatch POLICY (the §8 debt in the design):
+ * the thread/queue queueItemId settlement rule + the signal-FSM skip-list. They
+ * live in the tool-manager module (isolated), NOT in a generic core — which is
+ * exactly why the module is not a publishable package (Earned Exposure / the
+ * standalone-utility test).
+ */
+/**
+ * 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>;
+/** Compose the pendingActionMap key. Pure helper; exported for tests. */
+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>;

package/dist/tool-manager/dispatch/tool-call-policy.js

@@ -0,0 +1,56 @@
+/**
+ * tool-call-policy.ts — pure OIS-Hub tool-call policy helpers (Slice B).
+ *
+ * Extracted VERBATIM from `dispatcher.ts` so both the dispatch authority
+ * (`dispatch.ts`) and the god-object shell can share them without a circular
+ * import. Pure functions + one constant; no closure, no MCP, no kernel.
+ *
+ * These encode OIS-Hub-specific dispatch POLICY (the §8 debt in the design):
+ * the thread/queue queueItemId settlement rule + the signal-FSM skip-list. They
+ * live in the tool-manager module (isolated), NOT in a generic core — which is
+ * exactly why the module is not a publishable package (Earned Exposure / the
+ * standalone-utility test).
+ */
+/**
+ * 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",
+]);
+/** Compose the pendingActionMap key. Pure helper; exported for tests. */
+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 };
+}
+//# sourceMappingURL=tool-call-policy.js.map

package/dist/tool-manager/dispatch/tool-call-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call-policy.js","sourceRoot":"","sources":["../../../src/tool-manager/dispatch/tool-call-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAwB,IAAI,GAAG,CAAC;IAChE,wBAAwB;IACxB,0BAA0B;IAC1B,sBAAsB;IACtB,wBAAwB;IACxB,eAAe;IACf,eAAe;IACf,uBAAuB;CACxB,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,UAAU,UAAU,CAAC,YAAoB,EAAE,SAAiB;IAChE,OAAO,GAAG,YAAY,IAAI,SAAS,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAY,EACZ,IAA6B,EAC7B,gBAAqC;IAErC,IAAI,IAAI,KAAK,qBAAqB;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAC/B,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC9C,IAAI,mBAAmB,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IAC7C,MAAM,WAAW,GAAG,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC,CAAC;IACjF,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,gBAAgB,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,OAAO,EAAE,GAAG,IAAI,EAAE,iBAAiB,EAAE,WAAW,EAAE,CAAC;AACrD,CAAC"}