agent-trellis 0.18.0 → 0.19.0

package/dist/lib/gatewayBackend.d.ts

@@ -41,7 +41,11 @@ export interface UpstreamSpec {
     name: string;
     def: McpServerDef;
 }
-export type UpstreamStatusKind = "ready" | "auth-required" | "unavailable" | "timeout" | "degraded";
+/** `reconnecting` is the transient state between a detected session
+ * invalidation and the recovery outcome (spec: an upstream whose MCP
+ * session is invalidated mid-session is recovered alone, with a status
+ * that never claims ready in the meantime). */
+export type UpstreamStatusKind = "ready" | "auth-required" | "unavailable" | "timeout" | "degraded" | "reconnecting";
 export interface UpstreamStatus {
     name: string;
     transport: "stdio" | "http" | "sse";
@@ -75,6 +79,10 @@ export interface LocalBackendOptions {
      * no terminal attached (design.md D9).
      */
     homeDir?: string;
+    /** How long a server whose mid-session recovery failed refuses automatic
+     * re-attempts, so a down upstream cannot trigger a reconnect storm. Test
+     * seam; defaults to `SESSION_RECOVERY_COOLDOWN_MS`. */
+    sessionRecoveryCooldownMs?: number;
 }
 /**
  * v1's backend: connects each upstream itself and aggregates the result.
@@ -87,9 +95,26 @@ export interface LocalBackendOptions {
  */
 export declare class LocalBackend implements GatewayBackend {
     private readonly warn;
+    private readonly sessionCooldownMs;
     private readonly registry;
+    /** server name → the client currently serving that upstream. Keyed by
+     * name (not a Set of clients) because recovery swaps the client under a
+     * stable name and callTool must ask "is this still the client I called?"
+     * by comparing against the current registration. */
     private readonly connected;
     private readonly statuses;
+    /** Saved at connect time so a mid-session recovery can rebuild the
+     * upstream through `addUpstream` itself — the recovery path IS the
+     * startup path, and inherits its OAuth resolution and special cases
+     * (mcp-router) wholesale instead of growing a parallel one. */
+    private readonly upstreamConfigs;
+    /** server name → in-flight session recovery; one recovery per server at
+     * a time, every racing caller awaits the same promise. */
+    private readonly recoveries;
+    /** server name → cooldown expiry; a recently failed recovery is not
+     * re-attempted until it lapses, so a down upstream sees one reconnect
+     * attempt per window, not a storm. */
+    private readonly sessionCooldowns;
     private closed;
     private readonly resources;
     private constructor();
@@ -103,14 +128,59 @@ export declare class LocalBackend implements GatewayBackend {
     getSkill(uri: string): Promise<SkillEntry | undefined>;
     listStatus(): readonly UpstreamStatus[];
     close(): Promise<void>;
-    private closeUpstream;
+    private closeClient;
     /** A dead grant surfaces mid-session: this upstream's calls now fail,
      * but its tools stay registered and every other upstream keeps serving.
      * The credential resolves per request, so the human's re-authorization
      * takes effect on the next call — no session restart required. */
     private markCredentialFailure;
     private restoreIfAuthRequired;
+    /** The pre-call hard failure for a server inside its recovery cooldown. */
+    private sessionCooldownBlock;
+    private enterSessionCooldown;
+    /** Join the server's in-flight recovery, or start exactly one. */
+    private ensureSessionRecovered;
+    /** Drop and rebuild one upstream through the exact startup path
+     * (`addUpstream`), keeping the old client connected until the fresh
+     * registration serves — so a failed recovery still surfaces the old
+     * session errors that re-trigger recovery after the cooldown, and the
+     * replaced connection is never closed before its successor exists. */
+    private reconnectUpstream;
+    /** The retried request failed on the fresh session too: an honest
+     * terminal state plus a cooldown — never a stale ready (D4). */
+    private markRetrySessionFailure;
+    /** Upstream-originated failures name their server (spec: call errors
+     * name the failing upstream server). */
+    private upstreamCallError;
 }
+/**
+ * How long a server whose session recovery failed refuses automatic
+ * re-attempts. Fixed by design: a reconnect storm against a down upstream
+ * buys nothing; the honest failure state plus this window is the v1
+ * answer, to be revisited with real-world data.
+ */
+export declare const SESSION_RECOVERY_COOLDOWN_MS = 30000;
+/**
+ * Whether an upstream error means "your MCP session no longer exists".
+ *
+ * The official TypeScript server SDK rejects an unknown session with HTTP
+ * 404 carrying the JSON-RPC error "Session not found", and pairs 401/403
+ * with -32000 for authentication rejections — so 401/403 gate the match
+ * out first, and an auth rejection can never enter recovery. The body
+ * reaches us inside the client SDK's `Error POSTing to endpoint: …`
+ * wrapper, so a word match covers custom upstream wordings (the real-world
+ * one says "MCP session no longer exists"). Real-machine verification
+ * (2026-10-23) showed custom upstreams also answer with other non-auth
+ * statuses — a 400 carrying that same -32000 body took the plain
+ * `SdkHttpError` path, not the enveloped `ProtocolError` one — hence the
+ * status gate is "not an auth rejection" rather than "exactly 404". A
+ * stray non-auth response that merely mentions "session" costs one
+ * idempotent-safe reconnect+retry, an acceptable price for covering every
+ * upstream wording. The `ProtocolError` branch covers the HTTP-200
+ * JSON-RPC error case, where the client SDK parses the envelope and
+ * rejects with the upstream's error code instead.
+ */
+export declare function isSessionInvalidation(err: unknown): boolean;
 /**
  * Whether the gateway manages the OAuth credential for this definition:
  * Trellis-owned OAuth, and no explicit `Authorization` header — someone

package/dist/lib/gatewayBackend.js

@@ -21,6 +21,7 @@ import { withTimeout } from "./mcpConnect.js";
 import { ensureFreshToken, forceRefresh, RefreshError } from "./oauth/refresh.js";
 import { readToken } from "./oauth/store.js";
 import { McpToolRegistry } from "./mcpToolRegistry.js";
+import { ProtocolError, SdkHttpError } from "@modelcontextprotocol/client";
 import { UpstreamResources } from "./upstreamResources.js";
 /**
  * v1's backend: connects each upstream itself and aggregates the result.
@@ -33,24 +34,47 @@ import { UpstreamResources } from "./upstreamResources.js";
  */
 export class LocalBackend {
     warn;
+    sessionCooldownMs;
     registry = new McpToolRegistry();
-    connected = new Set();
+    /** server name → the client currently serving that upstream. Keyed by
+     * name (not a Set of clients) because recovery swaps the client under a
+     * stable name and callTool must ask "is this still the client I called?"
+     * by comparing against the current registration. */
+    connected = new Map();
     statuses = new Map();
+    /** Saved at connect time so a mid-session recovery can rebuild the
+     * upstream through `addUpstream` itself — the recovery path IS the
+     * startup path, and inherits its OAuth resolution and special cases
+     * (mcp-router) wholesale instead of growing a parallel one. */
+    upstreamConfigs = new Map();
+    /** server name → in-flight session recovery; one recovery per server at
+     * a time, every racing caller awaits the same promise. */
+    recoveries = new Map();
+    /** server name → cooldown expiry; a recently failed recovery is not
+     * re-attempted until it lapses, so a down upstream sees one reconnect
+     * attempt per window, not a storm. */
+    sessionCooldowns = new Map();
     closed = false;
     resources;
-    constructor(warn, timeoutMs) {
+    constructor(warn, timeoutMs, sessionCooldownMs) {
         this.warn = warn;
+        this.sessionCooldownMs = sessionCooldownMs;
         this.resources = new UpstreamResources(timeoutMs, warn);
     }
     static async connect(upstreams, options) {
         const warn = options.onWarning ?? ((message) => console.error(message));
-        const backend = new LocalBackend(warn, options.connectTimeoutMs);
+        const backend = new LocalBackend(warn, options.connectTimeoutMs, options.sessionRecoveryCooldownMs ?? SESSION_RECOVERY_COOLDOWN_MS);
         await Promise.all(upstreams.map((upstream) => backend.addUpstream(upstream, options)));
         return backend;
     }
-    async addUpstream({ name, def }, options) {
+    async addUpstream({ name, def }, options, replaceOf) {
+        this.upstreamConfigs.set(name, { spec: { name, def }, options });
         const transport = def.transport === "http" || def.transport === "sse" ? def.transport : "stdio";
-        this.statuses.set(name, { name, transport, status: "unavailable", detail: "connecting" });
+        // A recovery set `reconnecting` before calling us; a first connect
+        // reports "connecting". The recovery's status stays until the outcome.
+        if (replaceOf === undefined) {
+            this.statuses.set(name, { name, transport, status: "unavailable", detail: "connecting" });
+        }
         let effectiveDef = def;
         if (options.homeDir && def.url) {
             try {
@@ -70,6 +94,10 @@ export class LocalBackend {
         // process, or written to disk by `trellis mcp auth` in another
         // terminal — affects the very next request, no restart. The static
         // header from withOAuthHeader stays as the connect-time fallback.
+        // (A mid-session recovery rebuilds this provider, so its `lastIssued`
+        // starts empty again: the first post-recovery 401 force-refreshes with
+        // no previous-token guard — at most one extra rotation, and safe,
+        // because forceRefresh re-reads the token file under its lock.)
         const authProvider = options.homeDir && (transport === "http" || transport === "sse") && oauthAttachApplies(def)
             ? trellisAuthProvider({
                 homeDir: options.homeDir,
@@ -84,10 +112,19 @@ export class LocalBackend {
         }
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to connect to MCP server "${name}": ${errorText(err)}`);
+            // A failed recovery keeps the replaced client: its dead session is
+            // what keeps surfacing the error that re-triggers recovery once the
+            // cooldown expires — close-after-success, never orphaned mid-failure.
+            if (replaceOf !== undefined)
+                this.connected.set(name, replaceOf);
             this.statuses.set(name, failureStatus(name, def, err));
             return;
         }
-        this.connected.add(client);
+        this.connected.set(name, client);
+        // Routes (and any skill registrations) a previous incarnation of this
+        // source left behind would route reads at the replaced client — forget
+        // the source entirely; the fresh registration re-adds its routes below.
+        this.resources.removeSource(name);
         let tools;
         try {
             const result = client.getServerCapabilities()?.tools
@@ -97,11 +134,19 @@ export class LocalBackend {
         }
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to list tools for MCP server "${name}": ${errorText(err)}`);
-            await this.closeUpstream(client);
+            this.connected.delete(name);
+            if (replaceOf !== undefined)
+                this.connected.set(name, replaceOf);
+            await this.closeClient(client);
             this.statuses.set(name, failureStatus(name, def, err));
             return;
         }
-        const { skipped } = this.registry.add(name, client, tools);
+        // A recovery swaps this server's whole registration: its previous
+        // candidates are dropped first, so a changed upstream tool set is
+        // reflected exactly rather than accumulated.
+        const { skipped } = replaceOf !== undefined
+            ? this.registry.replace(name, client, tools)
+            : this.registry.add(name, client, tools);
         this.resources.add(name, client);
         for (const collided of skipped) {
             this.warn(`trellis-mcp-gateway: tool "${collided}" from server "${name}" collides with an already-registered tool and was skipped`);
@@ -122,12 +167,63 @@ export class LocalBackend {
         else {
             this.statuses.set(name, { name, transport, status: "ready", toolCount: tools.length, detail: `connected; ${tools.length} tool(s) available` });
         }
+        // The fresh registration serves; only now is the replaced client
+        // retired. Callers mid-flight on it finish against it — their stale
+        // session errors are guarded in callTool and never start a second
+        // recovery — and a failed recovery left the old client connected.
+        if (replaceOf !== undefined)
+            await this.closeClient(replaceOf);
     }
     async listTools() {
         return this.registry.listTools();
     }
     async callTool(name, args) {
-        return this.registry.callTool(name, args);
+        let target = this.registry.resolve(name);
+        if (!target)
+            throw new Error(`unknown tool "${name}"`);
+        // A server inside its recovery cooldown fails hard and immediately:
+        // its automatic recovery is known to be failing, and a reconnect
+        // storm against a down upstream buys nothing (D3).
+        const blocked = this.sessionCooldownBlock(target.serverName);
+        if (blocked)
+            throw blocked;
+        // A recovery already in flight — started by a concurrent caller.
+        // Wait it out and aim at whatever registration it lands.
+        const pending = this.recoveries.get(target.serverName);
+        if (pending) {
+            await pending;
+            target = this.registry.resolve(name);
+            if (!target)
+                throw new Error(`unknown tool "${name}"`);
+        }
+        try {
+            return await target.upstream.callTool({ name: target.toolName, arguments: args });
+        }
+        catch (err) {
+            const { serverName } = target;
+            if (this.closed || !isSessionInvalidation(err))
+                throw this.upstreamCallError(serverName, err);
+            // A completed recovery already replaced the client this error came
+            // from (a racing caller's reconnect won): the stale error must not
+            // start a second recovery — just aim at the fresh registration.
+            const current = this.connected.get(serverName);
+            if (current === undefined || current === target.upstream) {
+                await this.ensureSessionRecovered(serverName, err);
+            }
+            const retried = this.registry.resolve(name);
+            if (!retried)
+                throw new Error(`unknown tool "${name}"`);
+            try {
+                return await retried.upstream.callTool({ name: retried.toolName, arguments: args });
+            }
+            catch (retryErr) {
+                // The fresh session failed the same way: an honest terminal state
+                // plus a cooldown — never a stale ready (D4).
+                if (isSessionInvalidation(retryErr))
+                    this.markRetrySessionFailure(retried.serverName, retryErr);
+                throw this.upstreamCallError(retried.serverName, retryErr);
+            }
+        }
     }
     listResources() { return this.resources.listResources(); }
     readResource(uri) { return this.resources.readResource(uri); }
@@ -140,12 +236,11 @@ export class LocalBackend {
         if (this.closed)
             return;
         this.closed = true;
-        const pending = [...this.connected];
+        const pending = [...this.connected.values()];
         this.connected.clear();
-        await Promise.all(pending.map((client) => this.closeUpstream(client)));
+        await Promise.all(pending.map((client) => this.closeClient(client)));
     }
-    async closeUpstream(client) {
-        this.connected.delete(client);
+    async closeClient(client) {
         try {
             await client.close();
         }
@@ -187,6 +282,152 @@ export class LocalBackend {
             requiresSessionRestart: undefined,
         });
     }
+    // ---------------------------------------------------------------------------
+    // Mid-session recovery (spec: an upstream whose MCP session is invalidated
+    // is recovered alone, in flight — restart is the remediation of last
+    // resort, not the default)
+    // ---------------------------------------------------------------------------
+    /** The pre-call hard failure for a server inside its recovery cooldown. */
+    sessionCooldownBlock(serverName) {
+        const until = this.sessionCooldowns.get(serverName);
+        if (until === undefined || Date.now() >= until)
+            return undefined;
+        return new Error(sessionRecoveryHint(serverName, "a recovery attempt failed recently and its cooldown has not expired"));
+    }
+    enterSessionCooldown(serverName) {
+        this.sessionCooldowns.set(serverName, Date.now() + this.sessionCooldownMs);
+    }
+    /** Join the server's in-flight recovery, or start exactly one. */
+    ensureSessionRecovered(serverName, trigger) {
+        const blocked = this.sessionCooldownBlock(serverName);
+        if (blocked)
+            return Promise.reject(blocked);
+        const existing = this.recoveries.get(serverName);
+        if (existing)
+            return existing;
+        const pending = this.reconnectUpstream(serverName, trigger);
+        this.recoveries.set(serverName, pending);
+        const cleanup = () => {
+            if (this.recoveries.get(serverName) === pending)
+                this.recoveries.delete(serverName);
+        };
+        pending.then(cleanup, cleanup);
+        return pending;
+    }
+    /** Drop and rebuild one upstream through the exact startup path
+     * (`addUpstream`), keeping the old client connected until the fresh
+     * registration serves — so a failed recovery still surfaces the old
+     * session errors that re-trigger recovery after the cooldown, and the
+     * replaced connection is never closed before its successor exists. */
+    async reconnectUpstream(serverName, trigger) {
+        const config = this.upstreamConfigs.get(serverName);
+        if (!config)
+            throw new Error(sessionRecoveryHint(serverName, "no saved connection config exists for it"));
+        // Preserve the tool count through reconnecting and failure: Agents
+        // reasoning about capability see the same number on both sides of a
+        // recovery, whatever its outcome (a success overwrites it with the
+        // fresh count inside addUpstream).
+        const toolCount = this.statuses.get(serverName)?.toolCount;
+        this.statuses.set(serverName, {
+            name: serverName,
+            transport: transportOf(config.spec.def),
+            status: "reconnecting",
+            toolCount,
+            detail: `MCP session invalidated; reconnecting (${errorText(trigger).slice(0, 160)})`,
+        });
+        try {
+            await this.addUpstream(config.spec, config.options, this.connected.get(serverName));
+        }
+        catch (err) {
+            // addUpstream isolates its own failures into statuses; reaching here
+            // is a bug guard, not the expected failure path.
+            this.statuses.set(serverName, { ...failureStatus(serverName, config.spec.def, err), toolCount, remediation: sessionRestartRemediation(serverName) });
+            this.enterSessionCooldown(serverName);
+            throw new Error(sessionRecoveryHint(serverName, errorText(err)));
+        }
+        const status = this.statuses.get(serverName);
+        if (status?.status === "ready" || status?.status === "degraded") {
+            this.sessionCooldowns.delete(serverName);
+            return;
+        }
+        // A failed recovery already landed in its classified failure status;
+        // sharpen its remediation to the restart hint and open the cooldown.
+        this.statuses.set(serverName, { ...status, toolCount, remediation: sessionRestartRemediation(serverName) });
+        this.enterSessionCooldown(serverName);
+        throw new Error(sessionRecoveryHint(serverName, status?.detail ?? "the reconnect failed"));
+    }
+    /** The retried request failed on the fresh session too: an honest
+     * terminal state plus a cooldown — never a stale ready (D4). */
+    markRetrySessionFailure(serverName, err) {
+        const config = this.upstreamConfigs.get(serverName);
+        const previous = this.statuses.get(serverName);
+        const base = config
+            ? failureStatus(serverName, config.spec.def, err)
+            : {
+                name: serverName,
+                transport: "http",
+                status: "unavailable",
+                detail: errorText(err).slice(0, 300),
+                requiresHuman: true,
+                requiresSessionRestart: true,
+            };
+        this.statuses.set(serverName, {
+            ...base,
+            toolCount: previous?.toolCount,
+            remediation: sessionRestartRemediation(serverName),
+        });
+        this.enterSessionCooldown(serverName);
+    }
+    /** Upstream-originated failures name their server (spec: call errors
+     * name the failing upstream server). */
+    upstreamCallError(serverName, err) {
+        return new Error(`upstream "${serverName}" tool call failed: ${errorText(err)}`, err instanceof Error ? { cause: err } : undefined);
+    }
+}
+/**
+ * How long a server whose session recovery failed refuses automatic
+ * re-attempts. Fixed by design: a reconnect storm against a down upstream
+ * buys nothing; the honest failure state plus this window is the v1
+ * answer, to be revisited with real-world data.
+ */
+export const SESSION_RECOVERY_COOLDOWN_MS = 30_000;
+function transportOf(def) {
+    if (def.transport === "sse")
+        return "sse";
+    return def.url ? "http" : "stdio";
+}
+function sessionRestartRemediation(serverName) {
+    return `restart the Agent session to re-establish the MCP session for "${serverName}"`;
+}
+function sessionRecoveryHint(serverName, reason) {
+    return `upstream "${serverName}" MCP session invalidated and automatic recovery failed (${reason}) — ${sessionRestartRemediation(serverName)}`;
+}
+/**
+ * Whether an upstream error means "your MCP session no longer exists".
+ *
+ * The official TypeScript server SDK rejects an unknown session with HTTP
+ * 404 carrying the JSON-RPC error "Session not found", and pairs 401/403
+ * with -32000 for authentication rejections — so 401/403 gate the match
+ * out first, and an auth rejection can never enter recovery. The body
+ * reaches us inside the client SDK's `Error POSTing to endpoint: …`
+ * wrapper, so a word match covers custom upstream wordings (the real-world
+ * one says "MCP session no longer exists"). Real-machine verification
+ * (2026-10-23) showed custom upstreams also answer with other non-auth
+ * statuses — a 400 carrying that same -32000 body took the plain
+ * `SdkHttpError` path, not the enveloped `ProtocolError` one — hence the
+ * status gate is "not an auth rejection" rather than "exactly 404". A
+ * stray non-auth response that merely mentions "session" costs one
+ * idempotent-safe reconnect+retry, an acceptable price for covering every
+ * upstream wording. The `ProtocolError` branch covers the HTTP-200
+ * JSON-RPC error case, where the client SDK parses the envelope and
+ * rejects with the upstream's error code instead.
+ */
+export function isSessionInvalidation(err) {
+    if (err instanceof SdkHttpError)
+        return err.status !== 401 && err.status !== 403 && /session/i.test(err.message);
+    if (err instanceof ProtocolError)
+        return err.code === -32000 && /session/i.test(err.message);
+    return false;
 }
 function failureStatus(name, def, error) {
     const detail = errorText(error).slice(0, 300);

package/dist/lib/mcpToolRegistry.d.ts

@@ -82,6 +82,16 @@ export declare class McpToolRegistry {
      * aggregated, with no special-casing here.
      */
     add(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
+    /**
+     * Swap one server's entire registration — the mid-session recovery path.
+     * Every candidate the server previously contributed is dropped before the
+     * fresh tool set is added, so a changed upstream tool set is reflected
+     * exactly rather than accumulated. Exposed names are re-allocated across
+     * the whole registry, so a name this server frees may be re-assigned
+     * deterministically to another server's colliding tool — accepted drift,
+     * pinned by the spec scenario.
+     */
+    replace(serverName: string, upstream: ToolUpstream, tools: readonly AggregatedTool[]): AddResult;
     private exposedNameFor;
     /** Every registered tool, under its prefixed name, in registration
      * order. Each tool's own `description`/`inputSchema` and any additional

package/dist/lib/mcpToolRegistry.js

@@ -127,6 +127,25 @@ export class McpToolRegistry {
         const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
         return { added, skipped: [] };
     }
+    /**
+     * Swap one server's entire registration — the mid-session recovery path.
+     * Every candidate the server previously contributed is dropped before the
+     * fresh tool set is added, so a changed upstream tool set is reflected
+     * exactly rather than accumulated. Exposed names are re-allocated across
+     * the whole registry, so a name this server frees may be re-assigned
+     * deterministically to another server's colliding tool — accepted drift,
+     * pinned by the spec scenario.
+     */
+    replace(serverName, upstream, tools) {
+        const kept = this.candidates.filter((candidate) => candidate.serverName !== serverName);
+        this.candidates.length = 0;
+        this.candidates.push(...kept);
+        for (const tool of tools)
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+        this.rebuild();
+        const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
+        return { added, skipped: [] };
+    }
     exposedNameFor(serverName, toolName) {
         for (const [name, entry] of this.entries) {
             if (entry.serverName === serverName && entry.toolName === toolName)

package/dist/lib/upstreamResources.d.ts

@@ -13,6 +13,11 @@ export declare class UpstreamResources {
     private readonly files;
     constructor(timeoutMs: number, warn: (message: string) => void);
     add(source: string, client: Client): void;
+    /** Forget one source entirely: its client and every file route it
+     * registered. Called before a source is re-added mid-session — stale
+     * routes would otherwise route reads at the closed previous client
+     * (`listResources`/`listSkills` re-register the fresh client's routes). */
+    removeSource(source: string): void;
     private skillsEnabled;
     private isolated;
     listResources(): Promise<Resource[]>;

package/dist/lib/upstreamResources.js

@@ -54,6 +54,16 @@ export class UpstreamResources {
         this.warn = warn;
     }
     add(source, client) { this.clients.set(source, client); }
+    /** Forget one source entirely: its client and every file route it
+     * registered. Called before a source is re-added mid-session — stale
+     * routes would otherwise route reads at the closed previous client
+     * (`listResources`/`listSkills` re-register the fresh client's routes). */
+    removeSource(source) {
+        this.clients.delete(source);
+        for (const [uri, route] of this.files)
+            if (route.source === source)
+                this.files.delete(uri);
+    }
     skillsEnabled(client) {
         return Boolean(client.getServerCapabilities()?.resources && client.getDiscoverResult()?.capabilities.extensions?.[EXTENSION]);
     }

package/dist/pi-bridge/bundle.js

@@ -46047,6 +46047,24 @@ var McpToolRegistry = class {
     const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== void 0);
     return { added, skipped: [] };
   }
+  /**
+   * Swap one server's entire registration — the mid-session recovery path.
+   * Every candidate the server previously contributed is dropped before the
+   * fresh tool set is added, so a changed upstream tool set is reflected
+   * exactly rather than accumulated. Exposed names are re-allocated across
+   * the whole registry, so a name this server frees may be re-assigned
+   * deterministically to another server's colliding tool — accepted drift,
+   * pinned by the spec scenario.
+   */
+  replace(serverName, upstream, tools) {
+    const kept = this.candidates.filter((candidate) => candidate.serverName !== serverName);
+    this.candidates.length = 0;
+    this.candidates.push(...kept);
+    for (const tool of tools) this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+    this.rebuild();
+    const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== void 0);
+    return { added, skipped: [] };
+  }
   exposedNameFor(serverName, toolName) {
     for (const [name, entry] of this.entries) {
       if (entry.serverName === serverName && entry.toolName === toolName) return name;

package/docs/runtime-infra.md

@@ -0,0 +1,55 @@
+# Runtime 基建调研议程
+
+> **状态:调研议程,尚未实施。** 记录于 2026-10-23。四个方向是"我们的 runtime"离不开的
+> 基建层;逐项调研,调研结果各自沉淀后再决定实施。自我进化(第 4 项)已有完整草案,
+> 见 `docs/self-evolution.md` 与 `openspec/changes/trellis-evolve/`。
+
+## 建议顺序:1 → 2 → 3,第 4 项按既有 tasks 推进
+
+先吃透模型接入层(网关),再往网络层(代理、多机)走;进化已是实施轨道,不是调研轨道。
+
+## 1. 大模型网关(Magpie)——子仓库化 + 核心实现研究
+
+已知:
+- Magpie 已在 Air 两层实测运行(macOS 与 OrbStack worker 各自 `127.0.0.1:3425/v1`);
+  worker 层 Codex 流式/工具往返/Responses 通过。用法见 `$local-model-gateway`、
+  `$mac-air-usage`。
+
+调研问题:
+- Magpie 源码在本机的位置(**未定位,第一步**);
+- 子仓库形态:git submodule / subtree / 研究副本(先例:`~/www/morphix-research/sources/`);
+- 核心实现:provider 路由与适配、流式转发、工具调用透传、错误与重试语义。
+
+## 2. 代理——稳定访问层
+
+调研问题:
+- Magpie 到各上游 provider 的代理路由(per-provider 配置、failover 策略);
+- npm/git 等开发工具链的代理;
+- 与网关层的边界:重试/切换由代理层还是网关层负责;
+- 与 Nore 的职责区分(设备互联 vs 外网代理,别混为一谈)。
+
+已有数据点:2026-10-22 npm publish 上传连接 ECONNRESET,IPv4-first + 单 socket 解决;
+GET/ping 正常、仅上传路径异常。
+
+## 3. 多机互通——相互委派任务的网络底座
+
+已知锚点:
+- Pro↔Air 私网由 Nore 设备互联提供(`ssh morphix-air-private` → `100.127.171.120`);
+- 本机有 `~/www/nore/` 与 `~/www/nore-next/` 两个仓库,调研以 Nore 源码为主对象之一;
+- 现网痛点:SSH 中继偶发超时(Air doctor 详情两次读取均超时)。
+
+委派已有雏形(分散,未统一):Trellis `tasks_handoff`(MCP)、Air 侧 Dagu
+(`morphix-air-tasks`,当前已禁用)、agent-collab mailbox。
+
+调研问题:网络可靠性(重连/唤醒)、服务发现、委派语义与安全边界。
+
+## 4. 自我进化——已是实施轨道
+
+不在本文重复。接手入口:`docs/self-evolution.md` 的"接手指南";下一步是其
+tasks 第 1 组的三个只读前置验证(元数据信号采样、provider 读取路径、扩展加载机制),
+之后才是托管扩展点(P1)。
+
+## 对照样本(见记忆 research-subjects-backlog)
+
+Raven(harness of harnesses)、Octop(腾讯云多 Agent,coordinator 调度与 workspace
+分层)、asyar(轻量启动器,仅交互效率参照)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-trellis",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "A unified Code Agent Runtime for Skills, MCP, Memory, and shared instructions across Claude Code, Codex, Kiro, pi, Kimi Code, and ZCode.",
   "license": "MIT",
   "author": "Paul Leo",