promethios-bridge 1.1.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promethios-bridge",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Run Promethios agent frameworks locally on your computer with full file, terminal, and browser access.",
   "main": "src/index.js",
   "bin": {

package/src/bridge.js

@@ -2,11 +2,17 @@
  * Promethios Local Bridge — Core
  *
  * 1. Authenticates with Promethios using a setup token
- * 2. Starts a local HTTP server on the configured port
+ * 2. Starts a local HTTP server on the configured port (for health checks)
  * 3. Registers the bridge endpoint with the Promethios API
- * 4. Listens for tool-call requests from the cloud orchestrator
- * 5. Executes tools locally and returns results
+ * 4. Polls the Promethios API for pending tool calls (Firestore relay)
+ * 5. Executes tools locally and posts results back to the API
  * 6. Sends heartbeats every 30s to keep the connection alive
+ *
+ * ── Why polling instead of direct HTTP? ─────────────────────────────────────
+ * The bridge only listens on 127.0.0.1 (localhost) for security — it is NOT
+ * reachable from the internet. Instead of requiring a tunnel, the bridge polls
+ * the Promethios API for pending tool calls queued by the cloud orchestrator.
+ * This works behind firewalls, NAT, and corporate proxies with no setup.
  */
 
 const express = require('express');
@@ -16,6 +22,7 @@ const fetch = require('node-fetch');
 const { executeLocalTool } = require('./executor');
 
 const HEARTBEAT_INTERVAL = 30_000; // 30s
+const POLL_INTERVAL = 1_000;       // 1s — poll for pending tool calls
 
 async function startBridge({ setupToken, apiBase, port, dev }) {
   const log = dev
@@ -40,17 +47,18 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
     process.exit(1);
   }
 
-  // ── Step 2: Start local HTTP server ──────────────────────────────────────
+  // ── Step 2: Start local HTTP server (health check only) ──────────────────
   const app = express();
   app.use(express.json());
 
   // Health check
   app.get('/health', (req, res) => res.json({ ok: true, version: require('../package.json').version }));
 
-  // Tool call endpoint — called by the Promethios cloud relay
+  // Legacy direct tool-call endpoint (kept for backward compatibility with
+  // older backend versions that call callbackUrl/tool-call directly)
   app.post('/tool-call', async (req, res) => {
     const { toolName, args, frameworkId, callId } = req.body;
-    log('Tool call received:', toolName, JSON.stringify(args).slice(0, 100));
+    log('Tool call received (direct):', toolName, JSON.stringify(args).slice(0, 100));
 
     try {
       const result = await executeLocalTool({ toolName, args, frameworkId, dev });
@@ -62,7 +70,7 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
     }
   });
 
-  // Capability query — cloud can ask what this bridge supports
+  // Capability query
   app.get('/capabilities', (req, res) => {
     res.json({ capabilities: getSupportedCapabilities() });
   });
@@ -108,10 +116,48 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
     }
   }, HEARTBEAT_INTERVAL);
 
+  // ── Step 5: Poll for pending tool calls (Firestore relay) ─────────────────
+  // The cloud backend queues tool calls in Firestore when the agent uses
+  // local_shell, local_file_read, or local_file_write. We poll for them here,
+  // execute locally, and post results back. This works behind firewalls/NAT.
+  let pollActive = true;
+
+  const pollLoop = async () => {
+    while (pollActive) {
+      try {
+        const res = await fetch(`${apiBase}/api/local-bridge/pending-calls`, {
+          headers: { Authorization: `Bearer ${authToken}` },
+        });
+
+        if (res.ok) {
+          const { calls } = await res.json();
+          if (calls && calls.length > 0) {
+            log(`Got ${calls.length} pending tool call(s)`);
+            // Execute all pending calls concurrently
+            await Promise.all(calls.map(call => executePendingCall({ call, authToken, apiBase, dev })));
+          }
+        } else {
+          log('Pending-calls poll returned', res.status);
+        }
+      } catch (err) {
+        log('Poll error:', err.message);
+      }
+
+      // Wait before next poll
+      await sleep(POLL_INTERVAL);
+    }
+  };
+
+  // Start polling in background (don't await — runs until shutdown)
+  pollLoop().catch(err => {
+    console.error(chalk.red('  ✗ Poll loop crashed:'), err.message);
+  });
+
   // Graceful shutdown
   const shutdown = async (signal) => {
     console.log('');
     console.log(chalk.yellow(`  Disconnecting (${signal})...`));
+    pollActive = false;
     clearInterval(heartbeatTimer);
     try {
       await fetch(`${apiBase}/api/local-bridge/unregister`, {
@@ -127,6 +173,49 @@ async function startBridge({ setupToken, apiBase, port, dev }) {
   process.on('SIGTERM', () => shutdown('SIGTERM'));
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Execute a single pending tool call and post the result back
+// ─────────────────────────────────────────────────────────────────────────────
+async function executePendingCall({ call, authToken, apiBase, dev }) {
+  const log = dev ? (...a) => console.log(chalk.gray('  [debug]'), ...a) : () => {};
+  const { callId, toolName, args } = call;
+
+  log(`Executing pending call ${callId}: ${toolName}`);
+  console.log(chalk.cyan(`  → Running ${toolName}...`));
+
+  let result, error;
+  try {
+    result = await executeLocalTool({ toolName, args, dev });
+    log(`Result for ${callId}:`, JSON.stringify(result).slice(0, 200));
+    console.log(chalk.green(`  ✓ ${toolName} completed`));
+  } catch (err) {
+    error = err.message;
+    console.error(chalk.red(`  ✗ ${toolName} failed:`), err.message);
+  }
+
+  // Post result back to the API
+  try {
+    const body = error ? { error } : { result };
+    const res = await fetch(`${apiBase}/api/local-bridge/tool-result/${callId}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      log(`Failed to post result for ${callId}: ${res.status} ${text}`);
+    } else {
+      log(`Result posted for ${callId}`);
+    }
+  } catch (err) {
+    log(`Error posting result for ${callId}:`, err.message);
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Auth: exchange setup token for a session bearer token
 // ─────────────────────────────────────────────────────────────────────────────
@@ -157,6 +246,15 @@ async function registerBridge({ authToken, apiBase, callbackUrl, port, dev }) {
   const deviceId = require('crypto').randomBytes(8).toString('hex');
   const capabilities = getSupportedCapabilities();
 
+  // Detect OS and shell so the cloud can inject OS-aware guidance into the agent
+  const osModule = require('os');
+  const platform = process.platform; // 'win32' | 'darwin' | 'linux'
+  const shell = platform === 'win32'
+    ? 'cmd'
+    : (process.env.SHELL || '/bin/zsh').split('/').pop();
+  const homeDir = osModule.homedir();
+  const username = osModule.userInfo().username;
+
   const res = await fetch(`${apiBase}/api/local-bridge/register`, {
     method: 'POST',
     headers: {
@@ -168,6 +266,10 @@ async function registerBridge({ authToken, apiBase, callbackUrl, port, dev }) {
       callbackUrl,
       capabilities,
       bridgeVersion: require('../package.json').version,
+      os: platform,   // 'win32' | 'darwin' | 'linux'
+      shell,          // 'cmd' | 'zsh' | 'bash' etc.
+      homeDir,        // e.g. 'C:\\Users\\ted' or '/Users/ted'
+      username,       // e.g. 'ted'
     }),
   });
 
@@ -191,4 +293,8 @@ function getSupportedCapabilities() {
   ];
 }
 
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 module.exports = { startBridge };

package/src/executor.js

@@ -23,6 +23,20 @@ const execAsync = promisify(exec);
 async function executeLocalTool({ toolName, args, frameworkId, dev }) {
   const log = dev ? (...a) => console.log('[executor]', ...a) : () => {};
 
+  // ── Aliases for the new universal bridge tool names ─────────────────────
+  // The Promethios backend injects local_shell, local_file_read, local_file_write
+  // into the agent's tool list when the bridge is connected. Map them to the
+  // existing executor handlers.
+  if (toolName === 'local_shell') {
+    return executeLocalTool({ toolName: 'run_command', args: { command: args.command, cwd: args.cwd, timeout: args.timeout }, frameworkId, dev });
+  }
+  if (toolName === 'local_file_read') {
+    return executeLocalTool({ toolName: 'read_file', args: { path: args.path, encoding: args.encoding }, frameworkId, dev });
+  }
+  if (toolName === 'local_file_write') {
+    return executeLocalTool({ toolName: 'write_file', args: { path: args.path, content: args.content, encoding: args.encoding }, frameworkId, dev });
+  }
+
   // ── local_execute is the built-in tool injected by the backend when the bridge
   //    is connected. It uses an `action` field to dispatch to the right handler.
   if (toolName === 'local_execute') {
@@ -95,8 +109,9 @@ async function executeLocalTool({ toolName, args, frameworkId, dev }) {
         throw new Error('Command blocked: potentially destructive operation');
       }
       log('run_command', cmd);
+      const timeoutMs = args.timeout ? Math.min(args.timeout * 1000, 120_000) : 30_000;
       const { stdout, stderr } = await execAsync(cmd, {
-        timeout: 30_000,
+        timeout: timeoutMs,
         cwd: args.cwd ? resolveSafePath(args.cwd) : process.env.HOME,
         maxBuffer: 1024 * 1024, // 1MB output limit
       });