@ixo/oracle-runtime-workers 0.13.0 → 0.15.0

package/README.md

@@ -2,7 +2,11 @@
 
 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.
+re-hosted on Durable Objects. This is the only maintained runtime: the Node
+runtime is deprecated, and what differs from it is in
+[node-parity](docs/node-parity.md). Bounded semantic Decisions are included too, and
+can run on Workers AI through the `AI` binding instead of account credentials
+(see [configuration](docs/configuration.md#decisions)).
 
 ```ts
 // src/index.ts of your oracle Worker
@@ -53,7 +57,8 @@ graph LR
   exported on a debounced alarm and re-imported on a cold boot. The oracle
   reaches it with the one delegation the user deposits for it
   (`POST /delegation`), which must carry `ixo:filesystem/.oracles` next to
-  the plugin grants — see [architecture](docs/architecture.md#self-sovereign-storage).
+  the plugin grants and must expire (a delegation with no expiry is refused)
+  — see [architecture](docs/architecture.md#self-sovereign-storage).
 - **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.
@@ -84,7 +89,13 @@ Every variable, binding and migration is explained in
 | `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                                          |
+| `GET /runs/:runId`, `GET /sessions/:id/messages`      | Re-join a durable run; one page of a transcript       |
 | `/delegation`, `/models`, `/socket.io/`, `/byo-llm/*` | Delegation, models, realtime channel, BYO LLM         |
+| `POST /channels/turn`                                 | IXO Channels ingress (its own channel UCAN policy)    |
+| `POST /messages/:sessionId/:messageId/feedback`       | Anonymous feedback on a reply (when configured)       |
+| `/topic-deliverables/:operationId`                    | Owner-only Topic deliverables (when enabled)          |
+| `GET /a/:id`, `GET /a/:id/data`                       | Artefact links opened from chat apps (public)         |
+| `GET/DELETE /artifacts/:id`                           | An artefact's canonical copy; revoke its link         |
 | `/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
@@ -92,14 +103,19 @@ 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                                    |
+| Page                                       | What it covers                                                                                |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| [architecture](docs/architecture.md)       | The objects, the gateway split, self-sovereign storage, cost model, workerd rules, tasks      |
+| [node-parity](docs/node-parity.md)         | What is identical to the Node runtime, what differs, what is Workers-only, what is not ported |
+| [configuration](docs/configuration.md)     | Wrangler config, migrations, every env var and binding, `createOracleWorker` options, setup   |
+| [operations](docs/operations.md)           | Routes, status fields, gateway and user-object lifecycle, the ChatGPT proxy, the runbook      |
+| [chat-delivery](docs/chat-delivery.md)     | Chat replies on WhatsApp and Matrix: profiles, Reply Plans, artefacts and their links         |
+| [channels](docs/channels.md)               | The IXO Channels ingress: authorization, retries, Reply Plans, Matrix continuity              |
+| [frontend-bridge](docs/frontend-bridge.md) | Browser tools and AG-UI actions over the socket: one invocation, one socket, unknown outcomes |
+| [pod-creator](docs/pod-creator.md)         | The POD Creator plugin: roles, state in `ctx.kv`, the create path and its launch gate         |
+| [ixo-transaction](docs/ixo-transaction.md) | The opt-in wallet-signing plugin: chain ids, signing outcomes, the mainnet receipt rule       |
+| [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)
 
@@ -114,6 +130,12 @@ lifetime are in [operations](docs/operations.md).
   attachments now use (a 50 MB Node-era checkpoint no longer resets the
   user object's isolate) and the crypto-snapshot flush before every keys
   upload.
+- October 2026: the Node runtime was deprecated (pull request 330), and the
+  Workers runtime gained the IXO Channels ingress, chat delivery with
+  artefacts, request admission, supplied-context tasks and the Topic
+  deliverable API, admin-plane tools, anonymous feedback, the POD Creator
+  and ixo-transaction plugins (see the pages above and
+  [node-parity](docs/node-parity.md#workers-only)).
 - 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)).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.13.0",
+  "version": "0.15.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": {
@@ -18,7 +18,8 @@
   "types": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./gateway": "./src/gateway-worker.ts"
+    "./gateway": "./src/gateway-worker.ts",
+    "./prompt": "./src/core/prompt-composer.ts"
   },
   "files": [
     "src",
@@ -26,7 +27,8 @@
     "!src/**/__snapshots__/",
     "!src/**/fixtures/",
     "!src/**/test-do.ts",
-    "!src/core/test-fixtures.ts"
+    "!src/core/test-fixtures.ts",
+    "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
     "@blocknote/server-util": "0.29.1",
@@ -36,9 +38,9 @@
     "@ixo/matrix-bot-workers-sdk": "0.7.0",
     "@ixo/matrix-crdt": "^1.2.5",
     "@langchain/core": "1.1.48",
-    "@langchain/langgraph": "1.3.2",
-    "@langchain/langgraph-checkpoint": "1.0.2",
-    "@langchain/mcp-adapters": "1.1.3",
+    "@langchain/langgraph": "1.4.17",
+    "@langchain/langgraph-checkpoint": "1.1.5",
+    "@langchain/mcp-adapters": "1.1.4",
     "@langchain/openai": "1.4.7",
     "@noble/hashes": "^1.8.0",
     "cron-parser": "^5.5.0",
@@ -46,7 +48,7 @@
     "hono": "^4.13.4",
     "jose": "^6.0.0",
     "langchain": "1.4.2",
-    "langsmith": "^0.5.26",
+    "langsmith": "^0.6.0",
     "linkedom": "^0.18.12",
     "marked": "^16.4.0",
     "matrix-js-sdk": "^42.2.0",
@@ -54,11 +56,14 @@
     "wa-sqlite": "1.0.0",
     "yjs": "13.6.32",
     "zod": "^4.4.3",
-    "@ixo/ucan": "2.2.0"
+    "@ixo/common": "1.6.0",
+    "@ixo/ixo-transaction": "0.1.0",
+    "@ixo/ucan": "2.2.1"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",
     "@cloudflare/workers-types": "^5.20260825.1",
+    "@modelcontextprotocol/sdk": "1.30.0",
     "happy-dom": "^19.0.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0",

package/src/artifacts/config.ts

@@ -0,0 +1,158 @@
+import type { OracleWorkerEnv } from '../do/contracts';
+
+/**
+ * Links default to "anyone with the link", expiring after this many days.
+ * The decision and its review note live in the repository README.
+ */
+export const DEFAULT_ARTIFACT_TTL_DAYS = 30;
+/** Expiry is part of the policy: no setting makes a link permanent. */
+export const MAX_ARTIFACT_TTL_DAYS = 365;
+
+/** How often the cron starts a full sweep of expired share copies. */
+export const DEFAULT_ARTIFACT_SWEEP_INTERVAL_HOURS = 24;
+export const MAX_ARTIFACT_SWEEP_INTERVAL_HOURS = 168;
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+/** Where share links point: the oracle's `/a/:id`, or a shared viewer page. */
+export interface ArtifactLinkBase {
+  /** The oracle Worker's public origin; share copies are served under `/a/`. */
+  publicUrl: string;
+  /** A shared viewer page (Qi.Space). Unset → the oracle's own `/a/:id` page. */
+  viewerUrl?: string;
+}
+
+/**
+ * Artefact storage. `links` is null while no usable public origin is set:
+ * no new artefact is created then, but the ones already stored stay
+ * readable, revocable and deleted with their session, because the bucket
+ * still holds their share copies.
+ */
+export interface ArtifactStorageConfig {
+  bucket: R2Bucket;
+  ttlMs: number;
+  links: ArtifactLinkBase | null;
+}
+
+type ArtifactEnv = Pick<
+  OracleWorkerEnv,
+  | 'ARTIFACT_BUCKET'
+  | 'ORACLE_PUBLIC_URL'
+  | 'ARTIFACT_VIEWER_URL'
+  | 'ARTIFACT_LINK_TTL_DAYS'
+>;
+
+function isLocalHost(url: URL): boolean {
+  return url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+}
+
+/** https, or http on localhost: a link carries its decryption key. */
+export function isSecureUrl(raw: string): boolean {
+  try {
+    const url = new URL(raw);
+    return (
+      url.protocol === 'https:' ||
+      (url.protocol === 'http:' && isLocalHost(url))
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Null when no bucket is bound. The env schema (`src/core/env.ts`) rejects a
+ * malformed or insecure URL and an out-of-range TTL at boot; anything that
+ * still reaches here unusable is reported through `warn`, never dropped
+ * silently.
+ */
+export function artifactStorageConfig(
+  env: ArtifactEnv,
+  warn: (message: string) => void = () => undefined,
+): ArtifactStorageConfig | null {
+  const bucket = env.ARTIFACT_BUCKET;
+  if (!bucket) {
+    if (env.ORACLE_PUBLIC_URL)
+      warn(
+        '[artifacts] ORACLE_PUBLIC_URL is set but no ARTIFACT_BUCKET is bound: artefacts are off',
+      );
+    return null;
+  }
+  let links: ArtifactLinkBase | null = null;
+  if (!env.ORACLE_PUBLIC_URL)
+    warn(
+      '[artifacts] ARTIFACT_BUCKET is bound but ORACLE_PUBLIC_URL is not set: no new artefacts; stored ones stay readable and revocable',
+    );
+  else if (!isSecureUrl(env.ORACLE_PUBLIC_URL))
+    warn(
+      `[artifacts] ORACLE_PUBLIC_URL must be an https URL (http only on localhost), got ${JSON.stringify(env.ORACLE_PUBLIC_URL)}: no new artefacts; stored ones stay readable and revocable`,
+    );
+  else {
+    const viewerRaw = env.ARTIFACT_VIEWER_URL;
+    const viewer =
+      viewerRaw && isSecureUrl(viewerRaw) ? new URL(viewerRaw) : null;
+    if (viewerRaw && !viewer)
+      warn(
+        `[artifacts] ARTIFACT_VIEWER_URL must be an https URL (http only on localhost), got ${JSON.stringify(viewerRaw)}: links use the oracle's own viewer`,
+      );
+    links = {
+      publicUrl: new URL(env.ORACLE_PUBLIC_URL).origin,
+      ...(viewer ? { viewerUrl: `${viewer.origin}${viewer.pathname}` } : {}),
+    };
+  }
+  let days = DEFAULT_ARTIFACT_TTL_DAYS;
+  if (env.ARTIFACT_LINK_TTL_DAYS !== undefined) {
+    const parsed = Number(env.ARTIFACT_LINK_TTL_DAYS);
+    if (
+      Number.isInteger(parsed) &&
+      parsed >= 1 &&
+      parsed <= MAX_ARTIFACT_TTL_DAYS
+    )
+      days = parsed;
+    else
+      warn(
+        `[artifacts] ARTIFACT_LINK_TTL_DAYS must be a whole number from 1 to ${MAX_ARTIFACT_TTL_DAYS}, got ${JSON.stringify(env.ARTIFACT_LINK_TTL_DAYS)}: links last ${DEFAULT_ARTIFACT_TTL_DAYS} days`,
+      );
+  }
+  return { bucket, ttlMs: days * DAY_MS, links };
+}
+
+/**
+ * The interval between full sweeps. The env schema rejects an out-of-range
+ * value at boot; one that still reaches the cron is reported through `warn`
+ * and replaced by the default.
+ */
+export function artifactSweepIntervalMs(
+  env: Pick<OracleWorkerEnv, 'ARTIFACT_SWEEP_INTERVAL_HOURS'>,
+  warn: (message: string) => void = () => undefined,
+): number {
+  const raw = env.ARTIFACT_SWEEP_INTERVAL_HOURS;
+  if (raw === undefined) return DEFAULT_ARTIFACT_SWEEP_INTERVAL_HOURS * HOUR_MS;
+  const hours = Number(raw);
+  if (
+    Number.isInteger(hours) &&
+    hours >= 1 &&
+    hours <= MAX_ARTIFACT_SWEEP_INTERVAL_HOURS
+  )
+    return hours * HOUR_MS;
+  warn(
+    `[artifacts] ARTIFACT_SWEEP_INTERVAL_HOURS must be a whole number from 1 to ${MAX_ARTIFACT_SWEEP_INTERVAL_HOURS}, got ${JSON.stringify(raw)}: sweeping every ${DEFAULT_ARTIFACT_SWEEP_INTERVAL_HOURS} hours`,
+  );
+  return DEFAULT_ARTIFACT_SWEEP_INTERVAL_HOURS * HOUR_MS;
+}
+
+/**
+ * Where a person opens an artefact. The oracle's own page reads the key from
+ * its fragment; a shared viewer also gets the source in the fragment, so its
+ * server learns nothing either.
+ */
+export function artifactLink(
+  config: ArtifactLinkBase,
+  artifactId: string,
+  key: string,
+): string {
+  const source = `${config.publicUrl}/a/${artifactId}`;
+  return config.viewerUrl
+    ? `${config.viewerUrl}#a=${encodeURIComponent(source)}&k=${key}`
+    : `${source}#k=${key}`;
+}

package/src/artifacts/crypto.ts

@@ -0,0 +1,94 @@
+/**
+ * Share-copy encryption. An artefact's share copy is AES-256-GCM ciphertext;
+ * the key travels only in the link's fragment (`#k=`), which browsers never
+ * send to a server, so the bucket, the logs and link-preview crawlers see
+ * nothing readable. Object layout: 12-byte IV, then the ciphertext.
+ */
+
+export interface ArtifactEnvelope {
+  v: 1;
+  title: string;
+  mime: 'text/markdown';
+  content: string;
+  createdAt: string;
+}
+
+const IV_BYTES = 12;
+
+export function base64url(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+export function fromBase64url(text: string): Uint8Array {
+  const padded = text.replace(/-/g, '+').replace(/_/g, '/');
+  const binary = atob(padded + '='.repeat((4 - (padded.length % 4)) % 4));
+  return Uint8Array.from(binary, (c) => c.charCodeAt(0));
+}
+
+/** A fresh 256-bit share key, base64url. */
+export function newShareKey(): string {
+  return base64url(crypto.getRandomValues(new Uint8Array(32)));
+}
+
+function importKey(
+  key: string,
+  usage: 'encrypt' | 'decrypt',
+): Promise<CryptoKey> {
+  return crypto.subtle.importKey('raw', fromBase64url(key), 'AES-GCM', false, [
+    usage,
+  ]);
+}
+
+export async function sealArtifact(
+  key: string,
+  envelope: ArtifactEnvelope,
+): Promise<Uint8Array> {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const ciphertext = new Uint8Array(
+    await crypto.subtle.encrypt(
+      { name: 'AES-GCM', iv },
+      await importKey(key, 'encrypt'),
+      new TextEncoder().encode(JSON.stringify(envelope)),
+    ),
+  );
+  const sealed = new Uint8Array(IV_BYTES + ciphertext.byteLength);
+  sealed.set(iv, 0);
+  sealed.set(ciphertext, IV_BYTES);
+  return sealed;
+}
+
+/** The viewer's decryption, for tests and the owner API. */
+export async function openArtifact(
+  key: string,
+  sealed: Uint8Array,
+): Promise<ArtifactEnvelope> {
+  const plain = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: sealed.slice(0, IV_BYTES) },
+    await importKey(key, 'decrypt'),
+    sealed.slice(IV_BYTES),
+  );
+  const parsed: unknown = JSON.parse(new TextDecoder().decode(plain));
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    !('content' in parsed) ||
+    typeof parsed.content !== 'string' ||
+    !('title' in parsed) ||
+    typeof parsed.title !== 'string' ||
+    !('createdAt' in parsed) ||
+    typeof parsed.createdAt !== 'string'
+  )
+    throw new Error('artifacts: the share copy is not a valid envelope');
+  return {
+    v: 1,
+    title: parsed.title,
+    mime: 'text/markdown',
+    content: parsed.content,
+    createdAt: parsed.createdAt,
+  };
+}

package/src/artifacts/routes.ts

@@ -0,0 +1,73 @@
+/**
+ * The public artefact routes. `GET /a/:id` is the same static page for every
+ * artefact; `GET /a/:id/data` returns the ciphertext. Neither needs auth:
+ * without the key in the link's fragment the bytes are unreadable, and any
+ * origin may fetch them (a shared viewer on Qi.Space does).
+ */
+import type { OracleWorkerEnv } from '../do/contracts';
+import { ARTIFACT_ID_RE, artifactObjectKey } from './store';
+import { viewerContentSecurityPolicy, viewerHtml } from './viewer-page';
+
+const SECURITY_HEADERS: Record<string, string> = {
+  'x-content-type-options': 'nosniff',
+  'referrer-policy': 'no-referrer',
+  'x-robots-tag': 'noindex, nofollow',
+};
+
+function notFound(): Response {
+  return new Response('Not found', {
+    status: 404,
+    headers: {
+      'content-type': 'text/plain',
+      'access-control-allow-origin': '*',
+      ...SECURITY_HEADERS,
+    },
+  });
+}
+
+export async function artifactPageResponse(
+  env: Pick<OracleWorkerEnv, 'ORACLE_NAME' | 'ARTIFACT_BUCKET'>,
+  artifactId: string,
+): Promise<Response> {
+  if (!env.ARTIFACT_BUCKET || !ARTIFACT_ID_RE.test(artifactId))
+    return notFound();
+  return new Response(viewerHtml(env.ORACLE_NAME || 'QiForge oracle'), {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'content-security-policy': await viewerContentSecurityPolicy(),
+      'cache-control': 'public, max-age=300',
+      ...SECURITY_HEADERS,
+    },
+  });
+}
+
+export async function artifactDataResponse(
+  env: Pick<OracleWorkerEnv, 'ARTIFACT_BUCKET'>,
+  artifactId: string,
+  now: number = Date.now(),
+): Promise<Response> {
+  const bucket = env.ARTIFACT_BUCKET;
+  if (!bucket || !ARTIFACT_ID_RE.test(artifactId)) return notFound();
+  const object = await bucket.get(artifactObjectKey(artifactId));
+  if (!object) return notFound();
+  const expiresAt = Date.parse(object.customMetadata?.expiresAt ?? '');
+  if (Number.isFinite(expiresAt) && expiresAt <= now) {
+    await bucket.delete(artifactObjectKey(artifactId));
+    return new Response('Expired', {
+      status: 410,
+      headers: {
+        'content-type': 'text/plain',
+        'access-control-allow-origin': '*',
+        ...SECURITY_HEADERS,
+      },
+    });
+  }
+  return new Response(object.body, {
+    headers: {
+      'content-type': 'application/octet-stream',
+      'cache-control': 'private, max-age=60',
+      'access-control-allow-origin': '*',
+      ...SECURITY_HEADERS,
+    },
+  });
+}