@ixo/common 1.1.2 → 1.1.4

package/src/services/memory-engine/memory-engine.service.ts

@@ -1,32 +1,52 @@
 import { Logger } from '@ixo/logger';
-import type {
-  SearchEnhancedRequest,
-  SearchEnhancedResponse,
-  UserContextData,
+import {
+  isBatchErrorSlot,
+  type SearchEnhancedBatchRequest,
+  type SearchEnhancedBatchResponse,
+  type SearchEnhancedRequest,
+  type SearchEnhancedResponse,
+  type UserContextData,
 } from './types.js';
 
+interface MemoryEngineAuthHeaders {
+  oracleToken: string;
+  userToken: string;
+  oracleHomeServer: string;
+  userHomeServer: string;
+  /** When set, uses UCAN auth instead of Matrix tokens */
+  ucanInvocation?: string;
+}
+
 export class MemoryEngineService {
-  private readonly QUERY_TIMEOUT_MS = 2500; // 2.5 seconds per query
+  // Batch covers 6 queries running in parallel server-side. Bound by the
+  // slowest query, not 6× — but we leave headroom for cold caches.
+  private readonly BATCH_TIMEOUT_MS = 15000;
 
-  constructor(
-    private readonly memoryEngineUrl: string,
-    private readonly memoryServiceApiKey: string,
-  ) {}
+  constructor(private readonly memoryEngineUrl: string) {}
 
   /**
-   * Wraps a promise with a timeout, returning fallback value if timeout is exceeded
+   * Build HTTP headers for memory engine requests (UCAN or Matrix)
    */
-  private async withTimeout<T>(
-    promise: Promise<T>,
-    timeoutMs: number,
-    fallback: T,
-  ): Promise<T> {
-    return Promise.race([
-      promise,
-      new Promise<T>((resolve) =>
-        setTimeout(() => resolve(fallback), timeoutMs),
-      ),
-    ]);
+  private buildHeaders(
+    auth: MemoryEngineAuthHeaders,
+    roomId: string,
+  ): Record<string, string> {
+    if (auth.ucanInvocation) {
+      return {
+        Authorization: `Bearer ${auth.ucanInvocation}`,
+        'X-Auth-Type': 'ucan',
+        'x-room-id': roomId,
+        'Content-Type': 'application/json',
+      };
+    }
+    return {
+      'x-oracle-token': auth.oracleToken,
+      'x-user-token': auth.userToken,
+      'x-oracle-matrix-homeserver': auth.oracleHomeServer,
+      'x-user-matrix-homeserver': auth.userHomeServer,
+      'x-room-id': roomId,
+      'Content-Type': 'application/json',
+    };
   }
 
   /**
@@ -34,101 +54,175 @@ export class MemoryEngineService {
    */
   async gatherUserContext(params: {
     oracleDid: string;
-    userDid: string;
     roomId: string;
+    oracleToken: string;
+    userToken: string;
+    oracleHomeServer: string;
+    userHomeServer: string;
+    /** When set, uses UCAN auth instead of Matrix tokens */
+    ucanInvocation?: string;
   }): Promise<UserContextData> {
-    const { oracleDid, userDid, roomId } = params;
+    const {
+      oracleDid,
+      roomId,
+      oracleToken,
+      userToken,
+      oracleHomeServer,
+      userHomeServer,
+      ucanInvocation,
+    } = params;
 
     Logger.info(
       `[MemoryEngineService] Gathering user context for oracle: ${oracleDid}, room: ${roomId}`,
     );
 
-    try {
-      // Execute all 6 queries in parallel with timeouts using Promise.allSettled
-      const results = await Promise.allSettled([
-        this.withTimeout(
-          this.queryIdentity(oracleDid, userDid, roomId),
-          this.QUERY_TIMEOUT_MS,
-          undefined,
-        ),
-        this.withTimeout(
-          this.queryWork(oracleDid, userDid, roomId),
-          this.QUERY_TIMEOUT_MS,
-          undefined,
-        ),
-        this.withTimeout(
-          this.queryGoals(oracleDid, userDid, roomId),
-          this.QUERY_TIMEOUT_MS,
-          undefined,
-        ),
-        this.withTimeout(
-          this.queryInterests(oracleDid, userDid, roomId),
-          this.QUERY_TIMEOUT_MS,
-          undefined,
-        ),
-        this.withTimeout(
-          this.queryRelationships(oracleDid, userDid, roomId),
-          this.QUERY_TIMEOUT_MS,
-          undefined,
-        ),
-        this.withTimeout(
-          this.queryRecent(oracleDid, userDid, roomId),
-          this.QUERY_TIMEOUT_MS,
-          undefined,
-        ),
-      ]);
-
-      // Extract results from Promise.allSettled outcomes
-      const identity =
-        results[0].status === 'fulfilled' ? results[0].value : undefined;
-      const work =
-        results[1].status === 'fulfilled' ? results[1].value : undefined;
-      const goals =
-        results[2].status === 'fulfilled' ? results[2].value : undefined;
-      const interests =
-        results[3].status === 'fulfilled' ? results[3].value : undefined;
-      const relationships =
-        results[4].status === 'fulfilled' ? results[4].value : undefined;
-      const recent =
-        results[5].status === 'fulfilled' ? results[5].value : undefined;
-
-      // Log any failures
-      results.forEach((result, index) => {
-        if (result.status === 'rejected') {
+    const authHeaders: MemoryEngineAuthHeaders = {
+      oracleToken,
+      userToken,
+      oracleHomeServer,
+      userHomeServer,
+      ucanInvocation,
+    };
+
+    // The 6 queries that make up userContext. Order matters: it determines
+    // how we map batch result slots back to UserContextData fields.
+    const labels = [
+      'identity',
+      'work',
+      'goals',
+      'interests',
+      'relationships',
+      'recent',
+    ] as const;
+    const requests: SearchEnhancedRequest[] = [
+      this.buildIdentityRequest(oracleDid),
+      this.buildWorkRequest(oracleDid),
+      this.buildGoalsRequest(oracleDid),
+      this.buildInterestsRequest(oracleDid),
+      this.buildRelationshipsRequest(oracleDid),
+      this.buildRecentRequest(oracleDid),
+    ];
+
+    const gatherStart = Date.now();
+    const batch = await this.executeBatch(requests, roomId, authHeaders);
+    const gatherElapsed = Date.now() - gatherStart;
+
+    if (!batch) {
+      Logger.error(
+        `[MemoryEngineService] gatherUserContext failed after ${gatherElapsed}ms — returning empty context`,
+      );
+      return {};
+    }
+
+    // Map each slot back to the labelled field. Error slots become undefined.
+    const fields: (SearchEnhancedResponse | undefined)[] = batch.results.map(
+      (slot, index) => {
+        const label = labels[index];
+        if (isBatchErrorSlot(slot)) {
           Logger.warn(
-            `[MemoryEngineService] Query ${index} failed:`,
-            result.reason,
+            `[MemoryEngineService] Batch slot "${label}" failed (${slot.error.status_code}): ${slot.error.detail}`,
           );
+          return undefined;
         }
-      });
+        return slot;
+      },
+    );
 
-      return {
-        identity,
-        work,
-        goals,
-        interests,
-        relationships,
-        recent,
-      };
-    } catch (error) {
-      Logger.error(
-        '[MemoryEngineService] Failed to gather user context:',
-        error,
+    if (batch.results.length !== labels.length) {
+      Logger.warn(
+        `[MemoryEngineService] Batch length mismatch: expected ${labels.length}, got ${batch.results.length}`,
       );
-      // Return empty context on error
-      return {};
     }
+
+    const summary = labels.map((label, index) => {
+      const value = fields[index];
+      if (value === undefined) return `${label}=missing`;
+      return `${label}=ok(f${value.total_results.facts}/e${value.total_results.entities})`;
+    });
+    Logger.info(
+      `[MemoryEngineService] gatherUserContext completed in ${gatherElapsed}ms (batch) — ${summary.join(', ')}`,
+    );
+
+    return {
+      identity: fields[0],
+      work: fields[1],
+      goals: fields[2],
+      interests: fields[3],
+      relationships: fields[4],
+      recent: fields[5],
+    };
   }
 
   /**
-   * Query 1: User Identity & Attributes
+   * POST /search-enhanced-batch — single round-trip for N parallel queries.
+   * Returns undefined on transport/HTTP failure; a partially-failed batch
+   * still resolves with per-slot error markers (handled by caller via
+   * `isBatchErrorSlot`).
    */
-  private async queryIdentity(
-    oracleDid: string,
-    userDid: string,
+  private async executeBatch(
+    queries: SearchEnhancedRequest[],
     roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    const request: SearchEnhancedRequest = {
+    auth: MemoryEngineAuthHeaders,
+  ): Promise<SearchEnhancedBatchResponse | undefined> {
+    if (!roomId) {
+      Logger.warn(
+        `[MemoryEngineService] No room id provided, skipping batch search`,
+      );
+      return undefined;
+    }
+    if (!auth.ucanInvocation && (!auth.oracleToken || !auth.userToken)) {
+      Logger.warn(
+        `[MemoryEngineService] Missing auth (no UCAN and no Matrix tokens), skipping batch search`,
+      );
+      return undefined;
+    }
+
+    const body: SearchEnhancedBatchRequest = { queries };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.BATCH_TIMEOUT_MS);
+
+    try {
+      const response = await fetch(
+        `${this.memoryEngineUrl}/search-enhanced-batch`,
+        {
+          method: 'POST',
+          headers: this.buildHeaders(auth, roomId),
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        },
+      );
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        Logger.warn(
+          `[MemoryEngineService] Batch search failed (${response.status}): ${errorText}`,
+        );
+        return undefined;
+      }
+
+      return (await response.json()) as SearchEnhancedBatchResponse;
+    } catch (error) {
+      if ((error as Error).name === 'AbortError') {
+        Logger.warn(
+          `[MemoryEngineService] Batch search aborted after ${this.BATCH_TIMEOUT_MS}ms`,
+        );
+      } else {
+        Logger.error(`[MemoryEngineService] Batch search threw:`, error);
+      }
+      return undefined;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ── Per-query request builders ────────────────────────────────────────────
+  // These produce SearchEnhancedRequest payloads consumed by gatherUserContext
+  // via the batch endpoint. Order matches the labels array in
+  // gatherUserContext — keep the two in sync.
+
+  private buildIdentityRequest(oracleDid: string): SearchEnhancedRequest {
+    return {
       oracle_dids: [oracleDid],
       query:
         'username and nickname and age user identity traits values personality characteristics communication style beliefs preferences',
@@ -152,19 +246,10 @@ export class MemoryEngineService {
         invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
       },
     };
-
-    return this.executeQuery(request, userDid, oracleDid, roomId);
   }
 
-  /**
-   * Query 2: Work Context
-   */
-  private async queryWork(
-    oracleDid: string,
-    userDid: string,
-    roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    const request: SearchEnhancedRequest = {
+  private buildWorkRequest(oracleDid: string): SearchEnhancedRequest {
+    return {
       oracle_dids: [oracleDid],
       query:
         'work job career projects skills organization employment role responsibilities expertise',
@@ -195,19 +280,10 @@ export class MemoryEngineService {
         invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
       },
     };
-
-    return this.executeQuery(request, userDid, oracleDid, roomId);
   }
 
-  /**
-   * Query 3: Goals & Habits
-   */
-  private async queryGoals(
-    oracleDid: string,
-    userDid: string,
-    roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    const request: SearchEnhancedRequest = {
+  private buildGoalsRequest(oracleDid: string): SearchEnhancedRequest {
+    return {
       oracle_dids: [oracleDid],
       query:
         'goals aspirations objectives milestones habits routines patterns achievements progress',
@@ -230,19 +306,10 @@ export class MemoryEngineService {
         invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
       },
     };
-
-    return this.executeQuery(request, userDid, oracleDid, roomId);
   }
 
-  /**
-   * Query 4: Interests & Preferences
-   */
-  private async queryInterests(
-    oracleDid: string,
-    userDid: string,
-    roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    const request: SearchEnhancedRequest = {
+  private buildInterestsRequest(oracleDid: string): SearchEnhancedRequest {
+    return {
       oracle_dids: [oracleDid],
       query:
         'interests hobbies passions preferences likes dislikes expertise topics content',
@@ -272,19 +339,10 @@ export class MemoryEngineService {
         invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
       },
     };
-
-    return this.executeQuery(request, userDid, oracleDid, roomId);
   }
 
-  /**
-   * Query 5: Relationships
-   */
-  private async queryRelationships(
-    oracleDid: string,
-    userDid: string,
-    roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    const request: SearchEnhancedRequest = {
+  private buildRelationshipsRequest(oracleDid: string): SearchEnhancedRequest {
+    return {
       oracle_dids: [oracleDid],
       query:
         'relationships people connections social network colleagues friends family contacts',
@@ -307,24 +365,17 @@ export class MemoryEngineService {
         invalid_at: [[{ date: null, comparison_operator: 'IS NULL' }]],
       },
     };
-
-    return this.executeQuery(request, userDid, oracleDid, roomId);
   }
 
-  /**
-   * Query 6: Recent Context
-   */
-  private async queryRecent(
-    oracleDid: string,
-    userDid: string,
-    roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    // Calculate date 90 days ago for recent context
+  private buildRecentRequest(oracleDid: string): SearchEnhancedRequest {
+    // Server-side `recent_memory` strategy auto-injects a created_at >= now-90d
+    // filter. We still pass it explicitly as defense-in-depth — the server's
+    // merge logic respects an existing lower bound and won't double-apply.
     const ninetyDaysAgo = new Date();
     ninetyDaysAgo.setDate(ninetyDaysAgo.getDate() - 90);
     const dateString = ninetyDaysAgo.toISOString();
 
-    const request: SearchEnhancedRequest = {
+    return {
       oracle_dids: [oracleDid],
       query:
         'recent conversations messages discussions activities updates interactions',
@@ -338,8 +389,6 @@ export class MemoryEngineService {
         created_at: [[{ date: dateString, comparison_operator: '>=' }]],
       },
     };
-
-    return this.executeQuery(request, userDid, oracleDid, roomId);
   }
 
   /**
@@ -347,9 +396,12 @@ export class MemoryEngineService {
    */
   async processConversationHistory({
     messages,
-    userDid,
-    oracleDid,
     roomId,
+    oracleToken,
+    userToken,
+    oracleHomeServer,
+    userHomeServer,
+    ucanInvocation,
   }: {
     messages: Array<{
       content: string;
@@ -358,25 +410,23 @@ export class MemoryEngineService {
       name?: string;
       source_description?: string;
     }>;
-    userDid: string;
-    oracleDid: string;
     roomId: string;
+    oracleToken: string;
+    userToken: string;
+    oracleHomeServer: string;
+    userHomeServer: string;
+    /** When set, uses UCAN auth instead of Matrix tokens */
+    ucanInvocation?: string;
   }): Promise<{ success: boolean }> {
-    if (!userDid) {
-      Logger.warn(
-        `[MemoryEngineService] No user DID provided, skipping conversation processing`,
-      );
-      return { success: false };
-    }
-    if (!oracleDid) {
+    if (!roomId) {
       Logger.warn(
-        `[MemoryEngineService] No oracle did provided, skipping conversation processing`,
+        `[MemoryEngineService] No room id provided, skipping conversation processing`,
       );
       return { success: false };
     }
-    if (!roomId) {
+    if (!ucanInvocation && (!oracleToken || !userToken)) {
       Logger.warn(
-        `[MemoryEngineService] No room id provided, skipping conversation processing`,
+        `[MemoryEngineService] Missing auth (no UCAN and no Matrix tokens), skipping conversation processing`,
       );
       return { success: false };
     }
@@ -388,15 +438,16 @@ export class MemoryEngineService {
     }
 
     try {
+      const auth: MemoryEngineAuthHeaders = {
+        oracleToken,
+        userToken,
+        oracleHomeServer,
+        userHomeServer,
+        ucanInvocation,
+      };
       const response = await fetch(`${this.memoryEngineUrl}/messages`, {
         method: 'POST',
-        headers: {
-          'x-user-did': userDid,
-          'x-oracle-did': oracleDid,
-          'x-room-id': roomId,
-          'x-service-api-key': this.memoryServiceApiKey,
-          'Content-Type': 'application/json',
-        },
+        headers: this.buildHeaders(auth, roomId),
         body: JSON.stringify({ messages }),
       });
 
@@ -420,67 +471,4 @@ export class MemoryEngineService {
       return { success: false };
     }
   }
-
-  /**
-   * Execute a search query against the Memory Engine API
-   */
-  private async executeQuery(
-    request: SearchEnhancedRequest,
-    userDid: string,
-    oracleDid: string,
-    roomId: string,
-  ): Promise<SearchEnhancedResponse | undefined> {
-    if (!userDid) {
-      Logger.warn(
-        `[MemoryEngineService] No user DID provided, skipping query "${request.query}"`,
-      );
-      return undefined;
-    }
-    if (!oracleDid) {
-      Logger.warn(
-        `[MemoryEngineService] No oracle did provided, skipping query "${request.query}"`,
-      );
-      return undefined;
-    }
-    if (!roomId) {
-      Logger.warn(
-        `[MemoryEngineService] No room id provided, skipping query "${request.query}"`,
-      );
-      return undefined;
-    }
-
-    try {
-      const response = await fetch(`${this.memoryEngineUrl}/search-enhanced`, {
-        method: 'POST',
-        headers: {
-          'x-user-did': userDid,
-          'x-oracle-did': oracleDid,
-          'x-room-id': roomId,
-          'x-service-api-key': this.memoryServiceApiKey,
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(request),
-      });
-
-      if (!response.ok) {
-        const errorText = await response.text();
-        Logger.warn(
-          `[MemoryEngineService] Memory Engine query failed (${response.status}): ${errorText}`,
-        );
-        return undefined;
-      }
-
-      const result = (await response.json()) as SearchEnhancedResponse;
-      Logger.info(
-        `[MemoryEngineService] Query "${request.query}" returned ${result.total_results.facts} facts, ${result.total_results.entities} entities`,
-      );
-      return result;
-    } catch (error) {
-      Logger.error(
-        `[MemoryEngineService] Failed to execute query "${request.query}":`,
-        error,
-      );
-      return undefined;
-    }
-  }
 }

package/src/services/memory-engine/types.ts

@@ -206,3 +206,37 @@ export interface UserContextData {
   relationships?: SearchEnhancedResponse;
   recent?: SearchEnhancedResponse;
 }
+
+// Batch search types — backend endpoint POST /search-enhanced-batch
+export interface SearchEnhancedBatchRequest {
+  queries: SearchEnhancedRequest[];
+}
+
+// A failed slot in the batch response. The server returns this in place of
+// SearchEnhancedResponse when a single query fails — the rest of the batch
+// still completes.
+export interface SearchEnhancedBatchErrorSlot {
+  error: {
+    status_code: number;
+    detail: string;
+  };
+  query: string;
+  strategy_used: string;
+}
+
+export type SearchEnhancedBatchSlot =
+  | SearchEnhancedResponse
+  | SearchEnhancedBatchErrorSlot;
+
+export interface SearchEnhancedBatchResponse {
+  results: SearchEnhancedBatchSlot[];
+}
+
+export function isBatchErrorSlot(
+  slot: SearchEnhancedBatchSlot,
+): slot is SearchEnhancedBatchErrorSlot {
+  return (
+    typeof (slot as SearchEnhancedBatchErrorSlot).error === 'object' &&
+    (slot as SearchEnhancedBatchErrorSlot).error !== null
+  );
+}

package/src/services/session-manager/dto.ts

@@ -32,6 +32,11 @@ export class ListChatSessionsDto extends UserAuthDto {
   @IsOptional()
   @Min(0)
   offset?: number;
+
+  /** Filter sessions by roomId. When set, only sessions in this room are returned. */
+  @IsString()
+  @IsOptional()
+  roomId?: string;
 }
 
 export class CreateChatSessionDto extends UserAuthDto {
@@ -50,6 +55,31 @@ export class CreateChatSessionDto extends UserAuthDto {
   @IsString()
   @IsOptional()
   slackThreadTs?: string;
+
+  @IsString()
+  @IsOptional()
+  oracleToken?: string;
+
+  @IsString()
+  @IsOptional()
+  userToken?: string;
+
+  @IsString()
+  @IsOptional()
+  oracleHomeServer?: string;
+
+  @IsString()
+  @IsOptional()
+  userHomeServer?: string;
+
+  @IsString()
+  @IsOptional()
+  ucanInvocation?: string;
+
+  /** Override the roomId stored on the session (e.g. task-specific room). */
+  @IsString()
+  @IsOptional()
+  roomId?: string;
 }
 
 export class DeleteChatSessionDto extends UserAuthDto {