@vurb/core 3.2.0

package/dist/observability/Tracing.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Tracing — OpenTelemetry-Compatible Tracing Abstraction
+ *
+ * Defines minimal interfaces that are structurally compatible with
+ * OpenTelemetry's `Tracer` and `Span`, allowing direct pass-through
+ * without adapter or `@opentelemetry/*` dependency.
+ *
+ * Design decisions:
+ * - **Structural subtyping**: `VurbTracer` is a subset of OTel's `Tracer`,
+ *   so `trace.getTracer('vurb')` can be passed directly.
+ * - **Strict attribute types**: `VurbAttributeValue` matches OTel's
+ *   `SpanAttributeValue` to avoid TypeScript contravariance errors.
+ * - **Optional `addEvent`**: Not all tracer implementations support events.
+ *   The pipeline uses `span.addEvent?.()` (optional chaining).
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // Direct OTel pass-through — no adapter needed
+ * registry.attachToServer(server, {
+ *     contextFactory: createContext,
+ *     tracing: trace.getTracer('vurb'),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom tracer (e.g. for testing)
+ * const spans: Array<{ name: string; attributes: Map<string, VurbAttributeValue> }> = [];
+ *
+ * const testTracer: VurbTracer = {
+ *     startSpan(name, options) {
+ *         const attrs = new Map<string, VurbAttributeValue>(
+ *             Object.entries(options?.attributes ?? {}),
+ *         );
+ *         const span: VurbSpan = {
+ *             setAttribute(k, v) { attrs.set(k, v); },
+ *             setStatus() {},
+ *             addEvent() {},
+ *             end() { spans.push({ name, attributes: attrs }); },
+ *             recordException() {},
+ *         };
+ *         return span;
+ *     },
+ * };
+ * ```
+ *
+ * @module
+ */
+/**
+ * Span status codes matching OpenTelemetry's `SpanStatusCode` enum.
+ *
+ * - `UNSET` (0) — Default. Used for validation errors (AI mistakes),
+ *   unknown actions, and other non-system failures that should NOT
+ *   trigger infrastructure alerts.
+ * - `OK` (1) — Successful execution.
+ * - `ERROR` (2) — System failure. Only used when the handler throws
+ *   an unhandled exception. This WILL trigger alerts in OTel backends.
+ *
+ * @see {@link https://opentelemetry.io/docs/specs/otel/trace/api/#set-status | OTel Spec: Set Status}
+ */
+export declare const SpanStatusCode: {
+    readonly UNSET: 0;
+    readonly OK: 1;
+    readonly ERROR: 2;
+};
+/**
+ * Strict attribute value type — matches OpenTelemetry's `SpanAttributeValue`.
+ *
+ * Using `unknown` here would cause TypeScript contravariance errors
+ * when assigning an OTel `Tracer` to `VurbTracer` in strict mode.
+ *
+ * @see {@link https://opentelemetry.io/docs/specs/otel/common/#attribute | OTel Spec: Attributes}
+ */
+export type VurbAttributeValue = string | number | boolean | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<boolean>;
+/**
+ * Minimal span interface — structural subtype of OTel's `Span`.
+ *
+ * All methods match OTel's signatures so that an OTel `Span` satisfies
+ * this interface without any adapter.
+ *
+ * @see {@link https://opentelemetry.io/docs/specs/otel/trace/api/#span | OTel Spec: Span}
+ */
+export interface VurbSpan {
+    /**
+     * Set a single attribute on this span.
+     * @param key - Attribute key (use `mcp.*` namespace for Vurb attributes)
+     * @param value - Primitive or array of primitives
+     */
+    setAttribute(key: string, value: VurbAttributeValue): void;
+    /**
+     * Set the span's status.
+     *
+     * Use `SpanStatusCode.UNSET` for AI/validation errors.
+     * Use `SpanStatusCode.ERROR` only for system failures (handler exceptions).
+     *
+     * @param status - Object with `code` and optional `message`
+     */
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    /**
+     * Add a timestamped event to this span.
+     *
+     * Optional — not all tracer implementations support events.
+     * The pipeline uses `span.addEvent?.()` (optional chaining).
+     *
+     * @param name - Event name (e.g. `'mcp.route'`, `'mcp.validate'`)
+     * @param attributes - Optional event attributes
+     */
+    addEvent?(name: string, attributes?: Record<string, VurbAttributeValue>): void;
+    /**
+     * End this span. Must be called exactly once.
+     * The pipeline calls this in a `finally` block to prevent span leaks.
+     */
+    end(): void;
+    /**
+     * Record an exception as a span event.
+     * Called before `setStatus(ERROR)` when a handler throws.
+     *
+     * @param exception - The caught error or string message
+     */
+    recordException(exception: Error | string): void;
+}
+/**
+ * Minimal tracer interface — structural subtype of OTel's `Tracer`.
+ *
+ * OTel's `Tracer.startSpan()` accepts `(name, options?, context?)`.
+ * Our interface matches the first two parameters, so an OTel `Tracer`
+ * can be assigned to `VurbTracer` without any adapter.
+ *
+ * **Context propagation limitation:** Since we don't use OTel's
+ * `Context` API (which would require a runtime dependency),
+ * auto-instrumented downstream calls (Prisma, HTTP client, Redis)
+ * inside tool handlers will NOT appear as children of the MCP span.
+ * They will be siblings in the trace. This is an intentional trade-off
+ * for zero dependencies.
+ *
+ * @see {@link https://opentelemetry.io/docs/specs/otel/trace/api/#tracer | OTel Spec: Tracer}
+ */
+export interface VurbTracer {
+    /**
+     * Create and start a new span.
+     *
+     * @param name - Span name (e.g. `'mcp.tool.projects'`)
+     * @param options - Optional span creation options
+     * @returns A started span that MUST be ended via `span.end()`
+     */
+    startSpan(name: string, options?: {
+        attributes?: Record<string, VurbAttributeValue>;
+    }): VurbSpan;
+}
+//# sourceMappingURL=Tracing.d.ts.map

package/dist/observability/Tracing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tracing.d.ts","sourceRoot":"","sources":["../../src/observability/Tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAMH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc;;;;CAAyC,CAAC;AAMrE;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GACxB,MAAM,GACN,MAAM,GACN,OAAO,GACP,aAAa,CAAC,MAAM,CAAC,GACrB,aAAa,CAAC,MAAM,CAAC,GACrB,aAAa,CAAC,OAAO,CAAC,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACrB;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAE3D;;;;;;;OAOG;IACH,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE5D;;;;;;;;OAQG;IACH,QAAQ,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAC;IAE/E;;;OAGG;IACH,GAAG,IAAI,IAAI,CAAC;IAEZ;;;;;OAKG;IACH,eAAe,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,UAAU;IACvB;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;KACnD,GAAG,QAAQ,CAAC;CAChB"}

package/dist/observability/Tracing.js

@@ -0,0 +1,67 @@
+/**
+ * Tracing — OpenTelemetry-Compatible Tracing Abstraction
+ *
+ * Defines minimal interfaces that are structurally compatible with
+ * OpenTelemetry's `Tracer` and `Span`, allowing direct pass-through
+ * without adapter or `@opentelemetry/*` dependency.
+ *
+ * Design decisions:
+ * - **Structural subtyping**: `VurbTracer` is a subset of OTel's `Tracer`,
+ *   so `trace.getTracer('vurb')` can be passed directly.
+ * - **Strict attribute types**: `VurbAttributeValue` matches OTel's
+ *   `SpanAttributeValue` to avoid TypeScript contravariance errors.
+ * - **Optional `addEvent`**: Not all tracer implementations support events.
+ *   The pipeline uses `span.addEvent?.()` (optional chaining).
+ *
+ * @example
+ * ```typescript
+ * import { trace } from '@opentelemetry/api';
+ *
+ * // Direct OTel pass-through — no adapter needed
+ * registry.attachToServer(server, {
+ *     contextFactory: createContext,
+ *     tracing: trace.getTracer('vurb'),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom tracer (e.g. for testing)
+ * const spans: Array<{ name: string; attributes: Map<string, VurbAttributeValue> }> = [];
+ *
+ * const testTracer: VurbTracer = {
+ *     startSpan(name, options) {
+ *         const attrs = new Map<string, VurbAttributeValue>(
+ *             Object.entries(options?.attributes ?? {}),
+ *         );
+ *         const span: VurbSpan = {
+ *             setAttribute(k, v) { attrs.set(k, v); },
+ *             setStatus() {},
+ *             addEvent() {},
+ *             end() { spans.push({ name, attributes: attrs }); },
+ *             recordException() {},
+ *         };
+ *         return span;
+ *     },
+ * };
+ * ```
+ *
+ * @module
+ */
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Span status codes matching OpenTelemetry's `SpanStatusCode` enum.
+ *
+ * - `UNSET` (0) — Default. Used for validation errors (AI mistakes),
+ *   unknown actions, and other non-system failures that should NOT
+ *   trigger infrastructure alerts.
+ * - `OK` (1) — Successful execution.
+ * - `ERROR` (2) — System failure. Only used when the handler throws
+ *   an unhandled exception. This WILL trigger alerts in OTel backends.
+ *
+ * @see {@link https://opentelemetry.io/docs/specs/otel/trace/api/#set-status | OTel Spec: Set Status}
+ */
+export const SpanStatusCode = { UNSET: 0, OK: 1, ERROR: 2 };
+//# sourceMappingURL=Tracing.js.map

package/dist/observability/Tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tracing.js","sourceRoot":"","sources":["../../src/observability/Tracing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAW,CAAC"}

package/dist/observability/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Observability — Barrel Export
+ *
+ * Public API for debug observers and OpenTelemetry-compatible tracing.
+ */
+export { createDebugObserver } from './DebugObserver.js';
+export type { DebugEvent, DebugObserverFn, RouteEvent, ValidateEvent, MiddlewareEvent, ExecuteEvent, ErrorEvent, GovernanceEvent, GovernanceOperation, } from './DebugObserver.js';
+export { SpanStatusCode } from './Tracing.js';
+export type { VurbSpan, VurbTracer, VurbAttributeValue } from './Tracing.js';
+export { createTelemetryBus, getTelemetryPath, discoverSockets } from './TelemetryBus.js';
+export type { TelemetryBusConfig, TelemetryBusInstance } from './TelemetryBus.js';
+export type { TelemetryEvent, TelemetrySink, DlpRedactEvent, PresenterSliceEvent, PresenterRulesEvent, SandboxExecEvent, FsmTransitionEvent, TopologyEvent, TopologyTool, HeartbeatEvent, } from './TelemetryEvent.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACzD,YAAY,EACR,UAAU,EAAE,eAAe,EAC3B,UAAU,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,UAAU,EACpE,eAAe,EAAE,mBAAmB,GACvC,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC1F,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAClF,YAAY,EACR,cAAc,EAAE,aAAa,EAC7B,cAAc,EAAE,mBAAmB,EAAE,mBAAmB,EACxD,gBAAgB,EAAE,kBAAkB,EACpC,aAAa,EAAE,YAAY,EAAE,cAAc,GAC9C,MAAM,qBAAqB,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,12 @@
+/**
+ * Observability — Barrel Export
+ *
+ * Public API for debug observers and OpenTelemetry-compatible tracing.
+ */
+// ── Debug Observer ───────────────────────────────────────
+export { createDebugObserver } from './DebugObserver.js';
+// ── Tracing (OpenTelemetry-compatible) ───────────────────
+export { SpanStatusCode } from './Tracing.js';
+// ── Telemetry (Shadow Socket Out-of-Band Transport) ──────
+export { createTelemetryBus, getTelemetryPath, discoverSockets } from './TelemetryBus.js';
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4DAA4D;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAOzD,4DAA4D;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAG9C,4DAA4D;AAC5D,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/presenter/PostProcessor.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PostProcessor — MVA Response Post-Processing
+ *
+ * Extracted from the ExecutionPipeline to uphold SRP.
+ * Transforms raw handler return values into valid MCP ToolResponse
+ * objects according to the MVA priority hierarchy.
+ *
+ * @internal
+ * @module
+ */
+import { type ToolResponse } from '../core/response.js';
+import { type Presenter } from './Presenter.js';
+import { type TelemetrySink } from '../observability/TelemetryEvent.js';
+/**
+ * Optional telemetry context for Presenter event emission.
+ * Keeps the fast path (no telemetry) at zero overhead.
+ * @internal
+ */
+export interface PostProcessTelemetry {
+    readonly sink: TelemetrySink;
+    readonly tool: string;
+    readonly action: string;
+}
+/**
+ * Post-process a handler's return value through the MVA priority hierarchy.
+ *
+ * Priority:
+ * 1. **ToolResponse** → use directly (backward compatibility)
+ * 2. **ResponseBuilder** → call `.build()` (auto-build)
+ * 3. **Raw data + Presenter** → pipe through `Presenter.make(data).build()`
+ * 4. **Raw data without Presenter** → wrap via canonical `success()` helper
+ *
+ * @param result - The handler's return value
+ * @param presenter - The action's Presenter (from `returns` field), if any
+ * @param ctx - Optional request context
+ * @param selectFields - Optional `_select` field names for context window optimization
+ * @param telemetry - Optional telemetry context for Presenter events
+ * @returns A valid MCP ToolResponse
+ *
+ * @internal
+ */
+export declare function postProcessResult(result: unknown, presenter: Presenter<unknown> | undefined, ctx?: unknown, selectFields?: string[], telemetry?: PostProcessTelemetry): ToolResponse;
+/**
+ * Check if a value is a valid MCP ToolResponse.
+ *
+ * A ToolResponse must have a `content` array — the canonical shape
+ * from `response.ts`.
+ *
+ * @internal
+ */
+export declare function isToolResponse(value: unknown): value is ToolResponse;
+//# sourceMappingURL=PostProcessor.d.ts.map

package/dist/presenter/PostProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostProcessor.d.ts","sourceRoot":"","sources":["../../src/presenter/PostProcessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,KAAK,YAAY,EAA8B,MAAM,qBAAqB,CAAC;AAEpF,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAIxE;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAID;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAC7B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,SAAS,EACzC,GAAG,CAAC,EAAE,OAAO,EACb,YAAY,CAAC,EAAE,MAAM,EAAE,EACvB,SAAS,CAAC,EAAE,oBAAoB,GACjC,YAAY,CAqGd;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAgBpE"}

package/dist/presenter/PostProcessor.js

@@ -0,0 +1,148 @@
+/**
+ * PostProcessor — MVA Response Post-Processing
+ *
+ * Extracted from the ExecutionPipeline to uphold SRP.
+ * Transforms raw handler return values into valid MCP ToolResponse
+ * objects according to the MVA priority hierarchy.
+ *
+ * @internal
+ * @module
+ */
+import { success as successResponse } from '../core/response.js';
+import { isResponseBuilder } from './ResponseBuilder.js';
+import {} from './Presenter.js';
+import {} from '../observability/TelemetryEvent.js';
+const _encoder = new TextEncoder();
+/**
+ * Post-process a handler's return value through the MVA priority hierarchy.
+ *
+ * Priority:
+ * 1. **ToolResponse** → use directly (backward compatibility)
+ * 2. **ResponseBuilder** → call `.build()` (auto-build)
+ * 3. **Raw data + Presenter** → pipe through `Presenter.make(data).build()`
+ * 4. **Raw data without Presenter** → wrap via canonical `success()` helper
+ *
+ * @param result - The handler's return value
+ * @param presenter - The action's Presenter (from `returns` field), if any
+ * @param ctx - Optional request context
+ * @param selectFields - Optional `_select` field names for context window optimization
+ * @param telemetry - Optional telemetry context for Presenter events
+ * @returns A valid MCP ToolResponse
+ *
+ * @internal
+ */
+export function postProcessResult(result, presenter, ctx, selectFields, telemetry) {
+    // Priority 1: Already a ToolResponse (has content array)
+    if (isToolResponse(result)) {
+        return result;
+    }
+    // Priority 2: ResponseBuilder instance → auto-call .build()
+    if (isResponseBuilder(result)) {
+        return result.build();
+    }
+    // Priority 3: Raw data + Presenter → pipe through MVA
+    if (presenter) {
+        // Measure raw data size for telemetry
+        const rawJson = telemetry ? JSON.stringify(result) : undefined;
+        const rawBytes = rawJson ? _encoder.encode(rawJson).byteLength : 0;
+        const rawRows = Array.isArray(result) ? result.length : 1;
+        const response = presenter.make(result, ctx, selectFields).build();
+        // Emit presenter.slice and presenter.rules events
+        if (telemetry) {
+            // Measure wire bytes from the built response
+            let wireBytes = 0;
+            for (const c of response.content) {
+                if ('text' in c && typeof c.text === 'string') {
+                    wireBytes += _encoder.encode(c.text).byteLength;
+                }
+            }
+            // Compute wire rows — agentLimit may have truncated
+            const agentLimitMax = presenter.getAgentLimitMax();
+            const wireRows = (agentLimitMax !== undefined && rawRows > agentLimitMax)
+                ? agentLimitMax
+                : rawRows;
+            telemetry.sink({
+                type: 'presenter.slice',
+                tool: telemetry.tool,
+                action: telemetry.action,
+                rawBytes,
+                wireBytes,
+                rowsRaw: rawRows,
+                rowsWire: wireRows,
+                // Enriched fields for Inspector X-Ray
+                ...(selectFields && selectFields.length > 0 ? {
+                    selectFields,
+                    totalFields: presenter.getSchemaKeys().length || undefined,
+                } : {}),
+                ...(agentLimitMax !== undefined && rawRows > agentLimitMax ? {
+                    guardrailFrom: rawRows,
+                    guardrailTo: agentLimitMax,
+                    guardrailHint: 'Results truncated by agentLimit. Use pagination or filters.',
+                } : {}),
+                timestamp: Date.now(),
+            });
+            // Extract rules from the built response text content
+            // Rules are embedded as <domain_rules> XML blocks by the ResponseBuilder
+            const rulesFromResponse = [];
+            for (const c of response.content) {
+                if ('text' in c && typeof c.text === 'string') {
+                    const match = c.text.match(/<domain_rules>\n([\s\S]*?)\n<\/domain_rules>/);
+                    if (match) {
+                        rulesFromResponse.push(...match[1].split('\n').filter(Boolean).map(r => r.replace(/^- /, '')));
+                    }
+                }
+            }
+            if (rulesFromResponse.length > 0) {
+                telemetry.sink({
+                    type: 'presenter.rules',
+                    tool: telemetry.tool,
+                    action: telemetry.action,
+                    rules: rulesFromResponse,
+                    timestamp: Date.now(),
+                });
+            }
+            // Emit DLP redaction event if the Presenter has redact paths
+            const redactPaths = presenter.getRedactPaths();
+            if (redactPaths.length > 0) {
+                telemetry.sink({
+                    type: 'dlp.redact',
+                    tool: telemetry.tool,
+                    action: telemetry.action,
+                    fieldsRedacted: redactPaths.length,
+                    paths: [...redactPaths],
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        return response;
+    }
+    // Priority 4: Raw data without Presenter → canonical success() helper
+    return successResponse(typeof result === 'string' || typeof result === 'object'
+        ? result
+        : String(result));
+}
+// ── Type Guard ───────────────────────────────────────────
+/**
+ * Check if a value is a valid MCP ToolResponse.
+ *
+ * A ToolResponse must have a `content` array — the canonical shape
+ * from `response.ts`.
+ *
+ * @internal
+ */
+export function isToolResponse(value) {
+    if (typeof value !== 'object' ||
+        value === null ||
+        !('content' in value) ||
+        !Array.isArray(value.content)) {
+        return false;
+    }
+    const content = value.content;
+    // Empty content array is valid (e.g. fire-and-forget)
+    if (content.length === 0)
+        return true;
+    // First element must have a string `type` property
+    const first = content[0];
+    return first != null && typeof first['type'] === 'string';
+}
+//# sourceMappingURL=PostProcessor.js.map

package/dist/presenter/PostProcessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostProcessor.js","sourceRoot":"","sources":["../../src/presenter/PostProcessor.ts"],"names":[],"mappings":"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"}