agent-anywhere-gateway 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# Agent Anywhere Gateway
+
+Standalone gateway for Agent Anywhere controlled machines.
+
+## Install
+
+```bash
+npm install -g agent-anywhere-gateway
+```
+
+## Run
+
+```bash
+agent-anywhere-gateway \
+  --server https://agent-anywhere.example.com \
+  --id office-mac \
+  --token replace-me \
+  --allowed-roots /Users/me/gitrepo \
+  --provider codex
+```
+
+One gateway can expose multiple local runtimes:
+
+```bash
+agent-anywhere-gateway \
+  --server https://agent-anywhere.example.com \
+  --id office-mac \
+  --token replace-me \
+  --allowed-roots /Users/me/gitrepo \
+  --providers codex,claude-code
+```
+
+`--server` accepts the Control Server or Worker URL and expands it to
+`/api/gateways/{gateway_id}/ws`. Use `--server-ws-url` when you need to pass
+the exact WebSocket URL.
+
+The same settings can be provided with environment variables:
+
+- `AGENT_ANYWHERE_SERVER_WS_URL`
+- `AGENT_ANYWHERE_GATEWAY_ID`
+- `AGENT_ANYWHERE_GATEWAY_TOKEN`
+- `AGENT_ANYWHERE_ALLOWED_ROOTS`
+- `AGENT_PROVIDER`
+- `AGENT_PROVIDERS`
+
+Version: 0.1.0

package/bin/agent-anywhere-gateway.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../src/gateway/main");
+
+try {
+  Promise.resolve(runCli()).catch((error) => {
+    console.error(error.stack || error.message);
+    process.exitCode = 1;
+  });
+} catch (error) {
+  console.error(error.stack || error.message);
+  process.exitCode = 1;
+}

package/config/cloudflare.gateway.env.example

@@ -0,0 +1,9 @@
+# Copy this file to .cloudflare/gateway.env on each controlled machine.
+# .cloudflare/ is ignored by git, so the gateway token stays local.
+
+AGENT_ANYWHERE_GATEWAY_ID=helix-mac
+AGENT_ANYWHERE_MACHINE_NAME=Helix Mac
+AGENT_ANYWHERE_SERVER_WS_URL=wss://agent-anywhere.songofhawk.workers.dev/api/gateways/{gateway_id}/ws
+AGENT_ANYWHERE_GATEWAY_TOKEN=replace-with-agent-anywhere-gateway-token
+AGENT_ANYWHERE_ALLOWED_ROOTS=/Users/helix/gitrepo
+AGENT_PROVIDERS=codex,claude-code

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "agent-anywhere-gateway",
+  "version": "0.1.0",
+  "description": "Standalone Agent Anywhere Gateway CLI for controlled machines.",
+  "main": "src/gateway/main.js",
+  "bin": {
+    "agent-anywhere-gateway": "bin/agent-anywhere-gateway.js"
+  },
+  "scripts": {
+    "start": "agent-anywhere-gateway",
+    "gateway": "node src/gateway.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "config",
+    "src",
+    "README.md",
+    "package.json"
+  ],
+  "dependencies": {
+    "@openai/codex-sdk": "^0.130.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapters/local-agent-adapter.js

@@ -0,0 +1,131 @@
+const { buildCapabilities } = require("../shared/capabilities");
+const { normalizeProviderName } = require("../shared/providers");
+const { ClaudeCodeHeadlessRuntime } = require("../runtimes/claude-code-headless-runtime");
+const { ClaudeCodeRuntime } = require("../runtimes/claude-code-runtime");
+const { CodexAppServerRuntime } = require("../runtimes/codex-app-server-runtime");
+const { CodexRuntime } = require("../runtimes/codex-runtime");
+const { MockRuntime } = require("../runtimes/mock-runtime");
+
+const LOCAL_ADAPTERS = {
+  codex: {
+    id: "codex",
+    kind: "local-process",
+    createRuntime: () => new CodexAppServerRuntime({ provider: "codex" })
+  },
+  "codex-sdk": {
+    id: "codex-sdk",
+    kind: "local-process",
+    createRuntime: () => new CodexRuntime({ provider: "codex-sdk" })
+  },
+  "codex-app-server": {
+    id: "codex-app-server",
+    kind: "local-process",
+    createRuntime: () => new CodexAppServerRuntime()
+  },
+  "claude-code": {
+    id: "claude-code",
+    kind: "local-process",
+    createRuntime: () => new ClaudeCodeRuntime()
+  },
+  "claude-code-headless": {
+    id: "claude-code-headless",
+    kind: "local-process",
+    createRuntime: () => new ClaudeCodeHeadlessRuntime()
+  },
+  mock: {
+    id: "mock",
+    kind: "local-process",
+    createRuntime: () => new MockRuntime()
+  }
+};
+
+class RuntimeAgentAdapter {
+  constructor({ id, kind, runtime }) {
+    this.id = id;
+    this.kind = kind;
+    this.runtime = runtime;
+  }
+
+  getCapabilities() {
+    return buildCapabilities(this.id);
+  }
+
+  async discoverCapabilities() {
+    if (typeof this.runtime.discoverCapabilities === "function") {
+      return this.runtime.discoverCapabilities();
+    }
+    return this.getCapabilities();
+  }
+
+  async *runTurn(context) {
+    yield* this.runtime.run({
+      session: context.session,
+      project: context.project,
+      message: context.message,
+      attachments: context.attachments,
+      settings: context.settings,
+      requestApproval: context.requestApproval
+    });
+  }
+
+  async cancelTurn(context) {
+    if (typeof this.runtime.cancelTurn !== "function") {
+      const error = new Error(`provider ${this.id} 不支持取消。`);
+      error.statusCode = 400;
+      throw error;
+    }
+    return this.runtime.cancelTurn(context);
+  }
+
+  async steerTurn(context) {
+    if (typeof this.runtime.steerTurn !== "function") {
+      const error = new Error(`provider ${this.id} 不支持运行中追加输入。`);
+      error.statusCode = 400;
+      throw error;
+    }
+    return this.runtime.steerTurn(context);
+  }
+
+  async listRuntimeSessions(context) {
+    if (typeof this.runtime.listRuntimeSessions !== "function") {
+      return [];
+    }
+    return this.runtime.listRuntimeSessions(context);
+  }
+
+  async readRuntimeSession(context) {
+    if (typeof this.runtime.readRuntimeSession !== "function") {
+      const error = new Error(`provider ${this.id} 不支持读取 runtime session。`);
+      error.statusCode = 400;
+      throw error;
+    }
+    return this.runtime.readRuntimeSession(context);
+  }
+}
+
+function createLocalAgentAdapter(provider) {
+  const normalizedProvider = normalizeProviderName(provider);
+  const definition = LOCAL_ADAPTERS[normalizedProvider];
+  if (!definition) {
+    const error = new Error(`不支持的 provider：${provider}`);
+    error.statusCode = 400;
+    throw error;
+  }
+
+  return new RuntimeAgentAdapter({
+    id: definition.id,
+    kind: definition.kind,
+    runtime: definition.createRuntime()
+  });
+}
+
+function listLocalAgentProviders() {
+  return Object.keys(LOCAL_ADAPTERS);
+}
+
+module.exports = {
+  LOCAL_ADAPTERS,
+  RuntimeAgentAdapter,
+  createLocalAgentAdapter,
+  listLocalAgentProviders
+};

package/src/gateway/client.js

@@ -0,0 +1,422 @@
+const os = require("node:os");
+const fs = require("node:fs");
+const path = require("node:path");
+const { createLocalAgentAdapter } = require("../adapters/local-agent-adapter");
+const { buildCapabilities, compactCapabilities } = require("../shared/capabilities");
+const { GatewayMessageType } = require("../shared/gateway-protocol");
+const { connectWebSocket } = require("../shared/websocket");
+const { handleApprovalDecision, handleRequest } = require("./runner");
+const { defaultProviderName, providerNames } = require("./providers");
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
+const DEFAULT_RECONNECT_MIN_MS = 1_000;
+const DEFAULT_RECONNECT_MAX_MS = 30_000;
+const REPLAY_DIR_NAME = "gateway-replays";
+
+function gatewayId() {
+  return process.env.AGENT_ANYWHERE_GATEWAY_ID || os.hostname() || "gateway";
+}
+
+function gatewayToken() {
+  return process.env.AGENT_ANYWHERE_GATEWAY_TOKEN || "please-change-me";
+}
+
+function providerName() {
+  return defaultProviderName();
+}
+
+function gatewayDataDir() {
+  return process.env.AGENT_ANYWHERE_DATA_DIR || path.join(process.cwd(), ".data");
+}
+
+function replayDir() {
+  return process.env.AGENT_ANYWHERE_GATEWAY_REPLAY_DIR || path.join(gatewayDataDir(), REPLAY_DIR_NAME);
+}
+
+function serverWsUrl() {
+  const id = gatewayId();
+  const raw = process.env.AGENT_ANYWHERE_SERVER_WS_URL || `ws://localhost:8787/api/gateways/${id}/ws`;
+  const url = new URL(raw.replace("{gateway_id}", encodeURIComponent(id)));
+  if (!url.searchParams.has("token")) {
+    url.searchParams.set("token", gatewayToken());
+  }
+  return url;
+}
+
+function registerUrl(wsUrl) {
+  const url = new URL(wsUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.pathname = "/api/machines/register";
+  url.search = "";
+  return url;
+}
+
+function machineRegistrationPayload(id, capabilities) {
+  return {
+    id,
+    name: process.env.AGENT_ANYWHERE_MACHINE_NAME || id,
+    host: "",
+    os: process.platform,
+    status: "online",
+    connection_mode: "gateway",
+    gateway_id: id,
+    capabilities
+  };
+}
+
+function mergeCapabilities(providerRows) {
+  const providers = [];
+  const models = [];
+  const inputModalities = [];
+  const reasoningEfforts = [];
+  const approvalPolicies = [];
+  const modes = [];
+  const providerCapabilities = {};
+  let defaultModel = null;
+  for (const row of providerRows) {
+    const capabilities = row.capabilities || buildCapabilities(row.provider);
+    providerCapabilities[row.provider] = capabilities;
+    for (const provider of capabilities.providers || [row.provider]) {
+      if (provider && !providers.includes(provider)) providers.push(provider);
+    }
+    for (const model of capabilities.models || []) {
+      if (model && !models.includes(model)) models.push(model);
+    }
+    for (const modality of capabilities.input_modalities || []) {
+      if (modality && !inputModalities.includes(modality)) inputModalities.push(modality);
+    }
+    for (const effort of capabilities.reasoning_efforts || []) {
+      if (effort && !reasoningEfforts.includes(effort)) reasoningEfforts.push(effort);
+    }
+    for (const policy of capabilities.approval_policies || []) {
+      if (policy && !approvalPolicies.includes(policy)) approvalPolicies.push(policy);
+    }
+    for (const mode of capabilities.modes || []) {
+      if (mode && !modes.includes(mode)) modes.push(mode);
+    }
+    if (!defaultModel && capabilities.default_model) {
+      defaultModel = capabilities.default_model;
+    }
+  }
+  const primaryProvider = providers[0] || providerName();
+  return compactCapabilities(primaryProvider, {
+    providers,
+    models,
+    default_model: defaultModel,
+    input_modalities: inputModalities,
+    reasoning_efforts: reasoningEfforts,
+    approval_policies: approvalPolicies,
+    modes,
+    provider_capabilities: providerCapabilities
+  });
+}
+
+async function discoverGatewayCapabilities(providers = providerNames()) {
+  const rows = [];
+  for (const provider of providers) {
+    const adapter = createLocalAgentAdapter(provider);
+    let capabilities;
+    try {
+      capabilities = await adapter.discoverCapabilities();
+    } catch {
+      capabilities = buildCapabilities(provider);
+    }
+    rows.push({ provider, capabilities });
+  }
+  return mergeCapabilities(rows);
+}
+
+async function registerMachine(wsUrl) {
+  const id = gatewayId();
+  const provider = providerName();
+  const capabilities = await discoverGatewayCapabilities();
+  const url = registerUrl(wsUrl);
+  const headers = {
+    "Content-Type": "application/json",
+    "x-agent-anywhere-gateway-token": gatewayToken()
+  };
+  const post = (payload) => fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(payload)
+  });
+
+  let response = await post(machineRegistrationPayload(id, capabilities));
+
+  if (!response.ok) {
+    const body = await response.text();
+    if (/SQLITE_TOOBIG|string or blob too big/i.test(body)) {
+      const fallback = compactCapabilities(provider, buildCapabilities(provider));
+      response = await post(machineRegistrationPayload(id, fallback));
+      if (response.ok) {
+        return;
+      }
+      const retryBody = await response.text();
+      throw new Error(`gateway 注册失败：${response.status} ${retryBody}`);
+    }
+    throw new Error(`gateway 注册失败：${response.status} ${body}`);
+  }
+}
+
+function replayFileName({ gateway_id, session_id, turn_id }) {
+  return [
+    gateway_id || gatewayId(),
+    session_id || "session",
+    turn_id || "turn",
+    Date.now(),
+    Math.random().toString(36).slice(2)
+  ].map((part) => String(part).replace(/[^A-Za-z0-9_.-]/g, "_")).join("__") + ".json";
+}
+
+function saveRunReplay(replay, { dir = replayDir() } = {}) {
+  if (!replay?.events?.length && !replay?.terminal_status) {
+    return null;
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  const filePath = path.join(dir, replayFileName(replay));
+  fs.writeFileSync(filePath, JSON.stringify(replay, null, 2));
+  return filePath;
+}
+
+function listRunReplayFiles({ dir = replayDir() } = {}) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs.readdirSync(dir)
+    .filter((name) => name.endsWith(".json"))
+    .map((name) => path.join(dir, name))
+    .sort();
+}
+
+function flushRunReplays(socket, { dir = replayDir() } = {}) {
+  if (socket.closed || socket.socket?.destroyed) {
+    return 0;
+  }
+  let sent = 0;
+  for (const filePath of listRunReplayFiles({ dir })) {
+    const replay = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    socket.sendJson({
+      type: GatewayMessageType.RUN_REPLAY,
+      payload: replay
+    });
+    fs.unlinkSync(filePath);
+    sent += 1;
+  }
+  return sent;
+}
+
+async function handleMessage(raw, socket, { isConnected = () => true, saveReplay = saveRunReplay } = {}) {
+  const message = JSON.parse(raw);
+  if (message.type === GatewayMessageType.APPROVAL_DECISION) {
+    handleApprovalDecision(message);
+    return;
+  }
+  if (message.type !== GatewayMessageType.REQUEST) {
+    return;
+  }
+
+  const replay = {
+    gateway_id: gatewayId(),
+    session_id: message.payload?.session?.id || null,
+    turn_id: message.payload?.turn?.id || null,
+    events: [],
+    terminal_status: null,
+    error: null
+  };
+  let shouldReplay = false;
+  const rememberForReplay = (payload) => {
+    if (payload.type === GatewayMessageType.STREAM_EVENT) {
+      replay.events.push(payload.payload);
+      if (payload.payload?.type === "cancelled") replay.terminal_status = "cancelled";
+      if (payload.payload?.type === "error") replay.terminal_status = "failed";
+      if (payload.payload?.type === "complete" && !replay.terminal_status) replay.terminal_status = "completed";
+    } else if (payload.type === GatewayMessageType.STREAM_COMPLETE) {
+      replay.terminal_status = replay.terminal_status || "completed";
+    } else if (payload.type === GatewayMessageType.STREAM_ERROR) {
+      replay.terminal_status = "failed";
+      replay.error = payload.error || null;
+    }
+  };
+
+  const send = (payload) => {
+    const connected = isConnected() && !socket.closed && !socket.socket?.destroyed;
+    if (!connected) {
+      shouldReplay = true;
+      rememberForReplay(payload);
+      return false;
+    }
+    try {
+      socket.sendJson({
+        request_id: message.request_id,
+        ...payload
+      });
+      return true;
+    } catch {
+      shouldReplay = true;
+      rememberForReplay(payload);
+      return false;
+    }
+  };
+
+  await handleRequest(message, send, { gatewayId: gatewayId() });
+  if (shouldReplay && (replay.events.length || replay.terminal_status)) {
+    saveReplay(replay);
+  }
+}
+
+function positiveInteger(value, fallback) {
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function reconnectDelayMs(failureCount, { minMs = DEFAULT_RECONNECT_MIN_MS, maxMs = DEFAULT_RECONNECT_MAX_MS } = {}) {
+  const min = positiveInteger(minMs, DEFAULT_RECONNECT_MIN_MS);
+  const max = Math.max(min, positiveInteger(maxMs, DEFAULT_RECONNECT_MAX_MS));
+  return Math.min(max, min * (2 ** Math.max(0, failureCount - 1)));
+}
+
+function wait(ms, signal) {
+  if (signal?.aborted || ms <= 0) {
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, ms);
+    function done() {
+      clearTimeout(timer);
+      signal?.removeEventListener?.("abort", done);
+      resolve();
+    }
+    signal?.addEventListener?.("abort", done, { once: true });
+  });
+}
+
+function logError(log, message) {
+  if (typeof log?.error === "function") {
+    log.error(message);
+  }
+}
+
+function logInfo(log, message) {
+  if (typeof log?.log === "function") {
+    log.log(message);
+  }
+}
+
+async function runGatewayConnection({
+  connect = connectWebSocket,
+  heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+  log = console,
+  register = registerMachine,
+  wsUrl = serverWsUrl()
+} = {}) {
+  await register(wsUrl);
+  const socket = await connect(wsUrl);
+  const connectedAt = Date.now();
+  let heartbeatTimer = null;
+  let settled = false;
+  let connected = true;
+  let closeConnection = () => {};
+
+  const finish = (resolve, reason) => {
+    if (settled) {
+      return;
+    }
+    settled = true;
+    connected = false;
+    if (heartbeatTimer) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    resolve({ reason, connectedForMs: Date.now() - connectedAt });
+  };
+
+  const closed = new Promise((resolve) => {
+    closeConnection = (reason) => finish(resolve, reason);
+    socket.on("message", (raw) => {
+      handleMessage(raw, socket, { isConnected: () => connected }).catch((error) => {
+        logError(log, error.stack || error.message);
+      });
+    });
+    socket.on("close", () => {
+      logError(log, "Agent Gateway disconnected.");
+      closeConnection("close");
+    });
+    socket.on("error", (error) => {
+      logError(log, error?.stack || "Agent Gateway connection error.");
+      closeConnection("error");
+    });
+  });
+
+  const heartbeat = () => {
+    try {
+      flushRunReplays(socket);
+      socket.sendJson({
+        type: GatewayMessageType.HEARTBEAT,
+        machine_id: gatewayId()
+      });
+    } catch (error) {
+      logError(log, error?.stack || error?.message || "Agent Gateway heartbeat failed.");
+      closeConnection("heartbeat_error");
+      if (typeof socket.close === "function") {
+        socket.close();
+      }
+    }
+  };
+
+  heartbeat();
+  heartbeatTimer = setInterval(heartbeat, heartbeatIntervalMs);
+  logInfo(log, `Agent Gateway connected: ${wsUrl.origin}`);
+
+  return closed;
+}
+
+async function startGateway(options = {}) {
+  const {
+    heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+    log = console,
+    reconnectMaxMs = process.env.AGENT_ANYWHERE_GATEWAY_RECONNECT_MAX_MS || DEFAULT_RECONNECT_MAX_MS,
+    reconnectMinMs = process.env.AGENT_ANYWHERE_GATEWAY_RECONNECT_MIN_MS || DEFAULT_RECONNECT_MIN_MS,
+    signal
+  } = options;
+  const wsUrl = options.wsUrl || serverWsUrl();
+  let failureCount = 0;
+
+  while (!signal?.aborted) {
+    try {
+      const result = await runGatewayConnection({
+        ...options,
+        heartbeatIntervalMs,
+        log,
+        wsUrl
+      });
+      failureCount = result.connectedForMs >= positiveInteger(reconnectMinMs, DEFAULT_RECONNECT_MIN_MS)
+        ? 1
+        : failureCount + 1;
+    } catch (error) {
+      failureCount += 1;
+      logError(log, error.stack || error.message);
+    }
+
+    if (signal?.aborted) {
+      break;
+    }
+    const delay = reconnectDelayMs(failureCount, { minMs: reconnectMinMs, maxMs: reconnectMaxMs });
+    logError(log, `Agent Gateway reconnecting in ${delay}ms.`);
+    await wait(delay, signal);
+  }
+}
+
+module.exports = {
+  discoverGatewayCapabilities,
+  gatewayId,
+  handleMessage,
+  mergeCapabilities,
+  reconnectDelayMs,
+  registerMachine,
+  registerUrl,
+  flushRunReplays,
+  runGatewayConnection,
+  saveRunReplay,
+  serverWsUrl,
+  startGateway
+};