agent-trellis 0.19.0 → 0.21.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/mcpConnect.d.ts

@@ -45,7 +45,7 @@ export declare function connectWithCleanup<T, TTransport extends {
     connect(transport: TTransport): Promise<unknown>;
 }, transport: TTransport, timeoutMs: number, message: string): Promise<T>;
 export declare function connectStdio(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
-export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Record<string, string> | undefined;
+export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Promise<Record<string, string> | undefined>;
 export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 export declare function connectSse(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo, authProvider?: AuthProvider): Promise<Client>;
 /**

package/dist/lib/mcpConnect.js

@@ -14,7 +14,7 @@
  */
 import { Client, StreamableHTTPClientTransport, SSEClientTransport } from "@modelcontextprotocol/client";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/client/stdio";
-import { resolveSecretEnv } from "./secretEnv.js";
+import { deliveredName, resolveSecretEnv } from "./secretEnv.js";
 import { extractTemplateVarNames } from "./envVarNames.js";
 export const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
 const FAILED_TRANSPORT_CLEANUP_TIMEOUT_MS = 1_000;
@@ -73,9 +73,20 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
     // `${sourceName}` placeholder text a consumer with no `${VAR}` runtime
     // of its own (like this bridge) would otherwise crash on parsing
     // (trellis-migrate-env-var-alias, the real notion-on-pi bug).
-    const resolved = resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
-    const namedEnv = Object.fromEntries((def.env ?? []).map((name) => [name, resolved[name] ?? ""]));
-    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => [targetKey, resolved[sourceName] ?? ""]));
+    //
+    // Entries may be `mxenv://` references: the resolved map is keyed by
+    // DELIVERED name (the `KEY` segment for a reference, the entry itself
+    // for a bare name), and the spawned server receives values under
+    // delivered names — never the raw reference text as a variable name
+    // (mx-env-secret-source spec).
+    const resolved = await resolveSecretEnv([...(def.env ?? []), ...Object.values(envAliases)], secretsPolicy);
+    const namedEnv = Object.fromEntries((def.env ?? []).map((entry) => {
+        const delivered = deliveredName(entry);
+        return [delivered, resolved[delivered] ?? ""];
+    }));
+    const aliasEnv = Object.fromEntries(Object.entries(envAliases).map(([targetKey, sourceName]) => {
+        return [targetKey, resolved[deliveredName(sourceName)] ?? ""];
+    }));
     const transport = new StdioClientTransport({
         command: def.command,
         args: def.args,
@@ -91,11 +102,11 @@ export async function connectStdio(def, secretsPolicy, timeoutMs, clientInfo) {
     });
     return connectWithCleanup(client, transport, timeoutMs, `connect timed out after ${timeoutMs}ms`);
 }
-export function resolveHeaders(def, secretsPolicy) {
+export async function resolveHeaders(def, secretsPolicy) {
     if (!def.headers || Object.keys(def.headers).length === 0)
         return undefined;
     const names = Object.keys(def.headers).flatMap((key) => extractTemplateVarNames(def.headers[key]));
-    const resolved = resolveSecretEnv(names, secretsPolicy);
+    const resolved = await resolveSecretEnv(names, secretsPolicy);
     const result = {};
     for (const [key, template] of Object.entries(def.headers)) {
         result[key] = template.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match, name) => resolved[name] ?? "");
@@ -104,7 +115,7 @@ export function resolveHeaders(def, secretsPolicy) {
 }
 export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     const client = new Client(clientInfo, { capabilities: {}, versionNegotiation: { mode: "auto", probe: { timeoutMs } } });
-    const headers = resolveHeaders(def, secretsPolicy);
+    const headers = await resolveHeaders(def, secretsPolicy);
     // authProvider is the SDK's per-request credential seam: `token()` runs
     // as each request's headers are assembled and its result overrides
     // `requestInit`'s Authorization — the alternative to burning a Bearer
@@ -118,7 +129,7 @@ export async function connectHttp(def, secretsPolicy, timeoutMs, clientInfo, aut
 export async function connectSse(def, secretsPolicy, timeoutMs, clientInfo, authProvider) {
     // HTTP+SSE is a legacy transport; it cannot carry modern discovery.
     const client = new Client(clientInfo, { capabilities: {} });
-    const headers = resolveHeaders(def, secretsPolicy);
+    const headers = await resolveHeaders(def, secretsPolicy);
     const opts = {
         ...(headers ? { requestInit: { headers } } : {}),
         ...(authProvider ? { authProvider } : {}),

package/dist/lib/mcpMigrateRead.js

@@ -13,6 +13,7 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { parseEnvEntry } from "./secretEnv.js";
 import { readJsonFile } from "./probeCommon.js";
 import { readServerEnvTable } from "./tomlSection.js";
 import { resolveZcodeProfile } from "../probes/zcode.js";
@@ -42,8 +43,19 @@ const VAR_REF_RE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
  * independent derivations of it.
  */
 export function resolvedEnvTextMap(def) {
-    const nameRefs = Object.fromEntries((def.env ?? []).map((name) => [name, `\${${name}}`]));
-    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, sourceName]) => [targetKey, `\${${sourceName}}`]));
+    // `mxenv://` reference entries render as `${KEY}` under their DELIVERED
+    // name (the KEY segment) — the raw reference text never appears as a
+    // variable name in a native-client config (mx-env-secret-source spec).
+    const nameRefs = Object.fromEntries((def.env ?? []).map((entry) => {
+        const parsed = parseEnvEntry(entry);
+        const delivered = parsed.kind === "invalid" ? entry : parsed.delivered;
+        return [delivered, `\${${delivered}}`];
+    }));
+    const aliasRefs = Object.fromEntries(Object.entries(def.envAliases ?? {}).map(([targetKey, source]) => {
+        const parsed = parseEnvEntry(source);
+        const delivered = parsed.kind === "invalid" ? source : parsed.delivered;
+        return [targetKey, `\${${delivered}}`];
+    }));
     return { ...nameRefs, ...aliasRefs, ...(def.staticEnv ?? {}) };
 }
 function splitJsonEnvMap(env) {

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. */