@apnex/network-adapter 0.1.0

package/dist/tool-manager/tool-catalog-cache.js

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync, unlinkSync, } from "node:fs";
+import { join, dirname } from "node:path";
+/**
+ * Bumping CATALOG_SCHEMA_VERSION forces all existing cache files to
+ * be treated as invalid + re-bootstrapped. Use when changing the
+ * cache file shape.
+ */
+export const CATALOG_SCHEMA_VERSION = 1;
+/** Compute the canonical cache path for a given WORK_DIR. */
+export function cachePathFor(workDir) {
+    return join(workDir, ".ois", "tool-catalog.json");
+}
+/**
+ * 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 function readCache(workDir, log) {
+    const path = cachePathFor(workDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.schemaVersion !== "number" ||
+            parsed.schemaVersion !== CATALOG_SCHEMA_VERSION ||
+            typeof parsed.hubVersion !== "string" ||
+            typeof parsed.fetchedAt !== "string" ||
+            !Array.isArray(parsed.catalog)) {
+            log?.(`[tool-catalog-cache] readCache: cache invalid (schema/shape mismatch) at ${path}`);
+            return null;
+        }
+        return {
+            schemaVersion: parsed.schemaVersion,
+            hubVersion: parsed.hubVersion,
+            fetchedAt: parsed.fetchedAt,
+            catalog: parsed.catalog,
+        };
+    }
+    catch (err) {
+        log?.(`[tool-catalog-cache] readCache: parse error at ${path}: ${err.message ?? err}`);
+        return 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 function writeCache(workDir, catalog, hubVersion, log) {
+    const path = cachePathFor(workDir);
+    const tmpPath = `${path}.tmp.${process.pid}`;
+    const body = {
+        schemaVersion: CATALOG_SCHEMA_VERSION,
+        hubVersion,
+        fetchedAt: new Date().toISOString(),
+        catalog,
+    };
+    try {
+        const dir = dirname(path);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(tmpPath, JSON.stringify(body), { encoding: "utf8" });
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        log?.(`[tool-catalog-cache] writeCache: failed at ${path}: ${err.message ?? err} — cache will not populate this run`);
+        try {
+            if (existsSync(tmpPath))
+                unlinkSync(tmpPath);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * 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 function isCacheValid(cached, currentHubVersion) {
+    if (currentHubVersion === null ||
+        currentHubVersion === undefined ||
+        currentHubVersion === "") {
+        return true;
+    }
+    return cached.hubVersion === currentHubVersion;
+}
+//# sourceMappingURL=tool-catalog-cache.js.map

package/dist/tool-manager/tool-catalog-cache.js.map

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

package/dist/wire/mcp-transport.d.ts

@@ -0,0 +1,120 @@
+/**
+ * McpTransport — first `ITransport` implementation, backed by the MCP
+ * SDK's `Client` + `StreamableHTTPClientTransport`.
+ *
+ * Phase 2 of the L4/L7 refactor: extracted alongside the existing
+ * `McpConnectionManager`, which stays intact for the rest of the
+ * migration. Nothing in the current runtime uses this file yet — it
+ * exists so the Phase-2 gap tests can exercise the L4 surface in
+ * isolation and prove the split holds before Phase 3 relocates the
+ * session FSM.
+ *
+ * ## What this class owns (L4)
+ *
+ *   - The MCP wire: SDK `Client` + `StreamableHTTPClientTransport`.
+ *   - SSE liveness: first-keepalive deadline, mid-stream watchdog,
+ *     heartbeat POST loop.
+ *   - Wire-level reconnection: on SSE death or heartbeat failure it
+ *     tears down the SDK client and rebuilds a fresh one. Callers see
+ *     only `reconnecting` + `reconnected` wire events.
+ *   - Untyped `request(method, params)` over MCP `callTool`.
+ *   - `listMethods()` via MCP `listTools`.
+ *
+ * ## What this class deliberately does NOT own
+ *
+ *   - `register_role`. The bare register_role call that the legacy
+ *     `McpConnectionManager` fires during `connect()` is a session
+ *     concern — it binds the MCP session to an engineer role on the
+ *     Hub. `McpTransport.connect()` returns once the MCP wire is
+ *     initialized, *without* calling register_role. The caller
+ *     (future `IAgentClient`) issues the role call via
+ *     `transport.request("register_role", {role})` itself.
+ *   - Session FSM. No synchronizing / streaming vocabulary, no
+ *     sync buffer, no `completeSync()`.
+ *   - `session_invalid` classification and retry. Callers see the
+ *     raw error from `request()` and reconnect at the session layer.
+ *
+ * ## Hub-event push delivery
+ *
+ * SSE notifications land on the MCP client's `LoggingMessageNotification`
+ * handler. This class splits them into two streams:
+ *
+ *   - `logger === "keepalive"` frames feed the SSE watchdog and are
+ *     NOT forwarded to subscribers — they are wire noise.
+ *   - `logger === "hub-event"` frames are emitted as
+ *     `{ type: "push", method: "hub-event", payload }` via the
+ *     `onWireEvent` stream. Classification, dedup, and routing happen
+ *     above this layer.
+ */
+import type { ITransport, TransportConfig, TransportMetrics, WireState, WireEventHandler } from "./transport.js";
+/**
+ * Wire-level reconnect backoff curve. Pure function so the invariant
+ * (start at `baseDelay`, double each consecutive failure, clamp at
+ * `maxDelay`) is unit-testable without spinning a real wire.
+ *
+ * The cap on the exponent (`6`) matches the legacy manager: after six
+ * consecutive failures we're pegged at 60s and further failures don't
+ * push the delay higher — they just sit at the cap until a keepalive
+ * arrives and resets `consecutiveReconnects` to zero.
+ */
+export declare function computeReconnectBackoff(consecutiveReconnects: number, baseDelay: number, maxDelay?: number): number;
+export declare class McpTransport implements ITransport {
+    private readonly cfg;
+    private readonly log;
+    private client;
+    private sdkTransport;
+    private _wireState;
+    private handlers;
+    private lastKeepaliveAt;
+    private sseVerified;
+    private heartbeatTimer;
+    private sseWatchdogTimer;
+    private firstKeepaliveTimer;
+    private reconnectTimer;
+    private totalReconnects;
+    private consecutiveReconnects;
+    private lastReconnectCause?;
+    private requestsInFlight;
+    private reconnecting;
+    private closed;
+    constructor(config: TransportConfig);
+    get wireState(): WireState;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    request(method: string, params: Record<string, unknown>): Promise<unknown>;
+    listMethods(): Promise<string[]>;
+    /**
+     * Escape hatch for shims that need full MCP tool definitions
+     * (name + inputSchema + description), not just method names.
+     * Consumed by proxy shims that re-advertise the Hub's tool surface
+     * to another MCP client (e.g. Claude Code stdio proxy).
+     */
+    listToolsRaw(): Promise<Array<Record<string, unknown>>>;
+    onWireEvent(handler: WireEventHandler): void;
+    getMetrics(): TransportMetrics;
+    /**
+     * Test-only helper. Session IDs are an MCP-specific concept exposed
+     * here so Phase-2 integration tests can assert that a wire reconnect
+     * rebuilds the session. Not part of `ITransport`.
+     */
+    getSessionId(): string | undefined;
+    private createWire;
+    private teardownWire;
+    /**
+     * Wire-level reconnect loop. Entered on any wire-death signal
+     * (SSE drop, heartbeat failure, transport error). Emits
+     * `reconnecting` + (on success) `reconnected` wire events so the
+     * AgentClient above can re-run its L7 handshake.
+     */
+    private reconnectWire;
+    private scheduleReconnectTimer;
+    private cancelReconnectTimer;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private startSseWatchdog;
+    private stopSseWatchdog;
+    private startFirstKeepaliveDeadline;
+    private cancelFirstKeepaliveDeadline;
+    private transition;
+    private emit;
+}