@ixo/oracle-runtime-workers 0.2.0

package/src/attachments/sandbox-archive.ts

@@ -0,0 +1,90 @@
+/**
+ * Archive an attachment's original bytes (and, for media, the helper model's
+ * analysis) into the user's sandbox at `/workspace/output/<name>` — the Node
+ * `FileProcessingService.uploadToSandbox` contract: multipart `file` + `path`
+ * to `<SANDBOX_MCP_URL without /mcp>/artifacts/upload`, authenticated with
+ * the same `Authorization: Bearer <ucan>` + `X-Auth-Type: ucan` the sandbox
+ * MCP client sends.
+ */
+import { sanitizeSandboxPath } from './sanitize';
+
+export interface SandboxUploadConfig {
+  sandboxMcpUrl: string;
+  authHeaders: Record<string, string>;
+}
+
+export interface SandboxUploadResult {
+  path: string;
+  url?: string;
+  previewUrl?: string;
+}
+
+const MAX_ERROR_BODY_LENGTH = 1024;
+
+export async function uploadToSandbox(
+  bytes: Uint8Array,
+  filename: string,
+  destPath: string,
+  config: SandboxUploadConfig,
+  mimetype: string,
+  fetchImpl: typeof fetch = fetch,
+): Promise<SandboxUploadResult> {
+  const baseUrl = config.sandboxMcpUrl.replace(/\/mcp\/?$/, '');
+  const safeFilename = sanitizeSandboxPath(filename);
+  const safePath = sanitizeSandboxPath(destPath);
+  const formData = new FormData();
+  // Copy into a fresh ArrayBuffer-backed view so the Blob never sees a
+  // SharedArrayBuffer-typed slice (the DOM lib types reject those).
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  formData.set(
+    'file',
+    new File([copy.buffer], safeFilename, { type: mimetype }),
+  );
+  formData.set('path', safePath);
+  const response = await fetchImpl(`${baseUrl}/artifacts/upload`, {
+    method: 'POST',
+    headers: { ...config.authHeaders },
+    body: formData,
+  });
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => '');
+    throw new Error(
+      `Sandbox upload failed (${response.status}): ${errorText.slice(0, MAX_ERROR_BODY_LENGTH)}`,
+    );
+  }
+  const raw: unknown = await response.json();
+  const result = raw as { path?: string; url?: string; previewUrl?: string };
+  return {
+    path: typeof result.path === 'string' ? result.path : safePath,
+    ...(result.url ? { url: result.url } : {}),
+    ...(result.previewUrl ? { previewUrl: result.previewUrl } : {}),
+  };
+}
+
+/** The `<name>-analysis.md` the extraction lane stores next to media files. */
+export function buildAnalysisMarkdown(
+  filename: string,
+  mimetype: string,
+  sizeBytes: number,
+  category: 'image' | 'video' | 'audio',
+  content: string,
+): string {
+  const labels: Record<'image' | 'video' | 'audio', string> = {
+    image: 'Image description',
+    video: 'Video description',
+    audio: 'Audio transcription',
+  };
+  return [
+    `# ${labels[category]}: ${filename}`,
+    '',
+    `- **File:** ${filename}`,
+    `- **Type:** ${mimetype}`,
+    `- **Size:** ${sizeBytes} bytes`,
+    `- **Processed:** ${new Date().toISOString()}`,
+    '',
+    '## Analysis',
+    '',
+    content,
+  ].join('\n');
+}

package/src/attachments/sanitize.ts

@@ -0,0 +1,35 @@
+/**
+ * Filename / sandbox-path hygiene — the Node runtime's `attachment-archive.ts`
+ * plus `FileProcessingService.sanitizeSandboxPath`.
+ */
+
+/** Where every attachment a user sends is archived in their sandbox. */
+export const SANDBOX_OUTPUT_PREFIX = '/workspace/output';
+
+/**
+ * Strip control characters and bracket sequences from a filename to prevent
+ * prompt injection when interpolated into LLM context. The archive writes
+ * under this exact name.
+ */
+export function sanitizeAttachmentFilename(filename: string): string {
+  return (
+    filename
+      // eslint-disable-next-line no-control-regex
+      .replace(/[\x00-\x1f\x7f]/g, '')
+      .replace(/[[\]]/g, '')
+      .slice(0, 255)
+  );
+}
+
+/**
+ * Sanitize a filename/path for the sandbox upload endpoint: only
+ * alphanumerics, dots, dashes, underscores and slashes, and no `..` segments
+ * so the sandbox cannot be escaped.
+ */
+export function sanitizeSandboxPath(p: string): string {
+  const charset = p.replace(/[^a-zA-Z0-9._\-/]/g, '_');
+  return charset
+    .split('/')
+    .filter((seg) => seg !== '..')
+    .join('/');
+}

package/src/attachments/types.ts

@@ -0,0 +1,86 @@
+/**
+ * Wire shape of a chat attachment — the Node runtime's `AttachmentDto`
+ * (`POST /messages/:sessionId` body `attachments[]`, also what
+ * `@ixo/oracles-client-sdk` sends): either an `mxcUri` (`mxc://…` or an
+ * `http(s)://` URL) or a Matrix `eventId` (encrypted uploads), plus the
+ * filename / mimetype / size the client knows.
+ */
+
+export interface AttachmentInput {
+  /** `mxc://server/id` or `http(s)://…`. Required when `eventId` is absent. */
+  mxcUri?: string;
+  /** Matrix event id (`$…`) — encrypted media is fetched and decrypted via the event. */
+  eventId?: string;
+  filename: string;
+  mimetype: string;
+  size?: number;
+}
+
+/** Same cap as the Node DTO (`@ArrayMaxSize`). */
+export const MAX_ATTACHMENTS = 10;
+
+const URI_RE = /^(mxc|https?):\/\/.+/i;
+const EVENT_ID_RE = /^\$/;
+const MAX_FILENAME = 255;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Validate the request's `attachments` the way the Node DTO does. Throws an
+ * `Error` whose message names the offending entry — callers surface it as
+ * the turn's error (Node answers 400 at the controller).
+ */
+export function parseAttachmentInputs(value: unknown): AttachmentInput[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new Error('attachments must be an array');
+  if (value.length > MAX_ATTACHMENTS)
+    throw new Error(`attachments: at most ${MAX_ATTACHMENTS} per message`);
+  return value.map((entry, i) => {
+    if (!isRecord(entry)) throw new Error(`attachments[${i}]: not an object`);
+    const mxcUri = entry['mxcUri'];
+    const eventId = entry['eventId'];
+    const filename = entry['filename'];
+    const mimetype = entry['mimetype'];
+    const size = entry['size'];
+    if (
+      mxcUri !== undefined &&
+      (typeof mxcUri !== 'string' || !URI_RE.test(mxcUri))
+    )
+      throw new Error(
+        `attachments[${i}].mxcUri must start with mxc://, http://, or https://`,
+      );
+    if (
+      eventId !== undefined &&
+      (typeof eventId !== 'string' || !EVENT_ID_RE.test(eventId))
+    )
+      throw new Error(`attachments[${i}].eventId must start with $`);
+    if (!mxcUri && !eventId)
+      throw new Error(
+        `attachments[${i}]: either mxcUri or eventId must be provided`,
+      );
+    if (
+      typeof filename !== 'string' ||
+      filename.length === 0 ||
+      filename.length > MAX_FILENAME
+    )
+      throw new Error(
+        `attachments[${i}].filename is required (≤ ${MAX_FILENAME} chars)`,
+      );
+    if (typeof mimetype !== 'string' || mimetype.length === 0)
+      throw new Error(`attachments[${i}].mimetype is required`);
+    if (
+      size !== undefined &&
+      (typeof size !== 'number' || !Number.isFinite(size) || size < 0)
+    )
+      throw new Error(`attachments[${i}].size must be a non-negative number`);
+    return {
+      ...(typeof mxcUri === 'string' ? { mxcUri } : {}),
+      ...(typeof eventId === 'string' ? { eventId } : {}),
+      filename,
+      mimetype,
+      ...(typeof size === 'number' ? { size } : {}),
+    };
+  });
+}

package/src/attachments/view.ts

@@ -0,0 +1,107 @@
+/**
+ * Re-fetch one attachment of a session on demand — the `view_attachment`
+ * lane behind payload retention (`retention.ts`). The same routing as the
+ * turn pipeline applies: when the current model reads the modality the bytes
+ * come back as a native content block, otherwise the helper (`vision` role)
+ * model turns them into text; plain text is decoded locally.
+ */
+import { classifyAttachment } from './classify';
+import type { NativeAttachment } from './content-blocks';
+import { loadAttachmentBytes, type MatrixMediaSource } from './download';
+import { extractText, type ExtractionProvider } from './extract';
+import { categorizeFile, verifyMagicBytes } from './magic';
+import { routeAttachment } from './route';
+import { sanitizeAttachmentFilename } from './sanitize';
+import type { AttachmentInput } from './types';
+import type { ModelInputCapabilities } from '../core/llm';
+import type { AttachmentMeta } from '../sqlite/serialization';
+import type { Logger } from '../plugin-api/types';
+import { bytesToBase64 } from '../plugins/base64';
+
+export type AttachmentView =
+  | { kind: 'native'; native: NativeAttachment }
+  | { kind: 'text'; text: string };
+
+export interface ViewAttachmentDeps {
+  source: MatrixMediaSource;
+  extraction: ExtractionProvider | null;
+  /** Capabilities of the model that will read the result. */
+  caps: ModelInputCapabilities;
+  roomId?: string;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  logger: Logger;
+}
+
+/** What the `view_attachment` tool sees on the host: session-scoped access. */
+export interface AttachmentViewSurface {
+  /** Whether any message of the session has had its inline payload offloaded. */
+  readonly offloaded: boolean;
+  /**
+   * Fetch one of the session's attachments again by the reference the
+   * placeholder lists (media event id or mxc URI). Rejects references that do
+   * not belong to an attachment of this session.
+   */
+  view(ref: string): Promise<{ meta: AttachmentMeta; view: AttachmentView }>;
+}
+
+function toInput(meta: AttachmentMeta): AttachmentInput {
+  return {
+    filename: meta.filename,
+    mimetype: meta.mimetype,
+    ...(meta.size !== undefined ? { size: meta.size } : {}),
+    ...(meta.mxcUri ? { mxcUri: meta.mxcUri } : {}),
+    ...(meta.eventId ? { eventId: meta.eventId } : {}),
+  };
+}
+
+export async function viewAttachment(
+  meta: AttachmentMeta,
+  deps: ViewAttachmentDeps,
+): Promise<AttachmentView> {
+  const attachment = toInput(meta);
+  const kind = classifyAttachment(attachment);
+  const strategy = routeAttachment(kind, deps.caps);
+  const { bytes, mimetype } = await loadAttachmentBytes(
+    attachment,
+    deps.roomId,
+    deps.source,
+    { fetchImpl: deps.fetchImpl, signal: deps.signal },
+  );
+  deps.logger.log(
+    `[attachments] view "${attachment.filename}" (${mimetype}) kind=${kind} → ${strategy} (${bytes.length} bytes)`,
+  );
+  if (strategy === 'send-native') {
+    const loaded = classifyAttachment({
+      mimetype,
+      filename: attachment.filename,
+    });
+    return {
+      kind: 'native',
+      native: {
+        kind: loaded === 'image' ? 'image' : 'file',
+        mimeType: mimetype,
+        base64: bytesToBase64(bytes),
+        filename: attachment.filename,
+      },
+    };
+  }
+  const category = categorizeFile(attachment.mimetype);
+  if (category === 'unsupported') {
+    return {
+      kind: 'text',
+      text: `[File "${sanitizeAttachmentFilename(attachment.filename)}" (${attachment.mimetype}) is not a supported file type and could not be processed]`,
+    };
+  }
+  verifyMagicBytes(bytes, category, attachment, (m) =>
+    deps.logger.warn(`[attachments] ${m}`),
+  );
+  const { text } = await extractText(
+    bytes,
+    attachment,
+    category,
+    deps.extraction,
+    { fetchImpl: deps.fetchImpl, signal: deps.signal },
+  );
+  return { kind: 'text', text };
+}

package/src/core/env.ts

@@ -0,0 +1,200 @@
+import { z } from 'zod';
+import type { OraclePlugin } from '../plugin-api/oracle-plugin';
+import type { Logger } from '../plugin-api/types';
+import { NOOP_LOGGER } from './utils';
+
+/**
+ * Tier-0 (core) environment for the Workers runtime. Mirrors
+ * `OracleWorkerEnv` in `src/do/contracts.ts`: every key here is a Worker
+ * secret or var. Plugin-owned keys are NOT declared here — each plugin's
+ * `configSchema` is folded onto this base by {@link composeEnvSchema}.
+ *
+ * Deliberately absent versus the Node runtime's base schema: `NODE_ENV`,
+ * `PORT`, `SQLITE_DATABASE_PATH`, `MATRIX_STORE_PATH`, `SECP_MNEMONIC`,
+ * `RPC_URL`, `OPENAI_API_KEY`, `SESSION_TITLE_MODEL`, `ORACLE_SECRETS`,
+ * `LIVE_AGENT_AUTH_API_KEY` — filesystem/process concerns that do not exist
+ * on Workers or features this runtime does not carry. Optional features
+ * (Nebius, LangSmith, BYO credentials, the account-room secrets key) are
+ * read straight from `OracleWorkerEnv` by the code that owns them.
+ *
+ * Unknown keys are stripped by Zod, so the Durable Object namespaces and any
+ * other non-string bindings on the Worker `env` object never reach plugins
+ * through `ctx.config`.
+ */
+export const baseEnvSchema = z.object({
+  // --- identity -----------------------------------------------------------
+  ORACLE_NAME: z.string().min(1),
+  /** UCAN audience — the DID users address invocations/delegations to. */
+  ORACLE_DID: z.string().min(1),
+  /**
+   * On-chain entity DID surfaced to the agent as `identity.entityDid`. Falls
+   * back to `ORACLE_DID` when unset (see `createRuntimeCore`).
+   */
+  ORACLE_ENTITY_DID: z.string().min(1).optional(),
+  NETWORK: z.enum(['mainnet', 'testnet', 'devnet']).default('mainnet'),
+
+  // --- auth ---------------------------------------------------------------
+  /** Blocksync GraphQL endpoint used to resolve `did:ixo` verification keys. */
+  BLOCKSYNC_GRAPHQL_URL: z.string().min(1),
+  /**
+   * Max lifetime (seconds) the oracle accepts for a user *auth* invocation.
+   * Bounds the replay window server-side regardless of the TTL the client
+   * declares. Default 15 minutes.
+   */
+  UCAN_AUTH_MAX_TTL_SECONDS: z.coerce.number().int().positive().default(900),
+
+  // --- matrix -------------------------------------------------------------
+  MATRIX_BASE_URL: z.string().min(1),
+  MATRIX_ORACLE_ADMIN_USER_ID: z.string().min(1),
+  /**
+   * The bot account's password. The gateway logs its own device in with it,
+   * keeps that device's token in its storage and re-logs in if the token is
+   * ever rejected; plugins that need their own client (editor, flows) get a
+   * second dedicated device from the gateway. No access token is ever
+   * configured: a token is a device, and a device shared with any other
+   * client splits its encryption state.
+   */
+  MATRIX_ORACLE_ADMIN_PASSWORD: z.string().min(1),
+  /** SSSS recovery passphrase — lets a fresh device restore room keys. */
+  MATRIX_RECOVERY_PHRASE: z.string().min(1).optional(),
+  /** Matrix server name used when composing per-user room aliases. */
+  MATRIX_HOMESERVER_NAME: z.string().min(1).optional(),
+
+  // --- storage ------------------------------------------------------------
+  /** Where the user-owned SQLite file lives; unset = the IXO VFS, `matrix` = legacy room media (local harness). */
+  OWNER_STORE: z.enum(['matrix', 'vfs']).optional(),
+  /** IXO VFS worker base URL when `OWNER_STORE=vfs` (defaults per NETWORK). */
+  VFS_BASE_URL: z.string().url().optional(),
+  /** UCAN store worker base URL (defaults per NETWORK). */
+  UCAN_STORE_URL: z.string().url().optional(),
+
+  // --- llm ----------------------------------------------------------------
+  OPEN_ROUTER_API_KEY: z.string().min(1),
+  /**
+   * Default model for new chats — an OpenRouter slug. When unset the runtime
+   * uses the catalog default. Lets an operator change the default per
+   * deployment without a code change.
+   */
+  DEFAULT_MODEL: z.string().min(1).optional(),
+  /**
+   * Multiplier applied to raw provider prices in `GET /models` (the price the
+   * user sees). Same default as the Node runtime.
+   */
+  MODEL_PRICE_MARKUP: z.coerce.number().positive().optional(),
+  /**
+   * Extended-thinking effort for the main model. Lower = faster time-to-first
+   * token, at some cost to hard multi-step reasoning.
+   */
+  MAIN_REASONING_EFFORT: z.enum(['low', 'medium', 'high']).default('medium'),
+
+  // --- misc ---------------------------------------------------------------
+  LOG_LEVEL: z.string().default('info'),
+  CORS_ORIGIN: z.string().default('*'),
+});
+
+export type BaseEnv = z.infer<typeof baseEnvSchema>;
+
+export interface ComposeEnvSchemaResult {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: z.ZodObject<any>;
+  /**
+   * Map of env field name -> the plugin that owns it. Used by
+   * {@link validateEnv} to attribute Zod issues to a plugin.
+   */
+  pluginOwnership: Map<string, string>;
+}
+
+export interface ValidateEnvError {
+  /** Plugin owning the failing field, or `'core'` if from a base schema. */
+  plugin: string;
+  /** Dotted field path from Zod's issue (e.g. `MEMORY_MCP_URL`). */
+  field: string;
+  /** Human-readable message from Zod. */
+  message: string;
+}
+
+export interface ValidateEnvResult {
+  valid: boolean;
+  /** Parsed config object — empty when `valid` is false. */
+  config: Record<string, unknown>;
+  errors: ValidateEnvError[];
+}
+
+/**
+ * Fold every plugin's `configSchema` into a single Zod object via
+ * `.extend()`. The returned `pluginOwnership` map records which plugin
+ * contributed each top-level field so {@link validateEnv} can attribute
+ * Zod issues by plugin.
+ *
+ * Conflict policy: later wins. When two plugins declare the same field,
+ * the later definition replaces the earlier one and a warning is emitted
+ * via the supplied logger naming both plugins.
+ */
+export function composeEnvSchema(
+  plugins: OraclePlugin[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  baseSchema?: z.ZodObject<any>,
+  logger: Logger = NOOP_LOGGER,
+): ComposeEnvSchemaResult {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let merged: z.ZodObject<any> = baseSchema ?? z.object({});
+  const pluginOwnership = new Map<string, string>();
+
+  if (baseSchema) {
+    for (const key of Object.keys(baseSchema.shape)) {
+      pluginOwnership.set(key, 'core');
+    }
+  }
+
+  for (const plugin of plugins) {
+    if (!plugin.configSchema) continue;
+    const shape = plugin.configSchema.shape as Record<string, unknown>;
+    for (const key of Object.keys(shape)) {
+      const previous = pluginOwnership.get(key);
+      if (previous !== undefined && previous !== plugin.name) {
+        logger.warn(
+          `[boot] env key '${key}' is defined by both '${previous}' and '${plugin.name}'; '${plugin.name}' wins.`,
+        );
+      }
+      pluginOwnership.set(key, plugin.name);
+    }
+    merged = merged.extend(shape);
+  }
+
+  return { schema: merged, pluginOwnership };
+}
+
+/**
+ * Validate `env` against the merged schema and produce structured errors
+ * naming the owning plugin per failing field.
+ *
+ * `env` is the Worker's `env` bindings object (or any plain record) — this
+ * module never reads `process.env`. On success, `config` holds the parsed
+ * object (with any Zod coercions/defaults applied). On failure, `config` is
+ * empty and every Zod issue is mapped through `pluginOwnership` to find the
+ * owner.
+ */
+export function validateEnv(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: z.ZodObject<any>,
+  env: Record<string, unknown>,
+  pluginOwnership: Map<string, string>,
+): ValidateEnvResult {
+  const result = schema.safeParse(env);
+  if (result.success) {
+    return {
+      valid: true,
+      config: result.data,
+      errors: [],
+    };
+  }
+
+  const errors: ValidateEnvError[] = result.error.issues.map((issue) => {
+    const topField = issue.path.length > 0 ? String(issue.path[0]) : '<root>';
+    const fullField = issue.path.length > 0 ? issue.path.join('.') : '<root>';
+    const plugin = pluginOwnership.get(topField) ?? 'unknown';
+    return { plugin, field: fullField, message: issue.message };
+  });
+
+  return { valid: false, config: {}, errors };
+}