@apnex/network-adapter 0.1.0

package/dist/hub-error.d.ts

@@ -0,0 +1,42 @@
+/**
+ * HubReturnedError — wraps an MCP isError envelope as a thrown Error.
+ *
+ * MCP tool calls can return two error shapes:
+ *
+ *   1. Transport-layer faults (network, 5xx, connection refused) —
+ *      these throw naturally from the transport layer.
+ *
+ *   2. Hub-layer application errors (Zod validation, unknown tool,
+ *      cascade-schema drift, authorization) — these come back as
+ *      `{ isError: true, content: [{ type: "text", text: "..." }] }`
+ *      envelopes. They do NOT throw by default — the legacy agent.call
+ *      return path delivers them as typed values.
+ *
+ * The cognitive pipeline's `onToolError` only fires on thrown errors.
+ * For ErrorNormalizer to observe Hub-layer application errors, the
+ * envelope must be converted to a throw. `McpAgentClient` does this
+ * in its cognitive path by wrapping the envelope in this error class
+ * before propagating.
+ *
+ * Legacy callers (no cognitive pipeline) continue to see envelope-as-
+ * return-value — unchanged contract.
+ */
+export declare class HubReturnedError extends Error {
+    readonly name = "HubReturnedError";
+    /** Original envelope `{ isError, content }` from the transport. */
+    readonly envelope: unknown;
+    constructor(envelope: unknown);
+}
+/**
+ * Type-guard: does this value look like an MCP isError envelope?
+ * Deliberately narrow — only `isError === true` + `content[0].text`
+ * shape qualifies. Avoids false positives on legitimate response
+ * payloads that happen to carry an `error` field.
+ */
+export declare function isErrorEnvelope(value: unknown): value is {
+    isError: true;
+    content: Array<{
+        type?: string;
+        text?: string;
+    }>;
+};

package/dist/hub-error.js

@@ -0,0 +1,74 @@
+/**
+ * HubReturnedError — wraps an MCP isError envelope as a thrown Error.
+ *
+ * MCP tool calls can return two error shapes:
+ *
+ *   1. Transport-layer faults (network, 5xx, connection refused) —
+ *      these throw naturally from the transport layer.
+ *
+ *   2. Hub-layer application errors (Zod validation, unknown tool,
+ *      cascade-schema drift, authorization) — these come back as
+ *      `{ isError: true, content: [{ type: "text", text: "..." }] }`
+ *      envelopes. They do NOT throw by default — the legacy agent.call
+ *      return path delivers them as typed values.
+ *
+ * The cognitive pipeline's `onToolError` only fires on thrown errors.
+ * For ErrorNormalizer to observe Hub-layer application errors, the
+ * envelope must be converted to a throw. `McpAgentClient` does this
+ * in its cognitive path by wrapping the envelope in this error class
+ * before propagating.
+ *
+ * Legacy callers (no cognitive pipeline) continue to see envelope-as-
+ * return-value — unchanged contract.
+ */
+export class HubReturnedError extends Error {
+    name = "HubReturnedError";
+    /** Original envelope `{ isError, content }` from the transport. */
+    envelope;
+    constructor(envelope) {
+        super(extractErrorMessage(envelope));
+        this.envelope = envelope;
+    }
+}
+/**
+ * Type-guard: does this value look like an MCP isError envelope?
+ * Deliberately narrow — only `isError === true` + `content[0].text`
+ * shape qualifies. Avoids false positives on legitimate response
+ * payloads that happen to carry an `error` field.
+ */
+export function isErrorEnvelope(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const v = value;
+    if (v.isError !== true)
+        return false;
+    if (!Array.isArray(v.content))
+        return false;
+    return true;
+}
+/**
+ * Extract a human-readable message from an isError envelope. If the
+ * content[0].text is valid JSON with an `error` field, return that;
+ * otherwise return the raw text. Falls back to a generic message
+ * when the envelope lacks a text block.
+ */
+function extractErrorMessage(envelope) {
+    if (!envelope || typeof envelope !== "object")
+        return "Hub returned an error";
+    const content = envelope.content;
+    const text = Array.isArray(content) && content[0]?.text;
+    if (!text)
+        return "Hub returned an error";
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed?.error === "string")
+            return parsed.error;
+        if (typeof parsed?.message === "string")
+            return parsed.message;
+        return text;
+    }
+    catch {
+        return text;
+    }
+}
+//# sourceMappingURL=hub-error.js.map

package/dist/hub-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-error.js","sourceRoot":"","sources":["../src/hub-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,GAAG,kBAAkB,CAAC;IACnC,mEAAmE;IAC1D,QAAQ,CAAU;IAE3B,YAAY,QAAiB;QAC3B,KAAK,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAI5C,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,KAGT,CAAC;IACF,IAAI,CAAC,CAAC,OAAO,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,QAAiB;IAC5C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,uBAAuB,CAAC;IAC9E,MAAM,OAAO,GAAI,QAAmD,CAAC,OAAO,CAAC;IAC7E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;IACxD,IAAI,CAAC,IAAI;QAAE,OAAO,uBAAuB,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,OAAO,MAAM,EAAE,KAAK,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,KAAK,CAAC;QAC3D,IAAI,OAAO,MAAM,EAAE,OAAO,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,OAAO,CAAC;QAC/D,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export type { ITransport, TransportConfig, TransportMetrics, WireState, WireReconnectCause, WireEvent, WireEventHandler, } from "./wire/transport.js";
+export { McpTransport } from "./wire/mcp-transport.js";
+export { McpAgentClient } from "./kernel/mcp-agent-client.js";
+export type { McpAgentClientOptions } from "./kernel/mcp-agent-client.js";
+export type { IAgentClient, AgentClientConfig, AgentClientCallbacks, AgentClientMetrics, AgentEvent, AgentHandshakeConfig, SessionState, SessionReconnectReason, } from "./kernel/agent-client.js";
+export type { HubEventType, HubEvent, EventDisposition, } from "./kernel/event-router.js";
+export { classifyEvent, parseHubEvent, createDedupFilter, } from "./kernel/event-router.js";
+export { loadOrCreateGlobalInstanceId } from "./kernel/instance.js";
+export type { LoadInstanceOptions } from "./kernel/instance.js";
+export { FATAL_CODES, parseHandshakeError, parseHandshakeResponse, buildHandshakePayload, performHandshake, makeStdioFatalHalt, } from "./kernel/handshake.js";
+export type { HandshakeClientMetadata, HandshakeAdvisoryTags, HandshakePayload, HandshakeResponse, HandshakeFatalError, HandshakeConfig, HandshakeContext, HandshakeResult, } from "./kernel/handshake.js";
+export { performStateSync } from "./kernel/state-sync.js";
+export type { StateSyncContext, DrainedPendingAction } from "./kernel/state-sync.js";
+export { PollBackstop, defaultCursorFile, readCursor, writeCursor, } from "./kernel/poll-backstop.js";
+export type { PollBackstopOptions } from "./kernel/poll-backstop.js";
+export { isEagerWarmupEnabled, parseClaimSessionResponse, formatSessionClaimedLogLine, } from "./kernel/session-claim.js";
+export type { ClaimSessionParsed } from "./kernel/session-claim.js";
+export { createSharedDispatcher, pendingKey, injectQueueItemId, } from "./tool-manager/dispatcher.js";
+export type { DispatcherClientInfo, DispatcherNotificationHooks, SharedDispatcherOptions, SharedDispatcher, } from "./tool-manager/dispatcher.js";
+export { CATALOG_SCHEMA_VERSION, cachePathFor, readCache, writeCache, isCacheValid, } from "./tool-manager/tool-catalog-cache.js";
+export type { ToolCatalog, CachedCatalog, } from "./tool-manager/tool-catalog-cache.js";
+export { HubReturnedError, isErrorEnvelope } from "./hub-error.js";
+export type { ILogger, LegacyStringLogger, LogField, LogFields } from "./logger.js";
+export { getActionText, buildPromptText, buildToastMessage, } from "./prompt-format.js";
+export type { PromptFormatConfig } from "./prompt-format.js";
+export { appendNotification } from "./notification-log.js";
+export type { NotificationLogEntry, NotificationLogOptions, } from "./notification-log.js";
+export { CognitivePipeline, CognitiveTelemetry, CircuitBreaker, HubUnavailableError, WriteCallDedup, DedupTimeoutError, ToolResultCache, FlushAllOnWriteStrategy, ToolDescriptionEnricher, ErrorNormalizer, NormalizedError, ResponseSummarizer, summarizeResult, buildPaginationHint, } from "@apnex/cognitive-layer";
+export type { CognitiveMiddleware, ToolCallContext, ListToolsContext, ToolErrorContext, Tool as CognitiveTool, StandardPipelineConfig, CognitiveTelemetryConfig, TelemetryEvent, TelemetryEventKind, CircuitBreakerConfig, CircuitState, CircuitStateChange, WriteCallDedupConfig, ToolResultCacheConfig, InvalidationStrategy, InvalidationDirective, CacheKey, ToolDescriptionEnricherConfig, ToolHints, ErrorNormalizerConfig, ErrorRule, CascadeDriftRule, ResponseSummarizerConfig, } from "@apnex/cognitive-layer";

package/dist/index.js

@@ -0,0 +1,31 @@
+// ── Layer 1a: Wire (transport / wire FSM) ──────────────────────────
+export { McpTransport } from "./wire/mcp-transport.js";
+// ── Layer 1b: Kernel (handshake / session FSM / agent client) ──────
+export { McpAgentClient } from "./kernel/mcp-agent-client.js";
+export { classifyEvent, parseHubEvent, createDedupFilter, } from "./kernel/event-router.js";
+export { loadOrCreateGlobalInstanceId } from "./kernel/instance.js";
+export { FATAL_CODES, parseHandshakeError, parseHandshakeResponse, buildHandshakePayload, performHandshake, makeStdioFatalHalt, } from "./kernel/handshake.js";
+export { performStateSync } from "./kernel/state-sync.js";
+export { PollBackstop, defaultCursorFile, readCursor, writeCursor, } from "./kernel/poll-backstop.js";
+export { isEagerWarmupEnabled, parseClaimSessionResponse, formatSessionClaimedLogLine, } from "./kernel/session-claim.js";
+// ── Layer 1c: tool-manager (Initialize/ListTools/CallTool factory) ──
+//
+// The MCP protocol tool-manager per Design v1.2 §4 naming discipline
+// (Director-ratified rename from "MCP-boundary dispatcher" 2026-04-26).
+// Distinct from the future Message-router (sovereign-package #6,
+// `@apnex/message-router`, M-Push-Foundation W4). Always qualify
+// ("tool-manager" or "Message-router") in new code; avoid bare
+// "dispatcher".
+export { createSharedDispatcher, pendingKey, injectQueueItemId, } from "./tool-manager/dispatcher.js";
+export { CATALOG_SCHEMA_VERSION, cachePathFor, readCache, writeCache, isCacheValid, } from "./tool-manager/tool-catalog-cache.js";
+// ── Cross-cutting primitives (root) ─────────────────────────────────
+export { HubReturnedError, isErrorEnvelope } from "./hub-error.js";
+export { getActionText, buildPromptText, buildToastMessage, } from "./prompt-format.js";
+export { appendNotification } from "./notification-log.js";
+// ── Cognitive layer re-exports (ADR-018) ────────────────────────────
+// The `cognitive` option on `McpAgentClient` accepts any
+// `@apnex/cognitive-layer` `CognitivePipeline`. Re-exporting the
+// essentials keeps downstream consumers from needing a separate
+// dependency declaration for the standard-pipeline pattern.
+export { CognitivePipeline, CognitiveTelemetry, CircuitBreaker, HubUnavailableError, WriteCallDedup, DedupTimeoutError, ToolResultCache, FlushAllOnWriteStrategy, ToolDescriptionEnricher, ErrorNormalizer, NormalizedError, ResponseSummarizer, summarizeResult, buildPaginationHint, } from "@apnex/cognitive-layer";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAYtE,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,sEAAsE;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAoB9D,OAAO,EACL,aAAa,EACb,aAAa,EACb,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AAGpE,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG1D,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,WAAW,GACZ,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,oBAAoB,EACpB,yBAAyB,EACzB,2BAA2B,GAC5B,MAAM,2BAA2B,CAAC;AAGnC,uEAAuE;AACvE,EAAE;AACF,qEAAqE;AACrE,wEAAwE;AACxE,iEAAiE;AACjE,iEAAiE;AACjE,+DAA+D;AAC/D,gBAAgB;AAEhB,OAAO,EACL,sBAAsB,EACtB,UAAU,EACV,iBAAiB,GAClB,MAAM,8BAA8B,CAAC;AAQtC,OAAO,EACL,sBAAsB,EACtB,YAAY,EACZ,SAAS,EACT,UAAU,EACV,YAAY,GACb,MAAM,sCAAsC,CAAC;AAM9C,uEAAuE;AAEvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAInE,OAAO,EACL,aAAa,EACb,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAM3D,uEAAuE;AACvE,yDAAyD;AACzD,iEAAiE;AACjE,gEAAgE;AAChE,4DAA4D;AAE5D,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,mBAAmB,GACpB,MAAM,wBAAwB,CAAC"}

package/dist/kernel/agent-client.d.ts

@@ -0,0 +1,192 @@
+/**
+ * IAgentClient — Layer-7 session surface for the network-adapter package.
+ *
+ * Phase 1: types only. Zero runtime change. The implementation that
+ * satisfies this interface is the current `UniversalClientAdapter`,
+ * which will be refactored in Phase 3 to own the session FSM itself
+ * (currently delegated down to McpConnectionManager).
+ *
+ * ## Responsibility boundary
+ *
+ * An AgentClient sits between a shim (the application-side adapter for
+ * Claude Code, OpenCode, etc.) and an `ITransport`. It owns:
+ *
+ *   1. The session FSM (disconnected → connecting → synchronizing →
+ *      streaming → reconnecting). Phase 3 moves this out of
+ *      `McpConnectionManager` and into the AgentClient implementation.
+ *   2. Role registration and the enriched handshake that binds a session
+ *      to an agentId + sessionEpoch.
+ *   3. State sync on entry to `synchronizing` (get_task,
+ *      get_pending_actions, state reconciliation).
+ *   4. Session-level reconnect policy on top of the wire: retry-once on
+ *      `session_invalid`, drive the FSM across wire bounces, coordinate
+ *      displacement checks (wasCreated / sessionEpoch monotonicity).
+ *   5. Event classification, dedup, and routing into the shim's
+ *      actionable/informational/state callbacks.
+ *   6. Discovery translation — turn `ITransport.listMethods()` into the
+ *      typed tool surface the shim consumes.
+ *
+ * It is NOT responsible for:
+ *
+ *   - Wire framing, SSE keepalive watchdogs, HTTP retries. All of that
+ *     lives in the Transport below.
+ *   - Shim-specific UX or side effects (toast formatting, prompt
+ *     injection, persistence). Those live in the shim above.
+ *
+ * ## Shim-facing surface
+ *
+ * A shim is handed an `IAgentClient` and sees only `call(method, ...)`,
+ * the session-state stream, and the classified-event callbacks. It
+ * does not see `ITransport` and must not. Phase 6 renames the existing
+ * `IClientShim` consumers onto `IAgentClient` to make this explicit.
+ */
+import type { ILogger, LegacyStringLogger } from "../logger.js";
+import type { ITransport } from "../wire/transport.js";
+import type { HandshakeFatalError, HandshakeResponse } from "./handshake.js";
+import type { DrainedPendingAction } from "./state-sync.js";
+/**
+ * Session FSM state exposed to shims.
+ *
+ *   disconnected → connecting → synchronizing → streaming
+ *                                    ↑                ↓
+ *                               reconnecting ← (wire death)
+ *
+ * Guarantees (when state === "streaming"):
+ *   G1: SSE stream is proven alive (at least one keepalive received)
+ *   G2: If SSE never opens, detected within firstKeepaliveDeadline
+ *   G3: If SSE dies mid-stream, detected within sseKeepaliveTimeout
+ *   G4: Consecutive SSE failures trigger exponential backoff
+ *   G5: All reconnections carry a classified SessionReconnectReason
+ */
+export type SessionState = "disconnected" | "connecting" | "synchronizing" | "streaming" | "reconnecting";
+/** Classifies why a session re-entered `reconnecting`. */
+export type SessionReconnectReason = "heartbeat_failed" | "sse_watchdog" | "sse_never_opened" | "session_invalid";
+/**
+ * Classified hub event delivered to the shim. Mirrors the existing
+ * `HubEvent` shape from `event-router.ts` but re-declared here so the
+ * AgentClient surface can be consumed without importing the router.
+ * Phase 3+ will unify these back to one source of truth.
+ */
+export interface AgentEvent {
+    readonly id?: number | string;
+    readonly event: string;
+    readonly data: Record<string, unknown>;
+    readonly timestamp?: string;
+    readonly targetRoles?: readonly string[];
+}
+/**
+ * What a shim plugs into an AgentClient. All callbacks are optional —
+ * a shim that doesn't care about, say, informational events can omit
+ * the handler entirely and the AgentClient will drop them silently.
+ */
+export interface AgentClientCallbacks {
+    onActionableEvent?: (event: AgentEvent) => void;
+    onInformationalEvent?: (event: AgentEvent) => void;
+    onStateChange?: (state: SessionState, previous: SessionState, reason?: SessionReconnectReason) => void;
+}
+/**
+ * Enriched handshake configuration. Optional — an AgentClient can run in
+ * "plain" mode with only a role, in which case handshake semantics
+ * collapse to the bare register_role call.
+ */
+export interface AgentHandshakeConfig {
+    globalInstanceId: string;
+    proxyName: string;
+    proxyVersion: string;
+    transport: string;
+    sdkVersion: string;
+    getClientInfo: () => {
+        name: string;
+        version: string;
+    };
+    llmModel?: string;
+    /** Fatal-code halt (agent_thrashing_detected / role_mismatch). */
+    onFatalHalt?: (err: HandshakeFatalError) => void;
+    /** Successful handshake callback — useful for shim state tracking. */
+    onHandshakeComplete?: (response: HandshakeResponse) => void;
+    /** ADR-017: optional durable-wake HTTP endpoint for this agent. */
+    wakeEndpoint?: string;
+    /** ADR-017: optional per-agent receipt-SLA override (ms). */
+    receiptSla?: number;
+    /** Optional hook invoked by state-sync when a pending task is discovered. */
+    onPendingTask?: (task: Record<string, unknown>) => void;
+    /**
+     * ADR-017: optional hook invoked per drained PendingActionItem on every
+     * state-sync (wake cycle). Adapters thread the `id` field as
+     * `sourceQueueItemId` on their settling tool call to complete-ACK.
+     * Omitting this hook means queue items drain without consumer — the
+     * Hub's watchdog escalates to Director after 3× receiptSla.
+     */
+    onPendingActionItem?: (item: DrainedPendingAction) => void;
+}
+export interface AgentClientConfig {
+    /** Role the session registers as (e.g. "engineer", "architect"). */
+    role: string;
+    /**
+     * Mission-19 routing labels. Persisted on first-create and immutable
+     * thereafter (INV-AG1). Only take effect when an enriched `handshake`
+     * config is also supplied — the Hub's bare register_role handler
+     * drops labels silently because it doesn't create an Agent entity.
+     */
+    labels?: Record<string, string>;
+    /** Optional full enriched handshake. When omitted, plain register_role. */
+    handshake?: AgentHandshakeConfig;
+    /** Structured logger. Legacy string logger accepted during migration. */
+    logger?: ILogger | LegacyStringLogger;
+}
+/**
+ * Pull-style telemetry on an AgentClient. Separate from
+ * `TransportMetrics` because the session layer has its own counters
+ * (session_invalid retries, handshakes, dedup hits) that the wire
+ * below has no visibility into.
+ */
+export interface AgentClientMetrics {
+    readonly sessionState: SessionState;
+    readonly agentId?: string;
+    readonly sessionEpoch?: number;
+    readonly totalHandshakes: number;
+    readonly totalSessionInvalidRetries: number;
+    readonly dedupDropCount: number;
+}
+export interface IAgentClient {
+    /** Current session FSM state. */
+    readonly state: SessionState;
+    /** True when `state === "streaming"`. Convenience alias. */
+    readonly isConnected: boolean;
+    /**
+     * Drive the session through connecting → synchronizing → streaming.
+     * Idempotent: a second start on an already-started client is a no-op.
+     */
+    start(): Promise<void>;
+    /** Gracefully tear down the session and close the underlying wire. */
+    stop(): Promise<void>;
+    /**
+     * Generic string-keyed call. Phase 2+: this routes through the
+     * underlying `ITransport.request` for MCP-style transports, but a
+     * future loopback or gRPC transport would translate here.
+     *
+     * On `session_invalid` classification, the AgentClient reconnects
+     * and retries exactly once on the fresh session before surfacing
+     * the error.
+     */
+    call(method: string, params: Record<string, unknown>): Promise<unknown>;
+    /**
+     * List the method surface currently advertised by the peer. The
+     * AgentClient delegates to `ITransport.listMethods()` and may cache
+     * the result; callers should treat this as a snapshot.
+     */
+    listMethods(): Promise<string[]>;
+    /** Register shim callbacks. Replaces any previously registered set. */
+    setCallbacks(callbacks: AgentClientCallbacks): void;
+    /** Current session id, if any. Undefined before first connect. */
+    getSessionId(): string | undefined;
+    /** Point-in-time session-layer metrics. */
+    getMetrics(): AgentClientMetrics;
+    /**
+     * Escape hatch for test harnesses and advanced shims that need to
+     * observe wire-level state or metrics. Implementations MAY return
+     * undefined if they're running on an in-memory / loopback transport
+     * without a meaningful wire surface.
+     */
+    getTransport(): ITransport | undefined;
+}

package/dist/kernel/agent-client.js

@@ -0,0 +1,44 @@
+/**
+ * IAgentClient — Layer-7 session surface for the network-adapter package.
+ *
+ * Phase 1: types only. Zero runtime change. The implementation that
+ * satisfies this interface is the current `UniversalClientAdapter`,
+ * which will be refactored in Phase 3 to own the session FSM itself
+ * (currently delegated down to McpConnectionManager).
+ *
+ * ## Responsibility boundary
+ *
+ * An AgentClient sits between a shim (the application-side adapter for
+ * Claude Code, OpenCode, etc.) and an `ITransport`. It owns:
+ *
+ *   1. The session FSM (disconnected → connecting → synchronizing →
+ *      streaming → reconnecting). Phase 3 moves this out of
+ *      `McpConnectionManager` and into the AgentClient implementation.
+ *   2. Role registration and the enriched handshake that binds a session
+ *      to an agentId + sessionEpoch.
+ *   3. State sync on entry to `synchronizing` (get_task,
+ *      get_pending_actions, state reconciliation).
+ *   4. Session-level reconnect policy on top of the wire: retry-once on
+ *      `session_invalid`, drive the FSM across wire bounces, coordinate
+ *      displacement checks (wasCreated / sessionEpoch monotonicity).
+ *   5. Event classification, dedup, and routing into the shim's
+ *      actionable/informational/state callbacks.
+ *   6. Discovery translation — turn `ITransport.listMethods()` into the
+ *      typed tool surface the shim consumes.
+ *
+ * It is NOT responsible for:
+ *
+ *   - Wire framing, SSE keepalive watchdogs, HTTP retries. All of that
+ *     lives in the Transport below.
+ *   - Shim-specific UX or side effects (toast formatting, prompt
+ *     injection, persistence). Those live in the shim above.
+ *
+ * ## Shim-facing surface
+ *
+ * A shim is handed an `IAgentClient` and sees only `call(method, ...)`,
+ * the session-state stream, and the classified-event callbacks. It
+ * does not see `ITransport` and must not. Phase 6 renames the existing
+ * `IClientShim` consumers onto `IAgentClient` to make this explicit.
+ */
+export {};
+//# sourceMappingURL=agent-client.js.map

package/dist/kernel/agent-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-client.js","sourceRoot":"","sources":["../../src/kernel/agent-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG"}

package/dist/kernel/event-router.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared Event Router — Classification, dedup, and parsing for Hub SSE events.
+ *
+ * Extracts the common event handling logic that was duplicated between
+ * the Engineer Plugin and the Architect Agent. Both consumers import
+ * from this module and only implement their own dispatch mechanisms
+ * (Push-to-LLM for the Plugin, Sandwich pattern for the Architect).
+ */
+/** All known Hub event types */
+export type HubEventType = "task_issued" | "directive_acknowledged" | "report_submitted" | "review_completed" | "revision_required" | "proposal_submitted" | "proposal_decided" | "clarification_requested" | "clarification_answered" | "thread_opened" | "thread_message" | "thread_convergence_finalized" | "thread_abandoned" | "idea_submitted" | "mission_created" | "mission_activated" | "turn_created" | "turn_updated" | "tele_defined" | "director_attention_required" | "cascade_failure" | "message_arrived" | "agent_state_changed";
+/** Parsed, typed event envelope */
+export interface HubEvent {
+    event: HubEventType | string;
+    data: Record<string, unknown>;
+    timestamp?: string;
+    id?: number | string;
+}
+/** Classification result */
+export type EventDisposition = "actionable" | "informational" | "unhandled";
+/**
+ * Classify an event for a given role.
+ *
+ * Returns "actionable" if the event requires the agent to respond,
+ * "informational" if it's FYI only, or "unhandled" if the event
+ * is not recognized for this role.
+ */
+export declare function classifyEvent(event: string, role: "engineer" | "architect"): EventDisposition;
+/**
+ * Parse raw eventData from the ConnectionManager into a typed HubEvent.
+ */
+export declare function parseHubEvent(eventData: Record<string, unknown>): HubEvent;
+/**
+ * Creates a dedup filter that tracks processed events by content hash.
+ * Prevents duplicate processing from notification replay or concurrent streams.
+ *
+ * The hash is computed from event type + entity ID + timestamp.
+ * Cache is LRU-style with a configurable max size.
+ */
+export declare function createDedupFilter(maxCache?: number): {
+    /**
+     * Returns true if this event has already been processed.
+     * If not a duplicate, marks it as processed.
+     */
+    isDuplicate(event: HubEvent): boolean;
+    /** Clear the dedup cache */
+    clear(): void;
+    /** Current cache size */
+    readonly size: number;
+};

package/dist/kernel/event-router.js

@@ -0,0 +1,150 @@
+/**
+ * Shared Event Router — Classification, dedup, and parsing for Hub SSE events.
+ *
+ * Extracts the common event handling logic that was duplicated between
+ * the Engineer Plugin and the Architect Agent. Both consumers import
+ * from this module and only implement their own dispatch mechanisms
+ * (Push-to-LLM for the Plugin, Sandwich pattern for the Architect).
+ */
+// ── Event Classification ─────────────────────────────────────────────
+/** Engineer events that require the LLM to respond */
+const ENGINEER_ACTIONABLE = new Set([
+    "thread_message",
+    "clarification_answered",
+    "task_issued",
+    // Mission-24 Phase 2 (M24-T3): thread_converged merged into
+    // thread_convergence_finalized.
+    "thread_convergence_finalized",
+    "revision_required",
+    // Mission-56 W2.2: Hub-side push-on-Message-create. Layer-2
+    // `@apnex/message-router` does kind/subkind-aware Message routing;
+    // Layer-1 dispositioning treats every push as wake-the-LLM since
+    // delivery="push-immediate" is itself the actionable signal.
+    "message_arrived",
+]);
+/** Engineer events that are FYI (context injection, no response) */
+const ENGINEER_INFORMATIONAL = new Set([
+    "review_completed",
+    "proposal_decided",
+    "mission_created",
+    "mission_activated",
+    "idea_submitted",
+    "turn_created",
+    "turn_updated",
+    "tele_defined",
+    // Mission-62 W1+W2 Pass 5: agent population cache-coherence updates.
+    // Adapter maintains a local cache (W3 wiring); LLM wake suppressed.
+    "agent_state_changed",
+]);
+/** Architect events that require a sandwich handler response */
+const ARCHITECT_ACTIONABLE = new Set([
+    "report_submitted",
+    "proposal_submitted",
+    "clarification_requested",
+    "thread_message",
+    // Mission-24 Phase 2 (M24-T3): thread_converged merged into
+    // thread_convergence_finalized.
+    "thread_convergence_finalized",
+    // Mission-56 W2.2: same dispositioning as engineer — push delivery
+    // is itself the wake-the-LLM signal.
+    "message_arrived",
+]);
+/** Architect events that are FYI */
+const ARCHITECT_INFORMATIONAL = new Set([
+    "directive_acknowledged",
+    "idea_submitted",
+    "turn_created",
+    "turn_updated",
+    "tele_defined",
+    "director_attention_required",
+    "cascade_failure",
+    // Mission-62 W1+W2 Pass 5: agent population cache-coherence updates.
+    "agent_state_changed",
+]);
+/**
+ * Classify an event for a given role.
+ *
+ * Returns "actionable" if the event requires the agent to respond,
+ * "informational" if it's FYI only, or "unhandled" if the event
+ * is not recognized for this role.
+ */
+export function classifyEvent(event, role) {
+    if (role === "engineer") {
+        if (ENGINEER_ACTIONABLE.has(event))
+            return "actionable";
+        if (ENGINEER_INFORMATIONAL.has(event))
+            return "informational";
+        return "unhandled";
+    }
+    else {
+        if (ARCHITECT_ACTIONABLE.has(event))
+            return "actionable";
+        if (ARCHITECT_INFORMATIONAL.has(event))
+            return "informational";
+        return "unhandled";
+    }
+}
+// ── Event Parsing ────────────────────────────────────────────────────
+/**
+ * Parse raw eventData from the ConnectionManager into a typed HubEvent.
+ */
+export function parseHubEvent(eventData) {
+    return {
+        event: eventData.event || "unknown",
+        data: eventData.data || {},
+        timestamp: eventData.timestamp,
+        id: eventData.id,
+    };
+}
+// ── Dedup Filter ─────────────────────────────────────────────────────
+/**
+ * Creates a dedup filter that tracks processed events by content hash.
+ * Prevents duplicate processing from notification replay or concurrent streams.
+ *
+ * The hash is computed from event type + entity ID + timestamp.
+ * Cache is LRU-style with a configurable max size.
+ */
+export function createDedupFilter(maxCache = 100) {
+    const processed = new Set();
+    function computeHash(event) {
+        const entity = event.data.taskId ||
+            event.data.proposalId ||
+            event.data.threadId ||
+            "unknown";
+        // Prefer the application-level timestamp from the event data
+        // (which represents the logical event identity) over the
+        // delivery-level timestamp set by the Hub on each send.
+        const ts = event.data.timestamp ||
+            event.timestamp ||
+            "";
+        return `${event.event}:${entity}:${ts}`;
+    }
+    return {
+        /**
+         * Returns true if this event has already been processed.
+         * If not a duplicate, marks it as processed.
+         */
+        isDuplicate(event) {
+            const hash = computeHash(event);
+            if (processed.has(hash))
+                return true;
+            processed.add(hash);
+            // Evict oldest entries if cache exceeds max
+            if (processed.size > maxCache) {
+                const first = processed.values().next().value;
+                if (first)
+                    processed.delete(first);
+            }
+            return false;
+        },
+        /** Clear the dedup cache */
+        clear() {
+            processed.clear();
+        },
+        /** Current cache size */
+        get size() {
+            return processed.size;
+        },
+    };
+}
+//# sourceMappingURL=event-router.js.map

package/dist/kernel/event-router.js.map

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