agent-office-cli 0.1.7 → 0.1.9

package/README.md

@@ -0,0 +1,168 @@
+# agent-office-cli
+
+`agent-office-cli` is the local runtime for AgentOffice.
+
+It starts the local session manager, restores tmux-backed AI workers, connects your machine to the hosted relay, and lets you launch or attach to Claude Code / Codex sessions from the terminal.
+
+## What This Package Does
+
+- Starts the local AgentOffice service with `ato start`
+- Restores existing tmux-backed workers after restart
+- Connects your machine to `agentoffice.top` or a custom relay
+- Launches Claude Code and Codex workers with one command
+- Exposes local worker terminals to the AgentOffice web or mobile UI
+
+## Install
+
+```bash
+npm i -g agent-office-cli
+```
+
+## Requirements
+
+- Node.js 18+
+- `tmux`
+- Claude Code and/or Codex CLI if you want to launch those providers
+
+Example on macOS:
+
+```bash
+brew install tmux
+```
+
+## Quick Start
+
+1. Create an API key on `https://agentoffice.top`
+2. Start the local runtime
+3. Launch workers from another terminal
+
+Using an environment variable:
+
+```bash
+export AGENTOFFICE_API_KEY=sk_your_api_key
+ato start
+```
+
+Or pass the key directly:
+
+```bash
+ato start --key sk_your_api_key
+```
+
+Launch workers:
+
+```bash
+ato claude
+ato codex
+```
+
+Launch with a custom title:
+
+```bash
+ato claude -t "Review PR #42"
+ato codex -t "Fix login bug"
+```
+
+Attach your local terminal to an existing worker:
+
+```bash
+ato attach <sessionId>
+```
+
+## Common Commands
+
+### `ato start`
+
+Starts the local AgentOffice runtime, restores managed sessions, and connects to the hosted relay when an API key is present.
+
+Examples:
+
+```bash
+ato start
+ato start --key sk_your_api_key
+ato start --key sk_your_api_key --relay https://your-relay.example.com
+```
+
+Notes:
+
+- On macOS, `ato start` keeps the machine awake while the tunnel is active
+- Hosted tunnel logs are written to `~/.agentoffice/logs/tunnel.log`
+
+### `ato claude`
+
+Launches a Claude Code worker in tmux so it can be supervised from AgentOffice.
+
+```bash
+ato claude
+ato claude -t "Investigate flaky test"
+```
+
+### `ato codex`
+
+Launches a Codex worker in tmux.
+
+```bash
+ato codex
+ato codex -t "Refactor websocket retry logic"
+```
+
+### `ato attach`
+
+Attaches your local shell directly to a worker's tmux session.
+
+```bash
+ato attach <sessionId>
+```
+
+## Hosted Mode
+
+When you start the runtime with an API key, the CLI opens a secure tunnel from your local machine to the AgentOffice relay.
+
+That tunnel is used to:
+
+- show your workers in the Office UI
+- open remote terminals from web or mobile
+- launch workers from the AgentOffice interface
+- proxy requests into the local runtime
+
+If the connection drops, the tunnel automatically retries and records reconnect details in the local tunnel log.
+
+## Troubleshooting
+
+### `tmux is required`
+
+Install `tmux` first, then run `ato start` again.
+
+### Worker launch commands are missing
+
+Make sure the provider CLI is installed and available on `PATH`:
+
+- `claude`
+- `codex`
+
+### Remote Office shows offline
+
+Check the local tunnel log:
+
+```bash
+tail -n 100 ~/.agentoffice/logs/tunnel.log
+```
+
+Look for:
+
+- websocket connection errors
+- reconnect attempts
+- auth failures
+- relay disconnect reasons
+
+## Package Scope
+
+This package is the CLI/runtime portion of AgentOffice only.
+
+It does not include the full web app source or product docs. Those live in the main repository:
+
+- GitHub: `https://github.com/fakeou/agent-office`
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-office-cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Run and manage AI agent sessions locally, with optional relay to agentoffice.top",
   "license": "MIT",
   "engines": {

package/src/tunnel.js

@@ -4,6 +4,9 @@ const { createTunnelLogger, describeWebSocketClose } = require("./runtime/tunnel
 
 const RECONNECT_BASE_MS = 1000;
 const RECONNECT_MAX_MS = 30000;
+const AUTH_RESPONSE_TIMEOUT_MS = 15000;
+const STALE_UPSTREAM_TIMEOUT_MS = 70000;
+const WATCHDOG_INTERVAL_MS = 5000;
 const LOCAL_PROXY_STRIP_HEADERS = new Set([
   "accept-encoding",
   "connection",
@@ -41,12 +44,49 @@ function buildLocalRequestHeaders(headers, localServerUrl) {
   return nextHeaders;
 }
 
-function createTunnelClient({ key, relayUrl, localServerUrl, logger = createTunnelLogger() }) {
+const TERMINAL_AUTH_REASONS = new Set([
+  "invalid_key",
+  "key_revoked"
+]);
+
+function isTerminalAuthFailure({ code, reason, error }) {
+  if (error) {
+    return TERMINAL_AUTH_REASONS.has(error);
+  }
+  if (code !== 4401) {
+    return false;
+  }
+  return TERMINAL_AUTH_REASONS.has(reason);
+}
+
+function closeSocket(socket) {
+  if (!socket) {
+    return;
+  }
+  if (typeof socket.terminate === "function") {
+    socket.terminate();
+    return;
+  }
+  socket.close();
+}
+
+function createTunnelClient({
+  key,
+  relayUrl,
+  localServerUrl,
+  logger = createTunnelLogger(),
+  reconnectBaseMs = RECONNECT_BASE_MS,
+  reconnectMaxMs = RECONNECT_MAX_MS,
+  authResponseTimeoutMs = AUTH_RESPONSE_TIMEOUT_MS,
+  staleUpstreamTimeoutMs = STALE_UPSTREAM_TIMEOUT_MS,
+  watchdogIntervalMs = WATCHDOG_INTERVAL_MS
+}) {
   let ws = null;
-  let reconnectDelay = RECONNECT_BASE_MS;
+  let reconnectDelay = reconnectBaseMs;
   let stopped = false;
   let authenticated = false;
   let pendingStatusSummary = [];
+  let reconnectTimer = null;
 
   function flushStatusSummary() {
     if (!authenticated || !ws || ws.readyState !== WebSocket.OPEN) {
@@ -58,6 +98,20 @@ function createTunnelClient({ key, relayUrl, localServerUrl, logger = createTunn
     }));
   }
 
+  function scheduleReconnect() {
+    if (stopped || reconnectTimer) {
+      return;
+    }
+
+    const delay = reconnectDelay;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      reconnectDelay = Math.min(reconnectDelay * 2, reconnectMaxMs);
+      connect();
+    }, delay);
+    reconnectTimer.unref?.();
+  }
+
   function connect() {
     if (stopped) {
       return;
@@ -65,16 +119,56 @@ function createTunnelClient({ key, relayUrl, localServerUrl, logger = createTunn
 
     authenticated = false;
     const url = `${relayUrl.replace(/^http/, "ws")}/upstream`;
-    ws = new WebSocket(url);
+    const socket = new WebSocket(url);
+    let socketAuthenticated = false;
+    let lastActivityAt = Date.now();
 
-    ws.on("open", () => {
-      reconnectDelay = RECONNECT_BASE_MS;
+    function markActivity() {
+      lastActivityAt = Date.now();
+    }
+
+    const watchdogTimer = setInterval(() => {
+      if (stopped || ws !== socket) {
+        return;
+      }
+
+      const idleForMs = Date.now() - lastActivityAt;
+      if (!socketAuthenticated) {
+        if (idleForMs < authResponseTimeoutMs) {
+          return;
+        }
+        logger.error(`[tunnel] auth response timeout after ${idleForMs}ms. Terminating socket and retrying.`);
+        closeSocket(socket);
+        return;
+      }
+
+      if (idleForMs < staleUpstreamTimeoutMs) {
+        return;
+      }
+
+      logger.error(`[tunnel] upstream stale for ${idleForMs}ms. Terminating socket and reconnecting.`);
+      closeSocket(socket);
+    }, watchdogIntervalMs);
+    watchdogTimer.unref?.();
+
+    ws = socket;
+
+    socket.on("open", () => {
+      markActivity();
       logger.info("[tunnel] connected to relay, authenticating...");
-      ws.send(JSON.stringify({ type: "auth", key }));
+      socket.send(JSON.stringify({ type: "auth", key }));
     });
 
-    ws.on("message", async (raw) => {
+    socket.on("ping", markActivity);
+    socket.on("pong", markActivity);
+
+    socket.on("message", async (raw) => {
       try {
+        if (ws !== socket) {
+          return;
+        }
+
+        markActivity();
         const str = String(raw);
 
         // Fast path: WS data forwarding uses "W:${connId}:${data}" prefix (no JSON parse)
@@ -91,15 +185,19 @@ function createTunnelClient({ key, relayUrl, localServerUrl, logger = createTunn
         const msg = JSON.parse(str);
 
         if (msg.type === "auth:ok") {
+          socketAuthenticated = true;
           authenticated = true;
+          reconnectDelay = reconnectBaseMs;
           logger.info(`[tunnel] authenticated with relay: ${relayUrl} (userId=${msg.userId})`);
           flushStatusSummary();
           return;
         }
         if (msg.type === "auth:error") {
           logger.error(`[tunnel] authentication failed: ${msg.error || "invalid key"}`);
-          stopped = true;
-          ws.close();
+          if (isTerminalAuthFailure({ error: msg.error })) {
+            stopped = true;
+          }
+          socket.close();
           return;
         }
 
@@ -113,26 +211,27 @@ function createTunnelClient({ key, relayUrl, localServerUrl, logger = createTunn
       }
     });
 
-    ws.on("close", (code, reasonBuffer) => {
+    socket.on("close", (code, reasonBuffer) => {
+      clearInterval(watchdogTimer);
+      if (ws === socket) {
+        ws = null;
+      }
       const reason = Buffer.isBuffer(reasonBuffer) ? reasonBuffer.toString("utf8") : String(reasonBuffer || "");
       const closeDetails = describeWebSocketClose({ code, reason });
       if (stopped) {
         logger.info(`[tunnel] stopped with close ${closeDetails}`);
         return;
       }
-      if (code === 4401) {
+      if (isTerminalAuthFailure({ code, reason })) {
         logger.error(`[tunnel] authentication rejected by relay (${closeDetails}). Not reconnecting.`);
         stopped = true;
         return;
       }
       logger.info(`[tunnel] disconnected (${closeDetails}). Reconnecting in ${reconnectDelay}ms...`);
-      setTimeout(() => {
-        reconnectDelay = Math.min(reconnectDelay * 2, RECONNECT_MAX_MS);
-        connect();
-      }, reconnectDelay);
+      scheduleReconnect();
     });
 
-    ws.on("error", (err) => {
+    socket.on("error", (err) => {
       logger.error(`[tunnel] ws error: ${err.message}`);
     });
   }
@@ -242,6 +341,10 @@ function createTunnelClient({ key, relayUrl, localServerUrl, logger = createTunn
 
   function stop() {
     stopped = true;
+    if (reconnectTimer) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
     for (const localWs of localWsConnections.values()) {
       localWs.close();
     }

package/src/tunnel.test.js

@@ -1,7 +1,10 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
+const { once } = require("node:events");
+const { createServer } = require("node:http");
+const { WebSocketServer } = require("ws");
 
-const { buildLocalRequestHeaders } = require("./tunnel");
+const { buildLocalRequestHeaders, createTunnelClient } = require("./tunnel");
 
 test("buildLocalRequestHeaders strips browser-only proxy headers and rewrites host", () => {
   const next = buildLocalRequestHeaders(
@@ -29,3 +32,167 @@ test("buildLocalRequestHeaders strips browser-only proxy headers and rewrites ho
     host: "127.0.0.1:8765"
   });
 });
+
+async function withRelaySocketServer(run) {
+  const server = createServer();
+  const wss = new WebSocketServer({ server });
+
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+
+  const address = server.address();
+  const relayUrl = `http://127.0.0.1:${address.port}`;
+
+  try {
+    await run({ relayUrl, wss });
+  } finally {
+    await new Promise((resolve) => wss.close(resolve));
+    await new Promise((resolve, reject) => {
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  }
+}
+
+function createNoopLogger() {
+  return {
+    info() {},
+    error() {}
+  };
+}
+
+async function waitFor(predicate, timeoutMs = 500) {
+  const startedAt = Date.now();
+  while (!predicate()) {
+    if (Date.now() - startedAt > timeoutMs) {
+      return false;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  return true;
+}
+
+test("createTunnelClient reconnects when auth never completes", async () => {
+  await withRelaySocketServer(async ({ relayUrl, wss }) => {
+    const connections = [];
+    wss.on("connection", (socket) => {
+      connections.push(socket);
+      socket.on("message", () => {
+        // Intentionally ignore auth messages to simulate a stalled handshake.
+      });
+    });
+
+    const tunnel = createTunnelClient({
+      key: "test-key",
+      relayUrl,
+      localServerUrl: "http://127.0.0.1:8765",
+      logger: createNoopLogger(),
+      reconnectBaseMs: 20,
+      reconnectMaxMs: 40,
+      authResponseTimeoutMs: 50,
+      watchdogIntervalMs: 10
+    });
+
+    try {
+      const reconnected = await waitFor(() => connections.length >= 2);
+      assert.ok(reconnected, `expected reconnect after stalled auth, saw ${connections.length} connection(s)`);
+    } finally {
+      tunnel.stop();
+    }
+  });
+});
+
+test("createTunnelClient reconnects when an authenticated tunnel goes silent", async () => {
+  await withRelaySocketServer(async ({ relayUrl, wss }) => {
+    const connections = [];
+    wss.on("connection", (socket) => {
+      connections.push(socket);
+      socket.once("message", () => {
+        socket.send(JSON.stringify({ type: "auth:ok", userId: "user_test" }));
+        // Intentionally stay silent after auth: no ping, no messages.
+      });
+    });
+
+    const tunnel = createTunnelClient({
+      key: "test-key",
+      relayUrl,
+      localServerUrl: "http://127.0.0.1:8765",
+      logger: createNoopLogger(),
+      reconnectBaseMs: 20,
+      reconnectMaxMs: 40,
+      staleUpstreamTimeoutMs: 60,
+      watchdogIntervalMs: 10
+    });
+
+    try {
+      const reconnected = await waitFor(() => connections.length >= 2);
+      assert.ok(reconnected, `expected reconnect after stale upstream, saw ${connections.length} connection(s)`);
+    } finally {
+      tunnel.stop();
+    }
+  });
+});
+
+test("createTunnelClient retries after relay auth timeout closes the socket", async () => {
+  await withRelaySocketServer(async ({ relayUrl, wss }) => {
+    const connections = [];
+    wss.on("connection", (socket) => {
+      connections.push(socket);
+      socket.once("message", () => {
+        socket.close(4401, "auth_timeout");
+      });
+    });
+
+    const tunnel = createTunnelClient({
+      key: "test-key",
+      relayUrl,
+      localServerUrl: "http://127.0.0.1:8765",
+      logger: createNoopLogger(),
+      reconnectBaseMs: 20,
+      reconnectMaxMs: 40,
+      watchdogIntervalMs: 10
+    });
+
+    try {
+      const reconnected = await waitFor(() => connections.length >= 2);
+      assert.ok(reconnected, `expected reconnect after auth_timeout, saw ${connections.length} connection(s)`);
+    } finally {
+      tunnel.stop();
+    }
+  });
+});
+
+test("createTunnelClient stops retrying after invalid key is rejected", async () => {
+  await withRelaySocketServer(async ({ relayUrl, wss }) => {
+    const connections = [];
+    wss.on("connection", (socket) => {
+      connections.push(socket);
+      socket.once("message", () => {
+        socket.send(JSON.stringify({ type: "auth:error", error: "invalid_key" }));
+        socket.close(4401, "invalid_key");
+      });
+    });
+
+    const tunnel = createTunnelClient({
+      key: "test-key",
+      relayUrl,
+      localServerUrl: "http://127.0.0.1:8765",
+      logger: createNoopLogger(),
+      reconnectBaseMs: 20,
+      reconnectMaxMs: 40,
+      watchdogIntervalMs: 10
+    });
+
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 120));
+      assert.equal(connections.length, 1);
+    } finally {
+      tunnel.stop();
+    }
+  });
+});