@ixo/oracle-runtime-workers 0.2.0

package/src/plugins/sandbox/sandbox-bridge.ts

@@ -0,0 +1,295 @@
+import { MultiServerMCPClient } from '@langchain/mcp-adapters';
+import type { RuntimeContext } from '../../plugin-api/types';
+import { base64ToBytes } from '../base64';
+import { adaptMcpClientTools } from '../mcp-tool-adapter';
+import { createDefaultAuthBuilder, SANDBOX_RUN_TOOL_NAME } from './sandbox-mcp';
+import type {
+  SandboxMcpClientFactory,
+  SandboxMcpClientLike,
+  SandboxMcpTool,
+} from './sandbox.plugin';
+
+/** Upstream tool name the sandbox MCP surfaces for byte-perfect file writes. */
+export const SANDBOX_WRITE_FILE_TOOL_NAME = 'sandbox_write_file';
+
+/** Per-call timeout for the sandbox MCP client (matches sandbox.plugin.ts). */
+const SANDBOX_MCP_TIMEOUT_MS = 180_000;
+
+/** Only destination the sandbox accepts for `sandbox_write_file` writes. */
+export const WORKSPACE_DATA_PREFIX = '/workspace/data/';
+
+/** Sentinel echoed by the read command when the source file is absent. */
+export const SANDBOX_NO_FILE_SENTINEL = '__SANDBOX_NOFILE__';
+
+/**
+ * Shown when the user hasn't authorized the oracle to use the sandbox — the
+ * default auth builder can't mint an `ixo:sandbox` invocation, so there's no
+ * `Authorization` header to connect with. Non-throwing degradation.
+ */
+export const SANDBOX_NOT_AUTHORIZED_MESSAGE =
+  "You haven't authorized the sandbox yet — grant sandbox access in the portal so I can move files between it and your files.";
+
+/**
+ * Default sandbox MCP-client factory. Wraps a real `MultiServerMCPClient` in
+ * the minimal {@link SandboxMcpClientLike} surface the bridge needs, adapting
+ * each upstream tool into a plain {@link SandboxMcpTool} (JSON-Schema →
+ * Zod via the shared adapter). Tests inject a stub instead so no real MCP
+ * connection is opened.
+ */
+export const defaultSandboxMcpClientFactory: SandboxMcpClientFactory = (
+  config,
+) => {
+  const client = new MultiServerMCPClient(config);
+  const wrapper: SandboxMcpClientLike = {
+    getTools: async () => adaptMcpClientTools(await client.getTools(), console),
+    close: () => client.close(),
+  };
+  return wrapper;
+};
+
+/** Live sandbox `sandbox_run` + `sandbox_write_file` handles plus a closer. */
+export interface SandboxBridge {
+  run: SandboxMcpTool;
+  writeFile: SandboxMcpTool;
+  /** Always safe — swallows and logs any close error. */
+  close: () => Promise<void>;
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** MIME map skewed toward binary outputs; unknown extensions stay opaque. */
+const EXT_MIME: Record<string, string> = {
+  md: 'text/markdown',
+  markdown: 'text/markdown',
+  txt: 'text/plain',
+  text: 'text/plain',
+  log: 'text/plain',
+  json: 'application/json',
+  csv: 'text/csv',
+  tsv: 'text/tab-separated-values',
+  xml: 'application/xml',
+  yaml: 'application/yaml',
+  yml: 'application/yaml',
+  html: 'text/html',
+  htm: 'text/html',
+  css: 'text/css',
+  js: 'text/javascript',
+  ts: 'text/plain',
+  py: 'text/x-python',
+  sh: 'application/x-sh',
+  pdf: 'application/pdf',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+};
+
+/** Best-effort MIME type for a path, from its extension. */
+export function inferMimeFromPath(path: string): string {
+  const dot = path.lastIndexOf('.');
+  const ext = dot >= 0 ? path.slice(dot + 1).toLowerCase() : '';
+  return EXT_MIME[ext] ?? 'application/octet-stream';
+}
+
+/** `true` when the path sits under the sandbox's writable data root. */
+export function isUnderWorkspaceData(path: string): boolean {
+  return path.startsWith(WORKSPACE_DATA_PREFIX);
+}
+
+/**
+ * `true` when a sandbox path can't be safely single-quoted into a shell
+ * command (`sandbox_run`). We reject rather than risk breaking the command.
+ */
+export function hasShellUnsafeChars(path: string): boolean {
+  return path.includes("'") || path.includes('\n') || path.includes('\0');
+}
+
+function safeStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}
+
+function truncate(s: string, max = 300): string {
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+export interface SandboxOutcome {
+  /** `false` when the envelope reports `success:false` or a non-zero exit. */
+  ok: boolean;
+  /** Captured stdout when the envelope exposes it, else the whole result. */
+  output: string;
+  /** The stringified result, for surfacing in an error message. */
+  text: string;
+}
+
+/**
+ * Read a sandbox MCP result defensively. The upstream returns either a JSON
+ * envelope (`{ success, exitCode, output, ... }`) or a bare string; both are
+ * handled. `output` is the captured stdout when present, otherwise the whole
+ * stringified result.
+ *
+ * ASSUMPTION (verify against a live sandbox): stdout lives in the `output`
+ * field and `success` / `exitCode` are top-level — the shape the sandbox
+ * manifest documents.
+ */
+export function readSandboxResult(result: unknown): SandboxOutcome {
+  const text = typeof result === 'string' ? result : safeStringify(result);
+
+  let envelope: unknown = isRecord(result) ? result : undefined;
+  if (typeof result === 'string') {
+    try {
+      envelope = JSON.parse(result);
+    } catch {
+      envelope = undefined;
+    }
+  }
+
+  let output: string | undefined;
+  let success: boolean | undefined;
+  let exitCode: number | undefined;
+  if (isRecord(envelope)) {
+    if (typeof envelope.output === 'string') output = envelope.output;
+    if (typeof envelope.success === 'boolean') success = envelope.success;
+    if (typeof envelope.exitCode === 'number') exitCode = envelope.exitCode;
+  }
+
+  const failedByFlag = success === false || /"success"\s*:\s*false/i.test(text);
+  const failedByExit = exitCode !== undefined && exitCode !== 0;
+  return { ok: !failedByFlag && !failedByExit, output: output ?? text, text };
+}
+
+/**
+ * Mint sandbox auth headers, connect an MCP client, and resolve the two tools
+ * the bridge needs. Non-throwing: every failure comes back as `{ error }` with
+ * an agent-facing message. On success the caller MUST `close()` in a finally.
+ */
+export async function getSandboxBridge(
+  rtCtx: RuntimeContext,
+  sandboxMcpUrl: string,
+  mcpClientFactory: SandboxMcpClientFactory = defaultSandboxMcpClientFactory,
+): Promise<SandboxBridge | { error: string }> {
+  let headers: Record<string, string>;
+  try {
+    headers = await createDefaultAuthBuilder()(
+      { sandboxMcpUrl, oracleSecrets: {}, userSecrets: {} },
+      rtCtx,
+    );
+  } catch (err) {
+    rtCtx.logger.warn(
+      `[sandbox-bridge] sandbox auth failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { error: SANDBOX_NOT_AUTHORIZED_MESSAGE };
+  }
+
+  if (!headers.Authorization) {
+    return { error: SANDBOX_NOT_AUTHORIZED_MESSAGE };
+  }
+
+  const client = mcpClientFactory({
+    mcpServers: {
+      sandbox: {
+        type: 'http',
+        url: sandboxMcpUrl,
+        transport: 'http',
+        headers,
+      },
+    },
+    defaultToolTimeout: SANDBOX_MCP_TIMEOUT_MS,
+    useStandardContentBlocks: true,
+  });
+
+  const close = async (): Promise<void> => {
+    try {
+      await client.close();
+    } catch (err) {
+      rtCtx.logger.warn(
+        `[sandbox-bridge] failed to close sandbox MCP client: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+
+  let tools: SandboxMcpTool[];
+  try {
+    tools = await client.getTools();
+  } catch (err) {
+    await close();
+    rtCtx.logger.warn(
+      `[sandbox-bridge] could not list sandbox tools: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { error: 'Could not connect to the sandbox right now.' };
+  }
+
+  const run = tools.find((t) => t.name === SANDBOX_RUN_TOOL_NAME);
+  const writeFile = tools.find((t) => t.name === SANDBOX_WRITE_FILE_TOOL_NAME);
+  if (!run || !writeFile) {
+    await close();
+    return {
+      error:
+        'The sandbox is not exposing the file tools needed to move files right now.',
+    };
+  }
+
+  return { run, writeFile, close };
+}
+
+/**
+ * Read a file out of the sandbox as bytes, base64-hopping over `sandbox_run`
+ * so binary content survives the transport. Non-throwing — a missing file, a
+ * failed command, and undecodable output all come back as `{ error }` with an
+ * agent-facing message.
+ */
+export async function readSandboxFile(
+  bridge: Pick<SandboxBridge, 'run'>,
+  sandboxPath: string,
+): Promise<{ bytes: Uint8Array } | { error: string }> {
+  const read = readSandboxResult(
+    await bridge.run.invoke({
+      code: `test -f '${sandboxPath}' && base64 -w0 '${sandboxPath}' || echo ${SANDBOX_NO_FILE_SENTINEL}`,
+    }),
+  );
+  if (!read.ok) {
+    return {
+      error: `Couldn't read \`${sandboxPath}\` from the sandbox: ${truncate(read.text)}`,
+    };
+  }
+  const stdout = read.output.trim();
+  if (stdout === SANDBOX_NO_FILE_SENTINEL) {
+    return { error: `No file at \`${sandboxPath}\` in the sandbox.` };
+  }
+  try {
+    return { bytes: base64ToBytes(stdout) };
+  } catch {
+    return {
+      error: `Couldn't decode \`${sandboxPath}\` from the sandbox (output was not valid base64).`,
+    };
+  }
+}
+
+/**
+ * Write a file into the sandbox via `sandbox_write_file`. `encoding` selects
+ * how `content` is interpreted upstream — `base64` for binary payloads.
+ * Non-throwing: a failed write comes back as `{ error }`.
+ */
+export async function writeSandboxFile(
+  bridge: Pick<SandboxBridge, 'writeFile'>,
+  sandboxPath: string,
+  content: string,
+  encoding: 'utf8' | 'base64',
+): Promise<{ ok: true } | { error: string }> {
+  const write = readSandboxResult(
+    await bridge.writeFile.invoke({ path: sandboxPath, content, encoding }),
+  );
+  if (!write.ok) {
+    return {
+      error: `Couldn't write \`${sandboxPath}\` in the sandbox: ${truncate(write.text)}`,
+    };
+  }
+  return { ok: true };
+}

package/src/plugins/sandbox/sandbox-mcp.ts

@@ -0,0 +1,127 @@
+import type { RuntimeContext } from '../../plugin-api/types';
+
+/** Tool name surfaced by the upstream sandbox MCP. */
+export const SANDBOX_RUN_TOOL_NAME = 'sandbox_run';
+
+/**
+ * Parse the `ORACLE_SECRETS` env value (format: `KEY1=value1,KEY2=value2`).
+ *
+ * Whitespace around keys and values is trimmed; entries lacking an `=` or
+ * an empty key/value are skipped silently so a stray comma can't break boot.
+ */
+export function parseOracleSecrets(raw: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!raw) return out;
+  for (const pair of raw.split(',')) {
+    const eqIdx = pair.indexOf('=');
+    if (eqIdx <= 0) continue;
+    const key = pair.slice(0, eqIdx).trim();
+    const val = pair.slice(eqIdx + 1).trim();
+    if (key && val) out[key] = val;
+  }
+  return out;
+}
+
+/** Inputs to a {@link SandboxAuthBuilder} invocation. */
+export interface SandboxHeaderInputs {
+  /** Sandbox MCP base URL — resolved to a did:web audience. */
+  sandboxMcpUrl: string;
+  /** Optional skills-service base URL for the X-Skills-Invocation header. */
+  skillsServiceUrl?: string;
+  /** Oracle operator secrets — mapped to `x-os-{key}` headers. */
+  oracleSecrets: Record<string, string>;
+  /** Per-room user secrets — mapped to `x-us-{key}` headers. */
+  userSecrets: Record<string, string>;
+}
+
+/**
+ * Mints the headers needed to call the sandbox MCP server on behalf of
+ * the current user. Encapsulates the four security-sensitive steps:
+ *
+ * 1. Resolve the sandbox service DID via did:web.
+ * 2. Mint an `ixo:sandbox` UCAN invocation → `Authorization: Bearer ...`.
+ * 3. Optionally mint a parallel `ixo:skills` invocation →
+ *    `X-Skills-Invocation: ...` (forwarded by sandbox to the skills service).
+ * 4. Layer oracle + user secrets as `x-os-*` / `x-us-*` headers.
+ *
+ * UCAN-only — no Matrix-OpenID fallback. If minting fails for any reason
+ * (no signing key, no cached delegation, did:web unresolved) the returned
+ * header set simply omits the relevant token and the downstream service
+ * surfaces a clean unauthorized error instead of leaking a half-built
+ * request.
+ */
+export type SandboxAuthBuilder = (
+  inputs: SandboxHeaderInputs,
+  runCtx: RuntimeContext,
+) => Promise<Record<string, string>>;
+
+/**
+ * Default {@link SandboxAuthBuilder}. Service-DID resolution and caching is
+ * delegated to `runCtx.ucan.resolveServiceDid` (cached per origin inside the
+ * UCAN service), so this builder is stateless.
+ */
+export function createDefaultAuthBuilder(): SandboxAuthBuilder {
+  return async (inputs, runCtx) => {
+    const headers: Record<string, string> = {};
+
+    const sandboxDid = await runCtx.ucan.resolveServiceDid(
+      inputs.sandboxMcpUrl,
+    );
+    if (sandboxDid) {
+      try {
+        const invocation = await runCtx.ucan.mintInvocation(
+          { did: sandboxDid, capability: 'ixo:sandbox' },
+          // Claim the ability the user's delegation actually grants. A `'*'`
+          // claim is satisfiable only by a `'*'` grant.
+          { can: 'sandbox/*' },
+        );
+        if (invocation) {
+          headers.Authorization = `Bearer ${invocation}`;
+          headers['X-Auth-Type'] = 'ucan';
+        }
+      } catch (error) {
+        const detail =
+          error instanceof Error
+            ? `${error.name}: ${error.message}`
+            : String(error);
+        runCtx.logger.warn(
+          `[sandbox] failed to mint sandbox UCAN invocation: ${detail}`,
+        );
+      }
+    }
+
+    if (inputs.skillsServiceUrl) {
+      const skillsDid = await runCtx.ucan.resolveServiceDid(
+        inputs.skillsServiceUrl,
+      );
+      if (skillsDid) {
+        try {
+          const skillsInvocation = await runCtx.ucan.mintInvocation(
+            { did: skillsDid, capability: 'ixo:skills' },
+            { can: 'skills/*' },
+          );
+          if (skillsInvocation) {
+            headers['X-Skills-Invocation'] = skillsInvocation;
+          }
+        } catch (error) {
+          const detail =
+            error instanceof Error
+              ? `${error.name}: ${error.message}`
+              : String(error);
+          runCtx.logger.warn(
+            `[sandbox] failed to mint skills UCAN invocation: ${detail}`,
+          );
+        }
+      }
+    }
+
+    for (const [k, v] of Object.entries(inputs.oracleSecrets)) {
+      headers[`x-os-${k.toLowerCase()}`] = v;
+    }
+    for (const [k, v] of Object.entries(inputs.userSecrets)) {
+      headers[`x-us-${k.toLowerCase()}`] = v;
+    }
+
+    return headers;
+  };
+}

package/src/plugins/sandbox/sandbox-write-blob.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { tool as pluginTool } from '../../plugin-api/tool-helper';
+import type { PluginTool, RuntimeContext } from '../../plugin-api/types';
+import type { SandboxMcpTool } from './sandbox.plugin';
+
+const sandboxWriteBlobSchema = z.object({
+  blobId: z
+    .string()
+    .describe(
+      'The blobId returned by the tool that produced the value (e.g. mint_invocation). Format: `blob_<16 hex chars>`.',
+    ),
+  path: z
+    .string()
+    .describe(
+      'Destination path in the sandbox, e.g. `/workspace/data/<skill>/ucan_token`. Must be under /workspace/data/.',
+    ),
+});
+
+const SANDBOX_WRITE_BLOB_DESCRIPTION = `Write a server-stored blob to a file in the sandbox without ever paste-relaying the value through the LLM.
+
+Use this whenever a tool returns a \`blobId\` (e.g. \`mint_invocation\`'s response). Pass the blobId + the destination path; the runtime looks the value up server-side and calls sandbox_write_file with its content. The long opaque value (base64 CARs, JWTs, etc.) never enters the LLM context — eliminates string-corruption-in-relay as a failure mode.
+
+Inputs:
+  - blobId: short hex identifier returned by the producing tool (format \`blob_<16 hex chars>\`).
+  - path: destination path in the sandbox. Must be under \`/workspace/data/\` (the sandbox enforces this; writes elsewhere are rejected).
+
+Returns: \`{ success: true, path, bytesWritten }\` on success, \`{ success: false, error }\` on failure. Common errors: blob not found (re-mint and retry — for invocations this can happen on a multi-replica deployment if the lookup lands on a different process), invalid blobId format, path outside /workspace/data/.`;
+
+export interface CreateSandboxWriteBlobToolParams {
+  /** Upstream MCP `sandbox_write_file` tool — looked up once per request from
+   * the MCP client's tool list. Required; without it the wrapper has nothing
+   * to forward to. */
+  sandboxWriteFileTool: SandboxMcpTool;
+}
+
+/**
+ * `sandbox_write_blob` — companion to `mint_invocation`. Takes a `blobId`
+ * (server-side stored long string) and a sandbox path; looks up the blob in
+ * the `BlobStore` and calls the underlying `sandbox_write_file` MCP tool
+ * with the value. The LLM only ever passes the short blobId + path — long
+ * base64 strings (UCAN CARs etc.) never enter its context, so they can't be
+ * corrupted in transit.
+ *
+ * The plugin must only register this tool when the upstream `sandbox_write_file`
+ * tool exists AND the request has a known user DID — without either the
+ * wrapper degrades into an always-failing stub, which is worse than absent.
+ */
+export function createSandboxWriteBlobTool(
+  params: CreateSandboxWriteBlobToolParams,
+): PluginTool {
+  return pluginTool(
+    async (rawArgs, ctx: RuntimeContext) => {
+      const { blobId, path } = sandboxWriteBlobSchema.parse(rawArgs);
+
+      if (!ctx.blobStore.isValidBlobId(blobId)) {
+        return JSON.stringify({
+          success: false,
+          error: `Invalid blobId format. Expected blob_<16 hex chars>, got "${blobId}".`,
+        });
+      }
+      if (typeof path !== 'string' || !path.startsWith('/workspace/data/')) {
+        return JSON.stringify({
+          success: false,
+          error: `path must be under /workspace/data/. Got: "${path}".`,
+        });
+      }
+
+      const userDid = ctx.user.did;
+      const blob = await ctx.blobStore.get({ userDid, blobId });
+      if (!blob) {
+        return JSON.stringify({
+          success: false,
+          error: `Blob "${blobId}" not found (expired, never existed, or owned by another user). Re-mint and retry — for single-use invocations this is expected if the blob's TTL elapsed.`,
+        });
+      }
+
+      try {
+        const result = await params.sandboxWriteFileTool.invoke({
+          path,
+          content: blob.value,
+          encoding: 'utf8',
+        });
+        return JSON.stringify({
+          success: true,
+          path,
+          bytesWritten: blob.value.length,
+          blobName: blob.name,
+          note: typeof result === 'string' ? result : undefined,
+        });
+      } catch (err) {
+        return JSON.stringify({
+          success: false,
+          error: `sandbox_write_file failed: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+    },
+    {
+      name: 'sandbox_write_blob',
+      description: SANDBOX_WRITE_BLOB_DESCRIPTION,
+      schema: sandboxWriteBlobSchema,
+    },
+  );
+}