@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/vfs/vfs.plugin.ts

@@ -0,0 +1,201 @@
+import { z } from 'zod';
+import {
+  UCAN_STORE_DEFAULT_URLS,
+  VFS_DEFAULT_BASE_URLS,
+} from '../../owner-store/ixo-vfs-store';
+import { OraclePlugin } from '../../plugin-api/oracle-plugin';
+import type {
+  PluginManifest,
+  PluginTool,
+  RuntimeContext,
+} from '../../plugin-api/types';
+import type { SandboxMcpClientFactory } from '../sandbox/sandbox.plugin';
+import { createVfsSandboxTools } from './vfs-sandbox-tools';
+import { createVfsTools } from './vfs-tools';
+
+/** Optional tuning env this plugin owns (the worker URLs come from NETWORK). */
+const configSchema = z.object({
+  VFS_MAX_READ_LINES: z.coerce.number().int().positive().default(2000),
+  VFS_REQUEST_TIMEOUT_MS: z.coerce.number().int().positive().default(20000),
+});
+
+/**
+ * Sibling env the VFS plugin reads but does not own. `NETWORK` (owned by the
+ * base runtime schema) selects the worker URLs; `VFS_BASE_URL` /
+ * `UCAN_STORE_URL` (also base-schema keys, used by the VFS owner store) act
+ * as per-deployment overrides; `SANDBOX_MCP_URL` (owned by the sandbox
+ * plugin), when set, adds the two sandbox↔files bridge tools so a file can
+ * move between the two without its bytes passing through the LLM.
+ */
+const siblingEnvSchema = z.object({
+  NETWORK: z.enum(['mainnet', 'testnet', 'devnet']).optional(),
+  VFS_BASE_URL: z.string().url().optional(),
+  UCAN_STORE_URL: z.string().url().optional(),
+  SANDBOX_MCP_URL: z.string().url().optional(),
+});
+
+/** Runtime VFS config the client + tools consume. URLs derived from NETWORK. */
+export interface VfsConfig {
+  VFS_BASE_URL: string;
+  UCAN_STORE_URL: string;
+  VFS_MAX_READ_LINES: number;
+  VFS_REQUEST_TIMEOUT_MS: number;
+}
+
+const manifest: PluginManifest = {
+  title: 'Files',
+  summary:
+    "The user's Virtual Filesystem (VFS) — their persistent, secure, governed filesystem: the canonical home for their real documents, notes, datasets, and artifacts, in folders, searchable and versioned linked to their domain. Reusable context that lives across sessions — not scratch files, not chat attachments, not the web. Securely stored and access-controlled (managed encryption); authorized IXO services can read content to power search, previews, and these tools, so it is NOT end-to-end encrypted — never describe it as zero-knowledge or unreadable by IXO.",
+  category: 'data',
+  // On-demand with two exceptions: `vfs_search` and `vfs_read` carry per-tool
+  // `visibility: 'always'` so recall ("what did my notes say…") works with no
+  // load step. The write/organise/share surface (and the sandbox bridges)
+  // loads via `load_capability(['vfs'])` — keeping ~11 tool schemas out of
+  // every unrelated chat turn.
+  visibility: 'on-demand',
+  whenToUse: [
+    "The user refers to a document, note, file, folder, or something they 'saved', 'uploaded', or 'shared with you'.",
+    'You need to create, update, or organise a file for the user (draft, report, notes, export) that should persist.',
+    'You need to find or quote something from the user\'s files ("what did my notes say about X", "find the contract").',
+    'You can reuse a file the user already has instead of asking them to paste or re-upload it.',
+    'The user asks you to share a file or make it downloadable.',
+    "Persist something the sandbox produced (a report, export, chart, or dataset under /workspace/…) into the user's files so it survives the session — use `sandbox_to_vfs`.",
+    "Feed one of the user's files into the sandbox so `sandbox_run` code can process it — use `vfs_to_sandbox` (writes under /workspace/data/).",
+    'Remember you act ONLY within the files and rights the user granted you. If a file action reports you have no access (or only read-only), relay the short grant steps the tool returns — with your agent DID — so the user can authorize you, then retry. Never claim a file is missing when the real issue is access.',
+  ],
+  whenNotToUse: [
+    "General knowledge or web questions — the files are the user's private content, not a knowledge base of the world.",
+    "Content the user pasted directly into chat (act on that inline; don't write it to a file unless asked).",
+    "Temporary/scratch or intermediate files produced during a code or compute run — those belong to the sandbox, not the user's filesystem.",
+    'Another plugin owns the data (flows, skills, memory) — use that plugin.',
+  ],
+  examples: [
+    {
+      user: 'What did my project notes say about the launch date?',
+      thought: "Search the user's files, then read the relevant lines.",
+      tool: 'vfs_search',
+      args: { q: 'launch date', path: '/' },
+    },
+    {
+      user: 'Save this summary as notes/meeting-2026-07.md',
+      thought: 'Create the file at that path.',
+      tool: 'vfs_write',
+      args: { path: '/notes/meeting-2026-07.md' },
+    },
+    {
+      user: 'In todo.md change "Draft" to "Final"',
+      thought: 'Exact-string edit.',
+      tool: 'vfs_edit',
+      args: { path: '/todo.md', oldString: 'Draft', newString: 'Final' },
+    },
+    {
+      user: 'Share my resume so I can send a link',
+      thought: 'Publish it and return the link.',
+      tool: 'vfs_share',
+      args: { path: '/resume.pdf', public: true },
+    },
+  ],
+};
+
+/** Optional dependency injection — primarily for tests. */
+export interface VfsPluginOptions {
+  /** Injected transport for the VFS client. Defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Retry backoff forwarded to the VFS client. Tests pass `0`. */
+  retryDelayMs?: number;
+  /** Injected sandbox MCP-client factory for the two bridge tools. */
+  sandboxMcpClientFactory?: SandboxMcpClientFactory;
+}
+
+/**
+ * VFS plugin.
+ *
+ * Contributes ten file tools (`vfs_search`, `vfs_grep`, `vfs_glob`,
+ * `vfs_list`, `vfs_read`, `vfs_write`, `vfs_edit`, `vfs_move`, `vfs_delete`,
+ * `vfs_share`) that read, create, edit, search, organise, and share a user's
+ * files on the IXO Virtual Filesystem. The oracle acts as the user, inside the
+ * folder the user delegated to it; each tool resolves a fresh single-use UCAN
+ * bearer per call.
+ *
+ * When the sandbox is also configured (`SANDBOX_MCP_URL`, a sibling env owned
+ * by the sandbox plugin), two extra bridge tools are added — `sandbox_to_vfs`
+ * and `vfs_to_sandbox` — that move a file between the user's sandbox and their
+ * files entirely server-side, so the bytes never pass through the LLM.
+ *
+ * Tools are request-time (`getRequestTools`) because auth needs the live
+ * `rtCtx.user.did` and the user's deposited delegation. With no signing key,
+ * or invalid config, the plugin contributes nothing and the agent simply
+ * doesn't see the filesystem that turn. Always on — no `autoDetect`.
+ */
+export class VfsPlugin extends OraclePlugin {
+  readonly name = 'vfs';
+
+  readonly version = '1.0.0';
+
+  readonly manifest = manifest;
+
+  override readonly configSchema = configSchema;
+
+  private readonly options: VfsPluginOptions;
+
+  constructor(options: VfsPluginOptions = {}) {
+    super();
+    this.options = options;
+  }
+
+  override getRequestTools(rtCtx: RuntimeContext): PluginTool[] {
+    if (!rtCtx.ucan.hasSigningKey()) {
+      rtCtx.logger.warn('[vfs] skipping — oracle has no UCAN signing key.');
+      return [];
+    }
+
+    const tuning = configSchema.safeParse(rtCtx.config);
+    const siblings = siblingEnvSchema.safeParse(rtCtx.config);
+    const network = (siblings.success && siblings.data.NETWORK) || 'mainnet';
+    const cfg: VfsConfig = {
+      VFS_BASE_URL:
+        (siblings.success && siblings.data.VFS_BASE_URL) ||
+        VFS_DEFAULT_BASE_URLS[network] ||
+        // Unreachable: `network` is one of the three keys the map declares.
+        'https://vfs.ixo.earth',
+      UCAN_STORE_URL:
+        (siblings.success && siblings.data.UCAN_STORE_URL) ||
+        UCAN_STORE_DEFAULT_URLS[network] ||
+        'https://store.ucan.ixo.earth',
+      VFS_MAX_READ_LINES: tuning.success
+        ? tuning.data.VFS_MAX_READ_LINES
+        : 2000,
+      VFS_REQUEST_TIMEOUT_MS: tuning.success
+        ? tuning.data.VFS_REQUEST_TIMEOUT_MS
+        : 20000,
+    };
+
+    const tools = createVfsTools({
+      cfg,
+      fetchImpl: this.options.fetchImpl,
+      retryDelayMs: this.options.retryDelayMs,
+    });
+
+    // When the sandbox is configured, add the two sandbox↔files bridge tools.
+    // The sandbox MCP client is built lazily inside each handler, so adding
+    // them costs nothing until one is actually called.
+    const sandboxMcpUrl = siblings.success
+      ? siblings.data.SANDBOX_MCP_URL
+      : undefined;
+    if (sandboxMcpUrl) {
+      tools.push(
+        ...createVfsSandboxTools(
+          {
+            vfsCfg: cfg,
+            sandboxMcpUrl,
+            vfsFetchImpl: this.options.fetchImpl,
+            vfsRetryDelayMs: this.options.retryDelayMs,
+          },
+          this.options.sandboxMcpClientFactory,
+        ),
+      );
+    }
+
+    return tools;
+  }
+}

package/src/realtime/frontend-call-registry.ts

@@ -0,0 +1,163 @@
+/**
+ * Pending frontend (browser-tool / AG-UI action) calls awaiting a result
+ * from the user's browser — the Workers counterpart of the Node runtime's
+ * `callFrontendTool`, which parks a promise on `rootEventEmitter` until the
+ * socket delivers `browser_tool_result` / `action_call_result` for the same
+ * `toolCallId`.
+ *
+ * Settlement rules are Node's, verbatim:
+ *   - `error` set                      → reject(Error(error))
+ *   - AG-UI and `result.success === false` → reject(Error(result.error ?? 'Action failed'))
+ *   - otherwise                        → resolve(result)
+ *   - no result within `timeoutMs`     → reject("<kind> timeout after <ms>ms: <tool>")
+ *
+ * Purely in-memory: a pending call does not survive an object restart, and
+ * neither does the turn that made it.
+ */
+
+export type FrontendCallKind = 'browser' | 'agui';
+
+export interface FrontendCallResult {
+  toolCallId: string;
+  result?: unknown;
+  error?: string;
+}
+
+export interface PendingFrontendCall {
+  kind: FrontendCallKind;
+  toolCallId: string;
+  toolName: string;
+  sessionId: string;
+  startedAt: number;
+}
+
+interface Pending extends PendingFrontendCall {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const KIND_LABEL: Record<FrontendCallKind, string> = {
+  browser: 'Browser tool',
+  agui: 'AG-UI action',
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function readSuccessFlag(result: unknown): {
+  success?: boolean;
+  error?: string;
+} {
+  if (!isRecord(result)) return {};
+  const record = result;
+  return {
+    ...(typeof record.success === 'boolean' ? { success: record.success } : {}),
+    ...(typeof record.error === 'string' ? { error: record.error } : {}),
+  };
+}
+
+export class FrontendCallRegistry {
+  private readonly pending = new Map<string, Pending>();
+
+  private key(kind: FrontendCallKind, toolCallId: string): string {
+    return `${kind}:${toolCallId}`;
+  }
+
+  /**
+   * Park a call until `settle` delivers its result or `timeoutMs` elapses.
+   * `signal` (the turn's abort signal) rejects early so an aborted turn does
+   * not keep a browser waiting.
+   */
+  wait(
+    call: Omit<PendingFrontendCall, 'startedAt'>,
+    opts: { timeoutMs: number; signal?: AbortSignal },
+  ): Promise<unknown> {
+    const key = this.key(call.kind, call.toolCallId);
+    const existing = this.pending.get(key);
+    if (existing) {
+      this.finish(key);
+      existing.reject(
+        new Error(`${KIND_LABEL[call.kind]} ${call.toolCallId} was superseded`),
+      );
+    }
+    return new Promise<unknown>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.finish(key);
+        reject(
+          new Error(
+            `${KIND_LABEL[call.kind]} timeout after ${opts.timeoutMs}ms: ${call.toolName}`,
+          ),
+        );
+      }, opts.timeoutMs);
+      const entry: Pending = {
+        ...call,
+        startedAt: Date.now(),
+        resolve,
+        reject,
+        timer,
+      };
+      this.pending.set(key, entry);
+      if (opts.signal) {
+        const onAbort = () => {
+          if (this.pending.get(key) !== entry) return;
+          this.finish(key);
+          reject(
+            new Error(`${KIND_LABEL[call.kind]} ${call.toolName} aborted`),
+          );
+        };
+        if (opts.signal.aborted) onAbort();
+        else opts.signal.addEventListener('abort', onAbort, { once: true });
+      }
+    });
+  }
+
+  /**
+   * Deliver a result from the socket. Returns false when nothing was waiting
+   * for that id (late, duplicate or unknown result — logged by the caller).
+   */
+  settle(kind: FrontendCallKind, data: FrontendCallResult): boolean {
+    const key = this.key(kind, data.toolCallId);
+    const entry = this.pending.get(key);
+    if (!entry) return false;
+    this.finish(key);
+    if (data.error) {
+      entry.reject(new Error(data.error));
+      return true;
+    }
+    if (kind === 'agui') {
+      const flags = readSuccessFlag(data.result);
+      if (flags.success === false) {
+        entry.reject(new Error(flags.error || 'Action failed'));
+        return true;
+      }
+    }
+    entry.resolve(data.result);
+    return true;
+  }
+
+  /** Pending calls, oldest first (diagnostics / status). */
+  list(): PendingFrontendCall[] {
+    return [...this.pending.values()]
+      .map(({ kind, toolCallId, toolName, sessionId, startedAt }) => ({
+        kind,
+        toolCallId,
+        toolName,
+        sessionId,
+        startedAt,
+      }))
+      .sort((a, b) => a.startedAt - b.startedAt);
+  }
+
+  get size(): number {
+    return this.pending.size;
+  }
+
+  private finish(key: string): void {
+    const entry = this.pending.get(key);
+    if (!entry) return;
+    clearTimeout(entry.timer);
+    this.pending.delete(key);
+  }
+}