@alfe.ai/openclaw-remote 0.0.15 → 0.0.16

package/README.md

@@ -0,0 +1,52 @@
+# `@alfe.ai/openclaw-remote`
+
+OpenClaw plugin for Alfe's interactive remote-control relay. One outbound
+WebSocket carries browser co-browse and web-terminal sessions; the package also
+registers bounded browser automation and human-takeover tools.
+
+OpenClaw loads the default-only `./plugin` entry. The package root exposes named
+runtime factories and types for tests and other library consumers.
+
+## Configuration
+
+The plugin reads its optional entry from
+`plugins.entries["@alfe.ai/openclaw-remote"].config`:
+
+| Key | Default | Boundary |
+| --- | --- | --- |
+| `remoteWsUrl` | Derived from the agent API URL | Credential-free `wss:`; `ws:` only on loopback |
+| `browserExecutablePath` | `/usr/bin/google-chrome-stable` | Absolute path, at most 4096 characters |
+| `browserHeadless` | `true` | Boolean |
+| `browserNoSandbox` | `true` | Boolean |
+| `handoffTimeoutMs` | 600000 | Integer from 1000 through 1800000 |
+
+The shared `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` escape hatch is
+off by default. With the default policy, BrowserSession request interception
+blocks credential-bearing URLs and private, loopback, link-local, multicast,
+benchmark, documentation, and reserved literal addresses. DNS rebinding still
+requires a resolving policy upstream.
+
+## Tools
+
+- `browser_navigate`
+- `browser_click`
+- `browser_type`
+- `browser_wait_for`
+- `browser_screenshot`
+- `browser_evaluate`
+- `request_browser_takeover`
+
+Validation failures deliberately safe for the model are returned as structured
+tool errors. Unexpected browser, relay, and API diagnostics are redacted.
+Screenshots use OpenClaw image content and keep base64 out of JSON details.
+
+## Development
+
+```bash
+pnpm --filter @alfe.ai/openclaw-remote lint
+pnpm --filter @alfe.ai/openclaw-remote typecheck
+pnpm --filter @alfe.ai/openclaw-remote test
+pnpm --filter @alfe.ai/openclaw-remote build
+```
+
+See [DEVELOPING.md](./DEVELOPING.md) for lifecycle and security invariants.

package/dist/index.cjs

@@ -1,7 +1,11 @@
-Object.defineProperties(exports, {
-	__esModule: { value: true },
-	[Symbol.toStringTag]: { value: "Module" }
-});
-const require_plugin = require("./plugin2.cjs");
-exports.buildIsNavigationAllowed = require_plugin.buildIsNavigationAllowed;
-exports.default = require_plugin.plugin;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_runtime = require("./runtime.cjs");
+exports.PLUGIN_VERSION = require_runtime.PLUGIN_VERSION;
+exports.REMOTE_ACTIVATION_KEY = require_runtime.REMOTE_ACTIVATION_KEY;
+exports.buildControlUrl = require_runtime.buildControlUrl;
+exports.buildIsNavigationAllowed = require_runtime.buildIsNavigationAllowed;
+exports.createRemotePlugin = require_runtime.createRemotePlugin;
+exports.createRemotePluginRuntimeState = require_runtime.createRemotePluginRuntimeState;
+exports.deriveDashboardBaseUrl = require_runtime.deriveDashboardBaseUrl;
+exports.deriveRemoteWsUrl = require_runtime.deriveRemoteWsUrl;
+exports.parseRemotePluginConfig = require_runtime.parseRemotePluginConfig;

package/dist/index.d.cts

@@ -1,28 +1,384 @@
-import { i as RemotePluginConfig, r as plugin } from "./plugin.cjs";
+import { n as RemotePluginConfig, t as OpenClawPluginApi } from "./types.cjs";
 
-//#region src/ssrf.d.ts
+//#region ../agent-api-client/dist/index.d.ts
+
+//#region src/tool-error-capture.d.ts
+/**
+ * Tool-error capture for Alfe OpenClaw plugins.
+ *
+ * OpenClaw converts a thrown tool handler into a model-facing `tool_result`
+ * WITHOUT logging, and most Alfe plugins catch-and-return an error result the
+ * same silent way — so tool failures never appear in the runtime's output and
+ * therefore never reach Sentry (the gateway daemon supervises the OpenClaw
+ * process and reports error-looking output lines to the `agent-runtime`
+ * project — see packages/gateway/src/runtime-output-monitor.ts).
+ *
+ * `installToolErrorCapture(api, { plugin })` closes that gap at the ONE choke
+ * point every plugin already has: it wraps `api.registerTool` so every tool's
+ * `execute` emits a deterministic, detector-matched line on failure:
+ *
+ *   [ERROR] alfe-tool plugin=<plugin> tool=<name> <thrown|result-error>: <msg> (at <first-frame>)
+ *
+ * The `[ERROR]` prefix at line start is exactly what the daemon's
+ * `ErrorLineDetector` classifies as an error-log block, so the failure lands
+ * in Sentry fingerprinted by its normalized message — no Sentry SDK inside
+ * the plugin process, no new dependency. Behavior toward OpenClaw and the
+ * model is UNCHANGED: throws are rethrown, results returned as-is.
+ */
+/**
+ * Minimal shape of the OpenClaw plugin api this helper relies on. Method
+ * syntax on purpose — TS checks method signatures bivariantly, so each
+ * plugin's own concretely-typed `registerTool(tool: ToolDef): void` is
+ * accepted without casts.
+ */
+interface ToolCaptureApi {
+  registerTool(...args: never[]): unknown;
+}
+interface InstallToolErrorCaptureOptions {
+  /** Plugin package short-name for attribution (e.g. "openclaw-secrets"). */
+  plugin: string;
+  /**
+   * Line sink — defaults to writing `process.stderr` directly (the plugin
+   * runs in-process in OpenClaw, so this lands on the runtime's stderr, which
+   * the daemon supervises — and a console patch can't reformat it away).
+   * Injectable for tests.
+   */
+  emit?: (line: string) => void;
+}
+/**
+ * Wrap `api.registerTool` so every tool registered AFTER this call gets
+ * failure capture. Handles both OpenClaw registration signatures:
+ * `registerTool(toolDef)` and `registerTool((ctx) => toolDef, opts)`.
+ * Call once, first thing in the plugin's `activate`/`register` entry.
+ * Never throws.
+ */
+declare function installToolErrorCapture(api: ToolCaptureApi, options: InstallToolErrorCaptureOptions): void;
+//# sourceMappingURL=tool-error-capture.d.ts.map
+//#endregion
+//#region src/transport.d.ts
+/**
+ * Shared HTTP transport for the Agent API client — request core, retry
+ * policy, error formatting, and the `ApiBase` class the domain method
+ * groups under `./domains/` build on.
+ */
+
+//#endregion
+//#region ../browser/dist/index.d.ts
+
+//#endregion
+//#region src/types.d.ts
+interface Logger$2 {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+//#endregion
+//#region src/turn-controller.d.ts
+/**
+ * TurnController — the write-mutex between agent automation and a human during
+ * a browser co-browse handoff. The plugin owns the single CDP session, so this
+ * lives plugin-side; the relay only forwards the control frames.
+ *
+ * Only *writes* are gated — screencast reads always flow so the human sees the
+ * live page regardless of who holds the token. Agent automation ops call
+ * `acquireAgent()` and park while the human is in control; the human's input is
+ * injected only while `owner === 'human'`.
+ */
+
+//#endregion
+//#endregion
+//#region src/types.d.ts
+interface BrowserSessionOptions {
+  /** Path to the Chrome/Chromium binary (from the headless-browser integration). */
+  executablePath: string;
+  /** Persistent profile dir so cookies/login survive process restarts. */
+  userDataDir: string;
+  /** Headless mode (default true). */
+  headless?: boolean;
+  /** Pass --no-sandbox (needed on most managed Linux VMs). */
+  noSandbox?: boolean;
+  /** Shut Chrome down after this many ms with no holds/activity (default 5 min). */
+  idleShutdownMs?: number;
+  /** Extra Chrome args. */
+  extraArgs?: string[];
+  /** Guard applied to every intercepted HTTP(S) page request. */
+  isNavigationAllowed?: (url: string) => boolean;
+  logger?: Logger$2;
+}
+type BrowserSurfaceOptions = BrowserSessionOptions;
+//#endregion
+//#region src/browser-session.d.ts
+
+//#endregion
+//#region src/browser-surface.d.ts
+interface HandoffResult {
+  released: boolean;
+  timedOut: boolean;
+  url: string;
+  title: string;
+}
+//#endregion
+//#region ../config/dist/index.d.ts
 
+/**
+ * Resolved runtime config — env vars override config file values.
+ *
+ * Hierarchy (highest priority first):
+ *   1. Environment variables (ALFE_API_KEY, ALFE_API_URL)
+ *   2. Config file (~/.alfe/config.toml)
+ *
+ * Consumers call resolveConfig() and get the resolved values —
+ * they don't need to know where the values came from.
+ */
+interface ResolvedConfig {
+  apiKey: string;
+  apiUrl: string;
+  /**
+   * Base URL for the voice service's agent-authed one-shot endpoints
+   * (`/voice/tts`, `/voice/stt`). Derived from the token via
+   * {@link getVoiceServiceUrlFromToken}; currently equals `apiUrl` (the
+   * endpoints are co-located on the shared api gateway), but kept as its own
+   * field so the voice plugin has a stable seam if voice ever moves hosts.
+   */
+  voiceServiceUrl: string;
+  socketPath: string;
+  workspacePath: string;
+  /**
+   * The active agent runtime — `"openclaw"` (default) or `"hermes"`. Read from
+   * the top-level `runtime` key of the config. Consumers that behave
+   * differently per runtime (e.g. AlfeSync's per-runtime default ignore set)
+   * read this rather than re-parsing the TOML.
+   */
+  runtime: string;
+}
+//#endregion
+//#region ../remote/dist/index.d.ts
+
+declare const RemoteFrameType: {
+  /** viewer→plugin: a viewer attached. Payload: SessionOpenPayload. */
+  readonly SESSION_OPEN: 1;
+  /** either direction: a viewer detached / session torn down. */
+  readonly SESSION_CLOSE: 2;
+  /** plugin→viewer: current surface state. Payload: SessionStatePayload. */
+  readonly SESSION_STATE: 3;
+  /** plugin→viewer (browser): the page navigated. Payload: { url }. */
+  readonly NAVIGATION: 4;
+  /** plugin→viewer: [metaLen:u16BE][meta JSON][raw JPEG]. */
+  readonly SCREENCAST_FRAME: 16;
+  /** viewer→plugin: { frameSeq } — drives ack-gated backpressure. */
+  readonly SCREENCAST_ACK: 17;
+  readonly INPUT_MOUSE: 32;
+  readonly INPUT_WHEEL: 33;
+  readonly INPUT_KEY: 34;
+  /** viewer→plugin: { width, height, dpr }. */
+  readonly RESIZE: 35;
+  readonly TAKEOVER_REQUEST: 48;
+  readonly TAKEOVER_GRANTED: 49;
+  readonly TAKEOVER_DENIED: 50;
+  readonly RELEASE_CONTROL: 51;
+  readonly CONTROL_REVOKED: 52;
+  /** plugin→viewer: raw PTY output bytes. */
+  readonly TERMINAL_DATA: 64;
+  /** viewer→plugin: raw keystroke bytes. */
+  readonly TERMINAL_INPUT: 65;
+  /** viewer→plugin: { cols, rows }. */
+  readonly TERMINAL_RESIZE: 66;
+};
+type RemoteFrameType = (typeof RemoteFrameType)[keyof typeof RemoteFrameType];
+type RemoteSurface = "browser" | "terminal";
+interface RemoteFrame {
+  type: RemoteFrameType;
+  sessionId: number;
+  payload: Buffer;
+}
+interface SessionOpenPayload {
+  surface: RemoteSurface;
+  /** Browser: initial viewport in device pixels. */
+  width?: number;
+  height?: number;
+  dpr?: number;
+  /** Terminal: initial PTY dimensions. */
+  cols?: number;
+  rows?: number;
+}
+//#endregion
+//#region src/types.d.ts
+interface Logger$1 {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+interface RemoteServiceClientOptions {
+  /** Relay WebSocket URL (e.g. wss://remote.dev.alfe.ai/ws). */
+  wsUrl: string;
+  /** Agent API key for Bearer auth on the WS upgrade. */
+  apiKey: string;
+  /**
+   * Handler for every well-formed inbound frame from the relay. The plugin
+   * dispatches by `frame.sessionId` to the owning surface handler. Kept on the
+   * transport as a single callback so this package stays surface-agnostic.
+   */
+  onFrame: (frame: RemoteFrame) => void | Promise<void>;
+  /** Called when the WS connection state changes. */
+  onConnectionChange?: (connected: boolean) => void | Promise<void>;
+  /** Optional logger (defaults to console). */
+  logger?: Logger$1;
+}
+//#endregion
+//#region src/client.d.ts
+//#endregion
+//#region ../terminal/dist/index.d.ts
+
+//#endregion
+//#region src/types.d.ts
+interface Logger {
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+  debug(msg: string, ...args: unknown[]): void;
+}
+//#endregion
+//#region src/types.d.ts
+interface TerminalSurfaceOptions {
+  /** Shell to spawn. Defaults to $SHELL or /bin/bash. */
+  shell?: string;
+  /** Working directory for the shell (the agent workspace). Defaults to cwd. */
+  cwd?: string;
+  /** Extra env for the shell. Merged over process.env. */
+  env?: Record<string, string>;
+  /** Max concurrent terminal sessions (default 8). */
+  maxSessions?: number;
+  logger?: Logger;
+}
+//#endregion
+//#region src/terminal-surface.d.ts
+//#endregion
+//#region src/runtime.d.ts
+declare const REMOTE_ACTIVATION_KEY: string;
+declare const PLUGIN_VERSION: string;
+interface RemoteApiClient {
+  whoami(): Promise<{
+    agentId: string;
+  }>;
+  requestBrowserTakeover(args: {
+    instructions: string;
+    url?: string;
+    conversationId?: string;
+  }): Promise<{
+    sessionId: string;
+    status: string;
+  }>;
+  completeRemoteSession(sessionId: string): Promise<unknown>;
+}
+interface BrowserSurfaceLike {
+  automation: {
+    navigate(url: string): Promise<unknown>;
+    click(selector: string): Promise<void>;
+    type(selector: string, text: string): Promise<void>;
+    waitFor(options: {
+      selector?: string;
+      urlPattern?: string;
+      ms?: number;
+    }): Promise<void>;
+    screenshot(): Promise<string>;
+    evaluate(expression: string): Promise<unknown>;
+  };
+  openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
+  closeSession(sessionId: number): void;
+  handleFrame(frame: RemoteFrame): void;
+  requestHandoff(timeoutMs: number): Promise<HandoffResult>;
+  addHold(): void;
+  removeHold(): void;
+  shutdown(): Promise<void>;
+}
+interface TerminalSurfaceLike {
+  openSession(sessionId: number, open: SessionOpenPayload): void | Promise<void>;
+  closeSession(sessionId: number): void;
+  handleFrame(frame: RemoteFrame): void;
+  shutdown(): void;
+}
+interface RemoteClientLike {
+  readonly bufferedAmount?: number;
+  start(): void;
+  stop(): void;
+  sendFrame(frame: Buffer): void;
+}
+interface RemotePluginRuntimeState {
+  generation: number;
+  remoteClient: RemoteClientLike | null;
+  browserSurface: BrowserSurfaceLike | null;
+  terminalSurface: TerminalSurfaceLike | null;
+  apiClient: RemoteApiClient | null;
+  handoffTimeoutMs: number;
+  dashboardBaseUrl?: string;
+  selfAgentId?: string;
+  sessionSurfaces: Map<number, RemoteSurface>;
+  stopPromise: Promise<void> | null;
+}
+interface RemotePluginDependencies {
+  resolveConfig?: () => ResolvedConfig;
+  createApiClient?: (config: {
+    apiKey: string;
+    apiUrl: string;
+  }) => RemoteApiClient;
+  createRemoteClient?: (options: RemoteServiceClientOptions) => RemoteClientLike;
+  createBrowserSurface?: (options: BrowserSurfaceOptions, sendFrame: (frame: Buffer) => void) => BrowserSurfaceLike;
+  createTerminalSurface?: (options: TerminalSurfaceOptions, sendFrame: (frame: Buffer) => void) => TerminalSurfaceLike;
+  installErrorCapture?: typeof installToolErrorCapture;
+  runtimeState?: RemotePluginRuntimeState;
+}
+declare function createRemotePluginRuntimeState(): RemotePluginRuntimeState;
+/**
+ * Derive the relay WebSocket URL from the agent's cloud apiUrl when the
+ * manifest doesn't provide one — mirrors @alfe.ai/console-client's
+ * `deriveConsoleWsUrl` so the URL is per-stage automatically:
+ *   https://api.dev.alfe.ai → wss://remote.dev.alfe.ai/ws
+ * (matches config.flyDomains.remote per stage). This is why the
+ * headless-browser integration manifest carries no hardcoded, prod-pinned
+ * `remoteWsUrl`: the plugin resolves it from the agent's own endpoint.
+ */
+declare function deriveRemoteWsUrl(apiUrl: string): string | undefined;
+/**
+ * Derive the dashboard (control-plane) base URL from the agent's cloud apiUrl,
+ * mirroring `deriveRemoteWsUrl` so it's per-stage automatically:
+ *   https://api.dev.alfe.ai → https://app.dev.alfe.ai
+ *   https://api.alfe.ai     → https://app.alfe.ai   (prod)
+ * The `api.` → `app.` swap matches config.*.ts `dashboardDomain` for every
+ * stage. Returns undefined for a non-`api.` host (e.g. localhost/dev override)
+ * so the caller can fall back to a session-only link.
+ */
+declare function deriveDashboardBaseUrl(apiUrl: string): string | undefined;
+/**
+ * Build the dashboard deep-link ("control URL") the human opens to take over.
+ * Prefers the full agent-scoped path; if the dashboard host or agentId is
+ * unavailable, degrades gracefully (session-only path, then null).
+ */
+declare function buildControlUrl(dashboardBaseUrl: string | undefined, agentId: string | undefined, sessionId: string): string | undefined;
+declare function createRemotePlugin(dependencies?: RemotePluginDependencies): {
+  id: string;
+  name: string;
+  description: string;
+  version: string;
+  activate(api: OpenClawPluginApi): void;
+  deactivate(api: OpenClawPluginApi): Promise<void>;
+};
+declare function parseRemotePluginConfig(value: unknown, browserFallback: unknown): RemotePluginConfig;
+//#endregion
+//#region src/ssrf.d.ts
 /**
  * SSRF navigation guard for the shared co-browse surface.
  *
- * Builds the `isNavigationAllowed` predicate that `BrowserSurface` consults
- * before the AGENT's `browser_navigate` tool drives a `page.goto` (see
- * @alfe.ai/browser `BrowserAutomation.navigate`). v1 is a synchronous
- * hostname / IP-literal check: it blocks navigation to private, loopback,
- * link-local, `.internal`, and cloud-metadata (169.254.169.254) hosts UNLESS
- * the integration's SSRF policy explicitly allows the private network
- * (`dangerouslyAllowPrivateNetwork`). The policy is the same one the `alfe`
- * integration exposes under `browser.ssrfPolicy` and threads into runtime
- * config.
+ * Builds the `isNavigationAllowed` predicate that `BrowserSurface` applies to
+ * explicit agent navigation and to every prepared page's request interception.
+ * It blocks non-web schemes, credential-bearing URLs, private, loopback,
+ * link-local, multicast, documentation, benchmark, and other reserved literal
+ * hosts unless the integration explicitly opts into private-network access.
  *
  * SCOPE — what this guard does and does NOT cover:
- *   - GATES the AGENT's `browser_navigate` tool (the only path through
- *     `automation.navigate`).
- *   - Does NOT gate HUMAN navigation during a takeover: the human types URLs
- *     into the live browser and those never pass through this predicate.
- *     Blocking that requires CDP-level request interception
- *     (`Fetch.enable` / `Network.requestIntercept`) inside the surface —
- *     deferred (follow-up).
+ *   - Gates agent `page.goto`, redirects, page subresources, popups, page-JS
+ *     fetches, and human navigation after a page is prepared by BrowserSession.
  *   - Does NOT defend against DNS rebinding: we deliberately do not resolve
  *     hostnames to IPs here (no async DNS in a sync predicate). A public
  *     hostname that resolves to a private IP at goto-time is NOT caught in v1
@@ -35,11 +391,10 @@ interface SsrfPolicy {
 /**
  * Build the navigation predicate for a given SSRF policy. When
  * `dangerouslyAllowPrivateNetwork` is true the predicate is allow-all
- * (matching the `alfe` integration's current default); otherwise it blocks
- * the reserved ranges above and any non-http(s) scheme.
+ * otherwise it blocks the reserved ranges above and any non-http(s) scheme.
  */
 declare function buildIsNavigationAllowed(policy: SsrfPolicy | undefined, log?: {
   warn(msg: string): void;
 }): (url: string) => boolean;
 //#endregion
-export { type RemotePluginConfig, type SsrfPolicy, buildIsNavigationAllowed, plugin as default };
+export { type BrowserSurfaceLike, PLUGIN_VERSION, REMOTE_ACTIVATION_KEY, type RemoteApiClient, type RemoteClientLike, type RemotePluginConfig, type RemotePluginDependencies, type RemotePluginRuntimeState, type SsrfPolicy, type TerminalSurfaceLike, buildControlUrl, buildIsNavigationAllowed, createRemotePlugin, createRemotePluginRuntimeState, deriveDashboardBaseUrl, deriveRemoteWsUrl, parseRemotePluginConfig };