Connect browser terminal and HTML views to native fx

[nandorojo]

This lets a web app use libfx’s terminal or HTML UI while native fx runs in Vercel Sandbox. The browser connects through the app’s backend; fx keeps the conversation, calls models, and executes tools in the sandbox.

Browser

Use the existing terminal component:

import { createFxTerminal, xtermAdapter } from 'libfx/browser';

const terminal = await createFxTerminal({
  terminal: xtermAdapter(term),
  remote: connection,
});
await terminal.interactive;

Or use HTML with fx-owned commands, model choices, and permission controls:

import { createFxView } from 'libfx/browser';
import { createFxHtmlView } from 'libfx/html';

let client;
const view = createFxHtmlView({
  container: document.querySelector('#fx'),
  send: action => client.interact(action),
});
client = await createFxView({ remote: connection, onSnapshot: view.render });
await client.interactive;

Backend

Start once using the application’s existing sandbox, then retain the private connection for that session:

import { startVercelTerminal } from './sdk/examples/remote-terminal/vercel.mjs';
import { createTerminalRelay } from './sdk/examples/remote-terminal/relay.mjs';

const privateConnection = await startVercelTerminal({
  sandbox,
  cwd: '/vercel/sandbox/repo',
  fxPath: '/vercel/sandbox/.local/bin/fx',
  origin: 'https://your-app.example',
  sessionId,
  env: { AI_GATEWAY_API_KEY: process.env.AI_GATEWAY_API_KEY },
  existingPorts: [3000],
});

const relay = createTerminalRelay({
  origin: 'https://your-app.example',
  resolveSession,
});
server.on('upgrade', relay.upgrade);

resolveSession(request) is the app’s authentication hook: return the authenticated user’s stored private connection, or null. Give the browser {url: 'wss://your-app.example/api/fx', sessionId}. Sandbox URLs and credentials stay on the backend.

The example needs Node and Python in the sandbox, and Bun to bundle the broker. It reuses the native process across prompts and browser reconnects. abort() detaches the view; interrupt() cancels the native operation.

Limits

HTML currently supports conversation, command suggestions, model selection, and permission prompts; other native screens explicitly offer terminal handoff. Replay is bounded, expired terminal cursors fail explicitly, and one view can write at a time.

Validation

Native/WASM builds, focused SDK tests, and 13 real PTY/relay tests pass. Real Chrome exercised native model selection and streaming; a prompt through the app relay survived reload without another model request. The provider was a local mock, not a live model or paid Vercel Sandbox.

Draft pending exact-commit Full CI across Linux and macOS.