@ixo/oracle-runtime-workers 0.2.0

package/src/gateway-worker.ts

@@ -0,0 +1,82 @@
+/* eslint-disable no-console -- console IS the logger on Workers (Logs/observability). */
+/**
+ * Entry for a deployment that runs the Matrix gateway as its OWN Worker
+ * script (`@ixo/oracle-runtime-workers/gateway`).
+ *
+ * Every Durable Object of one script shares that script's isolate on a
+ * server, and an isolate has a 128 MB heap. In the single-script layout the
+ * gateway (matrix-js-sdk, the crypto wasm, the sync store — tens of MB that
+ * never go away) sits in the same heap as every user object on that server,
+ * so a user's flush or import spike can reset the gateway and vice versa.
+ * With the gateway in a second script it gets its own isolate and its own
+ * budget; the user script's isolate holds only user objects.
+ *
+ * The two scripts talk over cross-script Durable Object bindings
+ * (`script_name` in the wrangler config): the shell's `MATRIX_GATEWAY`
+ * binding points at this script's class, this script's `USER_ORACLE`
+ * binding points back at the shell script's user class. RPC is identical
+ * either way, so nothing in the objects changes — this entry only exports
+ * the class and a keep-alive cron. This module deliberately imports nothing
+ * from the agent side (`core/`, `plugins/`), so the gateway bundle carries no
+ * LangChain, no MCP clients and no editor code.
+ */
+import type { OracleWorkerEnv } from './do/contracts';
+import { MatrixGatewayDO } from './matrix/gateway-do';
+
+export { MatrixGatewayDO } from './matrix/gateway-do';
+
+export interface GatewayWorker {
+  fetch: (
+    request: Request,
+    env: OracleWorkerEnv,
+    ctx: ExecutionContext,
+  ) => Promise<Response>;
+  scheduled: (
+    event: ScheduledController,
+    env: OracleWorkerEnv,
+    ctx: ExecutionContext,
+  ) => Promise<void>;
+  MatrixGatewayDO: typeof MatrixGatewayDO;
+}
+
+function gatewayStub(env: OracleWorkerEnv) {
+  return env.MATRIX_GATEWAY.get(env.MATRIX_GATEWAY.idFromName(env.ORACLE_DID));
+}
+
+/**
+ * Build the gateway script's handlers. The script needs no public route
+ * (`workers_dev: false` is fine): the shell reaches the gateway through the
+ * binding, and `/matrix/status`, `/debug/matrix/*` stay on the shell. The
+ * fetch handler answers `/health` for a deployment that does get a route
+ * and 404s everything else; the cron is the keep-alive safety net, same as
+ * the single-script layout's.
+ */
+export function createGatewayWorker(): GatewayWorker {
+  return {
+    MatrixGatewayDO,
+    fetch: async (request, env, ctx) => {
+      const { pathname } = new URL(request.url);
+      if (
+        request.method === 'GET' &&
+        (pathname === '/' || pathname === '/health')
+      ) {
+        ctx.waitUntil(
+          gatewayStub(env)
+            .ensureStarted()
+            .catch((err) =>
+              console.error('[matrix] ensureStarted failed', err),
+            ),
+        );
+        return Response.json({
+          ok: true,
+          role: 'matrix-gateway',
+          oracleDid: env.ORACLE_DID,
+        });
+      }
+      return new Response('Not found', { status: 404 });
+    },
+    scheduled: async (_event, env) => {
+      await gatewayStub(env).ensureStarted();
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,237 @@
+/* eslint-disable no-console -- console IS the logger on Workers (Logs/observability). */
+/**
+ * @ixo/oracle-runtime-workers — QiForge oracles on Cloudflare Workers.
+ *
+ * An oracle is a Worker whose entry does:
+ *
+ *   const oracle = createOracleWorker({ config, plugins: [new WeatherPlugin()] });
+ *   export const { UserOracleDO, MatrixGatewayDO } = oracle;
+ *   export default oracle;   // { fetch, scheduled }
+ *
+ * plus a `wrangler.jsonc` declaring the two Durable Object bindings
+ * (`USER_ORACLE` → `UserOracleDO`, `MATRIX_GATEWAY` → `MatrixGatewayDO`,
+ * both `new_sqlite_classes`) and the crypto-wasm alias. See
+ * `apps/qiforge-workers-example`.
+ */
+import {
+  createRuntimeCore,
+  listModels,
+  type RuntimeCoreOptions,
+  type RuntimeCore,
+} from './core';
+import type { OraclePlugin } from './plugin-api';
+import type { OracleConfig } from './plugin-api/types';
+import type { OracleWorkerEnv } from './do/contracts';
+import {
+  createUserOracleDO,
+  type OracleWorkerHooks,
+} from './do/user-oracle-do';
+import { MatrixGatewayDO } from './matrix/gateway-do';
+import { createShell, gateway, type PluginRoute } from './shell/app';
+import type { RouteExclusion } from './shell/auth';
+
+export * from './plugin-api';
+export * from './plugins';
+export * from './do/contracts';
+export type { OwnerStore } from './owner-store/types';
+export { MigratingOwnerStore } from './owner-store/migrating-store';
+export { IxoVfsOwnerStore } from './owner-store/ixo-vfs-store';
+export { MatrixMediaOwnerStore } from './owner-store/matrix-media-store';
+export { MatrixGatewayDO } from './matrix/gateway-do';
+export {
+  createUserOracleDO,
+  type OracleWorkerHooks,
+} from './do/user-oracle-do';
+export { createShell } from './shell/app';
+export { authenticate } from './shell/auth';
+export {
+  createRuntimeCore,
+  createMainAgent,
+  createLlmAdapter,
+  buildModelListing,
+  fetchOpenRouterPrices,
+  listModelCatalog,
+  listModels,
+  MODEL_CATALOG,
+  WeatherPlugin,
+  SkillsPlugin,
+  type RuntimeCore,
+  type RuntimeCoreOptions,
+} from './core';
+export {
+  NEBIUS_BASE_URL,
+  NEBIUS_MODEL_MAP,
+  langsmithEnvFromWorkerEnv,
+  llmEnvFromWorkerEnv,
+  resolveLangsmithTracing,
+  type LangsmithTracingDecision,
+  type LangsmithTracingEnv,
+  type LlmProvider,
+  type ResolveLangsmithTracingArgs,
+} from './core/llm';
+
+// --- per-room JWE secrets ---------------------------------------------------
+export { decryptJwe, encryptJwe, parseJwk, type JWK } from './secrets/jwe';
+export { decryptWithPin } from './secrets/pin-cipher';
+export {
+  RUNTIME_PUBLIC_KEY_ID,
+  WorkersSecretsService,
+  type SecretIndexEntry,
+  type SecretsGateway,
+  type WorkersSecretsServiceOptions,
+} from './secrets/secrets-service';
+export { createSecretsAdapter } from './do/secrets-adapter';
+
+// --- bring-your-own-credential LLMs ----------------------------------------
+export * from './llm/byo-catalog';
+export { createByoLlmAdapter, type ByoTurnResolution } from './llm/byo-adapter';
+export {
+  ANTHROPIC_OPENAI_COMPAT_BASE_URL,
+  CHATGPT_BACKEND_BASE_URL,
+  DEEPSEEK_BASE_URL,
+  GEMINI_OPENAI_COMPAT_BASE_URL,
+  createByoChatModel,
+  type CreateByoChatModelArgs,
+} from './llm/byo-client';
+export {
+  WorkersByoService,
+  type ByoCredentialMap,
+  type ByoProviderStatus,
+  type ByoSecretsBackend,
+  type ByoStateStore,
+  type ByoTurnState,
+  type WorkersByoServiceOptions,
+} from './llm/byo-service';
+export { handleByoRequest } from './llm/byo-routes';
+export {
+  BYO_FALLBACK_KIND,
+  buildByoFallbackNotice,
+  type ByoFallbackNoticePayload,
+  type ByoFallbackReason,
+} from './llm/provider-error';
+export {
+  CHATGPT_REDIRECT_URI,
+  ChatGptOAuthError,
+  DEFAULT_CHATGPT_CLIENT_ID,
+  DEVICE_VERIFICATION_URL,
+  TOKEN_REFRESH_SKEW_MS,
+  buildAuthorizeUrl,
+  createOAuthState,
+  createPkcePair,
+  exchangeAuthorizationCode,
+  pollDeviceToken,
+  refreshChatGptTokens,
+  startDeviceAuthorization,
+  type DeviceAuthorization,
+  type DevicePollResult,
+  type PkcePair,
+} from './llm/chatgpt-oauth';
+
+export interface CreateOracleWorkerOptions {
+  config: OracleConfig;
+  plugins?: OraclePlugin[];
+  features?: RuntimeCoreOptions['features'];
+  /** Extra host routes mounted on the shell. */
+  routes?: PluginRoute[];
+  /** Host routes exempt from UCAN auth. */
+  authExcludedRoutes?: RouteExclusion[];
+  /**
+   * Overrides for the model catalog exposed on `GET /models`. Default: the
+   * curated catalog with live OpenRouter prices (`listModels`).
+   */
+  listModels?: (env: OracleWorkerEnv) => unknown | Promise<unknown>;
+  /**
+   * Host hooks for the per-turn agent build — the Node runtime's
+   * `opts.hooks.getRoomTitle` / `safetyModel`, resolved per turn against the
+   * user object's ambient services.
+   */
+  hooks?: OracleWorkerHooks;
+}
+
+export interface OracleWorker {
+  fetch: (
+    request: Request,
+    env: OracleWorkerEnv,
+    ctx: ExecutionContext,
+  ) => Promise<Response>;
+  scheduled: (
+    event: ScheduledController,
+    env: OracleWorkerEnv,
+    ctx: ExecutionContext,
+  ) => Promise<void>;
+  UserOracleDO: ReturnType<typeof createUserOracleDO>;
+  MatrixGatewayDO: typeof MatrixGatewayDO;
+  /** Resolve (and memoize per isolate) the runtime core for an env. */
+  core: (env: OracleWorkerEnv) => RuntimeCore;
+}
+
+export function createOracleWorker(
+  opts: CreateOracleWorkerOptions,
+): OracleWorker {
+  // One core per isolate per env object. Isolates are reused across requests
+  // (cheap), evicted under pressure (rebuilt on demand) — same lifetime the
+  // Node runtime's boot caches had, minus the process.
+  const cores = new WeakMap<object, RuntimeCore>();
+  const coreFor = (env: OracleWorkerEnv): RuntimeCore => {
+    let core = cores.get(env);
+    if (!core) {
+      core = createRuntimeCore({
+        config: opts.config,
+        plugins: opts.plugins ?? [],
+        features: opts.features,
+        env,
+        logger: console,
+      });
+      cores.set(env, core);
+    }
+    return core;
+  };
+
+  const apps = new WeakMap<object, ReturnType<typeof createShell>>();
+  const appFor = (env: OracleWorkerEnv) => {
+    let app = apps.get(env);
+    if (!app) {
+      const core = coreFor(env);
+      app = createShell({
+        routes: [...core.pluginRoutes, ...(opts.routes ?? [])],
+        authExcludedRoutes: [
+          ...core.authExcludedRoutes,
+          ...(opts.authExcludedRoutes ?? []),
+        ],
+        listModels: opts.listModels ?? ((e) => listModels(e)),
+        banner: {
+          name: opts.config.name,
+          description: opts.config.description,
+        },
+      });
+      apps.set(env, app);
+    }
+    return app;
+  };
+
+  const UserOracleDO = createUserOracleDO({
+    core: coreFor,
+    ...(opts.hooks ? { hooks: opts.hooks } : {}),
+  });
+
+  return {
+    UserOracleDO,
+    MatrixGatewayDO,
+    core: coreFor,
+    fetch: async (request, env, ctx) => {
+      // Make sure the Matrix bot is running; the call is idempotent and cheap
+      // once started. Done in the background so it never delays a request.
+      ctx.waitUntil(
+        gateway(env)
+          .ensureStarted()
+          .catch((err) => console.error('[matrix] ensureStarted failed', err)),
+      );
+      return appFor(env).fetch(request, env, ctx);
+    },
+    scheduled: async (_event, env) => {
+      // Cron safety net: if the gateway's keep-alive loop ever died, this
+      // restarts it. Declare a `triggers.crons` entry (e.g. every 5 minutes).
+      await gateway(env).ensureStarted();
+    },
+  };
+}

package/src/llm/byo-adapter.ts

@@ -0,0 +1,59 @@
+/**
+ * Request-scoped LLM adapter for BYO turns — the Workers port of the Node
+ * runtime's `llm/byo-adapter.ts`.
+ *
+ * The host swaps this in for `ambient.llm` on turns where the user has an
+ * active BYO credential, so every downstream consumer — the main model,
+ * sub-agents, plugin tools reading `rtCtx.llm`, and middlewares —
+ * transparently runs on the user's provider. Roles the provider cannot serve
+ * (embedding everywhere, vision on DeepSeek) fall through to the platform
+ * adapter, so those stay platform-paid.
+ *
+ * The credential is captured in this closure only; it never appears on the
+ * request context, graph state, or trace metadata.
+ */
+
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { ChatOpenAIFields, Logger, ModelRole } from '../plugin-api/types';
+import type { LlmAdapter } from '../core/runtime-context';
+import { byoModelForRole, type ByoCredential } from './byo-catalog';
+import { createByoChatModel, type ChatGptBackendConfig } from './byo-client';
+
+export interface ByoTurnResolution {
+  credential: ByoCredential;
+  /** Provider-native id serving the `main` role this turn. */
+  mainModelId: string;
+  /** ChatGPT lane only: backend/proxy the requests go to. */
+  chatGptBackend?: ChatGptBackendConfig;
+}
+
+export function createByoLlmAdapter(
+  platform: LlmAdapter,
+  turn: ByoTurnResolution,
+  logger?: Logger,
+): LlmAdapter {
+  return {
+    get(role: ModelRole, params?: ChatOpenAIFields): BaseChatModel {
+      const modelId = byoModelForRole(
+        turn.credential.provider,
+        role,
+        turn.mainModelId,
+      );
+      if (modelId === null) {
+        // Role not served by this provider — platform model, platform key.
+        return platform.get(role, params);
+      }
+      // Strip a caller-supplied `model` (for `main` it carries the `byo:` id,
+      // which is not a wire id) — the translated id wins.
+      const { model: _model, ...rest } = params ?? {};
+      return createByoChatModel({
+        credential: turn.credential,
+        modelId,
+        role,
+        chatGptBackend: turn.chatGptBackend,
+        params: rest,
+        logger,
+      });
+    },
+  };
+}