@openclaw/libterminal

Shared TypeScript primitives for streaming, rendering, and bridging terminals across browsers, Node.js, and Cloudflare Workers.

import { BoundedReplayBuffer } from "@openclaw/libterminal/stream";
import { decodeTerminalFrame } from "@openclaw/libterminal/protocol";

The package deliberately does not own authentication, public listeners, terminal transcripts, or product-specific room/session state.

Install

pnpm add @openclaw/libterminal

Install node-pty in applications that use the Node.js PTY adapter:

pnpm add node-pty

Exports

• @openclaw/libterminal: universal terminal types and errors
• @openclaw/libterminal/protocol: terminal protocol v2 codecs
• @openclaw/libterminal/stream: bounded replay, fanout, and batching
• @openclaw/libterminal/browser: Ghostty WASM terminal integration and terminal hub client
• @openclaw/libterminal/node: local PTY, raw stdin, and asset helpers
• @openclaw/libterminal/worker: Worker-compatible WebSocket bridging
• @openclaw/libterminal/worker-assets: optional Worker-safe Ghostty asset payloads
• @openclaw/libterminal/testing: deterministic terminal test doubles

Streaming

TerminalFanout provides bounded replay and per-subscriber output queues. Close each subscription when its consumer finishes. IDs can be reused after closing; an old subscription handle cannot close a later subscription with the same ID.

Replay buffers, fanout subscriptions, and batch publishers copy incoming bytes, including Node.js Buffer inputs. Callers can reuse their input buffers after appending, publishing, or writing. Replay snapshots and subscriber output are independent copies, so changing one cannot corrupt other readers or stored replay. The exported testing helpers also copy recorded input and output bytes, including sources that reuse a Buffer between chunks.

Browser

Ghostty terminals default to read-only. The application owns authorization, the byte source, and the WASM asset route.

import { createGhosttyTerminal } from "@openclaw/libterminal/browser";

const terminal = await createGhosttyTerminal({
  parent: document.querySelector("#terminal")!,
  runtimeOptions: { wasmUrl: "/vendor/ghostty-vt.wasm" },
  signal: controller.signal,
});

await terminal.attach(output);

Aborting an attached stream stops buffered output as well as future reads. Cancellation also stops waiting for source cleanup. Cleanup failures never replace an existing read or terminal-write failure, and abort-only cleanup errors are ignored.

ghostty-web 0.4.0 does not emit responses for OSC 10-12 default-color queries. Applications that write PTY output into the browser terminal can use the replay-safe compatibility responder until that support lands upstream:

import { createTerminalDefaultColorQueryResponder } from "@openclaw/libterminal/browser";

const colorQueries = createTerminalDefaultColorQueryResponder({
  getColors: () => ({
    foreground: "#d7dae0",
    background: "#0e1015",
    cursor: "#ff5c5c",
  }),
  reply: (data) => pty.write(data),
});

colorQueries.primeFromReplay(replayedPrefix);
colorQueries.observe(recoveredSuffix);
colorQueries.observe(liveOutput);

When a replay contains an already-observed prefix and a newly recovered suffix, prime the responder with the prefix before observing the suffix. This prevents duplicate historical replies while preserving a query split across the seam.

Use GHOSTTY_ASSET_PATHS and readGhosttyAsset() from the Node.js export to serve the pinned ghostty-web module, WASM, and browser-external shim under their canonical /vendor routes.

TerminalHubClient owns protocol framing, binary message normalization, and optional reconnect scheduling for multiplexed terminal WebSockets. Applications continue to own URL construction, authorization, session subscriptions, and terminal lifecycle.

Normalized hub frames own their byte storage, including messages received as Node.js Buffer values from injected transports. Mutable message bytes are copied when received, before queued delivery, so transports can immediately reuse them.

import { TerminalHubClient } from "@openclaw/libterminal/browser";

const hub = new TerminalHubClient({
  url: () => terminalHubUrl(),
  shouldReconnect: () => activeTerminalCount() > 0,
  onFrame: handleTerminalFrame,
});
hub.connect();

hub.close(code, reason) sanitizes invalid close codes and limits the reason to 123 UTF-8 bytes without splitting characters. Valid application codes and reason whitespace are preserved. Injected transports may accept protocol codes such as 1001 that native browsers reject; these retain their existing behavior. If the socket rejects the close arguments, the hub retries with code 1000, then without arguments. If every attempt fails, onError receives the final error and the socket remains available for another close attempt.

Node.js

The built-in adapter dynamically imports the optional node-pty peer. Inject a compatible driver in tests or applications that own their PTY runtime.

import { attachLocalStdio, spawnLocalPty } from "@openclaw/libterminal/node";

const terminal = await spawnLocalPty({
  command: "codex",
  args: ["--yolo"],
  cwd: process.cwd(),
});

await attachLocalStdio(terminal);

PTY output queues are bounded by default. Raw stdin mode is restored when the session ends, errors, or aborts.

Stdio input bytes are copied when received, before queued terminal writes, so input producers can immediately reuse their buffers.

Aborting a stdio attachment restores it without waiting for a pending write or resize. Caller-owned streams stay open, and late errors from an outstanding stdout write remain handled until that write settles.

Workers

The Worker bridge forwards both directions in order and can revalidate control before every left-to-right message and on a periodic fail-closed timer.

import { bridgeWebSockets } from "@openclaw/libterminal/worker";

const bridge = bridgeWebSockets(viewer, terminal, {
  canSendLeft: async () => capabilities.canControl(sessionId),
  sanitizeCloseReason: redactCredentials,
});

await bridge.completed;

The product remains responsible for authenticating both sockets and deciding which capabilities grant control.

Closing the bridge stops forwarding immediately. completed still waits for already-started message conversions to settle, discarding their results after teardown.

Use the optional Worker asset export to serve the pinned Ghostty module, WASM, and browser-external shim without an application-local asset generator. The product owns the route, cache policy, and security headers.

import { GHOSTTY_ASSET_PATHS, readGhosttyWorkerAsset } from "@openclaw/libterminal/worker-assets";

const asset = readGhosttyWorkerAsset(new URL(request.url).pathname);
if (asset) {
  return new Response(asset.body, {
    headers: {
      "cache-control": "no-store",
      "content-type": asset.contentType,
    },
  });
}

Protocol

@openclaw/libterminal/protocol owns terminal protocol v2 codecs and golden vectors. Strict decoders throw LibterminalError; tryDecodeTerminalFrame() is available for nullable migration paths.

Subscribe payloads may use zero columns and rows together to ask the terminal service to select default dimensions. Resize payloads always require real dimensions.

Wire-protocol versions and npm package versions are independent compatibility surfaces.

Safety

• Terminal bytes are never logged or persisted by the package.
• Browser terminals default to read-only.
• Replay, subscriber, and PTY output buffers are bounded.
• Protocol frames and terminal dimensions are validated.
• Authorization, public listeners, storage, and transcripts stay in consumers.

Development

pnpm install
pnpm check
pnpm run check:release