@revealui/ai 0.3.0 → 0.4.0

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),
+                });
+            });
+        }
+    };
+}

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

@@ -0,0 +1,155 @@
+/**
+ * MCP Sampling — route server `sampling/createMessage` requests through
+ * the agent's configured LLM provider (Stage 5.2 of the MCP v1 plan).
+ *
+ * The MCP spec defines `sampling/createMessage` as a server-to-client
+ * request: an MCP server asks the client to invoke an LLM on its behalf.
+ * The client decides which model runs, keeps full control over costs +
+ * context, and the server gets LLM capabilities without bundling a
+ * provider. On RevealUI's Ubuntu reference stack, the target is a local
+ * Canonical Inference Snap — so sampling traffic stays on-device.
+ *
+ * This module exposes `createSamplingHandler()` — a factory that wraps
+ * the agent's `LLMProvider` (or `LLMClient`) into a handler of the
+ * structural shape `McpSamplingHandler`. Consumers pass the resulting
+ * handler to `McpClient` at construction time:
+ *
+ * @example
+ * ```typescript
+ * import { McpClient } from '@revealui/mcp/client';
+ * import { InferenceSnapsProvider, createSamplingHandler } from '@revealui/ai';
+ *
+ * const llm = new InferenceSnapsProvider({
+ *   baseURL: 'http://localhost:9090/v1',
+ *   model: 'gemma3',
+ * });
+ *
+ * const client = new McpClient({
+ *   clientInfo: { name: 'my-agent', version: '1.0.0' },
+ *   transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
+ *   samplingHandler: createSamplingHandler({
+ *     llm,
+ *     defaultModel: 'gemma3',
+ *     allowedModels: ['gemma3', 'deepseek-r1'],
+ *   }),
+ * });
+ * await client.connect();
+ * ```
+ *
+ * As with the rest of the MCP-adapter surface, this module uses
+ * structural typing to stay decoupled from `@revealui/mcp` at the
+ * package level — no runtime import of the SDK. The real
+ * `SamplingHandler` from `@revealui/mcp/client` structurally satisfies
+ * the `McpSamplingHandler` shape exported here.
+ */
+import type { LLMChatOptions, LLMResponse, Message } from '../llm/providers/base.js';
+import { type McpEventSink } from './mcp-events.js';
+/**
+ * Minimal shape needed from an LLM to serve sampling requests. Both
+ * `@revealui/ai`'s `LLMProvider` and `LLMClient` structurally satisfy this
+ * — consumers pass whichever they have. Decoupled via structural typing
+ * so test code can pass an even smaller stub.
+ */
+export interface SamplingLLM {
+    chat(messages: Message[], options?: LLMChatOptions): Promise<LLMResponse>;
+}
+/** One message in a `sampling/createMessage` request. */
+export interface McpSamplingMessage {
+    role: 'user' | 'assistant';
+    content: {
+        type: string;
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    };
+}
+/** Model preference hint (spec: `ModelHint`). */
+export interface McpModelHint {
+    name?: string;
+}
+/** Parameters of a `sampling/createMessage` request (spec-shaped subset). */
+export interface McpSamplingRequestParams {
+    messages: ReadonlyArray<McpSamplingMessage>;
+    modelPreferences?: {
+        hints?: ReadonlyArray<McpModelHint>;
+        costPriority?: number;
+        speedPriority?: number;
+        intelligencePriority?: number;
+    };
+    systemPrompt?: string;
+    includeContext?: 'none' | 'thisServer' | 'allServers';
+    temperature?: number;
+    maxTokens: number;
+    stopSequences?: ReadonlyArray<string>;
+    metadata?: Record<string, unknown>;
+}
+/** Result of a `sampling/createMessage` request (spec-shaped subset). */
+export interface McpSamplingResult {
+    model: string;
+    stopReason?: 'maxTokens' | 'endTurn' | 'stopSequence' | string;
+    role: 'user' | 'assistant';
+    content: {
+        type: 'text';
+        text: string;
+    };
+}
+/** Structural shape of the handler — matches `SamplingHandler` from `@revealui/mcp/client`. */
+export type McpSamplingHandler = (params: McpSamplingRequestParams) => Promise<McpSamplingResult>;
+export interface CreateSamplingHandlerOptions {
+    /** LLM to route sampling requests through. */
+    llm: SamplingLLM;
+    /**
+     * Allowlist of models that servers may request via `modelPreferences.hints`.
+     * Hint names outside the allowlist are filtered out of selection. When
+     * unset, every hint is accepted.
+     *
+     * **Advisory, not enforced.** `@revealui/ai`'s current `LLMProvider`
+     * shape fixes the model at provider construction — this handler does
+     * NOT re-route per-request to different providers. The resolved model
+     * is reported back to the server in `result.model` (so the server
+     * knows what actually ran) but the call always goes to `options.llm`.
+     * For per-model routing, the consumer wires their own multiplexer
+     * (e.g. via `selectModel` + an `LLMClient` that internally dispatches).
+     */
+    allowedModels?: ReadonlyArray<string>;
+    /**
+     * Label used for `result.model` when no hint matches (or no hints).
+     * Purely for reporting. When omitted, `'unknown'` is reported.
+     */
+    defaultModel?: string;
+    /**
+     * Custom model selector. Overrides the default hint-matching logic.
+     * Return `undefined` to fall back to `defaultModel`.
+     */
+    selectModel?: (hints: ReadonlyArray<McpModelHint>, options: {
+        allowedModels?: ReadonlyArray<string>;
+        defaultModel?: string;
+    }) => string | undefined;
+    /**
+     * Observability hook invoked before each sampling call. Useful for
+     * metering / audit trails / cost tracking.
+     */
+    onSamplingRequest?: (info: {
+        model: string;
+        messageCount: number;
+        maxTokens: number;
+        systemPrompt?: string;
+    }) => void;
+    /**
+     * Protocol-level observability sink (Stage 6.1). Fires once per
+     * `sampling/createMessage` call (after the LLM responds, or on
+     * failure) with `{ kind: 'mcp.sampling.create', model, messageCount,
+     * maxTokens, duration_ms, success, error? }`. Set `namespace` when
+     * the handler is attached to a single-server `McpClient` so events
+     * can be grouped in the aggregator.
+     */
+    onEvent?: McpEventSink;
+    /**
+     * Optional server identifier included in emitted events. Leave unset
+     * when the handler is shared across multiple servers — consumer's
+     * sink wrapper can fill in namespace from call-site context.
+     */
+    namespace?: string;
+}
+export declare function createSamplingHandler(options: CreateSamplingHandlerOptions): McpSamplingHandler;
+//# sourceMappingURL=mcp-sampling.d.ts.map

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

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

package/dist/tools/mcp-sampling.js

@@ -0,0 +1,171 @@
+/**
+ * MCP Sampling — route server `sampling/createMessage` requests through
+ * the agent's configured LLM provider (Stage 5.2 of the MCP v1 plan).
+ *
+ * The MCP spec defines `sampling/createMessage` as a server-to-client
+ * request: an MCP server asks the client to invoke an LLM on its behalf.
+ * The client decides which model runs, keeps full control over costs +
+ * context, and the server gets LLM capabilities without bundling a
+ * provider. On RevealUI's Ubuntu reference stack, the target is a local
+ * Canonical Inference Snap — so sampling traffic stays on-device.
+ *
+ * This module exposes `createSamplingHandler()` — a factory that wraps
+ * the agent's `LLMProvider` (or `LLMClient`) into a handler of the
+ * structural shape `McpSamplingHandler`. Consumers pass the resulting
+ * handler to `McpClient` at construction time:
+ *
+ * @example
+ * ```typescript
+ * import { McpClient } from '@revealui/mcp/client';
+ * import { InferenceSnapsProvider, createSamplingHandler } from '@revealui/ai';
+ *
+ * const llm = new InferenceSnapsProvider({
+ *   baseURL: 'http://localhost:9090/v1',
+ *   model: 'gemma3',
+ * });
+ *
+ * const client = new McpClient({
+ *   clientInfo: { name: 'my-agent', version: '1.0.0' },
+ *   transport: { kind: 'streamable-http', url: 'https://example.com/mcp' },
+ *   samplingHandler: createSamplingHandler({
+ *     llm,
+ *     defaultModel: 'gemma3',
+ *     allowedModels: ['gemma3', 'deepseek-r1'],
+ *   }),
+ * });
+ * await client.connect();
+ * ```
+ *
+ * As with the rest of the MCP-adapter surface, this module uses
+ * structural typing to stay decoupled from `@revealui/mcp` at the
+ * package level — no runtime import of the SDK. The real
+ * `SamplingHandler` from `@revealui/mcp/client` structurally satisfies
+ * the `McpSamplingHandler` shape exported here.
+ */
+import { emitMcpEvent } from './mcp-events.js';
+export function createSamplingHandler(options) {
+    const { llm, allowedModels, defaultModel, selectModel, onSamplingRequest, onEvent, namespace } = options;
+    return async (params) => {
+        const model = resolveModel(params.modelPreferences?.hints, {
+            allowedModels,
+            defaultModel,
+            selectModel,
+        });
+        const messages = convertToLLMMessages(params);
+        const reportedModel = model ?? 'unknown';
+        onSamplingRequest?.({
+            model: reportedModel,
+            messageCount: params.messages.length,
+            maxTokens: params.maxTokens,
+            ...(params.systemPrompt !== undefined ? { systemPrompt: params.systemPrompt } : {}),
+        });
+        // `stopSequences` is NOT passed — the current `LLMChatOptions` doesn't
+        // expose it (per-provider inconsistency). The MCP spec treats
+        // stopSequences as advisory, so omitting is compliant. A future
+        // provider-interface extension can wire this through.
+        const chatOptions = {
+            maxTokens: params.maxTokens,
+            ...(params.temperature !== undefined ? { temperature: params.temperature } : {}),
+        };
+        const started = Date.now();
+        try {
+            const response = await llm.chat(messages, chatOptions);
+            emitMcpEvent(onEvent, {
+                kind: 'mcp.sampling.create',
+                ...(namespace !== undefined ? { namespace } : {}),
+                model: reportedModel,
+                messageCount: params.messages.length,
+                maxTokens: params.maxTokens,
+                duration_ms: Date.now() - started,
+                success: true,
+            });
+            const stopReason = mapFinishReason(response.finishReason);
+            const result = {
+                model: reportedModel,
+                role: 'assistant',
+                content: {
+                    type: 'text',
+                    text: response.content,
+                },
+            };
+            if (stopReason !== undefined) {
+                result.stopReason = stopReason;
+            }
+            return result;
+        }
+        catch (error) {
+            emitMcpEvent(onEvent, {
+                kind: 'mcp.sampling.create',
+                ...(namespace !== undefined ? { namespace } : {}),
+                model: reportedModel,
+                messageCount: params.messages.length,
+                maxTokens: params.maxTokens,
+                duration_ms: Date.now() - started,
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveModel(hints, options) {
+    // Custom selector, when present, is the final say — no hint-matching
+    // fallback. Returning undefined means "I don't have a pick; use the
+    // default model label."
+    if (options.selectModel) {
+        const chosen = options.selectModel(hints ?? [], {
+            ...(options.allowedModels !== undefined ? { allowedModels: options.allowedModels } : {}),
+            ...(options.defaultModel !== undefined ? { defaultModel: options.defaultModel } : {}),
+        });
+        return chosen ?? options.defaultModel;
+    }
+    // Default logic: first hint whose name is in the allowlist (or any hint if
+    // no allowlist). Unknown / non-matching hints are ignored. The MCP spec
+    // treats hints as advisory only, so rejecting all of them and falling
+    // through to `defaultModel` is compliant.
+    if (hints && hints.length > 0) {
+        for (const hint of hints) {
+            if (!hint.name)
+                continue;
+            if (options.allowedModels && !options.allowedModels.includes(hint.name))
+                continue;
+            return hint.name;
+        }
+    }
+    return options.defaultModel;
+}
+/**
+ * Convert the MCP `sampling/createMessage` message array (and optional
+ * `systemPrompt`) into the agent's `Message[]` shape. Text content is
+ * passed through verbatim; non-text parts throw so the server gets a
+ * clear protocol error rather than a silently-dropped payload.
+ */
+function convertToLLMMessages(params) {
+    const out = [];
+    if (typeof params.systemPrompt === 'string' && params.systemPrompt.length > 0) {
+        out.push({ role: 'system', content: params.systemPrompt });
+    }
+    for (const msg of params.messages) {
+        if (msg.content.type !== 'text' || typeof msg.content.text !== 'string') {
+            throw new Error(`sampling/createMessage: non-text message content is not yet supported (got type=${msg.content.type}). Stage 5.2 ships text-only sampling.`);
+        }
+        out.push({ role: msg.role, content: msg.content.text });
+    }
+    return out;
+}
+function mapFinishReason(reason) {
+    switch (reason) {
+        case 'stop':
+            return 'endTurn';
+        case 'length':
+            return 'maxTokens';
+        case 'tool_calls':
+        case 'content_filter':
+            return reason;
+        default:
+            return undefined;
+    }
+}

package/dist/tools/ticket-tools.d.ts

@@ -7,6 +7,14 @@
  *
  * These are injected by createTicketTools() and are always paired with
  * admin tools so agents can act on content AND report back through the ticket.
+ *
+ * Retry-safe ids (CR8-P2-01 phase C prerequisite): when a `dispatchId`
+ * is provided, comment ids are derived deterministically from
+ * (dispatchId, call-ordinal). A crash-and-resume of the same dispatch
+ * re-issues tool calls in the same order and generates the same ids,
+ * letting the persistence layer's primary-key constraint dedupe
+ * naturally. When `dispatchId` is omitted, ids remain random (the
+ * caller's `TicketMutationClient` picks its own id).
  */
 import type { Tool } from './base.js';
 /**
@@ -22,10 +30,35 @@ export interface TicketMutationClient {
         id: string;
         status: string;
     } | null>;
-    createComment(ticketId: string, body: Record<string, unknown>): Promise<{
+    /**
+     * Create a comment on a ticket. When `options.id` is provided the
+     * implementation MUST use that id (enables deterministic replay under
+     * retry); when omitted the implementation picks its own id (typically
+     * a random UUID for backward compatibility).
+     */
+    createComment(ticketId: string, body: Record<string, unknown>, options?: {
+        id?: string;
+    }): Promise<{
         id: string;
         ticketId: string;
     } | null | undefined>;
 }
-export declare function createTicketTools(ticketId: string, client: TicketMutationClient): Tool[];
+export interface CreateTicketToolsOptions {
+    /**
+     * When set, tool calls that write rows (e.g. add_ticket_comment) use
+     * this as the seed for deterministic id derivation. Pair with the
+     * durable work queue's jobId so crash-resume produces the same ids
+     * and the DB's PK constraint dedupes duplicate attempts.
+     *
+     * When omitted, ids remain random (existing behavior).
+     */
+    dispatchId?: string;
+}
+/**
+ * Derive a deterministic, URL-safe comment id from (dispatchId,
+ * callOrdinal). Exported so the handler side can assert that the same
+ * inputs produce the same id (e.g. during crash-sim tests).
+ */
+export declare function deriveCommentId(dispatchId: string, callOrdinal: number): string;
+export declare function createTicketTools(ticketId: string, client: TicketMutationClient, options?: CreateTicketToolsOptions): Tool[];
 //# sourceMappingURL=ticket-tools.d.ts.map

package/dist/tools/ticket-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ticket-tools.d.ts","sourceRoot":"","sources":["../../src/tools/ticket-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GACA,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAElD,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,IAAI,EAAE,CAgExF"}
+{"version":3,"file":"ticket-tools.d.ts","sourceRoot":"","sources":["../../src/tools/ticket-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAc,MAAM,WAAW,CAAC;AAElD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;QACJ,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GACA,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAElD;;;;;OAKG;IACH,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;CACjE;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE,wBAA6B,GACrC,IAAI,EAAE,CAgFR"}

package/dist/tools/ticket-tools.js

@@ -7,9 +7,35 @@
  *
  * These are injected by createTicketTools() and are always paired with
  * admin tools so agents can act on content AND report back through the ticket.
+ *
+ * Retry-safe ids (CR8-P2-01 phase C prerequisite): when a `dispatchId`
+ * is provided, comment ids are derived deterministically from
+ * (dispatchId, call-ordinal). A crash-and-resume of the same dispatch
+ * re-issues tool calls in the same order and generates the same ids,
+ * letting the persistence layer's primary-key constraint dedupe
+ * naturally. When `dispatchId` is omitted, ids remain random (the
+ * caller's `TicketMutationClient` picks its own id).
  */
+import { createHash } from 'node:crypto';
 import { z } from 'zod/v4';
-export function createTicketTools(ticketId, client) {
+/**
+ * Derive a deterministic, URL-safe comment id from (dispatchId,
+ * callOrdinal). Exported so the handler side can assert that the same
+ * inputs produce the same id (e.g. during crash-sim tests).
+ */
+export function deriveCommentId(dispatchId, callOrdinal) {
+    const hash = createHash('sha256').update(`${dispatchId}:comment:${callOrdinal}`).digest('hex');
+    // 32 hex chars (~128 bits) is plenty for a PK and keeps the column
+    // narrower than a full hex digest.
+    return `cmt_${hash.slice(0, 32)}`;
+}
+export function createTicketTools(ticketId, client, options = {}) {
+    // Per-instance call counter. Because createTicketTools() is invoked
+    // fresh inside each dispatcher.dispatch() call, the ordinal is
+    // stable across the agentic loop of a single dispatch but reset for
+    // the next dispatch — which is exactly what retry-safe id derivation
+    // needs.
+    let commentOrdinal = 0;
     const updateStatusTool = {
         name: 'update_ticket_status',
         description: 'Update the status of the current ticket. Call this when work is complete (status="done") or if you cannot proceed (status="blocked"). Valid statuses: open, in_progress, done, blocked, cancelled.',
@@ -47,12 +73,16 @@ export function createTicketTools(ticketId, client) {
         }),
         async execute(params) {
             const { text } = params;
+            const ordinal = commentOrdinal++;
+            const derivedId = options.dispatchId
+                ? deriveCommentId(options.dispatchId, ordinal)
+                : undefined;
             try {
                 const body = {
                     type: 'doc',
                     content: [{ type: 'paragraph', content: [{ type: 'text', text }] }],
                 };
-                const comment = await client.createComment(ticketId, body);
+                const comment = await client.createComment(ticketId, body, derivedId ? { id: derivedId } : undefined);
                 if (!comment) {
                     return { success: false, error: 'Failed to create comment' };
                 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@revealui/ai",
-  "version": "0.3.0",
-  "description": "[Pro] AI system for RevealUI - memory, LLM, orchestration, and tools",
+  "version": "0.4.0",
+  "description": "AI runtime for agent-driven products — agents, memory, LLM providers (Inference Snaps, Ollama, OpenAI-compatible), tools, and orchestration. Anthropic-SDK-free.",
   "keywords": [
     "agent",
     "ai",
@@ -23,20 +23,22 @@
   },
   "license": "FSL-1.1-MIT",
   "dependencies": {
-    "lru-cache": "^11.3.5",
+    "lru-cache": "^11.3.6",
     "zod": "^4.3.6",
-    "@revealui/contracts": "1.4.0",
+    "@revealui/contracts": "0.4.0",
     "@revealui/core": "0.6.0",
-    "@revealui/db": "0.4.0"
+    "@revealui/db": "0.4.0",
+    "@revealui/resilience": "0.2.4"
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.4.4",
     "@testing-library/react": "^16.3.2",
-    "@vitest/coverage-v8": "^4.1.3",
-    "jsdom": "29.0.2",
-    "react": "^19.2.5",
-    "react-dom": "^19.2.5",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.3",
+    "@vitest/coverage-v8": "^4.1.5",
+    "jsdom": "29.1.1",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5",
     "@revealui/dev": "0.1.0"
   },
   "engines": {

package/dist/llm/providers/vultr.d.ts

@@ -1,18 +0,0 @@
-/**
- * Vultr Inference Provider
- *
- * Implements the LLMProvider interface for Vultr Serverless Inference API
- */
-import type { Embedding, LLMChatOptions, LLMChunk, LLMEmbedOptions, LLMProvider, LLMProviderConfig, LLMResponse, LLMStreamOptions, Message } from './base.js';
-export interface VultrProviderConfig extends LLMProviderConfig {
-    subscriptionId?: string;
-}
-export declare class VultrProvider implements LLMProvider {
-    private config;
-    private baseURL;
-    constructor(config: VultrProviderConfig);
-    chat(messages: Message[], options?: LLMChatOptions): Promise<LLMResponse>;
-    embed(text: string | string[], options?: LLMEmbedOptions): Promise<Embedding | Embedding[]>;
-    stream(messages: Message[], options?: LLMStreamOptions): AsyncIterable<LLMChunk>;
-}
-//# sourceMappingURL=vultr.d.ts.map