@mentiora-ai/loom-sdk

TypeScript client library for the loom browser-automation daemon.

Prerequisites

The SDK talks to a running loom-daemon over a Unix socket. Install loom (CLI + daemon + chromium pin) first via Homebrew, cargo install, or the install script — see the main README. Then start the daemon:

loom serve

Install

npm install @mentiora-ai/loom-sdk

Requires Node ≥ 20.

Quick start

import { Session } from "@mentiora-ai/loom-sdk";

const session = await Session.create();
try {
  const receipt = await session.navigate("https://example.com");
  console.log(receipt.action_hash);
} finally {
  await session.close();
}

What the SDK exposes

• Session — session lifecycle (create / close / abort / kill / replay / inspect / validate / export).
• Session.{navigate, click, typeText, select, hover, scroll, wait, evaluate, screenshot, snapshot} — every web action surface.
• Admin RPCs: killSession(sessionId, ...) (force-terminate without a handle), daemonHealth({ deep?, signal? }) (operational snapshot).
• Receipt + summary types in @mentiora-ai/loom-sdk/types — Receipt, SessionInfo, SessionInspection, DiffReport, ExportInfo, ValidationResult, GrantInfo, SchemaRegistry, LoomErrorCode, plus DaemonHealthResult, ShimDeepHealth, ShimBreakerSnapshot, ProbeStatus.
• Typed errors: LoomError, LoomRPCError, LoomConnectionError, LoomTokenError, LoomAbortError.

Cancellation

LoomTransport.call(method, params, { signal }) accepts an AbortSignal. On abort, the transport fires a request.cancel envelope at the daemon and rejects the returned promise with LoomAbortError (name === "AbortError"). Compose with AbortSignal.timeout(ms) or your own controller:

import { LoomTransport, daemonHealth, LoomAbortError } from "@mentiora-ai/loom-sdk";

try {
  const health = await daemonHealth({
    deep: true,
    signal: AbortSignal.timeout(2_000),
  });
  console.log(health);
} catch (err) {
  if (err instanceof LoomAbortError) {
    console.log("aborted");
  } else {
    throw err;
  }
}

Connection details

Session.create() defaults work when a single user runs the daemon on their own machine. Override per-call if needed:

const session = await Session.create({
  socketPath: "/var/run/loom/loom.sock",  // custom daemon socket
  token: "...",                            // explicit HELLO-token
  profile: "standard",                     // or "safe", "full"
  networkMode: "live",                     // the only mode (see below)
  seed: 42,                                // determinism seed
});

Network mode: page traffic is always live

networkMode accepts exactly one value, "live" (the default). Page traffic is always fetched live from the network — loom records the manifest hash chain and per-request metadata, not page-network responses. Response bodies are never captured, so HAR exports contain request entries without bodies, and replay re-executes the recorded actions rather than serving recorded responses. Any other value ("recorded", "mixed", "replay") is rejected at Session.create() with invalid_network_mode.

License

Apache-2.0. See the main repository for details.