@ixo/oracle-runtime-workers 0.2.0

package/src/matrix/ingest.ts

@@ -0,0 +1,209 @@
+/**
+ * Inbound message pipeline — the transport-agnostic half of the gateway.
+ *
+ * Mirrors the Node runtime's `MatrixListenerBridge` (per-thread debounce,
+ * thread handling, attachments) with the room→user mapping the Workers
+ * topology needs: each turn is dispatched to the user's own Durable Object,
+ * so the sender must resolve to a user DID before anything else happens.
+ * Own-message, stale and duplicate gating happens upstream, in the bot SDK's
+ * pipeline; `gateway-do.ts` adapts its `BotMessage`s into `InboundMessage`s.
+ */
+
+import { didToAliasPart } from '../do/contracts';
+
+/** A media message (`m.image` / `m.file` / `m.audio` / `m.video`) as the turn sees it. */
+export interface InboundAttachment {
+  eventId: string;
+  filename: string;
+  mimetype: string;
+  size?: number;
+}
+
+export interface InboundMessage {
+  eventId: string;
+  roomId: string;
+  /** Full Matrix user id of the sender (`@did-ixo-…:server`). */
+  sender: string;
+  /** `origin_server_ts`. */
+  ts: number;
+  /** Text body; empty for a media-only message. */
+  body: string;
+  /** Thread root when the message was sent inside a thread. */
+  threadRootId?: string;
+  /** Present for media messages — fetched and decrypted at turn time. */
+  attachment?: InboundAttachment;
+}
+
+export interface IngestTurn {
+  userDid: string;
+  matrixUserId: string;
+  roomId: string;
+  /** Present when the user wrote inside a thread; replies go there too. */
+  threadId?: string;
+  /** `matrix:<roomId>` (main timeline) or `thread:<threadRootId>`. */
+  sessionId: string;
+  /** Debounced messages joined with newlines, oldest first. */
+  message: string;
+  eventIds: string[];
+  /** Media shared in the same debounce window, oldest first. */
+  attachments?: InboundAttachment[];
+}
+
+export interface IngestDeps {
+  /** The DID that forms the oracle half of the user↔oracle room alias. */
+  oracleDid: string;
+  debounceMs?: number;
+  /** `m.room.canonical_alias` of the room, when known. */
+  canonicalAlias(roomId: string): string | null;
+  dispatch(turn: IngestTurn): Promise<void>;
+  onError?(err: unknown, context: string): void;
+}
+
+interface Pending {
+  timer: ReturnType<typeof setTimeout>;
+  messages: InboundMessage[];
+  userDid: string;
+}
+
+export const DEFAULT_DEBOUNCE_MS = 500;
+
+/** `did-ixo-ixo1abc` → `did:ixo:ixo1abc`. Only the first two dashes are separators. */
+export function aliasPartToDid(part: string): string | null {
+  const m = /^did-([a-z0-9]+)-(.+)$/.exec(part);
+  if (!m) return null;
+  return `did:${m[1]}:${m[2]}`;
+}
+
+/** Matrix user id → DID when the localpart is DID-shaped, else null. */
+export function matrixUserIdToDid(userId: string): string | null {
+  if (!userId.startsWith('@')) return null;
+  const colon = userId.indexOf(':');
+  const localpart = colon === -1 ? userId.slice(1) : userId.slice(1, colon);
+  return aliasPartToDid(localpart);
+}
+
+/**
+ * `#<userDidDashed>_<oracleDidDashed>:server` → user DID, or null when the
+ * alias is not a user↔oracle room alias for THIS oracle.
+ */
+export function userDidFromRoomAlias(
+  alias: string,
+  oracleDid: string,
+): string | null {
+  if (!alias.startsWith('#')) return null;
+  const colon = alias.indexOf(':');
+  const local = colon === -1 ? alias.slice(1) : alias.slice(1, colon);
+  const suffix = `_${didToAliasPart(oracleDid)}`;
+  if (!local.endsWith(suffix)) return null;
+  return aliasPartToDid(local.slice(0, -suffix.length));
+}
+
+/**
+ * Who is the user for this message? The canonical alias names the room's
+ * owner; the sender's localpart names the speaker. They agree in a 1:1
+ * oracle room. When the speaker is DID-shaped but differs from the room
+ * owner (a third member invited into the room), the SPEAKER wins — a turn
+ * must never run inside another user's object. A non-DID sender in an
+ * owner's room is attributed to the owner (legacy / non-DID accounts).
+ */
+export function resolveUserDid(opts: {
+  alias: string | null;
+  sender: string;
+  oracleDid: string;
+}): string | null {
+  const fromSender = matrixUserIdToDid(opts.sender);
+  const fromAlias = opts.alias
+    ? userDidFromRoomAlias(opts.alias, opts.oracleDid)
+    : null;
+  if (fromSender && fromAlias && fromSender !== fromAlias) return fromSender;
+  return fromAlias ?? fromSender;
+}
+
+export function sessionIdFor(roomId: string, threadRootId?: string): string {
+  return threadRootId ? `thread:${threadRootId}` : `matrix:${roomId}`;
+}
+
+export class IngestPipeline {
+  private readonly pending = new Map<string, Pending>();
+  private readonly debounceMs: number;
+
+  constructor(private readonly deps: IngestDeps) {
+    this.debounceMs = deps.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  }
+
+  /**
+   * Offer a decrypted message. Returns the reason it was dropped, or
+   * `'queued'` when it entered the debounce buffer.
+   */
+  offer(msg: InboundMessage): 'queued' | 'empty' | 'unmapped' {
+    if (!msg.body.trim() && !msg.attachment) return 'empty';
+    const userDid = resolveUserDid({
+      alias: this.deps.canonicalAlias(msg.roomId),
+      sender: msg.sender,
+      oracleDid: this.deps.oracleDid,
+    });
+    if (!userDid) return 'unmapped';
+
+    const key = `${msg.roomId}|${sessionIdFor(msg.roomId, msg.threadRootId)}`;
+    const existing = this.pending.get(key);
+    if (existing) {
+      clearTimeout(existing.timer);
+      existing.messages.push(msg);
+      existing.timer = setTimeout(() => void this.flush(key), this.debounceMs);
+    } else {
+      this.pending.set(key, {
+        messages: [msg],
+        userDid,
+        timer: setTimeout(() => void this.flush(key), this.debounceMs),
+      });
+    }
+    return 'queued';
+  }
+
+  /** Number of debounce buffers waiting to fire. */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  /** Cancel every buffer (shutdown). */
+  clear(): void {
+    for (const p of this.pending.values()) clearTimeout(p.timer);
+    this.pending.clear();
+  }
+
+  private async flush(key: string): Promise<void> {
+    const entry = this.pending.get(key);
+    if (!entry) return;
+    this.pending.delete(key);
+    const first = entry.messages[0];
+    if (!first) return;
+    const threadId = first.threadRootId;
+    const texts = entry.messages.map((m) => m.body).filter((b) => b.trim());
+    const attachments = entry.messages.flatMap((m) =>
+      m.attachment ? [m.attachment] : [],
+    );
+    // A file-only send still needs a user message the agent can act on —
+    // the Node bridge's wording.
+    const message =
+      texts.length > 0
+        ? texts.join('\n')
+        : attachments.length === 1
+          ? `User shared a file: ${attachments[0]?.filename ?? 'file'}`
+          : `User shared ${attachments.length} file(s): ${attachments.map((a) => a.filename).join(', ')}`;
+    const turn: IngestTurn = {
+      userDid: entry.userDid,
+      matrixUserId: first.sender,
+      roomId: first.roomId,
+      sessionId: sessionIdFor(first.roomId, threadId),
+      message,
+      eventIds: entry.messages.map((m) => m.eventId),
+      ...(threadId ? { threadId } : {}),
+      ...(attachments.length > 0 ? { attachments } : {}),
+    };
+    try {
+      await this.deps.dispatch(turn);
+    } catch (err) {
+      this.deps.onError?.(err, `dispatch ${turn.sessionId}`);
+    }
+  }
+}

package/src/matrix/replay-format.ts

@@ -0,0 +1,34 @@
+/**
+ * Room replay formatting — a port of `@ixo/matrix`'s `formatMsg`. The Node
+ * runtime replays every HTTP/SSE turn into the user's oracle room as a thread
+ * under the session's root event: the user message prefixed `**You:**`, the
+ * reply prefixed with the oracle's name, both rendered to HTML with marked.
+ */
+import { marked } from 'marked';
+
+export interface FormatReplayParams {
+  message: string;
+  /** `true` for the oracle's reply, `false` for the user's message. */
+  isOracle: boolean;
+  oracleName?: string;
+  /** Skip the speaker prefix (Node's `disablePrefix`). */
+  disablePrefix?: boolean;
+}
+
+export interface FormattedReplay {
+  body: string;
+  formattedBody: string;
+}
+
+export function formatReplay({
+  message,
+  isOracle,
+  oracleName = 'Oracle',
+  disablePrefix = false,
+}: FormatReplayParams): FormattedReplay {
+  const body = disablePrefix
+    ? message
+    : `**${isOracle ? oracleName : 'You'}:**\n${message}`;
+  const formattedBody = marked.parse(body, { gfm: true, async: false });
+  return { body, formattedBody };
+}

package/src/matrix/reply-chain.ts

@@ -0,0 +1,109 @@
+/**
+ * Quote-reply → thread resolution — the port of the Node listener bridge's
+ * `getThreadRoot`. A client that quote-replies (`m.in_reply_to`) to a
+ * message that lives in a thread, without adding the `m.thread` relation
+ * itself, still means "continue that thread": walk the reply chain upward
+ * until an event that carries `m.thread` (→ its root) or a bare event.
+ *
+ * Unlike Node — where every bare room message opens its own thread-session —
+ * this runtime keeps the main timeline as ONE session (`matrix:<roomId>`), so
+ * a chain that ends on a bare event resolves to "no thread" (main timeline)
+ * rather than to that event. Results are memoised per event id with a
+ * bounded cache; cycles and missing events terminate the walk.
+ */
+
+export interface MatrixRelatesTo {
+  rel_type?: string;
+  event_id?: string;
+  'm.in_reply_to'?: { event_id?: string };
+}
+
+export function readRelatesTo(content: unknown): MatrixRelatesTo | undefined {
+  if (typeof content !== 'object' || content === null) return undefined;
+  const rel = (content as Record<string, unknown>)['m.relates_to'];
+  return typeof rel === 'object' && rel !== null ? rel : undefined;
+}
+
+export function threadRootOf(rel: MatrixRelatesTo | undefined): string | null {
+  return rel?.rel_type === 'm.thread' && typeof rel.event_id === 'string'
+    ? rel.event_id
+    : null;
+}
+
+export function inReplyToOf(rel: MatrixRelatesTo | undefined): string | null {
+  const id = rel?.['m.in_reply_to']?.event_id;
+  return typeof id === 'string' && id.length > 0 ? id : null;
+}
+
+/** Bounded event-id → thread-root ('' = main timeline) memo. */
+export class ThreadRootCache {
+  private readonly map = new Map<string, string>();
+
+  constructor(private readonly capacity = 500) {}
+
+  get(eventId: string): string | undefined {
+    return this.map.get(eventId);
+  }
+
+  set(eventId: string, root: string): void {
+    if (this.map.size >= this.capacity) {
+      const oldest = this.map.keys().next().value;
+      if (oldest !== undefined) this.map.delete(oldest);
+    }
+    this.map.set(eventId, root);
+  }
+}
+
+export interface ResolveReplyChainInput {
+  eventId: string;
+  /** The event's own relation (from the clear or wire content). */
+  relatesTo: MatrixRelatesTo | undefined;
+  /** Fetches a room event's `m.relates_to` (null when the event is unavailable). */
+  fetchRelatesTo: (eventId: string) => Promise<MatrixRelatesTo | null>;
+  cache: ThreadRootCache;
+  /** Upper bound on the walk (Node has none beyond the visited set). */
+  maxHops?: number;
+}
+
+/**
+ * Thread root for the event, or `null` for the main timeline. Never throws:
+ * a fetch failure ends the walk at the last known event (→ main timeline).
+ */
+export async function resolveReplyChainRoot(
+  input: ResolveReplyChainInput,
+): Promise<string | null> {
+  const { eventId, relatesTo, fetchRelatesTo, cache } = input;
+  const maxHops = input.maxHops ?? 25;
+  const remember = (ids: string[], root: string | null): string | null => {
+    for (const id of ids) cache.set(id, root ?? '');
+    return root;
+  };
+
+  const own = threadRootOf(relatesTo);
+  if (own) return remember([eventId], own);
+  const firstParent = inReplyToOf(relatesTo);
+  if (!firstParent) return remember([eventId], null);
+
+  const path = [eventId];
+  const visited = new Set<string>([eventId]);
+  let cursor: string | null = firstParent;
+  let hops = 0;
+  while (cursor && !visited.has(cursor) && hops < maxHops) {
+    hops += 1;
+    visited.add(cursor);
+    path.push(cursor);
+    const known = cache.get(cursor);
+    if (known !== undefined) return remember(path, known === '' ? null : known);
+    let parentRel: MatrixRelatesTo | null;
+    try {
+      parentRel = await fetchRelatesTo(cursor);
+    } catch {
+      parentRel = null;
+    }
+    if (parentRel === null) return remember(path, null);
+    const parentRoot = threadRootOf(parentRel);
+    if (parentRoot) return remember(path, parentRoot);
+    cursor = inReplyToOf(parentRel);
+  }
+  return remember(path, null);
+}

package/src/matrix/room-state-codec.ts

@@ -0,0 +1,115 @@
+/**
+ * Wire codec for `ixo.room.state` events — byte-compatible with the Node
+ * runtime's `@ixo/matrix` `MatrixStateManager`, which is what the Portal,
+ * the Node oracle and every other IXO service read and write:
+ *
+ *   content = { data: base64( zlib-deflate( superjson.stringify(value) ) ) }
+ *
+ * Both runtimes share rooms (a user migrated from Node keeps the same
+ * user↔oracle room), so anything this runtime persists as room state MUST
+ * round-trip through the Node codec and vice versa — the UCAN delegation
+ * (`ucan_delegation`) and the user preferences (`user_prefs`) in particular.
+ *
+ * Reads are lenient, mirroring the Node manager's fallbacks:
+ *   1. `{ data: <compressed superjson> }` — the current format;
+ *   2. `{ data: <uncompressed superjson string> }` — the Node legacy format;
+ *   3. a plain JSON object — what earlier builds of this runtime wrote
+ *      (kept readable so nothing deposited before the codec is lost);
+ *   4. `{}` / missing → `null` (a cleared key).
+ *
+ * zlib "deflate" is the format Node's `deflateSync` emits and the Web
+ * `CompressionStream('deflate')` produces — the same 2-byte zlib header and
+ * Adler-32 trailer — so no Node polyfill is needed on workerd.
+ */
+import { parse, stringify } from 'superjson';
+import { base64ToBytes, bytesToBase64 } from '../plugins/base64';
+
+/** The state event type every IXO room-state key lives under. */
+export const ROOM_STATE_EVENT_TYPE = 'ixo.room.state';
+
+/** The compressed room-state envelope. */
+export interface RoomStateEnvelope {
+  data: string;
+}
+
+function bytesToStream(bytes: Uint8Array): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+async function streamToBytes(
+  stream: ReadableStream<Uint8Array>,
+): Promise<Uint8Array> {
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/** zlib-format deflate (what Node's `deflateSync` produces). */
+export async function deflate(bytes: Uint8Array): Promise<Uint8Array> {
+  return streamToBytes(
+    bytesToStream(bytes).pipeThrough(new CompressionStream('deflate')),
+  );
+}
+
+/** zlib-format inflate. Rejects on malformed input. */
+export async function inflate(bytes: Uint8Array): Promise<Uint8Array> {
+  return streamToBytes(
+    bytesToStream(bytes).pipeThrough(new DecompressionStream('deflate')),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * superjson's `parse` yields `undefined` for a JSON document that is not a
+ * superjson envelope (no `json` key). Treat that — and `null` — as "nothing
+ * stored" so callers get one absent value.
+ */
+function normalise(value: unknown): unknown {
+  return value === undefined ? null : value;
+}
+
+/**
+ * Encode a value the way the Node runtime does. The result is the state
+ * event's `content`.
+ */
+export async function encodeRoomStateContent(
+  value: unknown,
+): Promise<RoomStateEnvelope> {
+  const serialized = new TextEncoder().encode(stringify(value));
+  return { data: bytesToBase64(await deflate(serialized)) };
+}
+
+/**
+ * Decode a state event's `content` (any of the formats listed above) into
+ * the stored value, or `null` when nothing (readable) is stored. Never
+ * throws on malformed input: an unreadable payload is reported as absent,
+ * matching the Node manager's "return undefined + warn" behaviour.
+ */
+export async function decodeRoomStateContent(
+  content: unknown,
+): Promise<unknown> {
+  if (!isRecord(content)) return null;
+  const data = content['data'];
+  if (typeof data === 'string') {
+    if (data.length === 0) return null;
+    try {
+      const inflated = await inflate(base64ToBytes(data));
+      return normalise(parse(new TextDecoder().decode(inflated)));
+    } catch {
+      // Not compressed — fall through to the legacy uncompressed form.
+    }
+    try {
+      return normalise(parse(data));
+    } catch {
+      return null;
+    }
+  }
+  // Plain JSON written by earlier builds of this runtime (pre-codec).
+  return Object.keys(content).length === 0 ? null : content;
+}

package/src/matrix/user-homeserver.ts

@@ -0,0 +1,106 @@
+/**
+ * Which Matrix homeserver does a user live on?
+ *
+ * The user↔oracle room alias is `#<user>_<oracle>:<SERVER>` where SERVER is the
+ * USER's homeserver, not the oracle's — an oracle on `mx.example` serving a
+ * user registered on `devmx.ixo.earth` must look the room up as
+ * `#…:devmx.ixo.earth`. The Node runtime reads it per user from the DID
+ * document's `MatrixHomeServer` service via Blocksync
+ * (`getMatrixHomeServerCroppedForDid`); this is the Workers port, with the
+ * same normalisation of the user-supplied `serviceEndpoint`.
+ */
+
+export const MATRIX_SERVICE_TYPE = 'MatrixHomeServer';
+
+export interface DidService {
+  id?: string;
+  type?: string;
+  serviceEndpoint?: string;
+}
+
+/**
+ * On-chain `serviceEndpoint` values are registration-supplied and have been
+ * seen with trailing slashes and stray whitespace/CRLF. Strip whitespace, add
+ * `https://` to bare domains, drop trailing slashes. "" for empty input.
+ */
+export function normalizeMatrixHomeServerUrl(
+  url: string | null | undefined,
+): string {
+  if (!url) return '';
+  const trimmed = url.replace(/\s+/g, '');
+  if (trimmed === '') return '';
+  const withProtocol = /^https?:\/\//.test(trimmed)
+    ? trimmed
+    : `https://${trimmed}`;
+  return withProtocol.replace(/\/+$/, '');
+}
+
+/** `https://devmx.ixo.earth/` → `devmx.ixo.earth` (the Matrix server name). */
+export function extractUrlDomain(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    const cleaned = url.replace(/^https?:\/\//, '');
+    return cleaned.split('/')[0] ?? cleaned;
+  }
+}
+
+/** The server name from a DID document's services, or null when it has none. */
+export function matrixServerNameFromServices(
+  services: readonly DidService[] | null | undefined,
+): string | null {
+  const svc = (services ?? []).find((s) => s.type === MATRIX_SERVICE_TYPE);
+  const normalized = normalizeMatrixHomeServerUrl(svc?.serviceEndpoint);
+  if (!normalized) return null;
+  const domain = extractUrlDomain(normalized);
+  return domain ? domain.toLowerCase() : null;
+}
+
+const IID_SERVICES_QUERY = `
+  query UserMatrixHomeServer($id: String!) {
+    iids(filter: { id: { equalTo: $id } }) {
+      nodes { id service }
+    }
+  }
+`;
+
+/**
+ * Resolve a user's Matrix server name from Blocksync. Returns null when the
+ * DID is unknown or carries no MatrixHomeServer service; throws on transport
+ * failure so callers can decide whether to fall back.
+ */
+export async function fetchUserMatrixServerName(
+  blocksyncGraphqlUrl: string,
+  userDid: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<string | null> {
+  const res = await fetchImpl(blocksyncGraphqlUrl, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      query: IID_SERVICES_QUERY,
+      variables: { id: userDid },
+    }),
+  });
+  if (!res.ok) {
+    throw new Error(
+      `Blocksync ${res.status} resolving MatrixHomeServer for ${userDid}`,
+    );
+  }
+  const raw: unknown = await res.json();
+  const body = raw as {
+    data?: { iids?: { nodes?: Array<{ id: string; service?: unknown }> } };
+    errors?: Array<{ message?: string }>;
+  };
+  if (body.errors?.length) {
+    throw new Error(
+      `Blocksync error resolving MatrixHomeServer for ${userDid}: ${body.errors[0]?.message ?? 'unknown'}`,
+    );
+  }
+  const node = body.data?.iids?.nodes?.[0];
+  if (!node) return null;
+  const services: DidService[] = Array.isArray(node.service)
+    ? node.service
+    : [];
+  return matrixServerNameFromServices(services);
+}