@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/user-preferences/user-preferences-store.ts

@@ -0,0 +1,172 @@
+/**
+ * Per-room user preferences, persisted as the `ixo.room.state` /
+ * `user_prefs` state event of the user↔oracle room — the SAME event, in the
+ * SAME Node-compatible envelope, that the Node runtime's
+ * `UserPreferencesService` reads and writes. A user migrated from Node keeps
+ * their preferences; a user who sets them here keeps them if they ever move
+ * back.
+ *
+ * The store is a host object (one per `UserOracleDO`): the turn preparer
+ * reads through it to hydrate `state.userPreferences` before the agent is
+ * built, and the `set_user_preferences` tool writes through it, so the
+ * 5-minute read cache is invalidated by the very write that changes it —
+ * the Node service's cache-manager semantics, without a shared singleton.
+ */
+import type { UserPreferences } from '../../core/state';
+import {
+  decodeRoomStateContent,
+  encodeRoomStateContent,
+  ROOM_STATE_EVENT_TYPE,
+} from '../../matrix/room-state-codec';
+import type { Logger, UserPreferencesSurface } from '../../plugin-api/types';
+import {
+  USER_PREFS_STATE_KEY,
+  UserPreferencesSchema,
+  type StoredUserPreferences,
+} from './schema';
+
+/**
+ * The slice of the Matrix gateway the store needs. The gateway Durable
+ * Object stub satisfies it structurally (`getRoomStateEvent` /
+ * `sendStateEvent` are its RPC methods); tests pass an in-memory map.
+ */
+export interface RoomStateAccess {
+  getRoomStateEvent(
+    roomId: string,
+    type: string,
+    stateKey?: string,
+  ): Promise<string | null>;
+  sendStateEvent(
+    roomId: string,
+    type: string,
+    content: string,
+    stateKey?: string,
+  ): Promise<string>;
+}
+
+export interface UserPreferencesStoreOptions {
+  /** Read-cache TTL. Node caches for 5 minutes; same default here. */
+  ttlMs?: number;
+  logger?: Logger;
+  /** Clock, injectable for tests. */
+  now?: () => number;
+}
+
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** Bound the cache — one store serves one user, but rooms can accrue. */
+const MAX_CACHE_ENTRIES = 64;
+
+interface CacheEntry {
+  value: StoredUserPreferences | undefined;
+  expiresAt: number;
+}
+
+export class UserPreferencesStore implements UserPreferencesSurface {
+  private readonly cache = new Map<string, CacheEntry>();
+
+  private readonly ttlMs: number;
+
+  private readonly logger: Logger | undefined;
+
+  private readonly now: () => number;
+
+  constructor(
+    private readonly access: RoomStateAccess,
+    options: UserPreferencesStoreOptions = {},
+  ) {
+    this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    this.logger = options.logger;
+    this.now = options.now ?? (() => Date.now());
+  }
+
+  /**
+   * The room's preferences, or `undefined` when none are set, the payload
+   * is unreadable, or the read failed (each logged, never thrown — a
+   * preferences hiccup must not fail a turn). Misses are cached too, so a
+   * user without preferences costs one state read per TTL, not per turn.
+   */
+  async get(roomId: string): Promise<UserPreferences | undefined> {
+    const hit = this.cache.get(roomId);
+    if (hit && hit.expiresAt > this.now()) return hit.value;
+
+    let decoded: unknown;
+    try {
+      const json = await this.access.getRoomStateEvent(
+        roomId,
+        ROOM_STATE_EVENT_TYPE,
+        USER_PREFS_STATE_KEY,
+      );
+      decoded =
+        json === null
+          ? null
+          : await decodeRoomStateContent(JSON.parse(json) as unknown);
+    } catch (error) {
+      this.logger?.warn(
+        `[user-preferences] failed to load prefs for room ${roomId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      return undefined;
+    }
+
+    if (decoded === null) {
+      this.remember(roomId, undefined);
+      return undefined;
+    }
+    const parsed = UserPreferencesSchema.safeParse(decoded);
+    if (!parsed.success) {
+      this.logger?.warn(
+        `[user-preferences] invalid prefs payload for room ${roomId}: ${parsed.error.message}`,
+      );
+      return undefined;
+    }
+    this.remember(roomId, parsed.data);
+    return parsed.data;
+  }
+
+  /**
+   * Merge `partial` into the stored preferences (only the provided fields
+   * change; `undefined` values are ignored rather than clearing a field) and
+   * persist the result with a fresh `updatedAt`. Returns the merged record.
+   * An empty `partial` is a no-op that returns the current record.
+   */
+  async set(
+    roomId: string,
+    partial: Partial<UserPreferences>,
+  ): Promise<UserPreferences> {
+    const current = (await this.get(roomId)) ?? {};
+    const provided = Object.fromEntries(
+      Object.entries(partial).filter(([, value]) => value !== undefined),
+    );
+    if (Object.keys(provided).length === 0) return current;
+
+    const merged = UserPreferencesSchema.parse({
+      ...current,
+      ...provided,
+      updatedAt: new Date(this.now()).toISOString(),
+    });
+    await this.access.sendStateEvent(
+      roomId,
+      ROOM_STATE_EVENT_TYPE,
+      JSON.stringify(await encodeRoomStateContent(merged)),
+      USER_PREFS_STATE_KEY,
+    );
+    this.invalidate(roomId);
+    return merged;
+  }
+
+  invalidate(roomId: string): void {
+    this.cache.delete(roomId);
+  }
+
+  private remember(
+    roomId: string,
+    value: StoredUserPreferences | undefined,
+  ): void {
+    if (this.cache.size >= MAX_CACHE_ENTRIES) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) this.cache.delete(oldest);
+    }
+    this.cache.set(roomId, { value, expiresAt: this.now() + this.ttlMs });
+  }
+}

package/src/plugins/user-preferences/user-preferences-tool.ts

@@ -0,0 +1,131 @@
+/**
+ * `set_user_preferences` — the Node runtime's tool, verbatim in schema and
+ * description (the description is prompt material the model has been tuned
+ * against; keep it in sync with `packages/oracle-runtime`). The handler
+ * writes through the host's `ctx.preferences` surface for the active room.
+ */
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper';
+import type {
+  Logger,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import { FORMALITY_LEVELS } from './schema';
+
+export const SET_USER_PREFERENCES_TOOL_NAME = 'set_user_preferences';
+
+const NOOP_LOGGER: Logger = {
+  log: () => undefined,
+  warn: () => undefined,
+  error: () => undefined,
+};
+
+export const setUserPreferencesSchema = z.object({
+  agentName: z
+    .string()
+    .max(80)
+    .optional()
+    .describe(
+      "What the user wants you (the agent) to be called (e.g. 'Companion'). Use exactly the form the user asked for. Max 80 characters.",
+    ),
+  userName: z
+    .string()
+    .max(80)
+    .optional()
+    .describe(
+      "What the user wants you to call them (e.g. 'Yousef'). Use exactly the form the user asked for. Max 80 characters.",
+    ),
+  language: z
+    .string()
+    .max(20)
+    .optional()
+    .describe(
+      "Preferred reply language as a free-form code or name (e.g. 'en', 'ar', 'Arabic', 'Egyptian Arabic'). " +
+        'Be precise — if the user specified a dialect or variant, capture that. Max 20 characters.',
+    ),
+  tone: z
+    .string()
+    .optional()
+    .describe(
+      "Short tone label your future self will see at the top of every prompt (e.g. 'playful and warm', " +
+        "'concise and dry', 'patient teacher'). Pick descriptive words, not vague ones.",
+    ),
+  formality: z
+    .enum(FORMALITY_LEVELS)
+    .optional()
+    .describe(
+      'How formal the replies should be. Pick the value closest to what the user actually wants, ' +
+        'not what the request literally said.',
+    ),
+  customInstructions: z
+    .string()
+    .max(2000)
+    .optional()
+    .describe(
+      'Free-form custom instructions your FUTURE SELF will read every turn. Treat this like writing ' +
+        'a system prompt: be specific, complete, and unambiguous. Include the WHY when it matters ' +
+        "(e.g. 'User has dyslexia — keep sentences short and avoid long lists'). " +
+        'When updating, MERGE with existing instructions rather than replacing — read what is already ' +
+        'there (visible in your current system prompt under "User Preferences") and write the full new ' +
+        'instruction set, preserving anything still relevant. Max 2000 characters.',
+    ),
+});
+
+export const SET_USER_PREFERENCES_DESCRIPTION =
+  "Update the user's preferences. Call this whenever the user asks you to change how you behave " +
+  "(e.g. 'call me Yousef', 'reply in Arabic', 'be more casual').\n\n" +
+  'IMPORTANT — you are writing instructions for your FUTURE SELF. ' +
+  'On every later turn this exact text will be injected back into your system prompt and you will read it cold, ' +
+  'with no memory of this conversation or why the user asked. So:\n' +
+  "  • Be specific and self-contained. Don't write 'be more casual' — write 'Use casual, conversational " +
+  "tone. Avoid corporate phrasing. Use contractions. Drop filler words.'\n" +
+  "  • Capture intent, not just the literal request. If the user says 'stop being so formal', infer the " +
+  'positive form: what should you do instead?\n' +
+  '  • Preserve existing instructions when adding new ones — only overwrite the fields you mean to change. ' +
+  'Other fields are kept as-is.\n' +
+  "  • If unsure between two interpretations, pick the more specific one — your future self can't ask back.\n\n" +
+  "Note: changes apply from the user's NEXT message (the current turn's prompt is already built).";
+
+export interface CreateSetUserPreferencesToolOptions {
+  logger?: Logger;
+}
+
+/**
+ * Builds the `set_user_preferences` tool. Merges the supplied partial
+ * preferences into the active room's stored preferences; only the provided
+ * fields change. Errors come back as descriptive strings (never thrown) so
+ * the agent can recover — the Node tool's contract.
+ */
+export function createSetUserPreferencesTool(
+  options: CreateSetUserPreferencesToolOptions = {},
+): PluginTool {
+  const logger = options.logger ?? NOOP_LOGGER;
+
+  return tool(
+    async (rawArgs: unknown, ctx: RuntimeContext) => {
+      const args = setUserPreferencesSchema.parse(rawArgs);
+      const roomId = ctx.session.roomId;
+      if (!roomId) {
+        return '[Error updating user preferences: no active room on this session]';
+      }
+      const surface = ctx.preferences;
+      if (!surface) {
+        return '[Error updating user preferences: preferences are not available on this host]';
+      }
+      try {
+        const merged = await surface.set(roomId, args);
+        return `Updated. New preferences: ${JSON.stringify(merged, null, 2)}`;
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        logger.error(`set_user_preferences error: ${msg}`);
+        return `[Error updating user preferences: ${msg}]`;
+      }
+    },
+    {
+      name: SET_USER_PREFERENCES_TOOL_NAME,
+      description: SET_USER_PREFERENCES_DESCRIPTION,
+      schema: setUserPreferencesSchema,
+    },
+  );
+}

package/src/plugins/user-preferences/user-preferences.plugin.ts

@@ -0,0 +1,137 @@
+/**
+ * User Preferences plugin — the Workers port of
+ * `packages/oracle-runtime/src/plugins/user-preferences`.
+ *
+ *  - `state.userPreferences` is hydrated by the user object's turn preparer
+ *    (through the host `UserPreferencesStore`) BEFORE the agent is built,
+ *    so the system prompt sees the value on turn 1 — the Node AgentBuilder
+ *    contract.
+ *  - Exposes `set_user_preferences`, which the agent calls when the user
+ *    asks to change behavioural preferences (tone, language, formality,
+ *    what to call the agent / the user).
+ *  - Ships `GET /user-preferences` (the NestJS controller became a
+ *    `getRoutes()` entry): the caller's preferences, or `null`.
+ *
+ * Storage is the room's `ixo.room.state` / `user_prefs` event in the Node
+ * envelope, so preferences survive a Node ⇄ Workers migration intact.
+ */
+import type { OracleWorkerEnv } from '../../do/contracts';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type { PluginRoute } from '../../shell/app';
+import type {
+  PluginContext,
+  PluginManifest,
+  PluginTool,
+} from '../../plugin-api/types';
+import {
+  UserPreferencesStore,
+  type RoomStateAccess,
+} from './user-preferences-store';
+import {
+  createSetUserPreferencesTool,
+  SET_USER_PREFERENCES_TOOL_NAME,
+} from './user-preferences-tool';
+
+/** What the route needs from the Matrix gateway: room lookup + room state. */
+export interface PreferencesGateway extends RoomStateAccess {
+  resolveUserRoom(
+    userDid: string,
+  ): Promise<{ roomId: string; alias: string } | null>;
+}
+
+export interface UserPreferencesPluginOptions {
+  /**
+   * Resolves the oracle's Matrix gateway for a request. Defaults to the
+   * `MATRIX_GATEWAY` Durable Object stub; tests inject a fake.
+   */
+  gatewayFor?: (env: OracleWorkerEnv) => PreferencesGateway;
+}
+
+function defaultGatewayFor(env: OracleWorkerEnv): PreferencesGateway {
+  const id = env.MATRIX_GATEWAY.idFromName(env.ORACLE_DID);
+  return env.MATRIX_GATEWAY.get(id);
+}
+
+const manifest: PluginManifest = {
+  title: 'User Preferences',
+  summary:
+    'Behavioral preferences — how the user wants you to respond (tone, language, formality, what to call you).',
+  whenToUse: [
+    'User states how they want you to behave: "be more terse", "respond in Spanish", "call me Alex", "stop using emojis".',
+    'User asks to change the voice, formality, or language of your replies — save it so it persists across sessions, not just this turn.',
+  ],
+  whenNotToUse: [
+    'Facts about who the user is (name, role, project) — those go to memory, not preferences.',
+    'Artifacts you have produced or how the user reacted to them — also memory, not preferences.',
+    'One-turn formatting requests ("just for this answer, use bullets") — adapt locally without saving.',
+  ],
+  examples: [
+    {
+      user: 'From now on, please respond in Spanish.',
+      thought: 'Behavioral preference about language — save it so it persists.',
+      tool: SET_USER_PREFERENCES_TOOL_NAME,
+      args: { language: 'Spanish' },
+    },
+    {
+      user: 'Be more concise — drop the explanations.',
+      thought: 'Preference about tone/length, not a single-turn request.',
+      tool: SET_USER_PREFERENCES_TOOL_NAME,
+      args: { tone: 'concise' },
+    },
+  ],
+  visibility: 'always',
+  stability: 'stable',
+  category: 'core',
+};
+
+export class UserPreferencesPlugin extends OraclePlugin {
+  readonly name = 'user-preferences';
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  private readonly gatewayFor: (env: OracleWorkerEnv) => PreferencesGateway;
+
+  constructor(options: UserPreferencesPluginOptions = {}) {
+    super();
+    this.gatewayFor = options.gatewayFor ?? defaultGatewayFor;
+  }
+
+  override getTools(ctx: PluginContext): PluginTool[] {
+    return [createSetUserPreferencesTool({ logger: ctx.logger })];
+  }
+
+  override getRoutes(ctx: PluginContext): PluginRoute[] {
+    return [
+      {
+        method: 'GET',
+        path: '/user-preferences',
+        handler: async (_request, env, { auth }) => {
+          if (!auth) {
+            return Response.json(
+              { statusCode: 401, message: 'Unauthorized' },
+              { status: 401 },
+            );
+          }
+          const gateway = this.gatewayFor(env);
+          const room = await gateway.resolveUserRoom(auth.userDid);
+          if (!room) {
+            ctx.logger.warn(
+              `[user-preferences] could not resolve user↔oracle room for userDid=${auth.userDid}`,
+            );
+            return Response.json(null);
+          }
+          const store = new UserPreferencesStore(gateway, {
+            logger: ctx.logger,
+          });
+          const prefs = await store.get(room.roomId);
+          ctx.logger.log(
+            `[user-preferences] fetched for userDid=${auth.userDid}, roomId=${room.roomId}: ${prefs ? 'Found' : 'null'}`,
+          );
+          return Response.json(prefs ?? null);
+        },
+      },
+    ];
+  }
+}

package/src/plugins/vfs/index.ts

@@ -0,0 +1,40 @@
+export { VfsPlugin, type VfsConfig, type VfsPluginOptions } from './vfs.plugin';
+export {
+  buildClient,
+  createVfsTools,
+  invalidArgs,
+  validatePath,
+  type CreateVfsToolsDeps,
+} from './vfs-tools';
+export {
+  createVfsSandboxTools,
+  type CreateVfsSandboxToolsDeps,
+} from './vfs-sandbox-tools';
+export { vfsBearer, type VfsBearerResult } from './vfs-auth';
+export {
+  VfsClient,
+  type VfsBatchItemResult,
+  type VfsClientOptions,
+  type VfsContentBytes,
+  type VfsEditResult,
+  type VfsFileStat,
+  type VfsGlobMatch,
+  type VfsMintFn,
+  type VfsPublicResult,
+  type VfsReadWindow,
+  type VfsSearchHit,
+  type VfsSearchResult,
+  type VfsTreeEntry,
+} from './vfs-client';
+export { isTextMime, readForAgent } from './vfs-content';
+export {
+  isAlreadyExistsConflict,
+  isWriteConflict,
+  mapVfsError,
+  NO_ACCESS_MESSAGE,
+  noAccessMessage,
+  VfsAuthError,
+  VfsHttpError,
+  type VfsAbility,
+  type VfsAuthErrorKind,
+} from './vfs-errors';

package/src/plugins/vfs/vfs-auth.ts

@@ -0,0 +1,56 @@
+import type { RuntimeContext } from '../../plugin-api/types';
+import type { VfsAbility, VfsAuthErrorKind } from './vfs-errors';
+import type { VfsConfig } from './vfs.plugin';
+
+/** Personal-namespace resource the user delegates over. */
+const VFS_RESOURCE = 'ixo:filesystem';
+
+/** Invocations are single-use per call, so a short TTL suffices. */
+const INVOCATION_TTL_SECONDS = 60;
+
+export type VfsBearerResult =
+  | { bearer: string }
+  | { error: VfsAuthErrorKind; detail?: string };
+
+/**
+ * Resolve a fresh, single-use VFS bearer for one operation via the two-hop
+ * UCAN flow (the same flow `src/owner-store/ixo-vfs-store.ts` uses):
+ *
+ *   1. Fetch the user's delegation for this oracle from the store worker
+ *      (`getServiceDelegation`) over `ixo:filesystem`, requiring an ability
+ *      that covers `ability`.
+ *   2. Mint an invocation proved by that delegation, attenuated to
+ *      `{ can: ability, with: <granted resource> }`.
+ *
+ * Non-throwing: every failure is returned as `{ error, detail? }` so the
+ * client can surface an agent-actionable message instead of a stack.
+ */
+export async function vfsBearer(
+  rtCtx: RuntimeContext,
+  cfg: VfsConfig,
+  ability: VfsAbility,
+  targetResource?: string,
+): Promise<VfsBearerResult> {
+  const delegation = await rtCtx.ucan.getServiceDelegation(rtCtx.user.did, {
+    storeUrl: cfg.UCAN_STORE_URL,
+    resource: VFS_RESOURCE,
+    requiredAbility: ability,
+  });
+  if ('error' in delegation) {
+    // `{ error: 'no-delegation' | 'store-error', detail? }` widens cleanly to
+    // `VfsBearerResult` (both kinds are in `VfsAuthErrorKind`).
+    return delegation;
+  }
+
+  const minted = await rtCtx.ucan.createInvocationFromDelegation(
+    delegation.token,
+    cfg.VFS_BASE_URL,
+    { can: ability, with: targetResource ?? delegation.with },
+    { maxTtlSeconds: INVOCATION_TTL_SECONDS },
+  );
+  if ('error' in minted) {
+    return { error: 'mint-failed', detail: minted.error };
+  }
+
+  return { bearer: minted.invocation };
+}