@vurb/core 3.2.0

package/dist/core/middleware/ContextDerivation.js

@@ -0,0 +1,117 @@
+/**
+ * defineMiddleware() — Context Derivation (tRPC-style)
+ *
+ * Middlewares that return data have that data merged into the context
+ * for downstream handlers. TypeScript infers the derived context type
+ * automatically, so removing a middleware causes a compile error
+ * if the handler accesses properties that middleware provided.
+ *
+ * @example
+ * ```typescript
+ * const requireAuth = defineMiddleware(async (ctx: BaseCtx) => {
+ *     const user = await db.getUser(ctx.token);
+ *     if (!user) throw new Error('Unauthorized');
+ *     return { user };  // ← TS infers: { user: User }
+ * });
+ *
+ * const billing = defineTool('billing', {
+ *     middleware: [requireAuth],
+ *     actions: {
+ *         refund: {
+ *             handler: async (ctx, args) => {
+ *                 // ctx.user EXISTS and is typed! ✅
+ *                 return success(`Refunded by ${ctx.user.id}`);
+ *             },
+ *         },
+ *     },
+ * });
+ * ```
+ *
+ * @module
+ */
+import {} from '../types.js';
+// ============================================================================
+// defineMiddleware()
+// ============================================================================
+/**
+ * Define a context-deriving middleware.
+ *
+ * The returned object can be used in two ways:
+ * 1. As a type-level constraint (the generics carry the derived context)
+ * 2. As a runtime middleware via `.toMiddlewareFn()` (for the existing pipeline)
+ *
+ * @typeParam TContextIn - The input context type
+ * @typeParam TDerived - Auto-inferred derived properties
+ * @param derive - Function that inspects context and returns derived data
+ * @returns A {@link MiddlewareDefinition} with the derived type encoded
+ *
+ * @example
+ * ```typescript
+ * // Auth middleware that derives `user`
+ * const requireAuth = defineMiddleware(async (ctx: { token: string }) => {
+ *     const user = await db.getUser(ctx.token);
+ *     if (!user) throw new Error('Unauthorized');
+ *     return { user };
+ * });
+ *
+ * // Rate limit middleware that derives `rateLimitInfo`
+ * const rateLimit = defineMiddleware(async (ctx: { ip: string }) => {
+ *     const info = await checkRateLimit(ctx.ip);
+ *     if (info.exceeded) throw new Error('Rate limited');
+ *     return { rateLimitInfo: info };
+ * });
+ * ```
+ *
+ * @see {@link MiddlewareFn} for the standard middleware type
+ */
+export function defineMiddleware(derive) {
+    const toMiddlewareFn = () => {
+        return async (ctx, args, next) => {
+            const derived = await derive(ctx);
+            // Merge derived properties into ctx for downstream propagation.
+            // Uses explicit loop instead of Object.assign to guard against
+            // __proto__ injection from untrusted derive functions.
+            // ⚠️  contextFactory MUST return a fresh object per invocation
+            // to prevent cross-call property leakage in parallel scenarios.
+            for (const [key, value] of Object.entries(derived)) {
+                // Bug #110 fix: block constructor/prototype in addition to __proto__,
+                // matching FluentToolBuilder's inline middleware guard.
+                if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                    continue;
+                ctx[key] = value;
+            }
+            return next();
+        };
+    };
+    return {
+        __brand: 'MiddlewareDefinition',
+        derive,
+        toMiddlewareFn,
+    };
+}
+/**
+ * Type guard: check if a value is a MiddlewareDefinition.
+ *
+ * Used internally to auto-convert MiddlewareDefinitions to MiddlewareFns
+ * when passed to `defineTool({ middleware: [...] })`.
+ *
+ * @internal
+ */
+export function isMiddlewareDefinition(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        '__brand' in value &&
+        value.__brand === 'MiddlewareDefinition');
+}
+/**
+ * Convert a middleware arg (either MiddlewareFn or MiddlewareDefinition) to MiddlewareFn.
+ *
+ * @internal
+ */
+export function resolveMiddleware(mw) {
+    if (isMiddlewareDefinition(mw)) {
+        return mw.toMiddlewareFn();
+    }
+    return mw;
+}
+//# sourceMappingURL=ContextDerivation.js.map

package/dist/core/middleware/ContextDerivation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextDerivation.js","sourceRoot":"","sources":["../../../src/core/middleware/ContextDerivation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,EAAqB,MAAM,aAAa,CAAC;AAwDhD,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,gBAAgB,CAI5B,MAAyD;IAEzD,MAAM,cAAc,GAAG,GAA6B,EAAE;QAClD,OAAO,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC7B,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;YAClC,gEAAgE;YAChE,+DAA+D;YAC/D,uDAAuD;YACvD,+DAA+D;YAC/D,gEAAgE;YAChE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAkC,CAAC,EAAE,CAAC;gBAC5E,sEAAsE;gBACtE,wDAAwD;gBACxD,IAAI,GAAG,KAAK,WAAW,IAAI,GAAG,KAAK,aAAa,IAAI,GAAG,KAAK,WAAW;oBAAE,SAAS;gBACjF,GAA+B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAClD,CAAC;YACD,OAAO,IAAI,EAAE,CAAC;QAClB,CAAC,CAAC;IACN,CAAC,CAAC;IAEF,OAAO;QACH,OAAO,EAAE,sBAAsB;QAC/B,MAAM;QACN,cAAc;KACjB,CAAC;AACN,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAClC,KAAc;IAEd,OAAO,CACH,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QACjB,KAA8B,CAAC,OAAO,KAAK,sBAAsB,CACrE,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC7B,EAAoF;IAEpF,IAAI,sBAAsB,CAAW,EAAE,CAAC,EAAE,CAAC;QACvC,OAAO,EAAE,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,EAA4B,CAAC;AACxC,CAAC"}

package/dist/core/middleware/index.d.ts

@@ -0,0 +1,4 @@
+/** Middleware Bounded Context — Barrel Export */
+export { defineMiddleware, resolveMiddleware, isMiddlewareDefinition, } from './ContextDerivation.js';
+export type { MiddlewareDefinition, MergeContext, InferContextOut, } from './ContextDerivation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/middleware/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,OAAO,EACH,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,GACzB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EACR,oBAAoB,EACpB,YAAY,EACZ,eAAe,GAClB,MAAM,wBAAwB,CAAC"}

package/dist/core/middleware/index.js

@@ -0,0 +1,3 @@
+/** Middleware Bounded Context — Barrel Export */
+export { defineMiddleware, resolveMiddleware, isMiddlewareDefinition, } from './ContextDerivation.js';
+//# sourceMappingURL=index.js.map

package/dist/core/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/middleware/index.ts"],"names":[],"mappings":"AAAA,iDAAiD;AACjD,OAAO,EACH,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,GACzB,MAAM,wBAAwB,CAAC"}

package/dist/core/registry/ToolFilterEngine.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ToolFilterEngine — Tag-Based Tool Filtering Strategy
+ *
+ * Filters tool builders by tag criteria using the Specification pattern.
+ * Supports AND, OR, and exclusion logic with O(1) Set-based lookups.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import { type ToolBuilder } from '../types.js';
+/** Filter options for selective tool exposure */
+export interface ToolFilter {
+    /** Only include tools that have ALL these tags (AND logic) */
+    tags?: string[];
+    /** Only include tools that have at least ONE of these tags (OR logic) */
+    anyTag?: string[];
+    /** Exclude tools that have ANY of these tags */
+    exclude?: string[];
+}
+/**
+ * Filter and build tool definitions from a collection of builders.
+ *
+ * Uses Set-based lookups for O(1) tag matching and single-pass iteration
+ * to avoid intermediate array allocations.
+ */
+export declare function filterTools<TContext>(builders: Iterable<ToolBuilder<TContext>>, filter: ToolFilter): McpTool[];
+//# sourceMappingURL=ToolFilterEngine.d.ts.map

package/dist/core/registry/ToolFilterEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFilterEngine.d.ts","sourceRoot":"","sources":["../../../src/core/registry/ToolFilterEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACvB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAChC,QAAQ,EAAE,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,EACzC,MAAM,EAAE,UAAU,GACnB,OAAO,EAAE,CA+BX"}

package/dist/core/registry/ToolFilterEngine.js

@@ -0,0 +1,45 @@
+/**
+ * ToolFilterEngine — Tag-Based Tool Filtering Strategy
+ *
+ * Filters tool builders by tag criteria using the Specification pattern.
+ * Supports AND, OR, and exclusion logic with O(1) Set-based lookups.
+ *
+ * Pure-function module: no state, no side effects.
+ */
+import {} from '@modelcontextprotocol/sdk/types.js';
+import {} from '../types.js';
+// ── Filter Engine ────────────────────────────────────────
+/**
+ * Filter and build tool definitions from a collection of builders.
+ *
+ * Uses Set-based lookups for O(1) tag matching and single-pass iteration
+ * to avoid intermediate array allocations.
+ */
+export function filterTools(builders, filter) {
+    // Pre-convert filter arrays to Sets for O(1) lookup
+    const requiredTags = filter.tags && filter.tags.length > 0
+        ? new Set(filter.tags) : undefined;
+    const anyTags = filter.anyTag && filter.anyTag.length > 0
+        ? new Set(filter.anyTag) : undefined;
+    const excludeTags = filter.exclude && filter.exclude.length > 0
+        ? new Set(filter.exclude) : undefined;
+    const tools = [];
+    for (const builder of builders) {
+        const builderTags = builder.getTags();
+        // AND logic: builder must have ALL required tags
+        if (requiredTags && !Array.from(requiredTags).every(t => builderTags.includes(t))) {
+            continue;
+        }
+        // OR logic: builder must have at least ONE of these tags
+        if (anyTags && !builderTags.some(t => anyTags.has(t))) {
+            continue;
+        }
+        // Exclude: builder must not have ANY of these tags
+        if (excludeTags && builderTags.some(t => excludeTags.has(t))) {
+            continue;
+        }
+        tools.push(builder.buildToolDefinition());
+    }
+    return tools;
+}
+//# sourceMappingURL=ToolFilterEngine.js.map

package/dist/core/registry/ToolFilterEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFilterEngine.js","sourceRoot":"","sources":["../../../src/core/registry/ToolFilterEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAwB,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAoB,MAAM,aAAa,CAAC;AAc/C,4DAA4D;AAE5D;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CACvB,QAAyC,EACzC,MAAkB;IAElB,oDAAoD;IACpD,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;QACtD,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACvC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC;QACrD,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACzC,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;QAC3D,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE1C,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;QAEtC,iDAAiD;QACjD,IAAI,YAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAChF,SAAS;QACb,CAAC;QAED,yDAAyD;QACzD,IAAI,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACpD,SAAS;QACb,CAAC;QAED,mDAAmD;QACnD,IAAI,WAAW,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,SAAS;QACb,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC;AACjB,CAAC"}

package/dist/core/registry/ToolRegistry.d.ts

@@ -0,0 +1,259 @@
+/**
+ * ToolRegistry — Centralized Tool Registration & Routing
+ *
+ * The single place where all tool builders are registered and where
+ * incoming MCP calls are routed to the correct handler.
+ *
+ * @example
+ * ```typescript
+ * import { ToolRegistry, createTool, success } from 'vurb';
+ *
+ * const registry = new ToolRegistry<AppContext>();
+ *
+ * registry.register(
+ *     createTool<AppContext>('projects').action({ name: 'list', handler: listProjects }),
+ * );
+ *
+ * // Attach to any MCP server (duck-typed):
+ * const detach = registry.attachToServer(server, {
+ *     contextFactory: (extra) => createAppContext(extra),
+ * });
+ *
+ * // Clean teardown (e.g. in tests):
+ * detach();
+ * ```
+ *
+ * @see {@link createTool} for building tools
+ * @see {@link GroupedToolBuilder} for the builder API
+ *
+ * @module
+ */
+import { type Tool as McpTool } from '@modelcontextprotocol/sdk/types.js';
+import { type ToolResponse } from '../response.js';
+import { type ToolBuilder } from '../types.js';
+import { type DebugObserverFn } from '../../observability/DebugObserver.js';
+import { type TelemetrySink } from '../../observability/TelemetryEvent.js';
+import { type VurbTracer } from '../../observability/Tracing.js';
+import { type ToolFilter } from './ToolFilterEngine.js';
+import { type AttachOptions, type DetachFn } from '../../server/ServerAttachment.js';
+import { type ProgressSink } from '../execution/ProgressHelper.js';
+export type { ToolFilter } from './ToolFilterEngine.js';
+export type { AttachOptions, DetachFn } from '../../server/ServerAttachment.js';
+/**
+ * Centralized registry for MCP tool builders.
+ *
+ * Manages tool registration, filtered retrieval, call routing,
+ * and MCP server attachment.
+ *
+ * @typeParam TContext - Application context type shared across all tools
+ *
+ * @example
+ * ```typescript
+ * const registry = new ToolRegistry<AppContext>();
+ *
+ * // Register individually
+ * registry.register(projectsTool);
+ *
+ * // Register multiple at once
+ * registry.registerAll(usersTool, billingTool, adminTool);
+ *
+ * // Query registered tools
+ * registry.has('projects');  // true
+ * registry.size;             // 4
+ * ```
+ */
+export declare class ToolRegistry<TContext = void> {
+    private readonly _builders;
+    private _debug?;
+    private _tracer?;
+    private _telemetrySink?;
+    /**
+     * Register a single tool builder.
+     *
+     * Validates that the tool name is unique and triggers
+     * {@link GroupedToolBuilder.buildToolDefinition} to compile
+     * the tool definition at registration time.
+     *
+     * @param builder - A built or unbuilt tool builder
+     * @throws If a tool with the same name is already registered
+     *
+     * @example
+     * ```typescript
+     * registry.register(
+     *     createTool<AppContext>('projects')
+     *         .action({ name: 'list', handler: listProjects })
+     * );
+     * ```
+     */
+    register(builder: ToolBuilder<TContext>): void;
+    /**
+     * Register multiple tool builders at once.
+     *
+     * @param builders - One or more tool builders
+     *
+     * @example
+     * ```typescript
+     * registry.registerAll(usersTool, projectsTool, billingTool);
+     * ```
+     */
+    registerAll(...builders: ToolBuilder<TContext>[]): void;
+    /**
+     * Get all registered MCP tool definitions.
+     *
+     * Returns the compiled `McpTool` objects for all registered builders.
+     *
+     * @returns Array of MCP Tool objects
+     */
+    getAllTools(): McpTool[];
+    /**
+     * Get an iterable of all registered tool builders.
+     *
+     * Used by the introspection module to extract action
+     * metadata and presenter information from each builder.
+     *
+     * @returns Iterable of registered ToolBuilder instances
+     */
+    getBuilders(): Iterable<ToolBuilder<TContext>>;
+    /**
+     * Get tool definitions filtered by tags.
+     *
+     * Uses the {@link ToolFilter} to include/exclude tools
+     * based on their capability tags.
+     *
+     * @param filter - Tag-based filter configuration
+     * @returns Filtered array of MCP Tool objects
+     *
+     * @example
+     * ```typescript
+     * // Only core tools
+     * const coreTools = registry.getTools({ tags: ['core'] });
+     *
+     * // Everything except internal tools
+     * const publicTools = registry.getTools({ exclude: ['internal'] });
+     * ```
+     *
+     * @see {@link ToolFilter} for filter options
+     */
+    getTools(filter: ToolFilter): McpTool[];
+    /**
+     * Route an incoming tool call to the correct builder.
+     *
+     * Looks up the builder by name and delegates to its `execute()` method.
+     * Returns an error response if the tool is not found.
+     *
+     * @param ctx - Application context
+     * @param name - Tool name from the incoming MCP call
+     * @param args - Raw arguments from the LLM
+     * @param progressSink - Optional callback for streaming progress notifications.
+     *   When called from `attachToServer()`, this is automatically wired to
+     *   MCP `notifications/progress`. When omitted, progress events are silently consumed.
+     * @returns The handler's response
+     *
+     * @example
+     * ```typescript
+     * const response = await registry.routeCall(ctx, 'projects', {
+     *     action: 'list',
+     *     workspace_id: 'ws_123',
+     * });
+     * ```
+     */
+    routeCall(ctx: TContext, name: string, args: Record<string, unknown>, progressSink?: ProgressSink, signal?: AbortSignal): Promise<ToolResponse>;
+    /**
+     * Attach this registry to an MCP server.
+     *
+     * Registers `tools/list` and `tools/call` handlers on the server.
+     * Supports both `McpServer` (high-level SDK) and `Server` (low-level SDK)
+     * via duck-type detection.
+     *
+     * @param server - Any MCP server instance (duck-typed)
+     * @param options - Attachment options (context factory, tag filter)
+     * @returns A detach function for clean teardown
+     *
+     * @example
+     * ```typescript
+     * // Basic attachment
+     * const detach = registry.attachToServer(server, {
+     *     contextFactory: (extra) => createAppContext(extra),
+     * });
+     *
+     * // With tag filtering
+     * registry.attachToServer(server, {
+     *     contextFactory: (extra) => createAppContext(extra),
+     *     filter: { tags: ['core'] },
+     * });
+     *
+     * // Clean teardown (e.g. in tests)
+     * detach();
+     * ```
+     *
+     * @see {@link DetachFn} for the teardown function type
+     * @see {@link AttachOptions} for all options
+     */
+    attachToServer(server: unknown, options?: AttachOptions<TContext>): Promise<DetachFn>;
+    /** Check if a tool with the given name is registered. */
+    has(name: string): boolean;
+    /** Remove all registered tools. */
+    clear(): void;
+    /** Number of registered tools. */
+    get size(): number;
+    /**
+     * Enable debug observability for ALL registered tools.
+     *
+     * Propagates the debug observer to every registered builder that
+     * supports it (duck-typed via `.debug()` method).
+     *
+     * Also enables registry-level debug events (unknown tool errors).
+     *
+     * @param observer - A {@link DebugObserverFn} created by `createDebugObserver()`
+     *
+     * @example
+     * ```typescript
+     * const debug = createDebugObserver();
+     * registry.enableDebug(debug);
+     * // Now ALL tools + registry routing emit debug events
+     * ```
+     */
+    enableDebug(observer: DebugObserverFn): void;
+    /**
+     * Enable OpenTelemetry-compatible tracing for ALL registered tools.
+     *
+     * Propagates the tracer to every registered builder that supports
+     * it (duck-typed via `.tracing()` method).
+     *
+     * Also enables registry-level tracing for unknown tool routing errors.
+     *
+     * **Important**: When both `enableDebug()` and `enableTracing()` are active,
+     * tracing takes precedence and debug events are NOT emitted from tool builders.
+     *
+     * @param tracer - A {@link VurbTracer} (or OTel `Tracer`) instance
+     *
+     * @example
+     * ```typescript
+     * import { trace } from '@opentelemetry/api';
+     *
+     * const tracer = trace.getTracer('vurb');
+     * registry.enableTracing(tracer);
+     * // Now ALL tools + registry routing emit OTel spans
+     * ```
+     *
+     * @see {@link VurbTracer} for the tracer interface contract
+     * @see {@link SpanStatusCode} for status code semantics
+     */
+    enableTracing(tracer: VurbTracer): void;
+    /**
+     * Enable telemetry emission for ALL registered tools.
+     *
+     * Propagates the TelemetrySink to every registered builder that supports
+     * it (duck-typed via `.telemetry()` method). This enables real-time
+     * event emission to the Inspector TUI via Shadow Socket IPC.
+     *
+     * @param sink - A {@link TelemetrySink} from `startServer()` or `TelemetryBus`
+     */
+    enableTelemetry(sink: TelemetrySink): void;
+    /**
+     * Propagate active debug/tracing/telemetry to a newly registered builder.
+     * @internal
+     */
+    private _propagateObservability;
+}
+//# sourceMappingURL=ToolRegistry.d.ts.map

package/dist/core/registry/ToolRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../../src/core/registry/ToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAE,KAAK,IAAI,IAAI,OAAO,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,KAAK,UAAU,EAAkB,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAEH,KAAK,aAAa,EAAE,KAAK,QAAQ,EACpC,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAInE,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAMhF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,YAAY,CAAC,QAAQ,GAAG,IAAI;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,MAAM,CAAC,CAAkB;IACjC,OAAO,CAAC,OAAO,CAAC,CAAa;IAC7B,OAAO,CAAC,cAAc,CAAC,CAAgB;IAEvC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI;IAY9C;;;;;;;;;OASG;IACH,WAAW,CAAC,GAAG,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,EAAE,GAAG,IAAI;IAMvD;;;;;;OAMG;IACH,WAAW,IAAI,OAAO,EAAE;IAQxB;;;;;;;OAOG;IACH,WAAW,IAAI,QAAQ,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAI9C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,EAAE;IAIvC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,SAAS,CACX,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,YAAY,CAAC,EAAE,YAAY,EAC3B,MAAM,CAAC,EAAE,WAAW,GACrB,OAAO,CAAC,YAAY,CAAC;IAqBxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,cAAc,CAChB,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,aAAa,CAAC,QAAQ,CAAM,GACtC,OAAO,CAAC,QAAQ,CAAC;IAIpB,yDAAyD;IACzD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAE1B,mCAAmC;IACnC,KAAK,IAAI,IAAI;IAEb,kCAAkC;IAClC,IAAI,IAAI,IAAI,MAAM,CAAgC;IAElD;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI;IAa5C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAavC;;;;;;;;OAQG;IACH,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAS1C;;;OAGG;IACH,OAAO,CAAC,uBAAuB;CAWlC"}