@revealui/ai 0.2.9 → 0.4.0

package/dist/tools/mcp-elicitation.js

@@ -0,0 +1,121 @@
+/**
+ * MCP Elicitation — route server `elicitation/create` requests through
+ * a consumer-provided UI callback (Stage 5.3 of the MCP v1 plan).
+ *
+ * The MCP spec defines `elicitation/create` as a server-to-client
+ * request: a server asks the client to collect structured input from
+ * the user mid-flow (form inputs, confirmations, auth prompts). The
+ * agent runtime is NOT the right place to decide what UI to show —
+ * each consumer (admin inspector, agent execution panel, CLI tool,
+ * Slack bot, …) renders in its own idiom. This module exposes
+ * `createElicitationHandler({ onElicit })` — a thin factory that
+ * wraps the consumer's async UI callback into the structural handler
+ * shape that `McpClient` from `@revealui/mcp/client` expects.
+ *
+ * Safety defaults
+ * ---------------
+ * - Servers that request **URL mode** (out-of-band consent via a
+ *   separate browser tab) are auto-declined unless `allowUrlMode: true`
+ *   is passed. URL mode is a phishing vector when the user can't
+ *   easily verify what domain they're on — admin inspector (Stage 3.4)
+ *   takes the same posture; agent runtime matches for consistency.
+ * - Optional `timeoutMs` auto-declines after the deadline. Useful in
+ *   headless automation where no human is at the keyboard.
+ * - Thrown errors inside `onElicit` are converted to `{ action:
+ *   'cancel' }` rather than propagating — servers should see a clean
+ *   decline, not a protocol error the UI crashed on.
+ *
+ * As with the rest of the MCP-adapter surface, this module uses
+ * structural typing to stay decoupled from `@revealui/mcp` — the real
+ * `ElicitationHandler` from `@revealui/mcp/client` structurally
+ * satisfies the `McpElicitationHandler` shape exported here.
+ *
+ * @example
+ * ```typescript
+ * import { McpClient } from '@revealui/mcp/client';
+ * import { createElicitationHandler } from '@revealui/ai';
+ *
+ * const client = new McpClient({
+ *   clientInfo: { name: 'my-agent', version: '1.0.0' },
+ *   transport: { kind: 'streamable-http', url: '…' },
+ *   elicitationHandler: createElicitationHandler({
+ *     onElicit: async ({ message, requestedSchema }) => {
+ *       const form = await showFormDialog({ title: message, schema: requestedSchema });
+ *       if (!form) return { action: 'cancel' };
+ *       return { action: 'accept', content: form.values };
+ *     },
+ *     timeoutMs: 60_000,
+ *   }),
+ * });
+ * ```
+ */
+import { logger } from '@revealui/core/observability/logger';
+import { emitMcpEvent } from './mcp-events.js';
+export function createElicitationHandler(options) {
+    const { onElicit, timeoutMs, allowUrlMode, onElicitationRequest, onEvent, namespace } = options;
+    return async (params) => {
+        const fieldCount = countSchemaFields(params.requestedSchema);
+        const started = Date.now();
+        if (params.mode === 'url' && !allowUrlMode) {
+            emitMcpEvent(onEvent, {
+                kind: 'mcp.elicitation.create',
+                ...(namespace !== undefined ? { namespace } : {}),
+                action: 'decline',
+                fieldCount,
+                ...(params.mode !== undefined ? { mode: params.mode } : {}),
+                duration_ms: Date.now() - started,
+                success: true,
+            });
+            return { action: 'decline' };
+        }
+        onElicitationRequest?.({
+            message: params.message,
+            fieldCount,
+            ...(params.mode !== undefined ? { mode: params.mode } : {}),
+        });
+        let timeoutHandle;
+        let result;
+        try {
+            const userResponse = onElicit(params).catch((error) => {
+                // Errors inside the consumer's UI callback → cancel (not decline —
+                // the server should see a clean "didn't happen", not a
+                // misrepresented "user said no").
+                logger.warn('[createElicitationHandler] onElicit threw; returning cancel', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return { action: 'cancel' };
+            });
+            if (timeoutMs === undefined || timeoutMs <= 0) {
+                result = await userResponse;
+            }
+            else {
+                const timeoutPromise = new Promise((resolve) => {
+                    timeoutHandle = setTimeout(() => {
+                        resolve({ action: 'cancel' });
+                    }, timeoutMs);
+                });
+                result = await Promise.race([userResponse, timeoutPromise]);
+            }
+        }
+        finally {
+            if (timeoutHandle !== undefined)
+                clearTimeout(timeoutHandle);
+        }
+        emitMcpEvent(onEvent, {
+            kind: 'mcp.elicitation.create',
+            ...(namespace !== undefined ? { namespace } : {}),
+            action: result.action,
+            fieldCount,
+            ...(params.mode !== undefined ? { mode: params.mode } : {}),
+            duration_ms: Date.now() - started,
+            success: true,
+        });
+        return result;
+    };
+}
+/** Count the declared fields on a `requestedSchema.properties` record. */
+function countSchemaFields(schema) {
+    if (!(schema?.properties && typeof schema.properties === 'object'))
+        return 0;
+    return Object.keys(schema.properties).length;
+}

package/dist/tools/mcp-events.d.ts

@@ -0,0 +1,270 @@
+/**
+ * MCP protocol log channel — structured events per server-to-client call
+ * (Stage 6.1 of the MCP v1 plan).
+ *
+ * Stage 5 shipped the full agent-side MCP protocol surface
+ * (tools + resources + prompts + sampling + elicitation + progress +
+ * cancellation). Stage 6.1 adds observability: every adapter in
+ * `@revealui/ai/tools/mcp-*` grows an `onEvent?: McpEventSink` hook that
+ * fires once per protocol call with a structured summary. Consumers wire
+ * the sink to whatever aggregator they run — typically
+ * `@revealui/core/observability/logger` via `createCoreLoggerSink()`.
+ *
+ * Instrumentation lives at the agent-adapter layer by design. The
+ * hypervisor is a separate lane (Stage 6.2 lands `usage_meters` rows
+ * there, where `accountId` is in scope). Agent adapters are intentionally
+ * tenant-agnostic, so events carry no `accountId` field — the consumer
+ * adds tenant context in their sink wrapper if they need it for routing.
+ *
+ * PII note
+ * --------
+ * Errors surfaced by the server can legitimately contain user-identifying
+ * strings (e.g. "user 'alice@example.com' not found"). `error` is passed
+ * through to the sink verbatim. If your deployment's observability layer
+ * is subject to PII constraints, wrap the sink with a redactor
+ * (`redactLogContext` from `@revealui/security`) before passing it in.
+ *
+ * Params / args / content bodies are **not** included in events —
+ * observability is summary-grained by default to avoid accidentally
+ * logging credentials, prompts, or document contents.
+ */
+/** Common fields every MCP protocol-log event carries. */
+interface McpEventBase {
+    /**
+     * Wall-clock duration of the call in milliseconds, measured from
+     * handler entry to handler exit (success or failure). Includes the
+     * full round-trip across the transport plus any zod validation.
+     */
+    duration_ms: number;
+    /** `true` when the call completed without throwing and without `isError`. */
+    success: boolean;
+    /**
+     * Server-reported error text on failure (from `CallToolResult.content`
+     * when `isError: true`, or from `error.message` when the call threw).
+     * Omitted when `success: true`. May contain PII — see module docs.
+     */
+    error?: string;
+}
+export interface McpToolCallEvent extends McpEventBase {
+    kind: 'mcp.tool.call';
+    /** Server identifier the tool belongs to. */
+    namespace: string;
+    /** Tool name WITHOUT the `mcp_<namespace>__` adapter prefix. */
+    toolName: string;
+}
+export interface McpResourceListEvent extends McpEventBase {
+    kind: 'mcp.resource.list';
+    namespace: string;
+    /** Number of resources returned (omitted on failure). */
+    resourceCount?: number;
+}
+export interface McpResourceReadEvent extends McpEventBase {
+    kind: 'mcp.resource.read';
+    namespace: string;
+    /** Resource URI that was read. May be sensitive — see module docs. */
+    uri: string;
+}
+export interface McpPromptListEvent extends McpEventBase {
+    kind: 'mcp.prompt.list';
+    namespace: string;
+    /** Number of prompts returned (omitted on failure). */
+    promptCount?: number;
+}
+export interface McpPromptGetEvent extends McpEventBase {
+    kind: 'mcp.prompt.get';
+    namespace: string;
+    /** Prompt name that was requested. */
+    promptName: string;
+}
+export interface McpSamplingCreateEvent extends McpEventBase {
+    kind: 'mcp.sampling.create';
+    /**
+     * Server identifier when the consumer attached one at handler
+     * construction via `createSamplingHandler({ namespace })`. Absent
+     * when the handler is wired to a shared `McpClient` that fans out
+     * to multiple servers — in that case the consumer's sink wrapper
+     * can fill it in from call-site context.
+     */
+    namespace?: string;
+    /** Model label reported back to the server in `result.model`. */
+    model: string;
+    messageCount: number;
+    maxTokens: number;
+}
+export interface McpElicitationCreateEvent extends McpEventBase {
+    kind: 'mcp.elicitation.create';
+    /** Server identifier when provided to `createElicitationHandler`. */
+    namespace?: string;
+    /** User's decision — `'accept' | 'decline' | 'cancel'`. */
+    action: 'accept' | 'decline' | 'cancel';
+    /** Number of fields in the requested schema. */
+    fieldCount: number;
+    /** Elicitation mode as declared by the server (`'form'`, `'url'`, …). */
+    mode?: string;
+}
+export type McpLogEvent = McpToolCallEvent | McpResourceListEvent | McpResourceReadEvent | McpPromptListEvent | McpPromptGetEvent | McpSamplingCreateEvent | McpElicitationCreateEvent;
+/**
+ * Consumer-wired observability sink. Called exactly once per protocol
+ * call. Must not throw — the adapter swallows sink-thrown errors
+ * internally, but a well-behaved sink returns quickly and cleanly.
+ */
+export type McpEventSink = (event: McpLogEvent) => void;
+export interface CreateCoreLoggerSinkOptions {
+    /**
+     * Minimum level for successful events. Default `'info'`. Set to
+     * `'debug'` to drop successful-call volume from info-level ingestion.
+     * Failed calls are always emitted at `'warn'` regardless.
+     */
+    successLevel?: 'debug' | 'info';
+}
+/**
+ * Build an `McpEventSink` that fans events into the central log
+ * aggregator via `@revealui/core/observability/logger`. This is the
+ * recommended default for in-process consumers (admin app, API, agent
+ * orchestration). Out-of-process consumers (CLI, remote inspector)
+ * typically construct a custom sink that forwards to their own transport.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createToolsFromMcpClient,
+ *   createCoreLoggerSink,
+ * } from '@revealui/ai';
+ *
+ * const onEvent = createCoreLoggerSink();
+ *
+ * const tools = await createToolsFromMcpClient(client, {
+ *   namespace: 'my-server',
+ *   onEvent,
+ * });
+ * ```
+ */
+export declare function createCoreLoggerSink(options?: CreateCoreLoggerSinkOptions): McpEventSink;
+/**
+ * Invoke a sink, swallowing any thrown error. A misbehaving sink must
+ * never break the underlying MCP call — observability is best-effort.
+ * Logs the sink failure at warn so the regression is still visible.
+ *
+ * @internal
+ */
+export declare function emitMcpEvent(sink: McpEventSink | undefined, event: McpLogEvent): void;
+/**
+ * Row shape consumed by the sink's `write` callback. Structurally
+ * matches `usage_meters` insert payload in `@revealui/db/schema/accounts`.
+ * Kept as a plain interface here to avoid importing Drizzle's inferred
+ * insert type and to let tests build rows without a db client.
+ */
+export interface McpUsageMeterRow {
+    /** Synthetic primary key. Default: `crypto.randomUUID()`. */
+    id: string;
+    /** Tenant / account fk (NOT NULL on `usage_meters`). */
+    accountId: string;
+    /** Dot-notation meter name: mirrors `McpLogEvent.kind`. */
+    meterName: string;
+    /**
+     * Event count. v1 uses `1` per call (row-per-call pattern); billing
+     * aggregation rolls these up. A larger quantity makes sense only
+     * when the meter represents a volume (tokens, bytes) rather than
+     * a count of events.
+     */
+    quantity: number;
+    /** Timestamp the metered event occurred. */
+    periodStart: Date;
+    /** Reserved for aggregation-mode rows; `null` for per-call rows. */
+    periodEnd: Date | null;
+    /**
+     * Origin label. Per the `usage_meters` CHECK constraint one of
+     * `'system' | 'user' | 'agent' | 'api'`. Defaults to `'agent'`
+     * since this sink consumes agent-runtime protocol events.
+     */
+    source: 'system' | 'user' | 'agent' | 'api';
+    /** Unique key. Backs `uniqueIndex` on `usage_meters`. */
+    idempotencyKey: string;
+    /**
+     * Wall-clock duration of the protocol call in milliseconds, lifted
+     * directly from `event.duration_ms`. Optional in the row shape so
+     * pre-A.3 consumers writing into rows without a `duration_ms`
+     * column don't break — the sink populates it whenever the consumer's
+     * schema accepts it. A.3 of the post-v1 MCP arc.
+     */
+    durationMs?: number;
+    /**
+     * `true` when the protocol call surfaced an error (`!event.success`).
+     * Optional for the same forward-compat reason as `durationMs`.
+     * The Usage tab on `/admin/mcp` aggregates these into success-rate
+     * counts per `meterName`. A.3.
+     */
+    errored?: boolean;
+}
+/**
+ * Consumer-supplied row writer. Typically:
+ * `(row) => db.insert(usageMeters).values(row)`.
+ * Can be sync (throws on error) or async. The sink awaits thenable
+ * results and logs rejections at warn — write failures never propagate
+ * back into the MCP call that produced the event.
+ */
+export type McpUsageMeterWriter = (row: McpUsageMeterRow) => void | Promise<void>;
+export interface CreateUsageMeterSinkOptions {
+    /**
+     * Tenant / account id required by the `usage_meters.accountId NOT
+     * NULL fk` constraint. Agent-side adapters are tenant-agnostic by
+     * design — consumer binds the correct account when constructing
+     * the sink, typically one sink per authenticated call path.
+     */
+    accountId: string;
+    /**
+     * Row persistence callback. Structural so consumers can plug in
+     * raw Drizzle, a wrapped client, or a test double.
+     */
+    write: McpUsageMeterWriter;
+    /**
+     * Origin label per `usage_meters.source` check constraint. Default
+     * `'agent'`.
+     */
+    source?: McpUsageMeterRow['source'];
+    /**
+     * Custom idempotency-key generator. Default: fresh
+     * `crypto.randomUUID()` per event (safe; no retry coalescence).
+     * Supply a deterministic generator (e.g. `${requestId}:${e.kind}`)
+     * to collapse duplicate retries of one semantic call to a single
+     * row.
+     */
+    idempotencyKey?: (event: McpLogEvent) => string;
+    /**
+     * Custom row-id generator. Default: fresh UUID. Provided as a hook
+     * for consumers integrating with an existing id scheme.
+     */
+    id?: (event: McpLogEvent) => string;
+}
+/**
+ * Build an `McpEventSink` that translates Stage 6.1 protocol log
+ * events into `usage_meters` insert rows (Stage 6.2).
+ *
+ * This is the agent-adapter-lane counterpart to the hypervisor's
+ * `setUsageMeterSink()` in `@revealui/mcp`. Both paths land rows in
+ * the same `usage_meters` table. The agent-adapter path covers the
+ * four boundaries the hypervisor doesn't own
+ * (`resource.list/read`, `prompt.list/get`, `sampling.create`,
+ * `elicitation.create`) plus the agent-side `tool.call` for
+ * `McpClient`-using agents.
+ *
+ * @example
+ * ```typescript
+ * import { usageMeters } from '@revealui/db';
+ * import {
+ *   createToolsFromMcpClient,
+ *   createUsageMeterSink,
+ * } from '@revealui/ai';
+ *
+ * const tools = await createToolsFromMcpClient(client, {
+ *   namespace: 'content',
+ *   onEvent: createUsageMeterSink({
+ *     accountId: session.accountId,
+ *     write: (row) => db.insert(usageMeters).values(row),
+ *   }),
+ * });
+ * ```
+ */
+export declare function createUsageMeterSink(options: CreateUsageMeterSinkOptions): McpEventSink;
+export {};
+//# sourceMappingURL=mcp-events.d.ts.map

package/dist/tools/mcp-events.d.ts.map

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

package/dist/tools/mcp-events.js

@@ -0,0 +1,165 @@
+/**
+ * MCP protocol log channel — structured events per server-to-client call
+ * (Stage 6.1 of the MCP v1 plan).
+ *
+ * Stage 5 shipped the full agent-side MCP protocol surface
+ * (tools + resources + prompts + sampling + elicitation + progress +
+ * cancellation). Stage 6.1 adds observability: every adapter in
+ * `@revealui/ai/tools/mcp-*` grows an `onEvent?: McpEventSink` hook that
+ * fires once per protocol call with a structured summary. Consumers wire
+ * the sink to whatever aggregator they run — typically
+ * `@revealui/core/observability/logger` via `createCoreLoggerSink()`.
+ *
+ * Instrumentation lives at the agent-adapter layer by design. The
+ * hypervisor is a separate lane (Stage 6.2 lands `usage_meters` rows
+ * there, where `accountId` is in scope). Agent adapters are intentionally
+ * tenant-agnostic, so events carry no `accountId` field — the consumer
+ * adds tenant context in their sink wrapper if they need it for routing.
+ *
+ * PII note
+ * --------
+ * Errors surfaced by the server can legitimately contain user-identifying
+ * strings (e.g. "user 'alice@example.com' not found"). `error` is passed
+ * through to the sink verbatim. If your deployment's observability layer
+ * is subject to PII constraints, wrap the sink with a redactor
+ * (`redactLogContext` from `@revealui/security`) before passing it in.
+ *
+ * Params / args / content bodies are **not** included in events —
+ * observability is summary-grained by default to avoid accidentally
+ * logging credentials, prompts, or document contents.
+ */
+import { logger } from '@revealui/core/observability/logger';
+/**
+ * Build an `McpEventSink` that fans events into the central log
+ * aggregator via `@revealui/core/observability/logger`. This is the
+ * recommended default for in-process consumers (admin app, API, agent
+ * orchestration). Out-of-process consumers (CLI, remote inspector)
+ * typically construct a custom sink that forwards to their own transport.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createToolsFromMcpClient,
+ *   createCoreLoggerSink,
+ * } from '@revealui/ai';
+ *
+ * const onEvent = createCoreLoggerSink();
+ *
+ * const tools = await createToolsFromMcpClient(client, {
+ *   namespace: 'my-server',
+ *   onEvent,
+ * });
+ * ```
+ */
+export function createCoreLoggerSink(options = {}) {
+    const successLevel = options.successLevel ?? 'info';
+    return (event) => {
+        const { kind, ...rest } = event;
+        const payload = { event: kind, ...rest };
+        if (!event.success) {
+            logger.warn(`[mcp] ${kind}`, payload);
+            return;
+        }
+        if (successLevel === 'debug') {
+            logger.debug(`[mcp] ${kind}`, payload);
+        }
+        else {
+            logger.info(`[mcp] ${kind}`, payload);
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Internal helper — shared across mcp-adapter / mcp-sampling / mcp-elicitation
+// ---------------------------------------------------------------------------
+/**
+ * Invoke a sink, swallowing any thrown error. A misbehaving sink must
+ * never break the underlying MCP call — observability is best-effort.
+ * Logs the sink failure at warn so the regression is still visible.
+ *
+ * @internal
+ */
+export function emitMcpEvent(sink, event) {
+    if (!sink)
+        return;
+    try {
+        sink(event);
+    }
+    catch (error) {
+        logger.warn('[mcp] event sink threw; continuing', {
+            event: event.kind,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Map an `McpLogEvent.kind` to a `usage_meters.meterName` string.
+ * One-to-one: the dot-notation kind IS the meter name.
+ *
+ * @internal
+ */
+const METER_NAMES = {
+    'mcp.tool.call': 'mcp.tool.call',
+    'mcp.resource.list': 'mcp.resource.list',
+    'mcp.resource.read': 'mcp.resource.read',
+    'mcp.prompt.list': 'mcp.prompt.list',
+    'mcp.prompt.get': 'mcp.prompt.get',
+    'mcp.sampling.create': 'mcp.sampling.create',
+    'mcp.elicitation.create': 'mcp.elicitation.create',
+};
+/**
+ * Build an `McpEventSink` that translates Stage 6.1 protocol log
+ * events into `usage_meters` insert rows (Stage 6.2).
+ *
+ * This is the agent-adapter-lane counterpart to the hypervisor's
+ * `setUsageMeterSink()` in `@revealui/mcp`. Both paths land rows in
+ * the same `usage_meters` table. The agent-adapter path covers the
+ * four boundaries the hypervisor doesn't own
+ * (`resource.list/read`, `prompt.list/get`, `sampling.create`,
+ * `elicitation.create`) plus the agent-side `tool.call` for
+ * `McpClient`-using agents.
+ *
+ * @example
+ * ```typescript
+ * import { usageMeters } from '@revealui/db';
+ * import {
+ *   createToolsFromMcpClient,
+ *   createUsageMeterSink,
+ * } from '@revealui/ai';
+ *
+ * const tools = await createToolsFromMcpClient(client, {
+ *   namespace: 'content',
+ *   onEvent: createUsageMeterSink({
+ *     accountId: session.accountId,
+ *     write: (row) => db.insert(usageMeters).values(row),
+ *   }),
+ * });
+ * ```
+ */
+export function createUsageMeterSink(options) {
+    const source = options.source ?? 'agent';
+    const genId = options.id ?? (() => crypto.randomUUID());
+    const genKey = options.idempotencyKey ?? (() => crypto.randomUUID());
+    return (event) => {
+        const row = {
+            id: genId(event),
+            accountId: options.accountId,
+            meterName: METER_NAMES[event.kind],
+            quantity: 1,
+            periodStart: new Date(),
+            periodEnd: null,
+            source,
+            idempotencyKey: genKey(event),
+            durationMs: event.duration_ms,
+            errored: !event.success,
+        };
+        const result = options.write(row);
+        if (result && typeof result.catch === 'function') {
+            result.catch((error) => {
+                logger.warn('[mcp] usage meter write rejected; continuing', {
+                    event: event.kind,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        }
+    };
+}