agent-trellis 0.18.0 → 0.20.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/hostEventBus.d.ts

@@ -0,0 +1,47 @@
+/**
+ * In-process host event bus (host-extension-points spec).
+ *
+ * Dispatch is synchronous and ordered: `emit` walks listeners at the event
+ * point so a session-end event is observably delivered before upstream
+ * release continues. Failures are contained per listener — a synchronous
+ * throw or a rejected promise is swallowed and warned, never propagated to
+ * the tool call or to sibling listeners. With no subscribers `emit` is a
+ * single length check (zero overhead; runtime behavior stays byte-identical
+ * to the pre-event world). Listeners are expected to return promptly; slow
+ * work belongs behind the returned promise, which the caller never awaits.
+ */
+import { type HostEvent, type ToolCallInfo } from "../host/hostEvents.js";
+export type HostEventListener = (event: HostEvent) => void | Promise<void>;
+export declare class HostEventBus {
+    private readonly warn;
+    private readonly listeners;
+    constructor(warn?: (message: string) => void);
+    /** Register a listener; returns its unsubscribe function. Registration
+     * failure isolation for extensions is the loader's job (8.6) — this method
+     * only ever pushes. */
+    subscribe(listener: HostEventListener): () => void;
+    emit(event: HostEvent): void;
+    get subscriberCount(): number;
+}
+/**
+ * Stamps events with process-level identity. One instance per gateway
+ * process: `sessionId` is generated here and carried unchanged on every
+ * event the process emits ("会话开始"/tool calls/"会话结束").
+ */
+export declare class HostEventEmitter {
+    private readonly opts;
+    readonly sessionId: string;
+    constructor(opts: {
+        bus: HostEventBus;
+        agent: string;
+        /** Workspace root observed by the process; null = no workspace
+         * attribution (consumers derive layer from this). */
+        workspaceRoot: string | null;
+        now?: () => number;
+        sessionId?: string;
+    });
+    private ts;
+    sessionStart(): void;
+    toolCall(info: ToolCallInfo): void;
+    sessionEnd(): void;
+}

package/dist/lib/hostEventBus.js

@@ -0,0 +1,94 @@
+/**
+ * In-process host event bus (host-extension-points spec).
+ *
+ * Dispatch is synchronous and ordered: `emit` walks listeners at the event
+ * point so a session-end event is observably delivered before upstream
+ * release continues. Failures are contained per listener — a synchronous
+ * throw or a rejected promise is swallowed and warned, never propagated to
+ * the tool call or to sibling listeners. With no subscribers `emit` is a
+ * single length check (zero overhead; runtime behavior stays byte-identical
+ * to the pre-event world). Listeners are expected to return promptly; slow
+ * work belongs behind the returned promise, which the caller never awaits.
+ */
+import { randomUUID } from "node:crypto";
+import { sessionEndEvent, sessionStartEvent, toolCallEvent, } from "../host/hostEvents.js";
+export class HostEventBus {
+    warn;
+    listeners = [];
+    constructor(warn = console.error) {
+        this.warn = warn;
+    }
+    /** Register a listener; returns its unsubscribe function. Registration
+     * failure isolation for extensions is the loader's job (8.6) — this method
+     * only ever pushes. */
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index >= 0)
+                this.listeners.splice(index, 1);
+        };
+    }
+    emit(event) {
+        if (this.listeners.length === 0)
+            return;
+        for (const listener of this.listeners) {
+            try {
+                const pending = listener(event);
+                if (pending && typeof pending.then === "function") {
+                    void pending.catch((err) => {
+                        this.warn(`trellis-host-events: subscriber failed: ${err instanceof Error ? err.message : String(err)}`);
+                    });
+                }
+            }
+            catch (err) {
+                this.warn(`trellis-host-events: subscriber failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    get subscriberCount() {
+        return this.listeners.length;
+    }
+}
+/**
+ * Stamps events with process-level identity. One instance per gateway
+ * process: `sessionId` is generated here and carried unchanged on every
+ * event the process emits ("会话开始"/tool calls/"会话结束").
+ */
+export class HostEventEmitter {
+    opts;
+    sessionId;
+    constructor(opts) {
+        this.opts = opts;
+        this.sessionId = opts.sessionId ?? randomUUID();
+    }
+    ts() {
+        return (this.opts.now ?? Date.now)();
+    }
+    sessionStart() {
+        this.opts.bus.emit(sessionStartEvent({
+            ts: this.ts(),
+            agent: this.opts.agent,
+            session: this.sessionId,
+            workspaceRoot: this.opts.workspaceRoot,
+        }));
+    }
+    toolCall(info) {
+        this.opts.bus.emit(toolCallEvent({
+            ts: this.ts(),
+            agent: this.opts.agent,
+            session: this.sessionId,
+            provider: info.provider,
+            tool: info.tool,
+            durationMs: info.durationMs,
+            result: info.result,
+        }));
+    }
+    sessionEnd() {
+        this.opts.bus.emit(sessionEndEvent({
+            ts: this.ts(),
+            agent: this.opts.agent,
+            session: this.sessionId,
+        }));
+    }
+}

package/dist/lib/hostExtensions.d.ts

@@ -0,0 +1,75 @@
+/**
+ * External host extension loading (host-extension-points spec, 8.6).
+ *
+ * The ONLY way an external module becomes a Trellis provider or event
+ * subscriber: it is declared in the canonical extension manifest at
+ * `~/.trellis/mcp/extensions.yaml` (entries carry `id` + a `load` module
+ * specifier) and its module exports `activate(ctx)` returning
+ * `{ providers?, subscribers? }`. There is no directory scan and no
+ * naming convention — a module on disk that the manifest does not name
+ * is never imported.
+ *
+ * Fault isolation is per extension and total: a manifest that fails to
+ * parse, an entry of the wrong shape, an import that throws, an
+ * `activate` that throws, or an activation of the wrong shape are each
+ * recorded as a failure (and warned), and none of them affect the core
+ * providers, upstream servers, or any other extension. With no manifest
+ * the loader returns empty everything and the gateway is byte-identical
+ * to the pre-extension world.
+ */
+import type { AgentId } from "../core/types.js";
+import type { HostEventListener } from "./hostEventBus.js";
+import type { TrellisProvider } from "./mcpRuntime.js";
+/** Manifest location relative to the home directory — canonical, not
+ * user-home-adjacent: extension declarations are canonical content. */
+export declare const EXTENSIONS_MANIFEST_REL: string;
+export declare function extensionsManifestPath(homeDir: string): string;
+export interface HostExtensionEntry {
+    id: string;
+    /** Module specifier for dynamic import — an absolute path or a file:
+     * URL is the reliable form; bare specifiers resolve by Node's rules
+     * from the trellis package itself. */
+    load: string;
+}
+/** What an extension's `activate` receives. Metadata only — the extension
+ * never gets the bus or registry itself; it RETURNS providers and
+ * subscribers and the host wires them through the same registration
+ * surface as everything else. */
+export interface HostExtensionContext {
+    homeDir: string;
+    agent: AgentId;
+    workspaceRoot: string | null;
+}
+export interface HostExtensionActivation {
+    providers?: TrellisProvider[];
+    subscribers?: HostEventListener[];
+}
+export type HostExtensionFailureStage = "manifest" | "invalid" | "import" | "activate";
+export interface HostExtensionFailure {
+    /** The manifest entry id, or the manifest itself when it could not be
+     * read as an extension list at all. */
+    id: string;
+    stage: HostExtensionFailureStage;
+    message: string;
+}
+export interface LoadedHostExtensions {
+    providers: TrellisProvider[];
+    subscribers: HostEventListener[];
+    failures: HostExtensionFailure[];
+}
+/**
+ * Load every extension the canonical manifest declares. Never throws:
+ * the worst case is a `failures` entry per broken extension.
+ */
+export declare function loadHostExtensions(context: HostExtensionContext, warn?: (message: string) => void): Promise<LoadedHostExtensions>;
+/**
+ * 写入(或原位更新)一条清单条目;幂等——同 id 旧条目被替换,其余条目
+ * 与未知键原样保留。清单是 canonical 内容,写入是显式管理动作(进化
+ * 启用命令 8.1),loader 侧永不写。
+ */
+export declare function upsertExtensionEntry(homeDir: string, entry: HostExtensionEntry): void;
+/**
+ * 移除一条清单条目;不存在时是无副作用的 no-op(返回 false)。不清空
+ * 文件、不动其他条目——清单还可能声明别的扩展。
+ */
+export declare function removeExtensionEntry(homeDir: string, id: string): boolean;