@ixo/oracle-runtime-workers 0.2.0

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

@@ -0,0 +1,181 @@
+import { HumanMessage } from '@langchain/core/messages';
+import type { MessageContent } from '@langchain/core/messages';
+import type { RuntimeContext } from '../../plugin-api/types';
+import { bytesToBase64 } from '../base64';
+import type { VfsClient, VfsFileStat } from './vfs-client';
+import { VfsHttpError } from './vfs-errors';
+
+/** Cap on the bytes we base64 into the vision model. */
+const MAX_VISION_BYTES = 10 * 1024 * 1024;
+
+/** MIME types that are text even though they don't start with `text/`. */
+const TEXT_MIME_EXACT = new Set<string>([
+  'application/json',
+  'application/xml',
+  'application/xhtml+xml',
+  'application/javascript',
+  'application/typescript',
+  'application/yaml',
+  'application/x-yaml',
+  'application/toml',
+  'application/csv',
+  'application/x-ndjson',
+  'application/x-sh',
+  'image/svg+xml',
+]);
+
+export function isTextMime(mime: string): boolean {
+  const m = mime.toLowerCase();
+  if (m.startsWith('text/')) return true;
+  if (m.endsWith('+json') || m.endsWith('+xml')) return true;
+  return TEXT_MIME_EXACT.has(m);
+}
+
+function isDocMime(mime: string): boolean {
+  const m = mime.toLowerCase();
+  return (
+    m === 'application/pdf' ||
+    m.startsWith('application/vnd.openxmlformats') ||
+    m.startsWith('application/vnd.oasis') ||
+    m === 'application/msword'
+  );
+}
+
+function basename(p: string): string {
+  const i = p.lastIndexOf('/');
+  return i >= 0 ? p.slice(i + 1) : p;
+}
+
+/**
+ * Render a text window for the agent. The VFS already returns display-ready
+ * numbered text (cat -n style), so we pass it through and only append a
+ * continuation footer when there are more lines to page.
+ */
+function renderTextWindow(
+  text: string,
+  offset: number,
+  count: number,
+  hasMore: boolean,
+  totalLines: number,
+): string {
+  if (text.trim().length === 0) return '(empty file)';
+  if (!hasMore) return text;
+
+  const nextOffset = offset + count;
+  return `${text}\n… more lines below (${totalLines} total). Call vfs_read again with offset=${nextOffset} to continue.`;
+}
+
+/**
+ * Read a non-text file for the agent. Fetches the bytes, then either returns a
+ * size stub (too large / unsupported binary) or routes the bytes through the
+ * vision model and returns its description/transcription. Never throws — a
+ * vision failure degrades to a metadata stub.
+ */
+async function renderBinary(
+  client: VfsClient,
+  rtCtx: RuntimeContext,
+  stat: VfsFileStat,
+): Promise<string> {
+  const { bytes, mimeType, size } = await client.contentBytes(stat.id);
+  const name = basename(stat.path) || stat.id;
+  const mime = mimeType || stat.mimeType || 'application/octet-stream';
+  const publicSuffix = stat.publicUrl
+    ? ` — public link: ${stat.publicUrl}`
+    : '';
+
+  if (size > MAX_VISION_BYTES) {
+    return `[binary file "${name}" — ${mime}, ${size} bytes — too large to render${publicSuffix}]`;
+  }
+
+  const isImage = mime.startsWith('image/');
+  const isDoc = isDocMime(mime);
+  if (!isImage && !isDoc) {
+    return `[binary file "${name}" — ${mime}, ${size} bytes — not rendered${publicSuffix}]`;
+  }
+
+  const base64 = bytesToBase64(new Uint8Array(bytes));
+  const prompt = isImage
+    ? 'Describe this image in detail and transcribe any text visible in it. Be factual and thorough.'
+    : 'Extract and transcribe the full text content of this document, preserving structure and headings where possible.';
+  // langchain 1.x standard "data content blocks". The @langchain/openai
+  // completions converter (the OpenRouter path) only recognises these when they
+  // carry `source_type: 'base64'` + snake_case `mime_type` — it emits
+  // `image_url: data:<mime_type>;base64,<data>` (and `file_data` for files).
+  // Omitting source_type / using camelCase makes the block unrecognised and the
+  // image never reaches the model.
+  const mediaBlock = isImage
+    ? { type: 'image', source_type: 'base64', mime_type: mime, data: base64 }
+    : {
+        type: 'file',
+        source_type: 'base64',
+        mime_type: mime,
+        data: base64,
+        filename: name,
+      };
+  const content: MessageContent = [{ type: 'text', text: prompt }, mediaBlock];
+
+  try {
+    const model = rtCtx.llm.get('vision');
+    const result = await model.invoke([new HumanMessage({ content })], {
+      signal: rtCtx.abortSignal,
+    });
+    const text =
+      typeof result.content === 'string'
+        ? result.content
+        : String(result.content);
+    if (text.trim().length > 0) return text;
+    return `[${isImage ? 'image' : 'document'} "${name}" — ${mime}, ${size} bytes — no description returned${publicSuffix}]`;
+  } catch (err) {
+    rtCtx.logger.warn(
+      `[vfs] vision render failed for ${name}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return `[${isImage ? 'image' : 'document'} "${name}" — ${mime}, ${size} bytes — could not be rendered${publicSuffix}]`;
+  }
+}
+
+/**
+ * Resolve a path to a file and return content the agent can read: numbered
+ * lines for text, a vision transcription for images/PDFs, or a metadata stub
+ * for other binaries. Throws a `404` {@link VfsHttpError} when the path
+ * doesn't resolve to a file.
+ */
+export async function readForAgent(
+  client: VfsClient,
+  rtCtx: RuntimeContext,
+  path: string,
+  offset: number,
+  limit: number,
+): Promise<string> {
+  const stat = await client.statByPath(path);
+  if (!stat) {
+    throw new VfsHttpError({
+      status: 404,
+      message: `No such file at ${path}`,
+      raw: '',
+    });
+  }
+
+  const mime = stat.mimeType || '';
+  // Clearly-binary MIME → skip the line read entirely.
+  if (mime && !isTextMime(mime)) {
+    return renderBinary(client, rtCtx, stat);
+  }
+
+  // Textual or unknown → attempt a windowed line read; fall back to the binary
+  // path if the VFS rejects it as not-text (415).
+  try {
+    const win = await client.readLines(stat.id, offset, limit);
+    return renderTextWindow(
+      win.text,
+      win.offset,
+      win.count,
+      win.hasMore,
+      win.totalLines,
+    );
+  } catch (err) {
+    if (err instanceof VfsHttpError && err.status === 415) {
+      return renderBinary(client, rtCtx, stat);
+    }
+    throw err;
+  }
+}

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

@@ -0,0 +1,163 @@
+/**
+ * VFS error contract.
+ *
+ * Every transport failure is mapped to one of two typed errors:
+ *   - {@link VfsHttpError}  — a non-2xx HTTP response (status + parsed message).
+ *   - {@link VfsAuthError}  — a two-hop UCAN auth failure (no delegation, store
+ *     unreachable, or mint failed) surfaced before any request leaves.
+ *
+ * {@link mapVfsError} turns either into a single agent-actionable string; the
+ * tools return that string (never a raw stack). The 409 family is
+ * disambiguated by message substring because the VFS reuses `409 Conflict`
+ * for five distinct situations.
+ */
+
+/** Minimum UCAN ability required for a VFS operation. */
+export type VfsAbility = 'fs/list' | 'fs/read' | 'fs/write' | 'fs/delete';
+
+/** Why the two-hop auth resolution failed. */
+export type VfsAuthErrorKind = 'no-delegation' | 'store-error' | 'mint-failed';
+
+/**
+ * Step-by-step guidance shown when the user hasn't granted the oracle
+ * filesystem access. Walks them through the portal's Manage-access flow
+ * (domain → Library → Files → Access). When the oracle's own DID is known it is
+ * appended so the user can paste it straight into the "Recipient DID" field.
+ */
+export function noAccessMessage(oracleDid?: string): string {
+  const steps =
+    "I don't have access to your files yet. To grant me access, in the portal: open your domain → **Library** → **Files**, click **Access** (top-right), then in **Manage access** paste my agent DID as the Recipient DID, choose the rights (Read / Write / Delete), set the scope and how long it lasts, and click **Grant access**. It's delivered to my inbox and I pick it up automatically — then ask me again.";
+  return oracleDid ? `${steps}\n\nMy agent DID: ${oracleDid}` : steps;
+}
+
+/** The no-access guidance with no DID (back-compat + barrel export). */
+export const NO_ACCESS_MESSAGE = noAccessMessage();
+
+/** A non-2xx response from the VFS, with the parsed message + raw body. */
+export class VfsHttpError extends Error {
+  readonly status: number;
+
+  readonly raw: string;
+
+  readonly code?: string;
+
+  constructor(params: {
+    status: number;
+    message: string;
+    raw: string;
+    code?: string;
+  }) {
+    super(params.message);
+    this.name = 'VfsHttpError';
+    this.status = params.status;
+    this.raw = params.raw;
+    if (params.code !== undefined) this.code = params.code;
+  }
+}
+
+/** A UCAN auth failure raised before (or instead of) an HTTP round-trip. */
+export class VfsAuthError extends Error {
+  readonly kind: VfsAuthErrorKind;
+
+  readonly detail?: string;
+
+  constructor(kind: VfsAuthErrorKind, detail?: string) {
+    super(detail && detail.length > 0 ? detail : kind);
+    this.name = 'VfsAuthError';
+    this.kind = kind;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+/** Lowercased `<message> <raw>` used for substring classification. */
+function haystack(err: VfsHttpError): string {
+  return `${err.message} ${err.raw}`.toLowerCase();
+}
+
+/**
+ * `true` when the error is a `409` whose body says the file was modified by
+ * another writer. This is the one mutation case tools retry once.
+ */
+export function isWriteConflict(err: unknown): err is VfsHttpError {
+  return (
+    err instanceof VfsHttpError &&
+    err.status === 409 &&
+    /modified concurrently/.test(haystack(err))
+  );
+}
+
+/** `true` when the error is a `409` from creating a file at an existing path. */
+export function isAlreadyExistsConflict(err: unknown): err is VfsHttpError {
+  return (
+    err instanceof VfsHttpError &&
+    err.status === 409 &&
+    /already exists/.test(haystack(err))
+  );
+}
+
+/** Agent-facing message for a `409`, disambiguated by the body substring. */
+function map409(err: VfsHttpError, path?: string): string {
+  const text = haystack(err);
+  if (/already exists/.test(text)) {
+    return path
+      ? `A file already exists at \`${path}\`. Ask the user before overwriting it.`
+      : 'A file already exists at that path. Ask the user before overwriting it.';
+  }
+  if (/oldstring/.test(text)) {
+    return `Couldn't apply the edit: ${err.message}. Read the file first and add more surrounding context so the text matches exactly once, or set replaceAll.`;
+  }
+  if (/destination occupied|duplicate id/.test(text)) {
+    return `Couldn't move it — the destination is occupied: ${err.message}.`;
+  }
+  if (/version limit reached/.test(text)) {
+    return 'This file hit its 50-version limit. Delete old versions before saving again, or write the change as a new file.';
+  }
+  if (/modified concurrently/.test(text)) {
+    return 'The file was changed by someone else while I was writing. Please try again.';
+  }
+  return (
+    err.message || 'That change conflicts with the current state of the file.'
+  );
+}
+
+/**
+ * Turn a {@link VfsHttpError} or {@link VfsAuthError} into a single
+ * agent-actionable sentence. `ctx.path` enriches the "already exists" message.
+ */
+export function mapVfsError(
+  err: unknown,
+  ctx: { path?: string; oracleDid?: string } = {},
+): string {
+  if (err instanceof VfsAuthError) {
+    return err.kind === 'no-delegation'
+      ? noAccessMessage(ctx.oracleDid)
+      : "Couldn't get filesystem access right now.";
+  }
+
+  if (err instanceof VfsHttpError) {
+    switch (err.status) {
+      case 401:
+        return "Couldn't authenticate to your filesystem right now.";
+      case 403:
+        return `That's outside what you shared with me — it may be read-only, or a different folder than the one you granted. To give me more access, re-grant in the portal: your domain → Library → Files → Access → Manage access.${ctx.oracleDid ? ` My agent DID: ${ctx.oracleDid}.` : ''}`;
+      case 404:
+        return "No such file, or it's outside the folder you shared.";
+      case 409:
+        return map409(err, ctx.path);
+      case 413:
+      case 415:
+        return `${err.message || `The file could not be handled (HTTP ${err.status})`} — try a smaller scope, or replace the file instead.`;
+      case 429:
+        return 'The filesystem is busy right now — please try again in a moment.';
+      case 503:
+        return 'Filesystem temporarily unavailable.';
+      default:
+        if (err.status === 0 || err.status >= 500) {
+          return 'Filesystem request failed.';
+        }
+        return err.message || 'Filesystem request failed.';
+    }
+  }
+
+  return 'Filesystem request failed.';
+}

package/src/plugins/vfs/vfs-sandbox-tools.ts

@@ -0,0 +1,272 @@
+import { z } from 'zod';
+import { tool } from '../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import { bytesToBase64 } from '../base64';
+import {
+  getSandboxBridge,
+  hasShellUnsafeChars,
+  inferMimeFromPath,
+  isUnderWorkspaceData,
+  readSandboxFile,
+  readSandboxResult,
+  writeSandboxFile,
+  type SandboxBridge,
+} from '../sandbox/sandbox-bridge';
+import type { SandboxMcpClientFactory } from '../sandbox/sandbox.plugin';
+import type { VfsFileStat } from './vfs-client';
+import { isTextMime } from './vfs-content';
+import {
+  isAlreadyExistsConflict,
+  mapVfsError,
+  VfsAuthError,
+  VfsHttpError,
+} from './vfs-errors';
+import { buildClient, invalidArgs, validatePath } from './vfs-tools';
+import type { VfsConfig } from './vfs.plugin';
+
+export interface CreateVfsSandboxToolsDeps {
+  /** Validated VFS config (the subset of merged env the VFS plugin owns). */
+  vfsCfg: VfsConfig;
+  /** Sandbox MCP base URL — owned by the sandbox plugin, read as a sibling. */
+  sandboxMcpUrl: string;
+  /** Injected transport for the VFS client in tests. Defaults to global `fetch`. */
+  vfsFetchImpl?: typeof fetch;
+  /** Retry backoff forwarded to the VFS client. Tests pass `0`. */
+  vfsRetryDelayMs?: number;
+}
+
+/**
+ * Run a transfer body, mapping VFS auth/HTTP errors to their agent-facing
+ * string and any other throw to a short generic message, then close the
+ * sandbox bridge. A handler never throws out to the graph.
+ */
+async function runTransfer(
+  ctx: RuntimeContext,
+  bridge: SandboxBridge,
+  info: { path?: string },
+  fn: () => Promise<string>,
+): Promise<string> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (err instanceof VfsHttpError || err instanceof VfsAuthError) {
+      return mapVfsError(err, info);
+    }
+    ctx.logger.warn(
+      `[vfs] sandbox transfer failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return 'The file transfer failed.';
+  } finally {
+    await bridge.close();
+  }
+}
+
+const sandboxToVfsSchema = z.object({
+  sandboxPath: z
+    .string()
+    .min(1)
+    .describe(
+      'Absolute path of the file inside the sandbox to save, e.g. /workspace/data/output/report.pdf or /workspace/output/export.csv.',
+    ),
+  vfsPath: z
+    .string()
+    .min(1)
+    .describe(
+      "Absolute destination path in the user's files, e.g. /reports/q3.pdf. The extension sets the stored file type.",
+    ),
+  overwrite: z
+    .boolean()
+    .optional()
+    .describe(
+      'Replace an existing file at vfsPath instead of failing. Default false.',
+    ),
+  deleteSource: z
+    .boolean()
+    .optional()
+    .describe(
+      'Delete the sandbox file after a successful save (move instead of copy). Default false.',
+    ),
+});
+
+const vfsToSandboxSchema = z.object({
+  vfsPath: z
+    .string()
+    .min(1)
+    .describe(
+      "Absolute path of the user's file to bring in, e.g. /data/sales.csv.",
+    ),
+  sandboxPath: z
+    .string()
+    .min(1)
+    .describe(
+      'Absolute destination in the sandbox. Must be under /workspace/data/, e.g. /workspace/data/input/sales.csv.',
+    ),
+  deleteSource: z
+    .boolean()
+    .optional()
+    .describe(
+      'Move the file to trash after copying it into the sandbox. Default false (copy).',
+    ),
+});
+
+/**
+ * Build the two sandbox↔VFS bridge tools. Each reads the bytes on one side and
+ * writes them on the other entirely server-side — the file content never
+ * passes through the LLM. The sandbox MCP client is built on demand inside the
+ * handler and always closed, so an unused bridge adds zero per-turn overhead.
+ */
+export function createVfsSandboxTools(
+  deps: CreateVfsSandboxToolsDeps,
+  mcpClientFactory?: SandboxMcpClientFactory,
+): PluginTool[] {
+  const vfsClient = (ctx: RuntimeContext) =>
+    buildClient(ctx, {
+      cfg: deps.vfsCfg,
+      fetchImpl: deps.vfsFetchImpl,
+      retryDelayMs: deps.vfsRetryDelayMs,
+    });
+
+  const sandboxToVfs = tool(
+    async (raw, ctx) => {
+      const parsed = sandboxToVfsSchema.safeParse(raw);
+      if (!parsed.success) return invalidArgs(parsed.error);
+      const { sandboxPath, vfsPath } = parsed.data;
+      const overwrite = parsed.data.overwrite ?? false;
+      const deleteSource = parsed.data.deleteSource ?? false;
+
+      if (hasShellUnsafeChars(sandboxPath)) {
+        return `The sandbox path contains characters I can't safely handle (quotes or newlines). Rename it and try again.`;
+      }
+      const vfsErr = validatePath(vfsPath);
+      if (vfsErr) return `Invalid destination path: ${vfsErr}`;
+
+      const bridge = await getSandboxBridge(
+        ctx,
+        deps.sandboxMcpUrl,
+        mcpClientFactory,
+      );
+      if ('error' in bridge) return bridge.error;
+
+      return runTransfer(ctx, bridge, { path: vfsPath }, async () => {
+        const read = await readSandboxFile(bridge, sandboxPath);
+        if ('error' in read) return read.error;
+
+        const bytes = read.bytes;
+        const mime = inferMimeFromPath(vfsPath);
+        const client = vfsClient(ctx);
+
+        let created: VfsFileStat;
+        try {
+          created = await client.create(vfsPath, bytes, mime);
+        } catch (err) {
+          if (!isAlreadyExistsConflict(err)) throw err;
+          if (!overwrite) {
+            return `A file already exists at \`${vfsPath}\` (set overwrite to replace it).`;
+          }
+          const stat = await client.statByPath(vfsPath);
+          if (!stat) {
+            throw new VfsHttpError({
+              status: 404,
+              message: `No such file at ${vfsPath}`,
+              raw: '',
+            });
+          }
+          created = await client.replace(stat.id, bytes, mime);
+        }
+
+        let deletedSource = false;
+        let note: string | undefined;
+        if (deleteSource) {
+          const rm = readSandboxResult(
+            await bridge.run.invoke({ code: `rm -f '${sandboxPath}'` }),
+          );
+          deletedSource = rm.ok;
+          if (!rm.ok) note = 'could not delete the sandbox source file';
+        }
+
+        return JSON.stringify({
+          ok: true,
+          vfsPath,
+          bytes: bytes.byteLength,
+          cid: created.id || undefined,
+          movedFromSandbox: sandboxPath,
+          deletedSource,
+          ...(note ? { note } : {}),
+        });
+      });
+    },
+    {
+      name: 'sandbox_to_vfs',
+      description:
+        "Save a file the sandbox produced (a generated report, export, chart, dataset under /workspace/…) into the user's permanent files so it persists and is searchable. Copies by default; set deleteSource to move.",
+      schema: sandboxToVfsSchema,
+    },
+  );
+
+  const vfsToSandbox = tool(
+    async (raw, ctx) => {
+      const parsed = vfsToSandboxSchema.safeParse(raw);
+      if (!parsed.success) return invalidArgs(parsed.error);
+      const { vfsPath, sandboxPath } = parsed.data;
+      const deleteSource = parsed.data.deleteSource ?? false;
+
+      if (!isUnderWorkspaceData(sandboxPath)) {
+        return `The sandbox destination must be under /workspace/data/ (got \`${sandboxPath}\`). Pick something like /workspace/data/input/<name>.`;
+      }
+      const vfsErr = validatePath(vfsPath);
+      if (vfsErr) return `Invalid source path: ${vfsErr}`;
+
+      const bridge = await getSandboxBridge(
+        ctx,
+        deps.sandboxMcpUrl,
+        mcpClientFactory,
+      );
+      if ('error' in bridge) return bridge.error;
+
+      return runTransfer(ctx, bridge, { path: vfsPath }, async () => {
+        const client = vfsClient(ctx);
+        const stat = await client.statByPath(vfsPath);
+        if (!stat) return `No such file at \`${vfsPath}\`.`;
+
+        const { bytes, mimeType } = await client.contentBytes(stat.id);
+        const data = new Uint8Array(bytes);
+        const isText = isTextMime(mimeType || stat.mimeType || '');
+
+        const write = await writeSandboxFile(
+          bridge,
+          sandboxPath,
+          isText ? new TextDecoder().decode(data) : bytesToBase64(data),
+          isText ? 'utf8' : 'base64',
+        );
+        if ('error' in write) return write.error;
+
+        let deletedSource = false;
+        let note: string | undefined;
+        if (deleteSource) {
+          const results = await client.trash([stat.id]);
+          deletedSource = !results.some((r) => !r.ok);
+          note = deletedSource
+            ? 'source moved to the files trash (recoverable)'
+            : 'could not move the source to trash';
+        }
+
+        return JSON.stringify({
+          ok: true,
+          sandboxPath,
+          bytes: data.byteLength,
+          movedFromVfs: vfsPath,
+          deletedSource,
+          ...(note ? { note } : {}),
+        });
+      });
+    },
+    {
+      name: 'vfs_to_sandbox',
+      description:
+        "Bring one of the user's files into the sandbox (under /workspace/data/) so code in `sandbox_run` can process it. Copies by default; set deleteSource to move it out of the files (to trash).",
+      schema: vfsToSandboxSchema,
+    },
+  );
+
+  return [sandboxToVfs, vfsToSandbox];
+}