agent-trellis 0.19.0 → 0.20.0

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;

package/dist/lib/hostExtensions.js

@@ -0,0 +1,196 @@
+/**
+ * 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 { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { writeFileAtomicSync } from "./fsAtomic.js";
+/** Manifest location relative to the home directory — canonical, not
+ * user-home-adjacent: extension declarations are canonical content. */
+export const EXTENSIONS_MANIFEST_REL = join(".trellis", "mcp", "extensions.yaml");
+export function extensionsManifestPath(homeDir) {
+    return join(homeDir, EXTENSIONS_MANIFEST_REL);
+}
+function failureMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Minimal structural check for one provider handed back by an
+ * extension: it must at least be able to answer a call. */
+function isProviderShape(value) {
+    return (typeof value === "object" && value !== null &&
+        typeof value.id === "string" &&
+        typeof value.callTool === "function");
+}
+function isSubscriberShape(value) {
+    return typeof value === "function";
+}
+/**
+ * Load every extension the canonical manifest declares. Never throws:
+ * the worst case is a `failures` entry per broken extension.
+ */
+export async function loadHostExtensions(context, warn = console.error) {
+    const providers = [];
+    const subscribers = [];
+    const failures = [];
+    const report = (failure) => {
+        failures.push(failure);
+        warn(`trellis-mcp-gateway: extension "${failure.id}" failed (${failure.stage}): ${failure.message}`);
+    };
+    const manifestPath = extensionsManifestPath(context.homeDir);
+    if (!existsSync(manifestPath)) {
+        return { providers, subscribers, failures };
+    }
+    let parsed;
+    try {
+        parsed = (parseYaml(readFileSync(manifestPath, "utf-8")) ?? {});
+    }
+    catch (err) {
+        report({ id: "<manifest>", stage: "manifest", message: failureMessage(err) });
+        return { providers, subscribers, failures };
+    }
+    const rawEntries = parsed.extensions;
+    if (rawEntries === undefined || rawEntries === null) {
+        return { providers, subscribers, failures };
+    }
+    if (!Array.isArray(rawEntries)) {
+        report({ id: "<manifest>", stage: "manifest", message: "extensions must be a list of {id, load} entries" });
+        return { providers, subscribers, failures };
+    }
+    for (const raw of rawEntries) {
+        const entry = raw;
+        if (typeof entry !== "object" || entry === null ||
+            typeof entry.id !== "string" || entry.id === "" ||
+            typeof entry.load !== "string" || entry.load === "") {
+            report({ id: "<manifest>", stage: "invalid", message: `entry is not a {id, load} pair: ${JSON.stringify(raw)}` });
+            continue;
+        }
+        let mod;
+        try {
+            mod = await import(entry.load);
+        }
+        catch (err) {
+            report({ id: entry.id, stage: "import", message: failureMessage(err) });
+            continue;
+        }
+        if (typeof mod.activate !== "function") {
+            report({ id: entry.id, stage: "invalid", message: "module does not export an activate function" });
+            continue;
+        }
+        let activation;
+        try {
+            activation = (await mod.activate(context)) ?? {};
+        }
+        catch (err) {
+            report({ id: entry.id, stage: "activate", message: failureMessage(err) });
+            continue;
+        }
+        if (typeof activation !== "object") {
+            report({ id: entry.id, stage: "invalid", message: "activate did not return an object" });
+            continue;
+        }
+        const returnedProviders = Array.isArray(activation.providers) ? activation.providers : [];
+        for (const provider of returnedProviders) {
+            if (isProviderShape(provider)) {
+                providers.push(provider);
+            }
+            else {
+                report({ id: entry.id, stage: "invalid", message: "activation.providers contains a non-provider entry" });
+            }
+        }
+        const returnedSubscribers = Array.isArray(activation.subscribers) ? activation.subscribers : [];
+        for (const subscriber of returnedSubscribers) {
+            if (isSubscriberShape(subscriber)) {
+                subscribers.push(subscriber);
+            }
+            else {
+                report({ id: entry.id, stage: "invalid", message: "activation.subscribers contains a non-function entry" });
+            }
+        }
+    }
+    return { providers, subscribers, failures };
+}
+// ---------- 清单写入(声明面的唯一写路径) ----------
+/**
+ * 写入(或原位更新)一条清单条目;幂等——同 id 旧条目被替换,其余条目
+ * 与未知键原样保留。清单是 canonical 内容,写入是显式管理动作(进化
+ * 启用命令 8.1),loader 侧永不写。
+ */
+export function upsertExtensionEntry(homeDir, entry) {
+    if (typeof entry.id !== "string" || entry.id === "" || typeof entry.load !== "string" || entry.load === "") {
+        throw new Error(`extensions.yaml: entry must be a non-empty {id, load} pair, got ${JSON.stringify(entry)}`);
+    }
+    const manifestPath = extensionsManifestPath(homeDir);
+    let parsed = {};
+    if (existsSync(manifestPath)) {
+        const raw = parseYaml(readFileSync(manifestPath, "utf-8"));
+        if (raw !== null && raw !== undefined) {
+            if (typeof raw !== "object" || Array.isArray(raw)) {
+                throw new Error("extensions.yaml: top level must be a mapping with an `extensions` list");
+            }
+            parsed = raw;
+        }
+    }
+    const existing = parsed.extensions;
+    if (existing !== undefined && !Array.isArray(existing)) {
+        // 非数组的 extensions 键是手误产物:抛错而不是静默重置,避免
+        // 其余条目无声丢失。
+        throw new Error("extensions.yaml: `extensions` must be a list of {id, load} entries");
+    }
+    const entries = (existing ?? []);
+    const next = [];
+    let replaced = false;
+    for (const raw of entries) {
+        const candidate = raw;
+        if (candidate !== null && typeof candidate === "object" && candidate.id === entry.id) {
+            next.push({ id: entry.id, load: entry.load });
+            replaced = true;
+        }
+        else {
+            next.push(raw);
+        }
+    }
+    if (!replaced)
+        next.push({ id: entry.id, load: entry.load });
+    parsed.extensions = next;
+    mkdirSync(dirname(manifestPath), { recursive: true });
+    writeFileAtomicSync(manifestPath, stringifyYaml(parsed));
+}
+/**
+ * 移除一条清单条目;不存在时是无副作用的 no-op(返回 false)。不清空
+ * 文件、不动其他条目——清单还可能声明别的扩展。
+ */
+export function removeExtensionEntry(homeDir, id) {
+    const manifestPath = extensionsManifestPath(homeDir);
+    if (!existsSync(manifestPath))
+        return false;
+    const raw = parseYaml(readFileSync(manifestPath, "utf-8"));
+    if (raw === null || raw === undefined || typeof raw !== "object" || Array.isArray(raw))
+        return false;
+    const parsed = raw;
+    const existing = Array.isArray(parsed.extensions) ? parsed.extensions : [];
+    const next = existing.filter((item) => {
+        const candidate = item;
+        return !(candidate !== null && typeof candidate === "object" && candidate.id === id);
+    });
+    if (next.length === existing.length)
+        return false;
+    parsed.extensions = next;
+    writeFileAtomicSync(manifestPath, stringifyYaml(parsed));
+    return true;
+}

package/dist/lib/mcpRuntime.d.ts

@@ -3,6 +3,7 @@ import type { CallToolResult, GetPromptResult, Implementation, Prompt, ReadResou
 import type { AgentId } from "../core/types.js";
 import type { GatewayBackend } from "./gatewayBackend.js";
 import type { SkillEntry } from "./skillManifest.js";
+import type { ToolCallInfo } from "../host/hostEvents.js";
 export interface RuntimeContext {
     agentId: AgentId;
     homeDir: string;
@@ -23,14 +24,24 @@ export interface TrellisProvider {
 export declare class BuiltinRegistry {
     private readonly providers;
     private readonly warn;
+    /** Event choke point (host-extension-points): called after every routed
+     * tool call with metadata only. Absent = pre-event behavior, unchanged. */
+    private readonly onToolCall?;
     private readonly toolOwners;
     private readonly originalToolOwners;
     private readonly exposedToOriginal;
     private readonly resourceOwners;
     private readonly promptOwners;
-    constructor(providers: readonly TrellisProvider[], warn?: (message: string) => void);
+    constructor(providers: readonly TrellisProvider[], warn?: (message: string) => void, 
+    /** Event choke point (host-extension-points): called after every routed
+     * tool call with metadata only. Absent = pre-event behavior, unchanged. */
+    onToolCall?: ((info: ToolCallInfo) => void) | undefined);
     listTools(context: RuntimeContext): Promise<Tool[]>;
     callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
+    /** Metadata-only event emission at the call choke point. Fully
+     * transparent: a failing observer never changes the tool call's result or
+     * error semantics (host-events transparency requirement). */
+    private emitToolCall;
     listResources(context: RuntimeContext): Promise<Resource[]>;
     readResource(uri: URL, context: RuntimeContext): Promise<ReadResourceResult>;
     listSkills(context: RuntimeContext): Promise<SkillEntry[]>;

package/dist/lib/mcpRuntime.js

@@ -8,17 +8,32 @@ function compactBuiltinToolName(name) {
 function providerError(provider, error) {
     return `trellis-mcp-runtime: provider "${provider}" failed: ${error instanceof Error ? error.message : String(error)}`;
 }
+function resultCategory(result) {
+    if (!result?.isError)
+        return "ok";
+    const text = JSON.stringify(result.content ?? "");
+    return /timed? ?out/i.test(text) ? "timeout" : "error";
+}
+function thrownCategory(err) {
+    const message = err instanceof Error ? `${err.name} ${err.message}` : String(err);
+    return /timed? ?out/i.test(message) ? "timeout" : "error";
+}
 export class BuiltinRegistry {
     providers;
     warn;
+    onToolCall;
     toolOwners = new Map();
     originalToolOwners = new Map();
     exposedToOriginal = new Map();
     resourceOwners = new Map();
     promptOwners = new Map();
-    constructor(providers, warn = console.error) {
+    constructor(providers, warn = console.error, 
+    /** Event choke point (host-extension-points): called after every routed
+     * tool call with metadata only. Absent = pre-event behavior, unchanged. */
+    onToolCall) {
         this.providers = providers;
         this.warn = warn;
+        this.onToolCall = onToolCall;
     }
     async listTools(context) {
         const candidates = [];
@@ -67,13 +82,30 @@ export class BuiltinRegistry {
         }
         if (!provider)
             return { content: [{ type: "text", text: `unknown Trellis tool "${name}"` }], isError: true };
+        const started = Date.now();
         try {
-            return await provider.callTool(originalName, args, context);
+            const result = await provider.callTool(originalName, args, context);
+            this.emitToolCall({ provider: provider.id, tool: name, durationMs: Date.now() - started, result: resultCategory(result) });
+            return result;
         }
         catch (err) {
+            this.emitToolCall({ provider: provider.id, tool: name, durationMs: Date.now() - started, result: thrownCategory(err) });
             return { content: [{ type: "text", text: providerError(provider.id, err) }], isError: true };
         }
     }
+    /** Metadata-only event emission at the call choke point. Fully
+     * transparent: a failing observer never changes the tool call's result or
+     * error semantics (host-events transparency requirement). */
+    emitToolCall(info) {
+        if (!this.onToolCall)
+            return;
+        try {
+            this.onToolCall(info);
+        }
+        catch (err) {
+            this.warn(`trellis-mcp-runtime: tool-call observer failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     async listResources(context) {
         const resources = [];
         this.resourceOwners.clear();

package/dist/lib/mcpToolRegistry.d.ts

@@ -52,6 +52,17 @@ export declare function prefixedToolName(serverName: string, toolName: string):
 export interface ToolNameCandidate {
     serverName: string;
     toolName: string;
+    /**
+     * Force the `server__tool` prefix regardless of uniqueness or length.
+     * Gateway aggregation sets this on every candidate so an Agent can always
+     * read the owning server from the exposed name (mcp-tool-name-preservation:
+     * "Prefix every upstream tool with its server name"). A tool whose name
+     * already starts with its server's name (e.g. `tanka_memo_search` on
+     * `tanka`) is not prefixed again — the name is already source-qualified.
+     * Other consumers (e.g. the built-in Runtime registry) leave it unset to
+     * keep their own naming contracts.
+     */
+    alwaysPrefix?: boolean;
 }
 /** Allocate all exposed names together so normalization collisions are
  * deterministic and no upstream tool is silently lost. The returned array
@@ -94,8 +105,13 @@ export declare class McpToolRegistry {
     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
-     * fields the upstream sent are preserved verbatim; only `name` changes. */
+     * order. Each tool's own `inputSchema` and any additional fields the
+     * upstream sent are preserved verbatim; `name` changes, and the
+     * description gains a trailing `Source: <server>` line so an Agent can
+     * confirm the owning server without relying on the name alone
+     * (mcp-gateway-hosting: "Resold tool metadata identifies its upstream
+     * source"). The upstream's own description text is never altered or
+     * removed — the source line is appended. */
     listTools(): AggregatedTool[];
     /** The owning upstream and original tool name for a prefixed name, or
      * `undefined` if nothing owns it. */

package/dist/lib/mcpToolRegistry.js

@@ -81,12 +81,23 @@ export function allocateExposedToolNames(candidates) {
         // registry (for example `fixture__env` reaching the Runtime provider).
         // Do not add a second provider prefix around it.
         const sourceQualified = normalized.includes("__") || normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
+        // Narrower than `sourceQualified`: for forced-prefix candidates the
+        // exemption applies only when the tool name already starts with ITS
+        // OWN server's name (a second prefix would be redundant, e.g.
+        // `tanka__tanka_memo_search`). A tool that merely contains `__`
+        // (`b__c`) or gained a `__hash` length bound still needs its server
+        // prefix to be identifiable.
+        const serverRedundant = normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
         const unique = (counts.get(candidate.toolName) ?? 0) === 1;
-        const base = unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH
-            ? normalized
-            : unique && sourceQualified
+        const base = candidate.alwaysPrefix
+            ? serverRedundant
                 ? normalized
-                : prefixedToolName(candidate.serverName, candidate.toolName);
+                : prefixedToolName(candidate.serverName, candidate.toolName)
+            : unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH
+                ? normalized
+                : unique && sourceQualified
+                    ? normalized
+                    : prefixedToolName(candidate.serverName, candidate.toolName);
         let exposed = base;
         let suffix = 2;
         while (used.has(exposed)) {
@@ -122,7 +133,7 @@ export class McpToolRegistry {
      */
     add(serverName, upstream, tools) {
         for (const tool of tools)
-            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool, alwaysPrefix: true });
         this.rebuild();
         const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
         return { added, skipped: [] };
@@ -141,7 +152,7 @@ export class McpToolRegistry {
         this.candidates.length = 0;
         this.candidates.push(...kept);
         for (const tool of tools)
-            this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+            this.candidates.push({ serverName, toolName: tool.name, upstream, tool, alwaysPrefix: true });
         this.rebuild();
         const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== undefined);
         return { added, skipped: [] };
@@ -154,8 +165,13 @@ export class McpToolRegistry {
         return undefined;
     }
     /** Every registered tool, under its prefixed name, in registration
-     * order. Each tool's own `description`/`inputSchema` and any additional
-     * fields the upstream sent are preserved verbatim; only `name` changes. */
+     * order. Each tool's own `inputSchema` and any additional fields the
+     * upstream sent are preserved verbatim; `name` changes, and the
+     * description gains a trailing `Source: <server>` line so an Agent can
+     * confirm the owning server without relying on the name alone
+     * (mcp-gateway-hosting: "Resold tool metadata identifies its upstream
+     * source"). The upstream's own description text is never altered or
+     * removed — the source line is appended. */
     listTools() {
         this.rebuild();
         return this.order.map((name) => {
@@ -163,7 +179,11 @@ export class McpToolRegistry {
             const title = name === entry.toolName || entry.tool.title !== undefined
                 ? entry.tool.title
                 : `${entry.serverName} / ${entry.toolName}`;
-            return { ...entry.tool, name, ...(title === undefined ? {} : { title }) };
+            const sourceLine = `Source: ${entry.serverName}`;
+            const description = entry.tool.description
+                ? `${entry.tool.description}\n\n${sourceLine}`
+                : sourceLine;
+            return { ...entry.tool, name, description, ...(title === undefined ? {} : { title }) };
         });
     }
     /** The owning upstream and original tool name for a prefixed name, or

package/dist/pi-bridge/bundle.js

@@ -46008,8 +46008,9 @@ function allocateExposedToolNames(candidates) {
     const normalized = normalizedToolName(candidate.toolName);
     const source = compactSourceSegment(candidate.serverName);
     const sourceQualified = normalized.includes("__") || normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
+    const serverRedundant = normalized === source || normalized.startsWith(`${source}_`) || normalized.startsWith(`${source}__`);
     const unique = (counts.get(candidate.toolName) ?? 0) === 1;
-    const base = unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH ? normalized : unique && sourceQualified ? normalized : prefixedToolName(candidate.serverName, candidate.toolName);
+    const base = candidate.alwaysPrefix ? serverRedundant ? normalized : prefixedToolName(candidate.serverName, candidate.toolName) : unique && normalized.length > SHORT_EXPOSED_TOOL_NAME_LENGTH ? normalized : unique && sourceQualified ? normalized : prefixedToolName(candidate.serverName, candidate.toolName);
     let exposed = base;
     let suffix = 2;
     while (used.has(exposed)) {
@@ -46042,7 +46043,7 @@ var McpToolRegistry = class {
    * aggregated, with no special-casing here.
    */
   add(serverName, upstream, tools) {
-    for (const tool of tools) this.candidates.push({ serverName, toolName: tool.name, upstream, tool });
+    for (const tool of tools) this.candidates.push({ serverName, toolName: tool.name, upstream, tool, alwaysPrefix: true });
     this.rebuild();
     const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== void 0);
     return { added, skipped: [] };
@@ -46060,7 +46061,7 @@ var McpToolRegistry = class {
     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 });
+    for (const tool of tools) this.candidates.push({ serverName, toolName: tool.name, upstream, tool, alwaysPrefix: true });
     this.rebuild();
     const added = tools.map((tool) => this.exposedNameFor(serverName, tool.name)).filter((name) => name !== void 0);
     return { added, skipped: [] };
@@ -46072,14 +46073,23 @@ var McpToolRegistry = class {
     return void 0;
   }
   /** Every registered tool, under its prefixed name, in registration
-   * order. Each tool's own `description`/`inputSchema` and any additional
-   * fields the upstream sent are preserved verbatim; only `name` changes. */
+   * order. Each tool's own `inputSchema` and any additional fields the
+   * upstream sent are preserved verbatim; `name` changes, and the
+   * description gains a trailing `Source: <server>` line so an Agent can
+   * confirm the owning server without relying on the name alone
+   * (mcp-gateway-hosting: "Resold tool metadata identifies its upstream
+   * source"). The upstream's own description text is never altered or
+   * removed — the source line is appended. */
   listTools() {
     this.rebuild();
     return this.order.map((name) => {
       const entry = this.entries.get(name);
       const title = name === entry.toolName || entry.tool.title !== void 0 ? entry.tool.title : `${entry.serverName} / ${entry.toolName}`;
-      return { ...entry.tool, name, ...title === void 0 ? {} : { title } };
+      const sourceLine = `Source: ${entry.serverName}`;
+      const description = entry.tool.description ? `${entry.tool.description}
+
+${sourceLine}` : sourceLine;
+      return { ...entry.tool, name, description, ...title === void 0 ? {} : { title } };
     });
   }
   /** The owning upstream and original tool name for a prefixed name, or