@ixo/oracle-runtime-workers 0.2.0

package/src/matrix/work-status.ts

@@ -0,0 +1,294 @@
+/**
+ * The per-turn `work_status` liveness card — the port of the Node runtime's
+ * `matrix/work-status-producer.ts` + `matrix/oracle-component-event.ts`.
+ *
+ * A Matrix turn posts ONE `ixo.oracle.component` event (`component:
+ * 'work_status'`) into the user's thread when it starts, then edits it in
+ * place (`m.replace`) as the agent moves through phases:
+ * routing → working (one "Step n · <action>" per model/tool call) →
+ * delivering → done, or superseded when a newer message restarts the turn.
+ * Clients that render oracle components show a live card; everything else
+ * sees the plain `body` fallback ("Status: Working…").
+ *
+ * Frames are coalesced per turn: anything staged behind an in-flight post is
+ * stale by the time the homeserver would accept it, so the newest frame
+ * replaces it — which also guarantees a terminal phase is never dropped.
+ * Fire-and-forget throughout: a failed post is logged, never thrown.
+ */
+
+export const ORACLE_COMPONENT_EVENT_TYPE = 'ixo.oracle.component';
+
+export type OracleComponentName =
+  | 'list_services'
+  | 'show_contract'
+  | 'work_status'
+  | 'work_delivered'
+  | 'payment_update';
+
+export interface OracleComponentThreadRelation {
+  rel_type: 'm.thread';
+  event_id: string;
+}
+
+export interface OracleComponentReplaceRelation {
+  rel_type: 'm.replace';
+  event_id: string;
+}
+
+export interface OracleComponentEnvelope {
+  component: OracleComponentName;
+  props: Record<string, unknown>;
+  body: string;
+  sessionId: string;
+  requestId: string;
+  toolCallId?: string;
+}
+
+export interface OracleComponentEventContent extends OracleComponentEnvelope {
+  'm.new_content'?: OracleComponentEnvelope;
+  'm.relates_to'?:
+    | OracleComponentThreadRelation
+    | OracleComponentReplaceRelation;
+}
+
+export interface OracleComponentInput {
+  component: OracleComponentName;
+  props: Record<string, unknown>;
+  body: string;
+  sessionId: string;
+  requestId: string;
+  toolCallId?: string;
+  threadId?: string;
+  replacesEventId?: string;
+}
+
+/** Byte-compatible with the Node runtime's `buildOracleComponentContent`. */
+export function buildOracleComponentContent(
+  input: OracleComponentInput,
+): OracleComponentEventContent {
+  const { threadId, replacesEventId, toolCallId, ...rest } = input;
+  const envelope: OracleComponentEnvelope = {
+    ...rest,
+    ...(toolCallId !== undefined && { toolCallId }),
+  };
+  const relation: OracleComponentEventContent['m.relates_to'] | undefined =
+    replacesEventId !== undefined
+      ? { rel_type: 'm.replace', event_id: replacesEventId }
+      : threadId !== undefined
+        ? { rel_type: 'm.thread', event_id: threadId }
+        : undefined;
+  return {
+    ...envelope,
+    ...(replacesEventId !== undefined && { 'm.new_content': envelope }),
+    ...(relation !== undefined && { 'm.relates_to': relation }),
+  };
+}
+
+export type WorkStatusPhase =
+  | 'routing'
+  | 'working'
+  | 'delivering'
+  | 'done'
+  | 'superseded';
+
+const ANCHOR_RETRY_DELAY_MS = 1000;
+
+const ANCHOR_PHASES: ReadonlySet<WorkStatusPhase> = new Set([
+  'routing',
+  'working',
+]);
+
+const DEFAULT_LABELS: Record<WorkStatusPhase, string> = {
+  routing: 'Routing your request…',
+  working: 'Working…',
+  delivering: 'Sending your reply…',
+  done: 'Done',
+  superseded: 'Got your new message — restarting',
+};
+
+export interface WorkStatusTurn {
+  requestId: string;
+  roomId: string;
+  /** Thread the card is posted into (the user's message thread root). */
+  threadId: string;
+  sessionId: string;
+  /** The user's message event the card reports on. */
+  forEventId: string;
+}
+
+interface StatusFrame {
+  phase: WorkStatusPhase;
+  label?: string;
+}
+
+interface TurnEntry extends WorkStatusTurn {
+  anchorEventId?: string;
+  steps: number;
+  pending?: StatusFrame;
+  draining: boolean;
+}
+
+export interface WorkStatusProducerDeps {
+  /** Posts a room event and resolves its event id (the gateway's `sendEvent`). */
+  postEvent: (
+    roomId: string,
+    eventType: string,
+    content: object,
+  ) => Promise<string>;
+  clock?: () => Date;
+  logger?: { warn: (message: string) => void };
+  /** Delay before the single retry of a failed anchor post (tests: 0). */
+  anchorRetryDelayMs?: number;
+}
+
+export class WorkStatusProducer {
+  private readonly turns = new Map<string, TurnEntry>();
+
+  private readonly postEvent: WorkStatusProducerDeps['postEvent'];
+
+  private readonly clock: () => Date;
+
+  private readonly logger: { warn: (message: string) => void };
+
+  private readonly anchorRetryDelayMs: number;
+
+  constructor(deps: WorkStatusProducerDeps) {
+    this.postEvent = deps.postEvent;
+    this.clock = deps.clock ?? (() => new Date());
+    this.logger = deps.logger ?? { warn: () => undefined };
+    this.anchorRetryDelayMs = deps.anchorRetryDelayMs ?? ANCHOR_RETRY_DELAY_MS;
+  }
+
+  /** Register a turn so later `emit`/`step`/`finish` calls have a card to drive. */
+  beginTurn(turn: WorkStatusTurn): void {
+    this.turns.set(turn.requestId, { ...turn, steps: 0, draining: false });
+  }
+
+  /**
+   * Post a status phase for a registered turn. The first anchor-capable phase
+   * (`routing`/`working`) creates the card; every later phase updates it via
+   * `m.replace`. Unregistered requestIds — and closing phases with no card to
+   * close — are no-ops.
+   */
+  emit(requestId: string, phase: WorkStatusPhase, label?: string): void {
+    const entry = this.turns.get(requestId);
+    if (!entry) return;
+    this.enqueue(entry, phase, label);
+  }
+
+  /**
+   * Post the next agent step: bumps the turn's counter and emits `working`
+   * with a `Step n · <action>` label. The counter can outrun the numbers the
+   * room actually sees (coalesced frames are skipped, not renumbered) so the
+   * line always moves forward.
+   */
+  step(requestId: string, action: string): void {
+    const entry = this.turns.get(requestId);
+    if (!entry) return;
+    entry.steps += 1;
+    this.enqueue(entry, 'working', `Step ${entry.steps} · ${action}`);
+  }
+
+  /**
+   * Post a final phase (`done`/`superseded`) and unregister the turn. Later
+   * emissions for this requestId become no-ops immediately.
+   */
+  finish(requestId: string, phase: WorkStatusPhase, label?: string): void {
+    const entry = this.turns.get(requestId);
+    if (!entry) return;
+    this.turns.delete(requestId);
+    this.enqueue(entry, phase, label);
+  }
+
+  private async postWithRetry(
+    roomId: string,
+    content: object,
+    retryOnce: boolean,
+  ): Promise<string> {
+    try {
+      return await this.postEvent(roomId, ORACLE_COMPONENT_EVENT_TYPE, content);
+    } catch (error) {
+      if (!retryOnce) throw error;
+      await new Promise((resolve) =>
+        setTimeout(resolve, this.anchorRetryDelayMs),
+      );
+      return this.postEvent(roomId, ORACLE_COMPONENT_EVENT_TYPE, content);
+    }
+  }
+
+  /** Unregister a turn without posting (error paths, turns with no card). */
+  endTurn(requestId: string): void {
+    this.turns.delete(requestId);
+  }
+
+  /** Whether a turn is registered (tests + the ingest supersede path). */
+  has(requestId: string): boolean {
+    return this.turns.has(requestId);
+  }
+
+  private enqueue(
+    entry: TurnEntry,
+    phase: WorkStatusPhase,
+    label?: string,
+  ): void {
+    entry.pending = { phase, label };
+    if (entry.draining) return;
+    entry.draining = true;
+    void this.drain(entry);
+  }
+
+  private async drain(entry: TurnEntry): Promise<void> {
+    try {
+      while (entry.pending) {
+        const frame = entry.pending;
+        entry.pending = undefined;
+        await this.post(entry, frame);
+      }
+    } finally {
+      entry.draining = false;
+    }
+  }
+
+  private async post(entry: TurnEntry, frame: StatusFrame): Promise<void> {
+    const { phase, label } = frame;
+    if (!entry.anchorEventId && !ANCHOR_PHASES.has(phase)) return;
+    const resolvedLabel = label ?? DEFAULT_LABELS[phase];
+    try {
+      const content = buildOracleComponentContent({
+        component: 'work_status',
+        props: {
+          forEventId: entry.forEventId,
+          phase,
+          label: resolvedLabel,
+          updatedAt: this.clock().toISOString(),
+        },
+        body: `Status: ${resolvedLabel}`,
+        sessionId: entry.sessionId,
+        requestId: entry.requestId,
+        ...(entry.anchorEventId
+          ? { replacesEventId: entry.anchorEventId }
+          : { threadId: entry.threadId }),
+      });
+      const eventId = await this.postWithRetry(
+        entry.roomId,
+        content,
+        // The anchor decides whether the turn gets a card at all: retry it.
+        !entry.anchorEventId,
+      );
+      if (!entry.anchorEventId) entry.anchorEventId = eventId;
+    } catch (error) {
+      this.logger.warn(
+        `work_status post failed (room=${entry.roomId}, phase=${phase}): ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
+}
+
+/** `generate_tax_report` → `Generate tax report…`. */
+export function humanizeToolLabel(toolName: string): string {
+  const words = toolName.replace(/[_-]+/g, ' ').trim();
+  if (words.length === 0) return DEFAULT_LABELS.working;
+  return `${words.charAt(0).toUpperCase()}${words.slice(1)}…`;
+}

package/src/memory/session-history-indexer.ts

@@ -0,0 +1,328 @@
+/**
+ * Session-history → memory-engine indexing — the Workers port of the Node
+ * runtime's `SessionHistoryProcessor` (`modules/sessions/session-history-
+ * processor.service.ts`).
+ *
+ * Policy (identical to Node):
+ *  - Runs in the background when a session is CREATED (indexes the most
+ *    recent previous session) and when a session is DELETED (indexes it
+ *    before it goes). The request never waits for, or fails on, indexing.
+ *  - Only messages after the session's `lastProcessedCount` are sent, then
+ *    the count is advanced — a session is never indexed twice.
+ *  - Speakers get real identities (the user's preferred name / the oracle's
+ *    preferred or configured name) so Graphiti's extractor does not pin
+ *    facts to literal "user"/"assistant" nodes. Tool replies fold into the
+ *    assistant role (the engine has no tool role).
+ *  - Auth is the oracle's two-hop UCAN invocation minted from the user's
+ *    delegation (`ixo:memory` / `memory/*`) — no delegation, no indexing.
+ *  - Endpoint: `POST <MEMORY_ENGINE_URL>/messages` with `x-room-id`, as
+ *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`.
+ *  - A per-session lock prevents overlapping runs; a failed upload is
+ *    retried 3× with a 10 s pause (Node's numbers).
+ *
+ * Not ported: Node also asks Matrix for the user's display name when no
+ * preferred name is set; here the fallback is the literal "Me" straight away.
+ */
+import type { Logger } from '../plugin-api/types';
+
+export interface HistoryMessage {
+  /** LangChain message type: `human` | `ai` | `tool` | `system`. */
+  type: string;
+  content: string;
+}
+
+export interface MemoryEngineMessage {
+  content: string;
+  role_type: 'user' | 'assistant' | 'system';
+  role?: string;
+  name?: string;
+  source_description?: string;
+}
+
+export interface IndexableSession {
+  title?: string;
+  roomId?: string;
+  lastProcessedCount?: number;
+}
+
+export interface SpeakerLabels {
+  user: string;
+  oracle: string;
+}
+
+export interface SessionHistoryIndexerDeps {
+  /** `MEMORY_ENGINE_URL`; undefined disables indexing (memory plugin absent). */
+  memoryEngineUrl: string | undefined;
+  getSession(sessionId: string): Promise<IndexableSession | undefined>;
+  /** The session transcript, summarisation bookkeeping already removed. */
+  listMessages(sessionId: string): Promise<HistoryMessage[]>;
+  setProcessedCount(sessionId: string, count: number): Promise<void>;
+  /** The user↔oracle room, for sessions whose row carries none. */
+  resolveUserRoom(): Promise<{ roomId: string } | null>;
+  ucan: {
+    hasSigningKey(): boolean;
+    resolveServiceDid(serviceUrl: string): Promise<string | null>;
+    mintInvocation(
+      target: { did: string; capability: string },
+      opts?: { can?: string },
+    ): Promise<string>;
+  };
+  speakerLabels(roomId: string): Promise<SpeakerLabels>;
+  logger: Logger;
+  fetchImpl?: typeof fetch;
+  /** Test hooks. */
+  sleep?: (ms: number) => Promise<void>;
+  maxRetries?: number;
+  retryDelayMs?: number;
+  /** Hard timeout for the memory-engine request (default 20 s). */
+  requestTimeoutMs?: number;
+}
+
+export type IndexOutcome = 'processed' | 'skipped' | 'failed';
+
+/**
+ * Bounded background work: the indexer runs under `ctx.waitUntil`, so the
+ * whole retry envelope keeps the user object resident (and un-hibernatable
+ * with sockets attached). Two attempts, a short pause, and a hard timeout on
+ * the memory-engine request keep that under a minute; a failed session is
+ * simply retried on the next session create (the watermark did not move).
+ */
+const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_RETRY_DELAY_MS = 3_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 20_000;
+
+/** Node's `transformMessagesToMemoryEngineFormat`, verbatim in mapping. */
+export function transformMessagesToMemoryEngineFormat(
+  messages: readonly HistoryMessage[],
+  sessionTitle: string,
+  userSpeakerLabel: string,
+  oracleSpeakerLabel: string,
+): MemoryEngineMessage[] {
+  return messages.map((message) => {
+    let role_type: MemoryEngineMessage['role_type'];
+    let label: string;
+    switch (message.type) {
+      case 'human':
+        role_type = 'user';
+        label = userSpeakerLabel;
+        break;
+      case 'ai':
+        role_type = 'assistant';
+        label = oracleSpeakerLabel;
+        break;
+      case 'system':
+        role_type = 'system';
+        label = 'System';
+        break;
+      case 'tool':
+        // The engine has no tool role — tool replies are the oracle
+        // reporting back, so they share the oracle speaker label.
+        role_type = 'assistant';
+        label = oracleSpeakerLabel;
+        break;
+      default:
+        role_type = 'user';
+        label = userSpeakerLabel;
+    }
+    return {
+      content: message.content,
+      role_type,
+      role: label,
+      name: label,
+      source_description: `Chat Session: ${sessionTitle}`,
+    };
+  });
+}
+
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export class SessionHistoryIndexer {
+  private readonly inFlight = new Set<string>();
+
+  private readonly fetchImpl: typeof fetch;
+
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  private readonly maxRetries: number;
+
+  private readonly retryDelayMs: number;
+
+  private readonly requestTimeoutMs: number;
+
+  constructor(private readonly deps: SessionHistoryIndexerDeps) {
+    this.fetchImpl = deps.fetchImpl ?? fetch.bind(globalThis);
+    this.sleep =
+      deps.sleep ??
+      ((ms) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+    this.maxRetries = deps.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.retryDelayMs = deps.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS;
+    this.requestTimeoutMs = deps.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  }
+
+  /** Sessions currently being indexed (background work keeping the object busy). */
+  get inFlightCount(): number {
+    return this.inFlight.size;
+  }
+
+  /** Whether indexing is configured at all (memory engine URL present). */
+  get enabled(): boolean {
+    return typeof this.deps.memoryEngineUrl === 'string';
+  }
+
+  /**
+   * Index a session's unprocessed messages. Never throws: outcomes are
+   * `processed`, `skipped` (nothing to do / prerequisites missing) or
+   * `failed` (upload failed after retries). Concurrent calls for the same
+   * session collapse into one.
+   */
+  async process(sessionId: string): Promise<IndexOutcome> {
+    const { logger } = this.deps;
+    if (!this.enabled) {
+      logger.log(
+        `[history-indexer] MEMORY_ENGINE_URL not configured; not indexing session ${sessionId}`,
+      );
+      return 'skipped';
+    }
+    if (this.inFlight.has(sessionId)) {
+      logger.log(
+        `[history-indexer] session ${sessionId} is already being indexed, skipping`,
+      );
+      return 'skipped';
+    }
+    this.inFlight.add(sessionId);
+    try {
+      for (let attempt = 1; attempt <= this.maxRetries; attempt += 1) {
+        try {
+          const outcome = await this.processOnce(sessionId);
+          if (outcome === 'processed') {
+            logger.log(
+              `[history-indexer] indexed session ${sessionId} into the memory engine`,
+            );
+          }
+          return outcome;
+        } catch (err) {
+          logger.warn(
+            `[history-indexer] attempt ${attempt}/${this.maxRetries} failed for session ${sessionId}: ${describe(err)}`,
+          );
+          if (attempt === this.maxRetries) {
+            logger.error(
+              `[history-indexer] giving up on session ${sessionId} after ${this.maxRetries} attempts`,
+            );
+            return 'failed';
+          }
+          await this.sleep(this.retryDelayMs);
+        }
+      }
+      return 'failed';
+    } finally {
+      this.inFlight.delete(sessionId);
+    }
+  }
+
+  private async processOnce(sessionId: string): Promise<IndexOutcome> {
+    const { deps } = this;
+    const { logger } = deps;
+    const memoryEngineUrl = deps.memoryEngineUrl!.replace(/\/+$/, '');
+
+    const session = await deps.getSession(sessionId);
+    if (!session) {
+      logger.warn(`[history-indexer] session ${sessionId} not found, skipping`);
+      return 'skipped';
+    }
+
+    const roomId =
+      session.roomId ?? (await deps.resolveUserRoom())?.roomId ?? null;
+    if (!roomId) {
+      logger.warn(
+        `[history-indexer] no oracle room for session ${sessionId}, skipping`,
+      );
+      return 'skipped';
+    }
+
+    const messages = await deps.listMessages(sessionId);
+    if (messages.length === 0) {
+      logger.log(`[history-indexer] no messages in session ${sessionId}`);
+      return 'skipped';
+    }
+
+    const lastProcessedCount = session.lastProcessedCount ?? 0;
+    const newMessages = messages.slice(lastProcessedCount);
+    if (newMessages.length === 0) {
+      logger.log(
+        `[history-indexer] no new messages for session ${sessionId} (lastProcessedCount: ${lastProcessedCount})`,
+      );
+      return 'skipped';
+    }
+
+    const labels = await deps.speakerLabels(roomId);
+    const transformed = transformMessagesToMemoryEngineFormat(
+      // Tool-call-only AI turns carry no text; the engine has nothing to
+      // extract from them and rejects empty episodes.
+      newMessages.filter((m) => m.content.trim().length > 0),
+      session.title ?? '',
+      labels.user,
+      labels.oracle,
+    );
+
+    if (!deps.ucan.hasSigningKey()) {
+      logger.warn(
+        `[history-indexer] no UCAN signing key; skipping memory engine processing for session ${sessionId}`,
+      );
+      return 'skipped';
+    }
+
+    // Node: a failed mint is a warn + skip, not a retry — the user simply has
+    // not delegated `ixo:memory` to this oracle (yet).
+    let invocation: string | null = null;
+    try {
+      const memoryDid = await deps.ucan.resolveServiceDid(memoryEngineUrl);
+      if (memoryDid) {
+        invocation = await deps.ucan.mintInvocation(
+          { did: memoryDid, capability: 'ixo:memory' },
+          // Claim the ability the user's delegation actually grants. A `'*'`
+          // claim is satisfiable only by a `'*'` grant.
+          { can: 'memory/*' },
+        );
+      }
+    } catch (err) {
+      logger.warn(
+        `[history-indexer] could not mint a memory engine invocation: ${describe(err)}`,
+      );
+    }
+    if (!invocation) {
+      logger.warn(
+        `[history-indexer] no memory engine invocation for session ${sessionId}; skipping`,
+      );
+      return 'skipped';
+    }
+
+    if (transformed.length > 0) {
+      const res = await this.fetchImpl(`${memoryEngineUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${invocation}`,
+          'X-Auth-Type': 'ucan',
+          'x-room-id': roomId,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ messages: transformed }),
+        signal: AbortSignal.timeout(this.requestTimeoutMs),
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(
+          `memory engine rejected the conversation (${res.status}): ${text.slice(0, 200)}`,
+        );
+      }
+    }
+
+    const newCount = lastProcessedCount + newMessages.length;
+    await deps.setProcessedCount(sessionId, newCount);
+    logger.log(
+      `[history-indexer] processed ${newMessages.length} new messages for session ${sessionId} (lastProcessedCount → ${newCount})`,
+    );
+    return 'processed';
+  }
+}