@kortix/agent-tunnel 0.13.41 → 0.13.43

package/dist/client-cli.js

@@ -123,9 +123,7 @@ class TunnelClient {
       }
     }
     this.cachedTunnelId = null;
-    throw new TunnelClientError(-1, `No tunnel connection found. The user needs to set up Agent Tunnel first:
-` + `1. Create a tunnel connection
-` + "2. Connect the local machine from the Kortix desktop app or run the tunnel connect command");
+    throw new TunnelClientError(-1, "No tunnel connection found. Connect this computer from the Kortix desktop app, " + "or run `npx @kortix/agent-tunnel connect`.");
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kortix/agent-tunnel",
-  "version": "0.13.41",
+  "version": "0.13.43",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kortix-ai/suna.git",

package/src/agent/access.test.ts

@@ -0,0 +1,164 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync, statSync, utimesSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  ACCESS_HOLD_MS,
+  accessFilePath,
+  accessRequestPath,
+  decideAccess,
+  keepAwakeCommand,
+  readAccess,
+  wakeDesktopApp,
+  writeAccess,
+  writeAccessRequest,
+} from './access';
+
+const homes: string[] = [];
+afterEach(() => {
+  for (const home of homes.splice(0)) rmSync(home, { recursive: true, force: true });
+});
+function tempHome(): string {
+  const home = mkdtempSync(join(tmpdir(), 'agent-tunnel-access-'));
+  homes.push(home);
+  return home;
+}
+
+describe('access.json', () => {
+  test('a machine without the file keeps working: it reads as always allowed', () => {
+    expect(readAccess(tempHome())).toEqual({ mode: 'always', grantedUntil: null, deniedUntil: null, keepAwake: false });
+  });
+
+  test('a damaged file fails closed to ask, never to always', () => {
+    const home = tempHome();
+    writeFileSync(accessFilePath(home), '{not json');
+    expect(readAccess(home).mode).toBe('ask');
+    writeFileSync(accessFilePath(home), JSON.stringify({ mode: 'sometimes' }));
+    expect(readAccess(home).mode).toBe('ask');
+  });
+
+  test('writes atomically and privately, and reads back', () => {
+    const home = join(tempHome(), 'nested');
+    const state = { mode: 'ask' as const, grantedUntil: '2030-01-01T00:00:00.000Z', deniedUntil: null, keepAwake: true };
+    writeAccess(state, home);
+    expect(readAccess(home)).toEqual(state);
+    expect(statSync(accessFilePath(home)).mode & 0o077).toBe(0);
+  });
+});
+
+describe('decideAccess', () => {
+  const now = Date.parse('2030-01-01T12:00:00.000Z');
+  const base = { grantedUntil: null, deniedUntil: null, keepAwake: false };
+
+  test('always runs, off refuses', () => {
+    expect(decideAccess({ ...base, mode: 'always' }, now)).toBe('run');
+    expect(decideAccess({ ...base, mode: 'off' }, now)).toBe('off');
+  });
+
+  test('ask runs inside a grant, fails fast while denied, otherwise asks', () => {
+    expect(decideAccess({ ...base, mode: 'ask', grantedUntil: '2030-01-01T12:30:00.000Z' }, now)).toBe('run');
+    expect(decideAccess({ ...base, mode: 'ask', grantedUntil: '2030-01-01T11:59:59.000Z' }, now)).toBe('ask');
+    expect(decideAccess({ ...base, mode: 'ask', deniedUntil: '2030-01-01T12:05:00.000Z' }, now)).toBe('denied');
+    expect(decideAccess({ ...base, mode: 'ask', deniedUntil: '2030-01-01T11:00:00.000Z' }, now)).toBe('ask');
+    expect(decideAccess({ ...base, mode: 'ask' }, now)).toBe('ask');
+  });
+
+  test('a grant that reaches more than 24 hours ahead is not honoured', () => {
+    const tooLong = new Date(now + 48 * 3_600_000).toISOString();
+    expect(decideAccess({ ...base, mode: 'ask', grantedUntil: tooLong }, now)).toBe('ask');
+    const day = new Date(now + 24 * 3_600_000).toISOString();
+    expect(decideAccess({ ...base, mode: 'ask', grantedUntil: day }, now)).toBe('run');
+  });
+
+  test('the hold is 20 seconds', () => {
+    expect(ACCESS_HOLD_MS).toBe(20_000);
+  });
+});
+
+describe('access request and desktop wake', () => {
+  test('the request file names the capability and method', () => {
+    const home = tempHome();
+    const request = writeAccessRequest({ capability: 'filesystem', method: 'fs.list' }, home);
+    const saved = JSON.parse(readFileSync(accessRequestPath(home), 'utf8'));
+    expect(saved).toEqual(request);
+    expect(saved).toMatchObject({ capability: 'filesystem', method: 'fs.list' });
+    expect(typeof saved.id).toBe('string');
+    expect(Date.parse(saved.requestedAt)).toBeGreaterThan(Date.now() - 5_000);
+  });
+
+  test('launches the recorded desktop command when the app is not running, as a GUI app, not as Node', async () => {
+    const home = tempHome();
+    const marker = join(home, 'launched.json');
+    const script = join(home, 'fake-app.js');
+    writeFileSync(
+      script,
+      `require('fs').writeFileSync(${JSON.stringify(marker)}, JSON.stringify({ args: process.argv.slice(2), runAsNode: process.env.ELECTRON_RUN_AS_NODE ?? null, home: process.env.AGENT_TUNNEL_HOME ?? null, url: process.env.KORTIX_DESKTOP_URL ?? null }));`,
+    );
+    writeFileSync(
+      join(home, 'desktop-app.json'),
+      JSON.stringify({ command: process.execPath, args: [script, '--from-agent'], pid: 2 ** 22 + 4321, env: { KORTIX_DESKTOP_URL: 'http://localhost:3000' } }),
+    );
+    const previous = { run: process.env.ELECTRON_RUN_AS_NODE, home: process.env.AGENT_TUNNEL_HOME };
+    process.env.ELECTRON_RUN_AS_NODE = '1';
+    process.env.AGENT_TUNNEL_HOME = home;
+    try {
+      expect(wakeDesktopApp(home)).toBe('launched');
+    } finally {
+      if (previous.run === undefined) delete process.env.ELECTRON_RUN_AS_NODE;
+      else process.env.ELECTRON_RUN_AS_NODE = previous.run;
+      if (previous.home === undefined) delete process.env.AGENT_TUNNEL_HOME;
+      else process.env.AGENT_TUNNEL_HOME = previous.home;
+    }
+    const deadline = Date.now() + 5_000;
+    while (!existsSync(marker) && Date.now() < deadline) await Bun.sleep(20);
+    expect(JSON.parse(readFileSync(marker, 'utf8'))).toEqual({
+      args: ['--from-agent'],
+      runAsNode: null,
+      home: null,
+      url: 'http://localhost:3000',
+    });
+  });
+
+  test('does not launch a second copy of a running app, and ignores a missing or relative command', () => {
+    const home = tempHome();
+    expect(wakeDesktopApp(home)).toBe('no-app');
+    writeFileSync(join(home, 'desktop-app.json'), JSON.stringify({ command: process.execPath, args: [], pid: process.pid }));
+    expect(wakeDesktopApp(home)).toBe('running');
+    writeFileSync(join(home, 'desktop-app.json'), JSON.stringify({ command: 'kortix', args: [], pid: 0 }));
+    expect(wakeDesktopApp(home)).toBe('no-app');
+  });
+
+  test('a recorded app that no longer exists is no-app, and a spawn failure never crashes the agent', async () => {
+    const home = tempHome();
+    writeFileSync(join(home, 'desktop-app.json'), JSON.stringify({ command: '/tmp/.mount_gone/kortix', args: [], pid: 0 }));
+    expect(wakeDesktopApp(home)).toBe('no-app');
+    // Exists but cannot execute: ENOENT/EACCES arrives later as an 'error' event.
+    const notExecutable = join(home, 'Kortix');
+    writeFileSync(notExecutable, 'not a program', { mode: 0o600 });
+    writeFileSync(join(home, 'desktop-app.json'), JSON.stringify({ command: notExecutable, args: [], pid: 0 }));
+    expect(wakeDesktopApp(home)).toBe('launched');
+    await Bun.sleep(200);
+  });
+
+  test('a live pid with a stale heartbeat is not the app (pid reuse after a reboot)', () => {
+    const home = tempHome();
+    const file = join(home, 'desktop-app.json');
+    writeFileSync(file, JSON.stringify({ command: process.execPath, args: ['-e', '0'], pid: process.pid }));
+    expect(wakeDesktopApp(home)).toBe('running');
+    const old = new Date(Date.now() - 120_000);
+    utimesSync(file, old, old);
+    expect(wakeDesktopApp(home)).toBe('launched');
+  });
+});
+
+describe('keep awake', () => {
+  test('macOS uses caffeinate tied to the agent pid; Linux uses systemd-inhibit; Windows is unsupported', () => {
+    expect(keepAwakeCommand('darwin', 42)).toEqual({ command: 'caffeinate', args: ['-s', '-w', '42'] });
+    expect(keepAwakeCommand('linux', 42)).toEqual({
+      command: 'systemd-inhibit',
+      args: ['--what=sleep', '--who=Kortix', '--why=Keep this computer reachable', '--mode=block', 'tail', '--pid=42', '-f', '/dev/null'],
+    });
+    expect(keepAwakeCommand('win32', 42)).toBeNull();
+  });
+});

package/src/agent/access.ts

@@ -0,0 +1,176 @@
+import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'fs';
+import { isAbsolute, join } from 'path';
+
+import { agentTunnelHome } from './service-paths';
+
+/**
+ * AnyDesk-style access control, enforced on this machine (contract v2 §A).
+ *
+ * `<home>/access.json` is the owner's standing answer. The desktop app writes
+ * it (grant, deny, mode); the agent reads it before every call. A machine
+ * without the file predates access control and stays `always`.
+ */
+export type AccessMode = 'ask' | 'always' | 'off';
+
+export interface AccessState {
+  mode: AccessMode;
+  grantedUntil: string | null;
+  deniedUntil: string | null;
+  keepAwake: boolean;
+}
+
+export interface AccessRequest {
+  id: string;
+  requestedAt: string;
+  capability: string;
+  method: string;
+}
+
+/** How long a call waits for the owner to answer the prompt. */
+export const ACCESS_HOLD_MS = 20_000;
+/** The desktop app touches desktop-app.json this often; older means it is gone (pid reuse). */
+export const DESKTOP_APP_HEARTBEAT_MS = 30_000;
+/** A grant never lasts longer than this, whatever the file says. */
+export const MAX_GRANT_MS = 24 * 3_600_000;
+
+const MODES: readonly AccessMode[] = ['ask', 'always', 'off'];
+const COMPAT: AccessState = { mode: 'always', grantedUntil: null, deniedUntil: null, keepAwake: false };
+
+export const accessFilePath = (home = agentTunnelHome()) => join(home, 'access.json');
+export const accessRequestPath = (home = agentTunnelHome()) => join(home, 'access-request.json');
+export const desktopAppPath = (home = agentTunnelHome()) => join(home, 'desktop-app.json');
+
+const isoOrNull = (value: unknown) => (typeof value === 'string' && !Number.isNaN(Date.parse(value)) ? value : null);
+
+/** Missing file = `always` (compat). A damaged file fails closed to `ask`. */
+export function readAccess(home = agentTunnelHome()): AccessState {
+  let raw: string;
+  try {
+    raw = readFileSync(accessFilePath(home), 'utf8');
+  } catch {
+    return { ...COMPAT };
+  }
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return {
+      mode: MODES.includes(parsed.mode as AccessMode) ? (parsed.mode as AccessMode) : 'ask',
+      grantedUntil: isoOrNull(parsed.grantedUntil),
+      deniedUntil: isoOrNull(parsed.deniedUntil),
+      keepAwake: parsed.keepAwake === true,
+    };
+  } catch {
+    return { mode: 'ask', grantedUntil: null, deniedUntil: null, keepAwake: false };
+  }
+}
+
+function writePrivateJson(file: string, home: string, value: unknown): void {
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  try { chmodSync(tmp, 0o600); } catch {}
+  renameSync(tmp, file);
+}
+
+export function writeAccess(state: AccessState, home = agentTunnelHome()): void {
+  writePrivateJson(accessFilePath(home), home, state);
+}
+
+export type AccessDecision = 'run' | 'off' | 'denied' | 'ask';
+
+export function decideAccess(state: AccessState, now = Date.now()): AccessDecision {
+  if (state.mode === 'always') return 'run';
+  if (state.mode === 'off') return 'off';
+  const denied = state.deniedUntil ? Date.parse(state.deniedUntil) : 0;
+  if (denied > now) return 'denied';
+  const granted = state.grantedUntil ? Date.parse(state.grantedUntil) : 0;
+  // ponytail: the cap is measured from now, not from when the grant was given;
+  // a hand-edited far-future grant still expires within 24 h of any check.
+  return granted > now && granted - now <= MAX_GRANT_MS ? 'run' : 'ask';
+}
+
+export function writeAccessRequest(
+  input: { capability: string; method: string },
+  home = agentTunnelHome(),
+): AccessRequest {
+  const request: AccessRequest = { id: randomUUID(), requestedAt: new Date().toISOString(), ...input };
+  writePrivateJson(accessRequestPath(home), home, request);
+  return request;
+}
+
+export function readAccessRequest(home = agentTunnelHome()): AccessRequest | null {
+  try {
+    const parsed = JSON.parse(readFileSync(accessRequestPath(home), 'utf8')) as AccessRequest;
+    return typeof parsed?.id === 'string' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function clearAccessRequest(id: string, home = agentTunnelHome()): void {
+  if (readAccessRequest(home)?.id === id) rmSync(accessRequestPath(home), { force: true });
+}
+
+function isAlive(pid: unknown): boolean {
+  if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM';
+  }
+}
+
+/**
+ * Starts the desktop app so it can show the access prompt. The app records how
+ * to launch it in `desktop-app.json` at startup and touches the file while it
+ * runs; a running app sees the request file itself, so nothing is launched
+ * twice. A live pid alone is not proof: after a reboot another process may
+ * hold it.
+ */
+export function wakeDesktopApp(home = agentTunnelHome(), now = Date.now()): 'running' | 'launched' | 'no-app' {
+  let app: { command?: unknown; args?: unknown; pid?: unknown; env?: unknown };
+  let touchedAt = 0;
+  try {
+    app = JSON.parse(readFileSync(desktopAppPath(home), 'utf8'));
+    touchedAt = statSync(desktopAppPath(home)).mtimeMs;
+  } catch {
+    return 'no-app';
+  }
+  if (isAlive(app.pid) && now - touchedAt < DESKTOP_APP_HEARTBEAT_MS) return 'running';
+  // A moved or uninstalled app, or a Linux AppImage mount that is gone.
+  if (typeof app.command !== 'string' || !isAbsolute(app.command) || !existsSync(app.command)) return 'no-app';
+  const args = Array.isArray(app.args) ? app.args.filter((arg): arg is string => typeof arg === 'string') : [];
+  const recorded = app.env && typeof app.env === 'object' ? (app.env as Record<string, unknown>) : {};
+  // The service runs the app binary as Node; the app itself must start as an app.
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  delete env.ELECTRON_RUN_AS_NODE;
+  delete env.AGENT_TUNNEL_HOME;
+  for (const [key, value] of Object.entries(recorded)) if (typeof value === 'string') env[key] = value;
+  try {
+    // Detached: its own process group, so a service restart never takes the app down.
+    const child = spawn(app.command, args, { detached: true, stdio: 'ignore', env });
+    // spawn reports ENOENT/EACCES as an async 'error' event; unheard, it kills the agent.
+    child.on('error', () => {});
+    child.unref();
+    return 'launched';
+  } catch {
+    return 'no-app';
+  }
+}
+
+/** The sleep blocker for `keepAwake`, tied to the agent's lifetime. Windows: unsupported. */
+export function keepAwakeCommand(
+  platform: NodeJS.Platform,
+  pid: number,
+): { command: string; args: string[] } | null {
+  if (platform === 'darwin') return { command: 'caffeinate', args: ['-s', '-w', String(pid)] };
+  if (platform === 'linux') {
+    return {
+      command: 'systemd-inhibit',
+      args: ['--what=sleep', '--who=Kortix', '--why=Keep this computer reachable', '--mode=block', 'tail', `--pid=${pid}`, '-f', '/dev/null'],
+    };
+  }
+  return null;
+}