@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/memory/memory.plugin.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { OraclePlugin, type PluginEnv } from '../../plugin-api/oracle-plugin';
+import type {
+  MergedConfig,
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+  UserContextData,
+} from '../../plugin-api/types';
+import {
+  createDefaultMemoryMcpFactory,
+  DEFAULT_MEMORY_TOOLS,
+  fetchMemoryTools,
+  type MemoryMcpFactory,
+} from './memory-tools';
+
+const configSchema = z.object({
+  MEMORY_MCP_URL: z.string().url('MEMORY_MCP_URL must be a valid HTTP(S) URL.'),
+  MEMORY_ENGINE_URL: z
+    .string()
+    .url('MEMORY_ENGINE_URL must be a valid HTTP(S) URL.'),
+});
+
+const manifest: PluginManifest = {
+  title: 'Memory',
+  summary:
+    'Durable memory across conversations: who the user is, what you have made for them, and what worked.',
+  whenToUse: [
+    'First contact (no prior context loaded): greet, ask their name and what they want help with, then save what they tell you.',
+    'You learn something durable about the user — name, role, ongoing project, a constraint, a relationship.',
+    'You create an artifact for the user (file, document, edit, generated content): record what it is, what it is for, and the structural choices you made.',
+    'The user expresses satisfaction or dissatisfaction with something you produced: capture what worked or what did not — tone, length, structure, style — against that artifact entry.',
+    'The user references something they told you before, or something you made before.',
+  ],
+  whenNotToUse: [
+    'Ephemeral conversation-only state (use the current message thread).',
+    'Behavioral preferences about how to respond (call the user-preferences tool instead).',
+    'Public web facts that are not specific to this user (use a web-search capability).',
+    'Anything the user asked you to forget or framed as temporary.',
+  ],
+  tags: ['memory', 'recall', 'artifacts', 'personalization'],
+  category: 'memory',
+  visibility: 'always',
+  stability: 'stable',
+};
+
+export interface MemoryPluginOptions {
+  /**
+   * Override the MCP-tools factory. Defaults to an HTTP MCP client against
+   * `MEMORY_MCP_URL` authenticated with a per-request UCAN invocation.
+   */
+  mcpFactory?: (memoryMcpUrl: string) => MemoryMcpFactory;
+  /**
+   * Filter the upstream tool surface. Defaults to {@link DEFAULT_MEMORY_TOOLS}
+   * (search + add + delete-episode + clear). Pass an explicit list to expose
+   * `add_oracle_knowledge`, `delete_edge`, etc.
+   */
+  selectedTools?: readonly string[];
+}
+
+function resolveMemoryUrl(config: MergedConfig): string {
+  const parsed = configSchema.parse(config);
+  return parsed.MEMORY_MCP_URL;
+}
+
+/**
+ * Memory plugin. Surfaces upstream Memory Engine MCP tools directly — the
+ * agent sees the upstream names (`memory-engine__search_memory_engine`,
+ * `memory-engine__add_memory`, ...) with the upstream's own schemas. This
+ * matches the pattern that worked in production and avoids schema-mismatch
+ * failures from a local wrapper layer.
+ *
+ * Tool list is fetched per-request via `getRequestTools` because the MCP
+ * headers depend on the in-flight user's UCAN delegation.
+ */
+export class MemoryPlugin extends OraclePlugin {
+  static readonly NAME = 'memory';
+
+  readonly name = MemoryPlugin.NAME;
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override readonly configSchema = configSchema;
+
+  override readonly autoDetectHint = 'MEMORY_MCP_URL';
+
+  private readonly mcpFactory: (memoryMcpUrl: string) => MemoryMcpFactory;
+
+  private readonly selectedTools: readonly string[];
+
+  constructor(options: MemoryPluginOptions = {}) {
+    super();
+    this.mcpFactory = options.mcpFactory ?? createDefaultMemoryMcpFactory;
+    this.selectedTools = options.selectedTools ?? DEFAULT_MEMORY_TOOLS;
+  }
+
+  override autoDetect(env: PluginEnv): boolean {
+    return (
+      typeof env.MEMORY_MCP_URL === 'string' && env.MEMORY_MCP_URL.length > 0
+    );
+  }
+
+  override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
+    const memoryUrl = resolveMemoryUrl(rtCtx.config);
+    const factory = this.mcpFactory(memoryUrl);
+    return fetchMemoryTools(rtCtx, factory, this.selectedTools);
+  }
+
+  override getSharedState(): Record<
+    string,
+    (
+      state: { userContext?: UserContextData },
+      runCtx: RuntimeContext,
+    ) => unknown
+  > {
+    return {
+      userProfile: (state) => state.userContext,
+    };
+  }
+}

package/src/plugins/memory/types.ts

@@ -0,0 +1,147 @@
+// ─── Shared primitives ────────────────────────────────────────────────────────
+
+export type ComparisonOperator =
+  | '='
+  | '<>'
+  | '>'
+  | '<'
+  | '>='
+  | '<='
+  | 'IS NULL'
+  | 'IS NOT NULL';
+
+/** A single date filter condition. `date` can be omitted for IS NULL / IS NOT NULL. */
+export interface DateFilter {
+  date?: string; // ISO-8601 datetime string, e.g. "2025-01-01T00:00:00Z"
+  comparison_operator: ComparisonOperator;
+}
+
+/**
+ * Date filters are passed as groups of OR-conditions combined with AND between groups:
+ *   [[a, b], [c]]  →  (a OR b) AND (c)
+ */
+export type DateFilterGroups = DateFilter[][];
+
+export type SearchStrategy =
+  | 'balanced'
+  | 'diverse'
+  | 'precise'
+  | 'contextual'
+  | 'recent_memory'
+  | 'facts_only'
+  | 'entities_only'
+  | 'topics_only';
+
+export type KnowledgeLevel = 'user' | 'oracle' | 'both';
+
+export type EntityType =
+  // Personal Identity
+  | 'Person'
+  | 'Trait'
+  | 'Value'
+  | 'Identity'
+  | 'Attribute'
+  // Mental & Emotional
+  | 'Emotion'
+  | 'Stress'
+  | 'CopingStrategy'
+  // Professional & Work
+  | 'Job'
+  | 'Project'
+  | 'Skill'
+  | 'Tool'
+  | 'Organization'
+  // Goals & Growth
+  | 'Goal'
+  | 'Milestone'
+  // Behaviors & Patterns
+  | 'Habit'
+  | 'Routine'
+  | 'Pattern'
+  // Interests & Entertainment
+  | 'Interest'
+  | 'Hobby'
+  | 'Content'
+  // Preferences
+  | 'Preference'
+  | 'Product'
+  // Knowledge & Learning
+  | 'Expertise'
+  | 'LearningGoal'
+  | 'Resource'
+  // Places & Experiences
+  | 'Location'
+  | 'Experience'
+  | 'Event'
+  // Social & Groups
+  | 'Group'
+  | 'Pet'
+  // Communication
+  | 'CommunicationStyle'
+  | 'Language'
+  // Tasks & Beliefs
+  | 'Task'
+  | 'Belief'
+  | 'Cause'
+  // Instructions
+  | 'Procedure'
+  // IXO/Qi Ontology
+  | 'Agent'
+  | 'SmartAccount'
+  | 'OutcomeUnit'
+  | 'Claim'
+  | 'Evaluation'
+  | 'ServiceEvent'
+  | 'Payment'
+  | 'VerifiableCredential';
+
+export type EdgeType =
+  // Personal Memory
+  | 'Knows'
+  | 'WorksWith'
+  | 'Causes'
+  | 'Enables'
+  | 'Blocks'
+  | 'PartOf'
+  | 'BelongsTo'
+  | 'Practices'
+  | 'Uses'
+  | 'Pursuing'
+  | 'Requires'
+  | 'Achieved'
+  | 'EmployedAt'
+  | 'WorksOn'
+  | 'Manages'
+  | 'LivesAt'
+  | 'VisitedLocation'
+  | 'LocatedIn'
+  | 'Prefers'
+  | 'Likes'
+  | 'Dislikes'
+  | 'InterestedIn'
+  | 'ExpertiseIn'
+  | 'Studying'
+  | 'LearnedFrom'
+  | 'Triggers'
+  | 'Motivates'
+  | 'ManagesVia'
+  | 'Influences'
+  | 'Supports'
+  | 'MemberOf'
+  | 'Owns'
+  | 'CurrentlyIs'
+  | 'WasPreviously'
+  | 'AlignedWith'
+  | 'ConflictsWith'
+  | 'RelatesTo'
+  // IXO/Qi Ontology
+  | 'OWNS'
+  | 'CONTROLS'
+  | 'SUBMITS_CLAIM'
+  | 'HAS_EVALUATION'
+  | 'RESULTS_IN_OUTCOME'
+  | 'TRIGGERS_PAYMENT'
+  | 'PAYS_FOR_SERVICE'
+  | 'HAS_IDENTITY';
+
+// ─── Tool input types ─────────────────────────────────────────────────────────

package/src/plugins/portal/action-log.ts

@@ -0,0 +1,34 @@
+/**
+ * The Node runtime's `logActionToMatrix`: a best-effort `ixo.action.log`
+ * room event recording a frontend action (browser tool / AG-UI action) and
+ * its outcome, posted only when the turn has a room. Never throws.
+ */
+import type { RuntimeContext } from '../../plugin-api/types';
+
+export const ACTION_LOG_EVENT_TYPE = 'ixo.action.log';
+
+export interface LoggedAction {
+  name: string;
+  args: Record<string, unknown>;
+  result: unknown;
+  error?: string;
+  success: boolean;
+}
+
+export function logActionToMatrix(
+  ctx: Pick<RuntimeContext, 'matrix' | 'session' | 'logger'>,
+  action: LoggedAction,
+): void {
+  const roomId = ctx.session.roomId;
+  if (!roomId) return;
+  void ctx.matrix
+    .postEvent(roomId, ACTION_LOG_EVENT_TYPE, {
+      action,
+      threadId: ctx.session.id,
+    })
+    .catch((err: unknown) => {
+      ctx.logger.warn?.(
+        `[portal] action log for ${action.name} not posted: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    });
+}

package/src/plugins/portal/index.ts

@@ -0,0 +1,2 @@
+export { PortalPlugin, parseBrowserTools } from './portal.plugin';
+export { logActionToMatrix, ACTION_LOG_EVENT_TYPE } from './action-log';

package/src/plugins/portal/portal.plugin.ts

@@ -0,0 +1,203 @@
+/**
+ * Portal plugin — the Workers port of the Node runtime's `PortalPlugin`.
+ *
+ * Every request-time tool comes from the client: the Portal declares its
+ * browser tools in the turn body (`tools[]` → `state.browserTools`, each a
+ * `{ name, description, schema }` JSON-schema descriptor), and this plugin
+ * turns each into an agent tool that runs IN THE BROWSER over the realtime
+ * channel (`ctx.frontend.callBrowserTool` → `browser_tool_call` socket event
+ * → the client answers `tool_result`).
+ *
+ * Runtime-supplied arguments: a descriptor may declare `oracleUserId`; it is
+ * hidden from the model and filled from `MATRIX_ORACLE_ADMIN_USER_ID` (the
+ * Portal's `create_page_room` uses it to invite the assistant into the new
+ * page), exactly as on Node.
+ */
+import { z } from 'zod';
+import type { BrowserToolCall } from '../../core/state';
+import { clientSchemaToZod } from '../../core/utils';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import { tool } from '../../plugin-api/tool-helper';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import { logActionToMatrix } from './action-log';
+
+const manifest: PluginManifest = {
+  title: 'Portal',
+  summary:
+    "Browser-side actions on the user's Portal UI — opens URLs, manipulates the DOM, runs FE-defined browser tools.",
+  whenToUse: [
+    'User asks for an action the Portal FE exposes as a browser tool (declared in `state.browserTools`).',
+    "A task needs a browser-side capability the server can't do alone — open a URL in the user's tab, click a Portal button, fill a form.",
+  ],
+  whenNotToUse: [
+    'No browser tools are declared on this request (no tools are contributed).',
+    'The task can be completed purely server-side (use a server tool or sub-agent).',
+  ],
+  examples: [
+    {
+      user: 'Open my workspace and navigate to the Reports page.',
+      thought:
+        'Portal exposes navigation as a browser tool — call the FE-declared tool (e.g. `open_url`) directly with the target URL.',
+      tool: 'open_url',
+    },
+  ],
+  tags: ['portal', 'browser', 'ui'],
+  category: 'ui',
+  visibility: 'on-demand',
+  stability: 'stable',
+};
+
+export const BROWSER_TOOL_TIMEOUT_MS = 15_000;
+
+const BROWSER_TOOL_SHAPE = z.object({
+  name: z.string(),
+  description: z.string(),
+  schema: z.record(z.string(), z.unknown()),
+});
+
+const ARGS_RECORD_SHAPE = z.record(z.string(), z.unknown());
+
+export function parseBrowserTools(value: unknown): BrowserToolCall[] {
+  if (!Array.isArray(value)) return [];
+  const out: BrowserToolCall[] = [];
+  for (const entry of value) {
+    const parsed = BROWSER_TOOL_SHAPE.safeParse(entry);
+    if (parsed.success) out.push(parsed.data);
+  }
+  return out;
+}
+
+function parseArgs(input: unknown): Record<string, unknown> {
+  const parsed = ARGS_RECORD_SHAPE.safeParse(input ?? {});
+  return parsed.success ? parsed.data : {};
+}
+
+/** Descriptor argument → config key whose value the runtime injects. */
+const RUNTIME_SUPPLIED_ARGS: Record<string, string> = {
+  oracleUserId: 'MATRIX_ORACLE_ADMIN_USER_ID',
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+export function stripRuntimeSuppliedArgs(
+  schema: Record<string, unknown>,
+): Record<string, unknown> {
+  const properties = schema.properties;
+  if (!isRecord(properties)) return schema;
+  const declared = Object.keys(RUNTIME_SUPPLIED_ARGS).filter(
+    (key) => key in properties,
+  );
+  if (declared.length === 0) return schema;
+  const nextProperties: Record<string, unknown> = { ...properties };
+  for (const key of declared) delete nextProperties[key];
+  const next: Record<string, unknown> = {
+    ...schema,
+    properties: nextProperties,
+  };
+  if (Array.isArray(schema.required)) {
+    next.required = schema.required.filter(
+      (name) => typeof name !== 'string' || !declared.includes(name),
+    );
+  }
+  return next;
+}
+
+export function withRuntimeSuppliedArgs(
+  args: Record<string, unknown>,
+  descriptor: BrowserToolCall,
+  config: Record<string, unknown>,
+): Record<string, unknown> {
+  const properties = descriptor.schema.properties;
+  if (!isRecord(properties)) return args;
+  const next = { ...args };
+  for (const [argName, configKey] of Object.entries(RUNTIME_SUPPLIED_ARGS)) {
+    if (!(argName in properties)) continue;
+    const value = config[configKey];
+    if (typeof value === 'string' && value.length > 0) next[argName] = value;
+  }
+  return next;
+}
+
+export function buildBrowserTool(
+  descriptor: BrowserToolCall,
+): PluginTool | null {
+  const schema = clientSchemaToZod(
+    stripRuntimeSuppliedArgs(descriptor.schema),
+    descriptor.name,
+  );
+  if (!schema) return null;
+  return tool(
+    async (input, ctx: RuntimeContext) => {
+      const sessionId = ctx.session.id;
+      if (!sessionId) {
+        throw new Error('sessionId is required for browser tools');
+      }
+      const frontend = ctx.frontend;
+      if (!frontend) {
+        throw new Error(
+          `Browser tool ${descriptor.name} needs the realtime channel, which this host does not provide.`,
+        );
+      }
+      if (!frontend.hasClient(sessionId)) {
+        throw new Error(
+          `No browser is connected to session ${sessionId}, so browser tool ${descriptor.name} cannot run — the client must open the realtime (socket.io) channel for this session first.`,
+        );
+      }
+      const args = withRuntimeSuppliedArgs(
+        parseArgs(input),
+        descriptor,
+        ctx.config,
+      );
+      // Node uses `tc-<requestId>`; the suffix keeps two browser tool calls in
+      // one turn from sharing an id (the client echoes it back verbatim).
+      const toolCallId = `tc-${ctx.session.requestId || 'noreq'}-${crypto
+        .randomUUID()
+        .slice(0, 8)}`;
+      const result = await frontend.callBrowserTool({
+        sessionId,
+        toolCallId,
+        toolName: descriptor.name,
+        args,
+        timeoutMs: BROWSER_TOOL_TIMEOUT_MS,
+      });
+      logActionToMatrix(ctx, {
+        name: descriptor.name,
+        args,
+        result,
+        success: true,
+      });
+      return result;
+    },
+    {
+      name: descriptor.name,
+      description: descriptor.description,
+      schema,
+    },
+  );
+}
+
+function readBrowserTools(rtCtx: RuntimeContext): BrowserToolCall[] {
+  return parseBrowserTools(rtCtx.history.state.browserTools);
+}
+
+export class PortalPlugin extends OraclePlugin {
+  readonly name = 'portal';
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override async getRequestTools(rtCtx: RuntimeContext): Promise<PluginTool[]> {
+    const browserTools = readBrowserTools(rtCtx);
+    if (browserTools.length === 0) return [];
+    return browserTools
+      .map(buildBrowserTool)
+      .filter((t): t is PluginTool => t !== null);
+  }
+}

package/src/plugins/sandbox/index.ts

@@ -0,0 +1,34 @@
+export {
+  defaultSandboxMcpClientFactory,
+  getSandboxBridge,
+  hasShellUnsafeChars,
+  inferMimeFromPath,
+  isUnderWorkspaceData,
+  readSandboxFile,
+  readSandboxResult,
+  SANDBOX_NO_FILE_SENTINEL,
+  SANDBOX_NOT_AUTHORIZED_MESSAGE,
+  SANDBOX_WRITE_FILE_TOOL_NAME,
+  WORKSPACE_DATA_PREFIX,
+  writeSandboxFile,
+  type SandboxBridge,
+  type SandboxOutcome,
+} from './sandbox-bridge';
+export {
+  createDefaultAuthBuilder,
+  parseOracleSecrets,
+  SANDBOX_RUN_TOOL_NAME,
+  type SandboxAuthBuilder,
+  type SandboxHeaderInputs,
+} from './sandbox-mcp';
+export {
+  createSandboxWriteBlobTool,
+  type CreateSandboxWriteBlobToolParams,
+} from './sandbox-write-blob';
+export {
+  SandboxPlugin,
+  type SandboxMcpClientFactory,
+  type SandboxMcpClientLike,
+  type SandboxMcpTool,
+  type SandboxPluginOptions,
+} from './sandbox.plugin';