@ixo/oracle-runtime-workers 0.2.0

package/README.md

@@ -0,0 +1,110 @@
+# @ixo/oracle-runtime-workers
+
+Run a QiForge oracle on **Cloudflare Workers** — no server, no disk, no Redis.
+The same plugin API, wire protocol and UCAN auth as `@ixo/oracle-runtime`,
+re-hosted on Durable Objects.
+
+```ts
+// src/index.ts of your oracle Worker
+import { createOracleWorker, WeatherPlugin } from '@ixo/oracle-runtime-workers';
+
+const oracle = createOracleWorker({
+  config: { name: 'My Oracle', org: 'IXO', description: '…' },
+  plugins: [new WeatherPlugin()],
+});
+
+export const { UserOracleDO, MatrixGatewayDO } = oracle;
+export default oracle; // { fetch, scheduled }
+```
+
+Deploying is `wrangler deploy` with two Durable Object bindings and a
+handful of secrets. [`apps/qiforge-workers-example`](../../apps/qiforge-workers-example)
+is the complete, runnable reference: the single-script `wrangler.jsonc` for
+local development, the two-script devnet configs, `.dev.vars.example`, and
+the test suites.
+
+## How it works
+
+One Worker deployment = one oracle.
+
+```mermaid
+graph LR
+    Client[Portal / SDK / curl] -->|HTTP + SSE, UCAN auth| Shell[Hono shell]
+    Shell -->|per user DID| UserDO[UserOracleDO × N users]
+    Matrix[(Matrix homeserver)] <-->|/sync, E2EE| Gateway[MatrixGatewayDO × 1]
+    Gateway -->|decrypted turn| UserDO
+    UserDO -->|reply / media| Gateway
+    UserDO -->|export .db.gz| Owner[User-owned file in the IXO VFS]
+```
+
+- **`UserOracleDO`** — one per user DID. The user's SQLite database
+  (checkpoints, sessions, transcript) lives in Durable Object storage behind
+  wa-sqlite; the object runs the agent turn and streams SSE itself.
+- **`MatrixGatewayDO`** — one per oracle. A subclass of `MatrixBotDO` from
+  [`@ixo/matrix-bot-workers-sdk`](https://www.npmjs.com/package/@ixo/matrix-bot-workers-sdk),
+  which owns the bot identity, E2EE, the sync loop, paced durable sends,
+  catch-up after a restart and device rotation. The subclass adds the
+  oracle parts: room messages → user turns, room ↔ user routing, snapshot
+  media, the account-room secrets key, the plugins' second device.
+- **The user owns the file.** The object holds a working copy; the durable
+  file is `/.oracles/<oracleDid>/state.db.gz` in the user's IXO VFS,
+  exported on a debounced alarm and re-imported on a cold boot.
+- **Two scripts in production.** The gateway runs in its own Worker script
+  so its memory footprint never competes with user objects; the scripts
+  talk over cross-script Durable Object bindings.
+
+## Deploy in five steps
+
+1. Copy the example's `wrangler.gateway.<env>.jsonc` and
+   `wrangler.<env>.jsonc`; set the names, `ORACLE_DID`, `ORACLE_ENTITY_DID`,
+   `MATRIX_*` vars and the plugin URLs.
+2. Deploy the gateway script, then its secrets
+   (`MATRIX_ORACLE_ADMIN_PASSWORD`, `MATRIX_RECOVERY_PHRASE`,
+   `MATRIX_VALUE_PIN`).
+3. Deploy the oracle script with its secrets (`OPEN_ROUTER_API_KEY`, the
+   same Matrix secrets, `ORACLE_SIGNING_MNEMONIC`).
+4. `POST /matrix/start`, then `GET /matrix/status` until `running` and
+   `cryptoReady` are true.
+5. Run the feature matrix against it (see [testing](docs/testing.md)).
+
+Every variable, binding and migration is explained in
+[configuration](docs/configuration.md).
+
+## Operate
+
+| Route                                                 | Purpose                                               |
+| ----------------------------------------------------- | ----------------------------------------------------- |
+| `GET /health`, `GET /health/matrix`                   | Liveness; the gateway's health (503 when not running) |
+| `GET /matrix/status`, `POST /matrix/start`            | Gateway status and start                              |
+| `POST/GET /sessions`, `POST/GET /messages/:id`        | The chat API                                          |
+| `/delegation`, `/models`, `/socket.io/`, `/byo-llm/*` | Delegation, models, realtime channel, BYO LLM         |
+| `/debug/*` (with `ORACLE_DEBUG_ROUTES=true`)          | Storage, tasks, sockets, outbox, gateway restart      |
+
+The status fields, the runbook and the behaviour of both objects over their
+lifetime are in [operations](docs/operations.md).
+
+## Documentation
+
+| Page                                   | What it covers                                                                           |
+| -------------------------------------- | ---------------------------------------------------------------------------------------- |
+| [architecture](docs/architecture.md)   | The objects, the gateway split, self-sovereign storage, cost model, the rules of workerd |
+| [node-parity](docs/node-parity.md)     | What is identical to the Node runtime, what is ported differently, what is not ported    |
+| [configuration](docs/configuration.md) | Wrangler config, migrations, every env var, first-time setup, the bot's send rate        |
+| [operations](docs/operations.md)       | Routes, status fields, gateway and user-object lifecycle, the ChatGPT proxy, the runbook |
+| [testing](docs/testing.md)             | Unit, harness e2e, the devnet feature matrix, stress                                     |
+| [load-tests](docs/load-tests.md)       | Measurements and the findings that shaped the gateway                                    |
+
+## Status (September 2026)
+
+- Deployed on devnet as `mike-devnet-oracle` + `mike-devnet-oracle-gateway`
+  and exercised by the full feature matrix and the 18-user stress run after
+  the move to `@ixo/matrix-bot-workers-sdk`; 0.1.3 is the first release fit
+  for production (0.1.0–0.1.2 could send plaintext into an encrypted room
+  after a lazy-member sync delta, and queued session markers behind
+  background replays — both fixed in 0.1.3 and re-measured, see
+  [load-tests](docs/load-tests.md#session-creation-is-the-one-funnel)).
+- Open: the memory engine's recall ranking on accounts with a long history;
+  the storage cost of task-holding users at scale (R2 page tier, see
+  [architecture](docs/architecture.md#storage-cost-planning)).
+- Not ported on purpose: the Slack transport, the commerce lane and Matrix
+  group chats — see [node-parity](docs/node-parity.md#not-ported).

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@ixo/oracle-runtime-workers",
+  "version": "0.2.0",
+  "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ixoworld/qiforge.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:core": "vitest run --config vitest.core.config.ts",
+    "lint": "eslint 'src/**/*.ts'"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./gateway": "./src/gateway-worker.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__/",
+    "!src/**/fixtures/",
+    "!src/**/test-do.ts",
+    "!src/core/test-fixtures.ts"
+  ],
+  "dependencies": {
+    "@blocknote/server-util": "0.29.1",
+    "@composio/core": "0.10.0",
+    "@composio/langchain": "0.9.2",
+    "@ixo/editor": "6.0.1",
+    "@ixo/matrix-bot-workers-sdk": "0.1.3",
+    "@ixo/matrix-crdt": "^1.2.5",
+    "@ixo/ucan": "workspace:*",
+    "@langchain/core": "1.1.48",
+    "@langchain/langgraph": "1.3.2",
+    "@langchain/langgraph-checkpoint": "1.0.2",
+    "@langchain/mcp-adapters": "1.1.3",
+    "@langchain/openai": "1.4.7",
+    "@noble/hashes": "^1.8.0",
+    "cron-parser": "^5.5.0",
+    "gray-matter": "^4.0.3",
+    "hono": "^4.13.4",
+    "jose": "^6.0.0",
+    "langchain": "1.4.2",
+    "langsmith": "^0.5.26",
+    "linkedom": "^0.18.12",
+    "marked": "^16.4.0",
+    "matrix-js-sdk": "^42.2.0",
+    "superjson": "1.13.3",
+    "wa-sqlite": "1.0.0",
+    "yjs": "^13.6.27",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.22.0",
+    "@cloudflare/workers-types": "^5.20260825.1",
+    "@ixo/typescript-config": "workspace:*",
+    "happy-dom": "^19.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.0",
+    "wrangler": "^4.125.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  }
+}

package/src/attachments/classify.ts

@@ -0,0 +1,114 @@
+/**
+ * Classify an attachment into a coarse `kind` from its mimetype (primary) and
+ * filename extension (fallback for generic mimetypes like
+ * `application/octet-stream`). The kind drives routing in `route.ts`.
+ * Verbatim port of the Node runtime's `attachments/classify.ts`.
+ *
+ * `text` means "plain text we can read ourselves for free" (csv/txt/json/md/…)
+ * — deliberately separate from `document` (pdf/office), which is richer and
+ * either sent to the model natively or extracted by the helper model.
+ */
+
+export type AttachmentKind =
+  | 'text'
+  | 'document'
+  | 'image'
+  | 'audio'
+  | 'video'
+  | 'unknown';
+
+const TEXT_MIMES = new Set([
+  'application/json',
+  'application/ld+json',
+  'application/xml',
+  'application/rtf',
+  'application/yaml',
+  'application/x-yaml',
+  'application/csv',
+]);
+const TEXT_EXTENSIONS = new Set([
+  'txt',
+  'csv',
+  'tsv',
+  'json',
+  'md',
+  'markdown',
+  'xml',
+  'yaml',
+  'yml',
+  'log',
+  'html',
+  'htm',
+  'rtf',
+]);
+
+const DOCUMENT_MIMES = new Set([
+  'application/pdf',
+  'application/msword',
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  'application/vnd.ms-excel',
+  'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  'application/vnd.ms-powerpoint',
+  'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+]);
+const DOCUMENT_EXTENSIONS = new Set([
+  'pdf',
+  'doc',
+  'docx',
+  'xls',
+  'xlsx',
+  'ppt',
+  'pptx',
+]);
+
+const IMAGE_EXTENSIONS = new Set([
+  'jpg',
+  'jpeg',
+  'png',
+  'gif',
+  'webp',
+  'bmp',
+  'tiff',
+  'tif',
+  'heic',
+  'svg',
+]);
+const AUDIO_EXTENSIONS = new Set([
+  'mp3',
+  'wav',
+  'ogg',
+  'oga',
+  'm4a',
+  'flac',
+  'aac',
+]);
+const VIDEO_EXTENSIONS = new Set(['mp4', 'mov', 'avi', 'mkv', 'webm', 'm4v']);
+
+function extensionOf(filename: string): string {
+  const dot = filename.lastIndexOf('.');
+  return dot >= 0 ? filename.slice(dot + 1).toLowerCase() : '';
+}
+
+export function classifyAttachment(input: {
+  mimetype: string;
+  filename: string;
+}): AttachmentKind {
+  const mime = input.mimetype.toLowerCase();
+  const ext = extensionOf(input.filename);
+
+  // Plain text first — cheap to read locally, and it should win over a generic
+  // `application/*` classification (e.g. a `.csv` sent as octet-stream).
+  if (
+    mime.startsWith('text/') ||
+    TEXT_MIMES.has(mime) ||
+    TEXT_EXTENSIONS.has(ext)
+  ) {
+    return 'text';
+  }
+  if (mime.startsWith('image/') || IMAGE_EXTENSIONS.has(ext)) return 'image';
+  if (mime.startsWith('audio/') || AUDIO_EXTENSIONS.has(ext)) return 'audio';
+  if (mime.startsWith('video/') || VIDEO_EXTENSIONS.has(ext)) return 'video';
+  if (DOCUMENT_MIMES.has(mime) || DOCUMENT_EXTENSIONS.has(ext))
+    return 'document';
+  return 'unknown';
+}

package/src/attachments/content-blocks.ts

@@ -0,0 +1,51 @@
+import type { MessageContent } from '@langchain/core/messages';
+
+/**
+ * An attachment we send to the model natively (base64). Only `image` and `file`
+ * are wired — the proven LangChain→OpenRouter path (same as the Node runtime).
+ */
+export interface NativeAttachment {
+  kind: 'image' | 'file';
+  mimeType: string;
+  base64: string;
+  filename: string;
+}
+
+/**
+ * Build the user message `content`. With no native attachments it stays a plain
+ * string (unchanged behaviour). Otherwise it becomes a LangChain "data content
+ * block" array: the text, then one block per attachment.
+ *
+ * The blocks MUST use `source_type: 'base64'` + snake_case `mime_type` — that is
+ * the only shape the `@langchain/openai` completions converter (the OpenRouter
+ * path) recognises; it emits `image_url: data:<mime>;base64,<data>` for images
+ * and `file_data` for files. camelCase or a missing `source_type` silently
+ * drops the attachment.
+ */
+export function buildUserMessageContent(
+  text: string,
+  natives: NativeAttachment[],
+): MessageContent {
+  if (natives.length === 0) return text;
+
+  const content: MessageContent = [
+    { type: 'text', text },
+    ...natives.map((native) =>
+      native.kind === 'image'
+        ? {
+            type: 'image',
+            source_type: 'base64',
+            mime_type: native.mimeType,
+            data: native.base64,
+          }
+        : {
+            type: 'file',
+            source_type: 'base64',
+            mime_type: native.mimeType,
+            data: native.base64,
+            filename: native.filename,
+          },
+    ),
+  ];
+  return content;
+}

package/src/attachments/download.ts

@@ -0,0 +1,235 @@
+/**
+ * Fetching attachment bytes — Matrix media (through the gateway, which holds
+ * the authenticated client and the room keys) and plain `http(s)` URLs with
+ * the Node runtime's SSRF guard, manual redirect validation and streaming
+ * size cap.
+ */
+import { detectMimeFromMagicBytes } from './magic';
+import type { AttachmentInput } from './types';
+
+export const MAX_FILE_SIZE = 25 * 1024 * 1024; // 25 MB per file
+export const MAX_TOTAL_SIZE = 50 * 1024 * 1024; // 50 MB across all attachments
+export const ALLOWED_URI_SCHEMES = /^(mxc|https?):\/\//i;
+const MAX_REDIRECT_COUNT = 5;
+const DOWNLOAD_TIMEOUT_MS = 60_000;
+
+/** Blocks redirects to internal / cloud-metadata addresses (SSRF). */
+const BLOCKED_HOST_PATTERNS = [
+  /^localhost$/i,
+  /^127\.\d+\.\d+\.\d+$/,
+  /^10\.\d+\.\d+\.\d+$/,
+  /^172\.(1[6-9]|2\d|3[01])\.\d+\.\d+$/,
+  /^192\.168\.\d+\.\d+$/,
+  /^169\.254\.\d+\.\d+$/, // AWS/cloud metadata
+  /^0\.0\.0\.0$/,
+  /^\[::1?\]$/, // IPv6 loopback (bracketed)
+  /^\[::ffff:[^\]]+\]$/i, // IPv4-mapped IPv6
+  /^\[f[cd][0-9a-f]{2}:.*\]$/i, // IPv6 unique-local (fc00::/7)
+  /^\[fe[89ab][0-9a-f]:.*\]$/i, // IPv6 link-local (fe80::/10)
+  /^metadata\.google\.internal$/i,
+];
+
+/** Throws when the URL is not http(s) or points at a blocked internal host. */
+export function validateUrlTarget(targetUrl: string): void {
+  let parsed: URL;
+  try {
+    parsed = new URL(targetUrl);
+  } catch {
+    throw new Error('Invalid URL');
+  }
+  if (!['http:', 'https:'].includes(parsed.protocol)) {
+    throw new Error(`Blocked URL scheme: ${parsed.protocol}`);
+  }
+  for (const pattern of BLOCKED_HOST_PATTERNS) {
+    if (pattern.test(parsed.hostname)) {
+      throw new Error('URL points to a blocked internal address');
+    }
+  }
+}
+
+/**
+ * Matrix media access the pipeline needs. Implemented over the gateway
+ * Durable Object in the user object; tests pass an in-memory fake.
+ */
+export interface MatrixMediaSource {
+  /** Raw bytes behind an `mxc://` URI (authenticated media download). */
+  downloadMxc(mxc: string): Promise<Uint8Array>;
+  /**
+   * Bytes of the media event `eventId` in `roomId`, decrypted when the event
+   * carries an encrypted `file`. Null when the event does not exist.
+   */
+  downloadEvent(
+    roomId: string,
+    eventId: string,
+  ): Promise<{
+    bytes: Uint8Array;
+    mimetype?: string;
+    filename?: string;
+  } | null>;
+}
+
+export interface DownloadOptions {
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  maxBytes?: number;
+}
+
+/** A controller that aborts on `signal` OR after `timeoutMs`, whichever first. */
+function boundedSignal(
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+): { signal: AbortSignal; release: () => void } {
+  const controller = new AbortController();
+  const onAbort = (): void => controller.abort();
+  if (signal?.aborted) controller.abort();
+  signal?.addEventListener('abort', onAbort);
+  const timer = setTimeout(onAbort, timeoutMs);
+  return {
+    signal: controller.signal,
+    release: () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    },
+  };
+}
+
+function concat(chunks: Uint8Array[], total: number): Uint8Array {
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+/**
+ * Download an http(s) URL: every redirect hop is SSRF-validated, the body is
+ * streamed with a running size check so an oversized file never lands in
+ * memory whole.
+ */
+export async function downloadFromUrl(
+  url: string,
+  opts: DownloadOptions = {},
+): Promise<{ data: Uint8Array; contentType?: string; finalUrl?: string }> {
+  validateUrlTarget(url);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const maxBytes = opts.maxBytes ?? MAX_FILE_SIZE;
+  const bound = boundedSignal(
+    opts.signal,
+    opts.timeoutMs ?? DOWNLOAD_TIMEOUT_MS,
+  );
+  try {
+    let currentUrl = url;
+    let response: Response | undefined;
+    for (let i = 0; i <= MAX_REDIRECT_COUNT; i += 1) {
+      response = await fetchImpl(currentUrl, {
+        signal: bound.signal,
+        redirect: 'manual',
+      });
+      const location = response.headers.get('location');
+      if (response.status >= 300 && response.status < 400 && location) {
+        currentUrl = new URL(location, currentUrl).toString();
+        validateUrlTarget(currentUrl);
+        continue;
+      }
+      break;
+    }
+    if (!response || (response.status >= 300 && response.status < 400)) {
+      throw new Error('Too many redirects');
+    }
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} downloading ${url}`);
+    }
+    const contentType =
+      response.headers.get('content-type')?.split(';')[0]?.trim() ?? undefined;
+    const contentLength = response.headers.get('content-length');
+    if (contentLength && parseInt(contentLength, 10) > maxBytes) {
+      throw new Error(
+        `File too large: server reports ${Math.round(parseInt(contentLength, 10) / 1024 / 1024)} MB (limit: ${Math.round(maxBytes / 1024 / 1024)} MB)`,
+      );
+    }
+    const reader = response.body?.getReader();
+    if (!reader) throw new Error('Response body is not readable');
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        void reader.cancel();
+        throw new Error(
+          `File exceeds maximum size (${Math.round(maxBytes / 1024 / 1024)} MB) — download aborted`,
+        );
+      }
+      chunks.push(value);
+    }
+    return {
+      data: concat(chunks, total),
+      contentType,
+      ...(currentUrl !== url ? { finalUrl: currentUrl } : {}),
+    };
+  } finally {
+    bound.release();
+  }
+}
+
+/**
+ * Bytes for one attachment from whichever source it names, with the per-file
+ * cap enforced before and after the transfer. `mimetype` is the best-known
+ * type: content sniffing, then the HTTP `content-type`, then the client's
+ * claim.
+ */
+export async function loadAttachmentBytes(
+  attachment: AttachmentInput,
+  roomId: string | undefined,
+  source: MatrixMediaSource,
+  opts: DownloadOptions = {},
+): Promise<{ bytes: Uint8Array; mimetype: string }> {
+  if (!attachment.eventId && !attachment.mxcUri) {
+    throw new Error('Either mxcUri or eventId must be provided');
+  }
+  if (attachment.mxcUri && !ALLOWED_URI_SCHEMES.test(attachment.mxcUri)) {
+    throw new Error('Invalid URI scheme');
+  }
+  const maxBytes = opts.maxBytes ?? MAX_FILE_SIZE;
+  if (attachment.size && attachment.size > maxBytes) {
+    throw new Error('File exceeds maximum size');
+  }
+
+  let bytes: Uint8Array;
+  let httpType: string | undefined;
+  if (attachment.eventId) {
+    if (!roomId)
+      throw new Error(
+        `Cannot fetch event ${attachment.eventId}: no Matrix room for this turn`,
+      );
+    const media = await source.downloadEvent(roomId, attachment.eventId);
+    if (!media) throw new Error(`Matrix event ${attachment.eventId} not found`);
+    bytes = media.bytes;
+    httpType = media.mimetype;
+  } else if (attachment.mxcUri!.startsWith('mxc://')) {
+    bytes = await source.downloadMxc(attachment.mxcUri!);
+  } else {
+    const result = await downloadFromUrl(attachment.mxcUri!, {
+      ...opts,
+      maxBytes,
+    });
+    bytes = result.data;
+    httpType = result.contentType;
+  }
+  if (bytes.length > maxBytes) {
+    throw new Error('File exceeds maximum size');
+  }
+  const sniffed = detectMimeFromMagicBytes(bytes);
+  return {
+    bytes,
+    mimetype:
+      sniffed ??
+      (httpType && httpType !== 'application/octet-stream'
+        ? httpType
+        : attachment.mimetype),
+  };
+}