@revealui/ai 0.3.0 → 0.4.0

package/dist/memory/services/reconciliation-service.js

@@ -0,0 +1,127 @@
+/**
+ * Reconciliation Service - Fact resolution for multi-agent memory.
+ *
+ * Reads shared facts from a coordination session, groups related facts,
+ * deduplicates, and resolves contradictions. Produces reconciled memories
+ * for Layer 3.
+ *
+ * Layer 3 of the multi-agent shared memory architecture.
+ *
+ * LICENSING BOUNDARY:
+ * - `reconcileHeuristic()` is the production path — no external API calls,
+ *   safe for all tiers including free customers.
+ * - `buildReconciliationPrompt()` and `parseReconciliationResponse()` are
+ *   reference implementations for internal/developer use only. They build
+ *   a prompt string but DO NOT call any LLM API. If wired to an LLM provider,
+ *   the caller is responsible for API pricing and usage compliance.
+ * - Customer-facing reconciliation MUST use the heuristic path or a
+ *   self-hosted model (e.g. Ollama). Do not proxy third-party LLM APIs
+ *   to end users without a commercial API agreement with the provider.
+ */
+/**
+ * Build the reconciliation prompt for an LLM.
+ * The prompt asks the model to analyze facts from multiple agents and
+ * produce a structured reconciliation result.
+ */
+export function buildReconciliationPrompt(facts, scratchpadContent) {
+    const factList = facts
+        .map((f, i) => `${i + 1}. [${f.factType}] (agent: ${f.agentId}, confidence: ${f.confidence}) ${f.content}` +
+        (f.tags.length > 0 ? ` [tags: ${f.tags.join(', ')}]` : ''))
+        .join('\n');
+    const scratchpadSection = scratchpadContent
+        ? `\n\nShared scratchpad content:\n${JSON.stringify(scratchpadContent, null, 2)}`
+        : '';
+    return `You are reconciling discoveries from multiple AI agents working on the same task.
+
+Facts discovered by agents:
+${factList}
+${scratchpadSection}
+
+Analyze these facts and produce a JSON response with:
+1. "canonicalFacts": Array of canonical truths. For each:
+   - "content": The canonical fact statement
+   - "type": One of: fact, preference, decision, warning, skill
+   - "sourceFactIds": Array of source fact indices (1-based) that support this
+   - "confidence": 0-1 confidence score
+2. "contradictions": Array of contradictions found. For each:
+   - "factIndices": The conflicting fact indices
+   - "description": What contradicts
+   - "resolution": How to resolve (which is correct and why)
+3. "duplicates": Array of arrays of fact indices that say the same thing
+4. "summary": One-sentence summary of the reconciliation
+
+Rules:
+- Merge duplicate facts into one canonical fact
+- When facts contradict, determine which is correct based on confidence and specificity
+- Preserve the most specific and actionable version of each fact
+- Do not invent facts not supported by the inputs
+
+Respond with ONLY valid JSON, no markdown fencing.`;
+}
+/**
+ * Parse the LLM response into a structured reconciliation result.
+ * Maps 1-based fact indices back to actual fact IDs.
+ */
+export function parseReconciliationResponse(response, facts) {
+    const parsed = JSON.parse(response);
+    const mapIndices = (indices) => indices
+        .filter((i) => i >= 1 && i <= facts.length)
+        .map((i) => facts[i - 1]?.id)
+        .filter((id) => id !== undefined);
+    return {
+        canonicalFacts: (parsed.canonicalFacts ?? []).map((cf) => ({
+            content: cf.content,
+            type: cf.type,
+            sourceFactIds: mapIndices(cf.sourceFactIds ?? []),
+            confidence: cf.confidence ?? 1.0,
+        })),
+        contradictions: (parsed.contradictions ?? []).map((c) => ({
+            factIds: mapIndices(c.factIndices ?? []),
+            description: c.description ?? '',
+            resolution: c.resolution ?? '',
+        })),
+        duplicates: (parsed.duplicates ?? []).map((group) => mapIndices(group)),
+        summary: parsed.summary ?? 'Reconciliation complete.',
+    };
+}
+/**
+ * Simple heuristic reconciliation (no LLM required).
+ * Deduplicates by normalized content and groups by type.
+ * Use this as a fallback when no LLM provider is configured.
+ */
+export function reconcileHeuristic(facts) {
+    const seen = new Map();
+    const canonicalFacts = [];
+    const duplicates = [];
+    for (const fact of facts) {
+        const normalized = fact.content.toLowerCase().trim();
+        const existing = seen.get(normalized);
+        if (existing) {
+            existing.push(fact.id);
+        }
+        else {
+            seen.set(normalized, [fact.id]);
+        }
+    }
+    for (const [, ids] of seen) {
+        if (ids.length > 1) {
+            duplicates.push(ids);
+        }
+        const sourceFact = facts.find((f) => f.id === ids[0]);
+        if (sourceFact) {
+            const memoryType = sourceFact.factType === 'bug' || sourceFact.factType === 'warning' ? 'warning' : 'fact';
+            canonicalFacts.push({
+                content: sourceFact.content,
+                type: memoryType,
+                sourceFactIds: ids,
+                confidence: sourceFact.confidence,
+            });
+        }
+    }
+    return {
+        canonicalFacts,
+        contradictions: [],
+        duplicates,
+        summary: `Reconciled ${facts.length} facts into ${canonicalFacts.length} canonical facts (${duplicates.length} duplicates).`,
+    };
+}

package/dist/memory/utils/sql-helpers.d.ts

@@ -1,14 +1,21 @@
 /**
- * SQL Helper Utilities
+ * Memory-layer query helpers
  *
- * Provides type-safe raw SQL query helpers to work around Neon HTTP driver
- * compatibility issues with Drizzle's relational query builder.
+ * Small, typed helpers for lookups performed by the agent-memory persistence
+ * layer. Every helper returns a Drizzle-inferred row shape — no manual
+ * snake_case → camelCase transformation needed.
  *
- * These helpers use Drizzle's sql tagged template for type safety and
- * SQL injection prevention.
+ * History: originally written with `db.execute(sql`…`)` + hand-rolled result
+ * unwrapping as a defensive posture against an early Neon HTTP driver
+ * incompatibility with Drizzle's relational query builder (`db.query.*`).
+ * Ported to the core query builder (`db.select().from(…).where(…).limit(1)`)
+ * in Phase 6.1 — the same callers already use `.update()` and `.insert()`
+ * against the same tables on the same Database client without issue, and the
+ * core builder is a different code path from the relational one.
  */
 import type { NodeIdMappingsRow } from '@revealui/contracts/generated';
 import type { Database } from '@revealui/db/client';
+import type { AgentContext, User } from '@revealui/db/schema';
 /**
  * Finds a node ID mapping by hash (primary key).
  *
@@ -18,7 +25,7 @@ import type { Database } from '@revealui/db/client';
  */
 export declare function findNodeIdMappingByHash(db: Database, hash: string): Promise<NodeIdMappingsRow | undefined>;
 /**
- * Finds a node ID mapping by entity ID and type.
+ * Finds a node ID mapping by entity type + entity ID.
  *
  * @param db - Database client
  * @param entityType - Type of entity ('session' or 'user')
@@ -27,32 +34,19 @@ export declare function findNodeIdMappingByHash(db: Database, hash: string): Pro
  */
 export declare function findNodeIdMappingByEntity(db: Database, entityType: 'session' | 'user', entityId: string): Promise<NodeIdMappingsRow | undefined>;
 /**
- * Finds an agent context by CRDT ID (returns raw database record format).
+ * Finds an agent context by CRDT ID.
  *
  * @param db - Database client
  * @param crdtId - CRDT identifier (format: sessionId:agentId)
- * @returns Raw database context record or undefined if not found
+ * @returns Agent context row or undefined if not found
  */
-export declare function findAgentContextById(db: Database, crdtId: string): Promise<{
-    id: string;
-    version: number;
-    sessionId: string;
-    agentId: string;
-    context: unknown;
-    priority: number | null;
-    embedding: number[] | null;
-    createdAt: Date;
-    updatedAt: Date;
-} | undefined>;
+export declare function findAgentContextById(db: Database, crdtId: string): Promise<AgentContext | undefined>;
 /**
- * Finds a user by ID.
+ * Finds a user by ID, returning only the columns the memory layer needs.
  *
  * @param db - Database client
  * @param userId - User identifier
- * @returns User record or undefined if not found
+ * @returns User record (id + preferences) or undefined if not found
  */
-export declare function findUserById(db: Database, userId: string): Promise<{
-    id: string;
-    preferences: unknown;
-} | undefined>;
+export declare function findUserById(db: Database, userId: string): Promise<Pick<User, 'id' | 'preferences'> | undefined>;
 //# sourceMappingURL=sql-helpers.d.ts.map

package/dist/memory/utils/sql-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sql-helpers.d.ts","sourceRoot":"","sources":["../../../src/memory/utils/sql-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AA8BpD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CA8BxC;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,SAAS,GAAG,MAAM,EAC9B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CA6BxC;AAMD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CACN;IACE,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB,GACD,SAAS,CACZ,CAwBA;AAMD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAAC,CAU3D"}
+{"version":3,"file":"sql-helpers.d.ts","sourceRoot":"","sources":["../../../src/memory/utils/sql-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAQ9D;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAGxC;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,QAAQ,EACZ,UAAU,EAAE,SAAS,GAAG,MAAM,EAC9B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAOxC;AAMD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAGnC;AAMD;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,aAAa,CAAC,GAAG,SAAS,CAAC,CAOvD"}

package/dist/memory/utils/sql-helpers.js

@@ -1,22 +1,20 @@
 /**
- * SQL Helper Utilities
+ * Memory-layer query helpers
  *
- * Provides type-safe raw SQL query helpers to work around Neon HTTP driver
- * compatibility issues with Drizzle's relational query builder.
+ * Small, typed helpers for lookups performed by the agent-memory persistence
+ * layer. Every helper returns a Drizzle-inferred row shape — no manual
+ * snake_case → camelCase transformation needed.
  *
- * These helpers use Drizzle's sql tagged template for type safety and
- * SQL injection prevention.
+ * History: originally written with `db.execute(sql`…`)` + hand-rolled result
+ * unwrapping as a defensive posture against an early Neon HTTP driver
+ * incompatibility with Drizzle's relational query builder (`db.query.*`).
+ * Ported to the core query builder (`db.select().from(…).where(…).limit(1)`)
+ * in Phase 6.1 — the same callers already use `.update()` and `.insert()`
+ * against the same tables on the same Database client without issue, and the
+ * core builder is a different code path from the relational one.
  */
-import { sql } from 'drizzle-orm';
-const getRows = (result) => {
-    if (Array.isArray(result)) {
-        return result;
-    }
-    if (result && typeof result === 'object' && Array.isArray(result.rows)) {
-        return result.rows;
-    }
-    return [];
-};
+import { agentContexts, nodeIdMappings, users } from '@revealui/db/schema';
+import { and, eq } from 'drizzle-orm';
 // =============================================================================
 // Node ID Mappings Queries
 // =============================================================================
@@ -28,27 +26,11 @@ const getRows = (result) => {
  * @returns Node ID mapping or undefined if not found
  */
 export async function findNodeIdMappingByHash(db, hash) {
-    const result = await db.execute(sql `SELECT id, entity_type, entity_id, node_id, created_at, updated_at
-        FROM node_id_mappings
-        WHERE id = ${hash}
-        LIMIT 1`);
-    // Handle different result formats (Neon HTTP vs direct Postgres)
-    const rows = getRows(result);
-    if (!rows[0])
-        return undefined;
-    // Transform snake_case to camelCase to match NodeIdMappingsRow type
-    const row = rows[0];
-    return {
-        id: row.id,
-        entityType: row.entity_type,
-        entityId: row.entity_id,
-        nodeId: row.node_id,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-    };
+    const [row] = await db.select().from(nodeIdMappings).where(eq(nodeIdMappings.id, hash)).limit(1);
+    return row;
 }
 /**
- * Finds a node ID mapping by entity ID and type.
+ * Finds a node ID mapping by entity type + entity ID.
  *
  * @param db - Database client
  * @param entityType - Type of entity ('session' or 'user')
@@ -56,71 +38,42 @@ export async function findNodeIdMappingByHash(db, hash) {
  * @returns Node ID mapping or undefined if not found
  */
 export async function findNodeIdMappingByEntity(db, entityType, entityId) {
-    const result = await db.execute(sql `SELECT id, entity_type, entity_id, node_id, created_at, updated_at
-        FROM node_id_mappings
-        WHERE entity_type = ${entityType} AND entity_id = ${entityId}
-        LIMIT 1`);
-    const rows = getRows(result);
-    if (!rows[0])
-        return undefined;
-    // Transform snake_case to camelCase to match NodeIdMappingsRow type
-    const row = rows[0];
-    return {
-        id: row.id,
-        entityType: row.entity_type,
-        entityId: row.entity_id,
-        nodeId: row.node_id,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-    };
+    const [row] = await db
+        .select()
+        .from(nodeIdMappings)
+        .where(and(eq(nodeIdMappings.entityType, entityType), eq(nodeIdMappings.entityId, entityId)))
+        .limit(1);
+    return row;
 }
 // =============================================================================
 // Agent Contexts Queries
 // =============================================================================
 /**
- * Finds an agent context by CRDT ID (returns raw database record format).
+ * Finds an agent context by CRDT ID.
  *
  * @param db - Database client
  * @param crdtId - CRDT identifier (format: sessionId:agentId)
- * @returns Raw database context record or undefined if not found
+ * @returns Agent context row or undefined if not found
  */
 export async function findAgentContextById(db, crdtId) {
-    const result = await db.execute(sql `SELECT id, version, session_id, agent_id, context, priority, 
-               embedding, created_at, updated_at
-        FROM agent_contexts 
-        WHERE id = ${crdtId} 
-        LIMIT 1`);
-    const rows = getRows(result);
-    if (!rows[0])
-        return undefined;
-    const row = rows[0];
-    return {
-        id: row.id,
-        version: row.version || 1,
-        sessionId: row.session_id,
-        agentId: row.agent_id,
-        context: row.context || {},
-        priority: row.priority || 0.5,
-        embedding: row.embedding,
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-    };
+    const [row] = await db.select().from(agentContexts).where(eq(agentContexts.id, crdtId)).limit(1);
+    return row;
 }
 // =============================================================================
 // Users Queries
 // =============================================================================
 /**
- * Finds a user by ID.
+ * Finds a user by ID, returning only the columns the memory layer needs.
  *
  * @param db - Database client
  * @param userId - User identifier
- * @returns User record or undefined if not found
+ * @returns User record (id + preferences) or undefined if not found
  */
 export async function findUserById(db, userId) {
-    const result = await db.execute(sql `SELECT id, preferences 
-        FROM users 
-        WHERE id = ${userId} 
-        LIMIT 1`);
-    const rows = getRows(result);
-    return rows[0];
+    const [row] = await db
+        .select({ id: users.id, preferences: users.preferences })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    return row;
 }

package/dist/memory/vector/vector-memory-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vector-memory-service.d.ts","sourceRoot":"","sources":["../../../src/memory/vector/vector-memory-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAM9D,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,GAAG,CAAmD;IAC9D,OAAO,CAAC,OAAO,CAAiD;IAEhE;;;OAGG;IACH,OAAO,KAAK,EAAE,GAKb;IAED,+DAA+D;IAC/D,OAAO,KAAK,MAAM,GAKjB;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CACjB,cAAc,EAAE,MAAM,EAAE,EACxB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2GhC;;;;;OAKG;IACG,MAAM,CACV,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,GAAG,YAAY,CAAC,GAAG;QAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GACA,OAAO,CAAC,WAAW,CAAC;IA4EvB;;;;;;OAMG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC,GACtD,OAAO,CAAC,WAAW,CAAC;IAyEvB;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1C;;;;;OAKG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CA8CvD"}
+{"version":3,"file":"vector-memory-service.d.ts","sourceRoot":"","sources":["../../../src/memory/vector/vector-memory-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAM9D,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,GAAG,CAAmD;IAC9D,OAAO,CAAC,OAAO,CAAiD;IAEhE;;;OAGG;IACH,OAAO,KAAK,EAAE,GAKb;IAED,+DAA+D;IAC/D,OAAO,KAAK,MAAM,GAKjB;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CACjB,cAAc,EAAE,MAAM,EAAE,EACxB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA2GhC;;;;;OAKG;IACG,MAAM,CACV,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,GAAG,YAAY,CAAC,GAAG;QAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,GACA,OAAO,CAAC,WAAW,CAAC;IA4EvB;;;;;;OAMG;IACG,MAAM,CACV,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,WAAW,CAAC,CAAC,GACtD,OAAO,CAAC,WAAW,CAAC;IA+EvB;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK1C;;;;;OAKG;IACG,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;CA8CvD"}

package/dist/memory/vector/vector-memory-service.js

@@ -14,7 +14,7 @@
  */
 import { getRestClient, getVectorClient } from '@revealui/db/client';
 import { agentMemories } from '@revealui/db/schema';
-import { safeVectorInsert } from '@revealui/db/validation';
+import { assertCrossDbRefs, safeVectorInsert } from '@revealui/db/validation';
 import { and, eq, sql } from 'drizzle-orm';
 /**
  * Vector Memory Service for semantic search operations.
@@ -257,6 +257,11 @@ export class VectorMemoryService {
         if (updates.metadata?.custom?.agentId !== undefined) {
             updateData.agentId = updates.metadata.custom.agentId || null;
         }
+        // Validate cross-DB references if siteId is changing
+        const newSiteId = updateData.siteId;
+        if (newSiteId) {
+            await assertCrossDbRefs(this.restDb, { siteId: newSiteId });
+        }
         const result = await this.db
             .update(agentMemories)
             .set(updateData)

package/dist/orchestration/runtime.d.ts

@@ -6,7 +6,7 @@
 import type { LLMClient } from '../llm/client.js';
 import type { AgentSkillProvider } from '../skills/integration/agent-skill-provider.js';
 import type { ApprovalCallback } from '../tools/base.js';
-import type { MCPToolSource } from '../tools/mcp-adapter.js';
+import type { MCPToolSource, McpClientLike } from '../tools/mcp-adapter.js';
 import type { Agent, AgentResult, Task } from './agent.js';
 /**
  * Controls how much of the model's token budget is allocated to internal reasoning.
@@ -39,8 +39,37 @@ export interface RuntimeConfig {
      * Optional MCP Hypervisor (or any MCPToolSource). When provided, tools from
      * all healthy MCP servers are merged into the agent's tool set before each
      * task execution. Pass an MCPHypervisor from @revealui/mcp.
+     *
+     * @deprecated Prefer `mcpClients` (Stage 5.1a). The hypervisor path doesn't
+     *   expose the full MCP protocol surface (resources, prompts, sampling,
+     *   elicitation). Standard `McpClient` instances do. This field stays for
+     *   backwards compatibility and will keep working until a future major.
      */
     mcpToolSource?: MCPToolSource;
+    /**
+     * Optional set of standard MCP clients (Stage 5.1a). When provided, each
+     * client's tools are listed and merged into the agent's tool set before
+     * each task. Tool names are namespaced as `mcp_<name>__<toolName>` so
+     * multiple clients can coexist without collisions. Consumers construct the
+     * client (stdio / Streamable HTTP + OAuth) and pre-connect it before
+     * passing it here. The runtime does NOT own client lifecycle.
+     *
+     * @example
+     * ```typescript
+     * import { McpClient } from '@revealui/mcp/client';
+     *
+     * const contentClient = new McpClient({ ... });
+     * await contentClient.connect();
+     *
+     * const runtime = new AgentRuntime({
+     *   mcpClients: [{ name: 'content', client: contentClient }],
+     * });
+     * ```
+     */
+    mcpClients?: ReadonlyArray<{
+        name: string;
+        client: McpClientLike;
+    }>;
     /**
      * Optional skill provider. When set, activated skills are injected into the
      * system prompt before the first LLM call, giving the agent contextual

package/dist/orchestration/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,kBAAkB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG7D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAWpF,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,gCAAgC,EAAE,SAAS,CAAC;IAC/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,cAAc,CAAgD;IACtE,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,GAAE,aAAkB;IAyBtC;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqBzE,OAAO;IAqOrB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI7B;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAc9E;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B9B;;OAEG;IACH,SAAS,IAAI;QACX,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB;CAOF"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,kBAAkB,CAAC;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAG5E,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAWpF,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IACpE;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,gCAAgC,EAAE,SAAS,CAAC;IAC/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,cAAc,CAAgD;IACtE,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,GAAE,aAAkB;IA0BtC;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqBzE,OAAO;IAoPrB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI7B;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAc9E;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B9B;;OAEG;IACH,SAAS,IAAI;QACX,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB;CAOF"}

package/dist/orchestration/runtime.js

@@ -7,7 +7,7 @@ import { registerCleanupHandler } from '@revealui/core/monitoring';
 import { z } from 'zod/v4';
 import { estimateCost } from '../llm/token-counter.js';
 import { ToolCallDeduplicator } from '../tools/deduplicator.js';
-import { discoverMCPTools } from '../tools/mcp-adapter.js';
+import { createToolsFromMcpClient, discoverMCPTools } from '../tools/mcp-adapter.js';
 import { createWebSearchTool } from '../tools/web/duck-duck-go.js';
 const THINKING_BUDGETS = {
     off: 0,
@@ -30,6 +30,7 @@ export class AgentRuntime {
             maxRetries: config.maxRetries ?? 3,
             enableCache: config.enableCache ?? true, // Enable by default for cost savings
             mcpToolSource: config.mcpToolSource,
+            mcpClients: config.mcpClients,
             skillProvider: config.skillProvider,
             thinkingLevel: config.thinkingLevel,
             modelTier: config.modelTier,
@@ -67,8 +68,24 @@ export class AgentRuntime {
         let iterations = 0;
         let totalTokens = 0;
         let totalCostUsd = 0;
-        // Merge MCP-discovered tools (from healthy servers) into the agent's tool set
-        const mcpTools = this.config.mcpToolSource ? discoverMCPTools(this.config.mcpToolSource) : [];
+        // Merge MCP-discovered tools into the agent's tool set. Two paths:
+        //   - Standard `McpClient` instances (Stage 5.1a, preferred)
+        //   - `MCPToolSource` / hypervisor (legacy, deprecated but supported)
+        const mcpTools = [];
+        if (this.config.mcpToolSource) {
+            mcpTools.push(...discoverMCPTools(this.config.mcpToolSource));
+        }
+        if (this.config.mcpClients && this.config.mcpClients.length > 0) {
+            for (const { name, client } of this.config.mcpClients) {
+                try {
+                    const fromClient = await createToolsFromMcpClient(client, { namespace: name });
+                    mcpTools.push(...fromClient);
+                }
+                catch {
+                    // empty-catch-ok: an unhealthy MCP client shouldn't fail the whole task — other clients + base tools still apply
+                }
+            }
+        }
         // Swap in a custom WebSearchProvider if the agent config specifies one (P4-3)
         const customProvider = agent.config?.webSearchProvider;
         let baseTools;

package/dist/orchestration/streaming-runtime.d.ts

@@ -11,8 +11,32 @@ import type { LLMClient } from '../llm/client.js';
 import type { ToolResult } from '../tools/base.js';
 import type { Agent, Task } from './agent.js';
 import { AgentRuntime, type RuntimeConfig } from './runtime.js';
+/**
+ * Chunk types emitted over the agent-stream SSE channel.
+ *
+ * The generator in `StreamingAgentRuntime.streamTask` emits the core turn
+ * events (`text`, `tool_call_start`, `tool_call_result`, `error`, `done`).
+ *
+ * Side-channel events originate outside the generator — route-level
+ * handlers (MCP sampling / elicitation) write them to the SSE stream
+ * directly between turns:
+ *
+ *   - `session_info` — emitted once at stream start with the
+ *     agent-run session id. Clients use the id to POST elicitation
+ *     responses back via `POST /api/agent-stream/elicit`.
+ *   - `sampling_request` — fired when a connected MCP server calls
+ *     `sampling/create`; the handler services the request synchronously
+ *     and emits this chunk for observability.
+ *   - `elicitation_request` — fired when a connected MCP server calls
+ *     `elicitation/create`; the handler pauses waiting for a POST
+ *     response keyed on `(sessionId, elicitationId)`.
+ *
+ * A.2b of the post-v1 MCP arc — the side-channel types are defined here
+ * so the `useAgentStream` consumer + future UI can narrow on them.
+ * A.2b-backend wires the emission; A.2b-frontend renders them.
+ */
 export interface AgentStreamChunk {
-    type: 'text' | 'tool_call_start' | 'tool_call_result' | 'error' | 'done';
+    type: 'text' | 'tool_call_start' | 'tool_call_result' | 'error' | 'done' | 'session_info' | 'sampling_request' | 'elicitation_request';
     content?: string;
     toolCall?: {
         name: string;
@@ -24,6 +48,29 @@ export interface AgentStreamChunk {
         tokensUsed?: number;
         executionTime?: number;
     };
+    /**
+     * Present on `session_info`, `sampling_request`, `elicitation_request`.
+     * Identifies the agent-run session; clients key elicitation POSTs on
+     * this.
+     */
+    sessionId?: string;
+    /**
+     * Namespace (MCP server id) the side-channel event originated from.
+     * Present on `sampling_request` + `elicitation_request`.
+     */
+    namespace?: string;
+    /** Present on `sampling_request` — requested model + shape. */
+    sampling?: {
+        model: string;
+        messageCount: number;
+        maxTokens: number;
+    };
+    /** Present on `elicitation_request` — form payload. */
+    elicitation?: {
+        elicitationId: string;
+        requestedSchema: unknown;
+        message?: string;
+    };
 }
 export declare class StreamingAgentRuntime extends AgentRuntime {
     constructor(config?: RuntimeConfig);

package/dist/orchestration/streaming-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/streaming-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,kBAAkB,GAAG,OAAO,GAAG,MAAM,CAAC;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH;AAED,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,MAAM,GAAE,aAAkB;IAItC;;;OAGG;IACI,UAAU,CACf,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,gBAAgB,CAAC;CAsLpC"}
+{"version":3,"file":"streaming-runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/streaming-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,MAAM,GACN,iBAAiB,GACjB,kBAAkB,GAClB,OAAO,GACP,MAAM,GACN,cAAc,GACd,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,uDAAuD;IACvD,WAAW,CAAC,EAAE;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,OAAO,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,MAAM,GAAE,aAAkB;IAItC;;;OAGG;IACI,UAAU,CACf,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,gBAAgB,CAAC;CAsLpC"}

package/dist/orchestration/ticket-agent.d.ts

@@ -64,7 +64,16 @@ export declare class TicketAgentDispatcher {
      * - Have access to all admin tools (create/update/delete content, globals, media, users)
      * - Have access to ticket mutation tools (update status, add comment)
      * - Run the agentic loop until done or max iterations
+     *
+     * When `options.dispatchId` is provided, id-generating tool calls
+     * (currently `add_ticket_comment`) derive their ids deterministically
+     * from (dispatchId, call-ordinal). This makes the dispatch retry-safe:
+     * a crash-and-resume re-issues tool calls in the same order and
+     * produces the same ids, so the persistence layer's PK constraint
+     * dedupes naturally. Pair with the durable work queue's jobId.
      */
-    dispatch(ticket: TicketInput): Promise<AgentResult>;
+    dispatch(ticket: TicketInput, options?: {
+        dispatchId?: string;
+    }): Promise<AgentResult>;
 }
 //# sourceMappingURL=ticket-agent.d.ts.map

package/dist/orchestration/ticket-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ticket-agent.d.ts","sourceRoot":"","sources":["../../src/orchestration/ticket-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,cAAc,EACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGrE,OAAO,KAAK,EAAS,WAAW,EAAQ,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAC;IAErB,2DAA2D;IAC3D,SAAS,EAAE,cAAc,CAAC;IAE1B,wEAAwE;IACxE,YAAY,EAAE,oBAAoB,CAAC;IAEnC,yEAAyE;IACzE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAEnC,yCAAyC;IACzC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAE3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IAEd,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwDD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,YAAY,CAAoB;gBAE5B,MAAM,EAAE,iBAAiB;IAUrC;;;;;;;;OAQG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAwD1D"}
+{"version":3,"file":"ticket-agent.d.ts","sourceRoot":"","sources":["../../src/orchestration/ticket-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,KAAK,EACV,cAAc,EAEd,kBAAkB,EAClB,cAAc,EACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAGrE,OAAO,KAAK,EAAS,WAAW,EAAQ,MAAM,YAAY,CAAC;AAG3D,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,EAAE,SAAS,CAAC;IAErB,2DAA2D;IAC3D,SAAS,EAAE,cAAc,CAAC;IAE1B,wEAAwE;IACxE,YAAY,EAAE,oBAAoB,CAAC;IAEnC,yEAAyE;IACzE,WAAW,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAEnC,yCAAyC;IACzC,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAE3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IAEd,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwDD,qBAAa,qBAAqB;IAChC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,YAAY,CAAoB;gBAE5B,MAAM,EAAE,iBAAiB;IAUrC;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,CAAC;CA0DjG"}

package/dist/orchestration/ticket-agent.js

@@ -94,13 +94,22 @@ export class TicketAgentDispatcher {
      * - Have access to all admin tools (create/update/delete content, globals, media, users)
      * - Have access to ticket mutation tools (update status, add comment)
      * - Run the agentic loop until done or max iterations
+     *
+     * When `options.dispatchId` is provided, id-generating tool calls
+     * (currently `add_ticket_comment`) derive their ids deterministically
+     * from (dispatchId, call-ordinal). This makes the dispatch retry-safe:
+     * a crash-and-resume re-issues tool calls in the same order and
+     * produces the same ids, so the persistence layer's PK constraint
+     * dedupes naturally. Pair with the durable work queue's jobId.
      */
-    async dispatch(ticket) {
+    async dispatch(ticket, options = {}) {
         const { apiClient, ticketClient, collections, globals, memory: sharedMemory, db } = this.config;
         // Build tool set: admin tools + ticket mutation tools + web scraper + optional summarizer
         const cmsConfig = { apiClient, collections, globals };
         const cmsTools = createAdminTools(cmsConfig);
-        const ticketTools = createTicketTools(ticket.id, ticketClient);
+        const ticketTools = createTicketTools(ticket.id, ticketClient, {
+            dispatchId: options.dispatchId,
+        });
         const extraTools = db
             ? [webScraperTool, createDocumentSummarizerTool(db, this.config.llmClient)]
             : [webScraperTool];