promethios-bridge 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "promethios-bridge",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Run Promethios agent frameworks locally on your computer with full file, terminal, and browser access.",
   "main": "src/index.js",
   "bin": {
@@ -10,7 +10,14 @@
     "start": "node src/cli.js",
     "dev": "node src/cli.js --dev"
   },
-  "keywords": ["promethios", "ai", "agent", "local", "bridge", "framework"],
+  "keywords": [
+    "promethios",
+    "ai",
+    "agent",
+    "local",
+    "bridge",
+    "framework"
+  ],
   "author": "Promethios <hello@promethios.ai>",
   "license": "MIT",
   "repository": {

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
 // ─────────────────────────────────────────────────────────────────────────────
@@ -191,4 +280,8 @@ function getSupportedCapabilities() {
   ];
 }
 
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
 module.exports = { startBridge };

package/src/cli.js

@@ -3,16 +3,24 @@
  * promethios-bridge CLI
  *
  * Usage:
- *   npx promethios-bridge                    # Interactive setup
- *   npx promethios-bridge --token <token>    # Pre-authenticated (from Promethios UI)
- *   npx promethios-bridge --port 7823        # Custom local port
- *   npx promethios-bridge --dev              # Dev mode (verbose logging)
+ *   npx promethios-bridge                        # Interactive setup
+ *   npx promethios-bridge --token <token>        # Pre-authenticated (from Promethios UI)
+ *   npx promethios-bridge --port 7823            # Custom local port
+ *   npx promethios-bridge --dev                  # Dev mode (verbose logging)
+ *   npx promethios-bridge --install              # Register promethios:// URI scheme on this OS
+ *   npx promethios-bridge --uri <uri>            # Handle a promethios:// deep link (called by OS)
+ *
+ * One-click connect flow:
+ *   1. User clicks "Connect My Computer" in the Promethios UI
+ *   2. Browser opens promethios://connect?token=<token>&api=<url>
+ *   3. OS routes it to this CLI via the registered URI handler
+ *   4. CLI parses the URI, extracts token + api, and starts the bridge
  */
 
 const { program } = require('commander');
 const chalk = require('chalk');
-const ora = require('ora');
 const { startBridge } = require('./bridge');
+const { registerUriScheme } = require('./uriScheme');
 
 const VERSION = require('../package.json').version;
 
@@ -29,10 +37,63 @@ program
   .option('--api <url>', 'Promethios API base URL', 'https://api.promethios.ai')
   .option('--port <port>', 'Local port for the bridge server', '7823')
   .option('--dev', 'Enable verbose debug logging')
+  .option('--install', 'Register the promethios:// URI scheme on this computer (run once after install)')
+  .option('--uri <uri>', 'Handle a promethios:// deep link URI (called automatically by the OS)')
   .parse(process.argv);
 
 const opts = program.opts();
 
+// ── --install: register URI scheme on this OS ────────────────────────────────
+if (opts.install) {
+  registerUriScheme()
+    .then(() => {
+      console.log(chalk.green('  ✓ promethios:// URI scheme registered'));
+      console.log(chalk.gray('  Clicking "Connect My Computer" in Promethios will now launch this app automatically.'));
+      console.log('');
+      process.exit(0);
+    })
+    .catch((err) => {
+      console.error(chalk.red('  ✗ Failed to register URI scheme:'), err.message);
+      console.log(chalk.yellow('  You can still connect by running: npx promethios-bridge --token <token>'));
+      process.exit(1);
+    });
+  return;
+}
+
+// ── --uri: handle a promethios:// deep link from the OS ──────────────────────
+if (opts.uri) {
+  const uri = opts.uri;
+  let token, apiBase;
+
+  try {
+    // promethios://connect?token=<token>&api=<encoded-url>
+    const url = new URL(uri);
+    token = url.searchParams.get('token');
+    apiBase = url.searchParams.get('api')
+      ? decodeURIComponent(url.searchParams.get('api'))
+      : 'https://api.promethios.ai';
+
+    if (!token) throw new Error('No token in URI');
+  } catch (err) {
+    console.error(chalk.red('  ✗ Invalid deep link URI:'), err.message);
+    console.log(chalk.gray('  URI received:'), uri);
+    process.exit(1);
+  }
+
+  console.log(chalk.cyan('  → Connecting via deep link…'));
+  startBridge({
+    setupToken: token,
+    apiBase,
+    port: parseInt(opts.port, 10),
+    dev: !!opts.dev,
+  }).catch((err) => {
+    console.error(chalk.red('\n  ✗ Bridge failed to start:'), err.message);
+    process.exit(1);
+  });
+  return;
+}
+
+// ── Standard start (--token or interactive) ──────────────────────────────────
 startBridge({
   setupToken: opts.token,
   apiBase: opts.api,

package/src/executor.js

@@ -23,6 +23,41 @@ 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') {
+    const action = args.action;
+    log('local_execute action:', action);
+    switch (action) {
+      case 'shell':
+        return executeLocalTool({ toolName: 'run_command', args: { command: args.command, cwd: args.cwd }, frameworkId, dev });
+      case 'read_file':
+        return executeLocalTool({ toolName: 'read_file', args: { path: args.path }, frameworkId, dev });
+      case 'write_file':
+        return executeLocalTool({ toolName: 'write_file', args: { path: args.path, content: args.content }, frameworkId, dev });
+      case 'list_dir':
+        return executeLocalTool({ toolName: 'list_directory', args: { path: args.path || '.' }, frameworkId, dev });
+      case 'open_browser':
+        return executeLocalTool({ toolName: 'open_browser', args: { url: args.url }, frameworkId, dev });
+      default:
+        throw new Error(`Unknown local_execute action: ${action}`);
+    }
+  }
+
   switch (toolName) {
     // ── Filesystem ────────────────────────────────────────────────────────
     case 'read_file': {
@@ -74,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
       });

package/src/index.js

@@ -0,0 +1,10 @@
+/**
+ * promethios-bridge — programmatic API
+ *
+ * This file is the package's main entry point (for require('promethios-bridge')).
+ * The CLI is invoked via the 'bin' field in package.json.
+ */
+
+const { startBridge } = require('./bridge');
+
+module.exports = { startBridge };

package/src/uriScheme.js

@@ -0,0 +1,146 @@
+/**
+ * Promethios Local Bridge — URI Scheme Registration
+ *
+ * Registers the promethios:// custom URI scheme on the current OS so that
+ * clicking "Connect My Computer" in the browser auto-launches this CLI.
+ *
+ * Platform implementations:
+ *   macOS   — writes a LaunchServices .plist to ~/Library/LaunchAgents/
+ *   Windows — writes a registry key under HKEY_CURRENT_USER\Software\Classes\promethios
+ *   Linux   — writes a .desktop file to ~/.local/share/applications/
+ *
+ * Run once after install: npx promethios-bridge --install
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const SCHEME = 'promethios';
+const CLI_PATH = process.execPath; // path to the node binary running this script
+const SCRIPT_PATH = path.resolve(__dirname, 'cli.js');
+
+async function registerUriScheme() {
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    return registerMacOS();
+  } else if (platform === 'win32') {
+    return registerWindows();
+  } else {
+    return registerLinux();
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// macOS — LaunchServices plist
+// ─────────────────────────────────────────────────────────────────────────────
+async function registerMacOS() {
+  const appDir = path.join(os.homedir(), 'Applications', 'Promethios Bridge.app');
+  const contentsDir = path.join(appDir, 'Contents');
+  const macOSDir = path.join(contentsDir, 'MacOS');
+  const resourcesDir = path.join(contentsDir, 'Resources');
+
+  await fs.mkdir(macOSDir, { recursive: true });
+  await fs.mkdir(resourcesDir, { recursive: true });
+
+  // Launcher script
+  const launcher = `#!/bin/bash
+# Promethios Bridge URI handler
+# Called by macOS when a promethios:// link is clicked
+exec "${CLI_PATH}" "${SCRIPT_PATH}" --uri "$1"
+`;
+  const launcherPath = path.join(macOSDir, 'promethios-bridge');
+  await fs.writeFile(launcherPath, launcher, { mode: 0o755 });
+
+  // Info.plist
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key>
+  <string>ai.promethios.bridge</string>
+  <key>CFBundleName</key>
+  <string>Promethios Bridge</string>
+  <key>CFBundleExecutable</key>
+  <string>promethios-bridge</string>
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key>
+      <string>Promethios Bridge</string>
+      <key>CFBundleURLSchemes</key>
+      <array>
+        <string>${SCHEME}</string>
+      </array>
+    </dict>
+  </array>
+  <key>LSMinimumSystemVersion</key>
+  <string>10.13</string>
+  <key>NSHighResolutionCapable</key>
+  <true/>
+</dict>
+</plist>`;
+  await fs.writeFile(path.join(contentsDir, 'Info.plist'), plist);
+
+  // Register with LaunchServices
+  try {
+    execSync(`/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -f "${appDir}"`, { stdio: 'ignore' });
+  } catch {
+    // lsregister may not be available on all macOS versions; the plist is still written
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Windows — Registry
+// ─────────────────────────────────────────────────────────────────────────────
+async function registerWindows() {
+  // Use reg.exe to write to HKEY_CURRENT_USER (no admin required).
+  // We use `cmd /c npx promethios-bridge --uri "%1"` rather than hardcoding
+  // the node/script path, because npx cache paths are temporary and get
+  // cleaned up after the install run — leaving a broken registry entry.
+  // Using npx ensures the handler always resolves to the installed package.
+  const command = `cmd /c npx --yes promethios-bridge --uri "%1"`;
+
+  const regCommands = [
+    `reg add "HKEY_CURRENT_USER\\Software\\Classes\\${SCHEME}" /ve /d "URL:Promethios Bridge Protocol" /f`,
+    `reg add "HKEY_CURRENT_USER\\Software\\Classes\\${SCHEME}" /v "URL Protocol" /d "" /f`,
+    `reg add "HKEY_CURRENT_USER\\Software\\Classes\\${SCHEME}\\shell\\open\\command" /ve /d "${command}" /f`,
+  ];
+
+  for (const cmd of regCommands) {
+    execSync(cmd, { stdio: 'ignore' });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Linux — .desktop file + xdg-mime
+// ─────────────────────────────────────────────────────────────────────────────
+async function registerLinux() {
+  const desktopDir = path.join(os.homedir(), '.local', 'share', 'applications');
+  await fs.mkdir(desktopDir, { recursive: true });
+
+  const desktopFile = `[Desktop Entry]
+Name=Promethios Bridge
+Exec="${CLI_PATH}" "${SCRIPT_PATH}" --uri %u
+Type=Application
+Terminal=true
+MimeType=x-scheme-handler/${SCHEME};
+Categories=Development;
+Comment=Connect your computer to Promethios AI agent frameworks
+`;
+
+  const desktopPath = path.join(desktopDir, 'promethios-bridge.desktop');
+  await fs.writeFile(desktopPath, desktopFile, { mode: 0o644 });
+
+  // Register with xdg-mime
+  try {
+    execSync(`xdg-mime default promethios-bridge.desktop x-scheme-handler/${SCHEME}`, { stdio: 'ignore' });
+    execSync('update-desktop-database ~/.local/share/applications/ 2>/dev/null || true', { stdio: 'ignore' });
+  } catch {
+    // xdg-mime may not be available; .desktop file is still written
+  }
+}
+
+module.exports = { registerUriScheme };