@buildifyx/desktop-agent 0.1.0

package/README.md

@@ -0,0 +1,337 @@
+# Buildifyx Desktop Agent
+
+Buildifyx Desktop Agent (`bdxa`) connects a user-controlled computer to Buildifyx Cloud so ChatGPT can use approved MCP tools on that machine.
+
+Default cloud:
+
+```text
+https://bdxa.buildifyx.com
+```
+
+Agent connection:
+
+```text
+wss://bdxa.buildifyx.com/agent
+```
+
+Current package version:
+
+```text
+@buildifyx/desktop-agent@0.1.0
+```
+
+## Install
+
+```bash
+npm install -g @buildifyx/desktop-agent
+```
+
+Check the installation:
+
+```bash
+bdxa --version
+bdxa doctor
+```
+
+## 1. Login
+
+Ask your Buildifyx administrator for a login token, then run:
+
+```bash
+bdxa login
+```
+
+Paste the token when prompted.
+
+For internal automation you can also use:
+
+```bash
+bdxa login --token "$BUILDFIYX_LOGIN_TOKEN"
+```
+
+Using `--token` directly may expose the token through shell history, so interactive login is preferred.
+
+A successful login registers this computer as a device and stores its device credential locally in:
+
+```text
+~/.buildifyx/credentials.json
+```
+
+On macOS and Linux the agent attempts to keep this file readable only by the current user.
+
+Login tokens are intended to be short-lived or one-time credentials. The device credential returned by Buildifyx Cloud is what `bdxa` uses for subsequent cloud connections.
+
+## 2. Check login status
+
+```bash
+bdxa status
+```
+
+The command shows the configured cloud, device ID, account when available, credential expiry, and whether Buildifyx Cloud currently accepts the device credential.
+
+## 3. Connect the device
+
+Run `bdxa` from the directory you want ChatGPT to work in:
+
+```bash
+cd ~/projects/my-project
+bdxa
+```
+
+Or choose the workspace explicitly:
+
+```bash
+bdxa --root ~/projects/my-project
+```
+
+`bdxa` now connects outward to Buildifyx Cloud. The computer does not need to expose a public port for normal cloud operation.
+
+Connection path:
+
+```text
+ChatGPT
+   ↓
+Buildifyx Cloud
+   ↓
+Secure WebSocket
+   ↓
+bdxa
+   ↓
+Local permissions
+   ↓
+Your files and commands
+```
+
+The local agent remains the final permission authority. A cloud request still has to pass the permission policy running on the user's computer before a tool can execute.
+
+## Cloud protocol
+
+When the agent connects, it authenticates the WebSocket handshake using the device credential and sends a `device.ready` message containing the agent version, device information, and MCP tool manifest hash.
+
+The cloud can send a tool request such as:
+
+```json
+{
+  "type": "tool.call",
+  "requestId": "req_123",
+  "tool": "read_file",
+  "arguments": {
+    "path": "README.md"
+  }
+}
+```
+
+The agent routes it through the same local runtime and permission system used by local MCP mode.
+
+Successful requests return:
+
+```json
+{
+  "type": "tool.result",
+  "requestId": "req_123",
+  "result": {}
+}
+```
+
+Failed requests return:
+
+```json
+{
+  "type": "tool.error",
+  "requestId": "req_123",
+  "error": {
+    "code": "PERMISSION_DENIED",
+    "message": "Permission denied"
+  }
+}
+```
+
+The agent also sends heartbeats and reconnects automatically with backoff when the cloud connection drops.
+
+## Permissions
+
+The default Auto profile allows normal reads, writes, and approved developer commands while asking before dangerous operations or access outside allowed roots.
+
+Available profiles are:
+
+```text
+Auto
+Read only
+Full access
+Custom
+```
+
+Full access is powerful and is not an operating-system sandbox. Commands run with the permissions of the operating-system user running `bdxa`.
+
+### ASK requests
+
+When a rule resolves to `ASK`, the cloud request waits while the TUI displays an approval prompt:
+
+```text
+APPROVAL REQUIRED
+
+docker ps
+
+> Allow once
+  Always allow this request
+  Deny
+```
+
+The tool executes only after local approval.
+
+If the agent is running with `--no-tui`, an ASK request returns a confirmation-required error instead of waiting indefinitely.
+
+### Custom command rules
+
+Command rules match executable name plus argument prefix.
+
+For example:
+
+```text
+docker       ALLOW
+docker ps    ASK
+```
+
+The more specific rule wins, so `docker ps` asks even though the broader `docker` rule allows other Docker commands.
+
+Commands are executed without a shell.
+
+## Allowed roots
+
+The primary root is the directory supplied through `--root`, or the current working directory when omitted.
+
+Additional roots can be managed from the TUI.
+
+Requests outside configured roots follow the `outsideRoot` permission setting and may be allowed, denied, or require approval.
+
+`.git` internals remain protected by the local path security layer.
+
+## MCP tools
+
+The current agent exposes:
+
+```text
+get_system_info
+list_directory
+read_file
+write_file
+edit_file
+run_command
+```
+
+The agent sends its tool count and schema hash to Buildifyx Cloud when connecting so the cloud can detect which tool definition set the device is running.
+
+## TUI controls
+
+Main screen:
+
+```text
+↑↓       Select activity
+P        Permissions
+R        Allowed roots
+C        Command rules
+T        MCP tools
+L        Audit log information
+? / H    Help
+Q        Back
+Ctrl+C   Quit
+```
+
+Approval screen:
+
+```text
+↑↓       Select decision
+Enter    Confirm
+Q        Deny / Back
+Ctrl+C   Quit
+```
+
+## Audit log
+
+Local activity is recorded at:
+
+```text
+~/.buildifyx/audit.log
+```
+
+The audit log records tool names, permission decisions, paths, commands, status, and timing information. Write/edit payload contents are redacted rather than intentionally duplicated into the audit log.
+
+## Logout
+
+```bash
+bdxa logout
+```
+
+The agent asks Buildifyx Cloud to revoke the device credential and then removes the local credential file.
+
+If the cloud cannot be reached, `bdxa` still removes the local credential and reports that remote revocation failed.
+
+## Update
+
+```bash
+bdxa update
+```
+
+Then restart the agent:
+
+```bash
+bdxa
+```
+
+## Useful commands
+
+```bash
+bdxa login
+bdxa status
+bdxa --root ~/projects
+bdxa connect --root ~/projects
+bdxa logout
+bdxa doctor
+bdxa update
+bdxa --version
+```
+
+## Local MCP compatibility mode
+
+For local development or debugging, the previous localhost MCP server remains available explicitly:
+
+```bash
+bdxa local --root ~/projects --port 3333
+```
+
+Normal users should use cloud mode by running `bdxa` without the `local` command.
+
+## Troubleshooting
+
+### `Not logged in`
+
+Run:
+
+```bash
+bdxa login
+```
+
+### `Device credential has expired`
+
+Request a new login token from your administrator and run `bdxa login` again.
+
+### ASK does not execute immediately
+
+This is expected. The request is waiting for a local approval in the TUI.
+
+### Cloud is temporarily unavailable
+
+Leave `bdxa` running. The cloud client automatically retries with exponential backoff.
+
+### Need to inspect the current tools
+
+Press `T` in the TUI to see the current tool count and schema hash.
+
+## Security notes
+
+- Buildifyx Cloud does not replace the local permission system.
+- Device authentication uses a dedicated device credential, separate from the login token.
+- Command execution uses direct executable invocation rather than shell command strings.
+- File access is constrained by configured roots and path checks.
+- Full access is not an OS sandbox.
+- Keep `~/.buildifyx/credentials.json` private.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@buildifyx/desktop-agent",
+  "version": "0.1.0",
+  "description": "Buildifyx cloud-connected desktop agent for securely running MCP tools on a user-controlled machine.",
+  "type": "module",
+  "bin": {
+    "bdxa": "./src/cli.js",
+    "buildifyx-agent": "./src/cli.js"
+  },
+  "scripts": {
+    "start": "node ./src/cli.js",
+    "doctor": "node ./src/cli.js doctor",
+    "check": "node ./scripts/check.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "ink": "^6.8.0",
+    "react": "^19.2.8",
+    "ws": "^8.21.3",
+    "zod": "4.5.4"
+  },
+  "license": "MIT"
+}

package/src/audit/logger.js

@@ -0,0 +1,30 @@
+import { mkdir, appendFile } from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+export function defaultAuditPath() {
+  return path.join(os.homedir(), '.buildifyx', 'audit.log');
+}
+
+export function createAuditLogger({ eventBus, filePath = defaultAuditPath() }) {
+  let unsubscribe;
+
+  async function writeEvent(event) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await appendFile(filePath, `${JSON.stringify(event)}\n`, 'utf8');
+  }
+
+  function start() {
+    if (unsubscribe) return;
+    unsubscribe = eventBus.subscribe((event) => {
+      void writeEvent(event).catch(() => undefined);
+    });
+  }
+
+  function stop() {
+    unsubscribe?.();
+    unsubscribe = undefined;
+  }
+
+  return { start, stop, filePath };
+}

package/src/cli/commands/cloud.js

@@ -0,0 +1,89 @@
+import os from 'node:os';
+import process from 'node:process';
+import { createAuditLogger } from '../../audit/logger.js';
+import { createRuntime } from '../../core/runtime.js';
+import { createPolicyManager } from '../../permissions/manager.js';
+import { loadPolicy } from '../../permissions/store.js';
+import { startTui } from '../../tui/index.js';
+import { createToolManifest } from '../../transport/mcp/tools/registry.js';
+import { inspectToolManifest } from '../../transport/mcp/manifest-store.js';
+import { createCloudAgent } from '../../transport/cloud.js';
+import { isCredentialExpired, loadCredentials } from '../../utils/credentials.js';
+import { getPackageMetadata } from '../../version.js';
+import { getOption, hasFlag, resolveRoot } from '../options.js';
+
+export async function runCloud(args) {
+  const credentials = await loadCredentials();
+  if (!credentials) throw new Error('Not logged in. Run `bdxa login` first.');
+  if (isCredentialExpired(credentials)) throw new Error('Device credential has expired. Run `bdxa login` again.');
+
+  const root = await resolveRoot(getOption(args, '--root', process.cwd()));
+  const fullAccess = hasFlag(args, '--full-access');
+  const useTui = process.stdin.isTTY && process.stdout.isTTY && !hasFlag(args, '--no-tui');
+  const metadata = await getPackageMetadata();
+  const policy = await loadPolicy();
+  const policyManager = createPolicyManager(policy);
+  const runtime = createRuntime({ root, fullAccess, policyManager, interactive: useTui });
+  const audit = createAuditLogger({ eventBus: runtime.eventBus });
+  const manifest = createToolManifest({ fullAccess });
+  const manifestState = await inspectToolManifest(manifest);
+  audit.start();
+
+  const cloud = createCloudAgent({
+    cloudUrl: credentials.cloudUrl,
+    credentials,
+    runtime,
+    manifest,
+    version: metadata.version,
+    deviceInfo: {
+      name: credentials.deviceName ?? os.hostname(),
+      hostname: os.hostname(),
+      platform: process.platform,
+      arch: process.arch
+    },
+    eventBus: runtime.eventBus
+  });
+
+  let closing = false;
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    audit.stop();
+    await cloud.stop();
+  };
+  const onSignal = async () => {
+    await shutdown();
+    process.exit(0);
+  };
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  cloud.connect();
+
+  if (!useTui) {
+    console.log(`Cloud:   ${cloud.endpoint}`);
+    console.log(`Device:  ${credentials.deviceName ?? credentials.deviceId}`);
+    console.log(`Root:    ${root}`);
+    console.log(`Audit:   ${audit.filePath}`);
+    console.log(`Tools:   ${manifest.count} (${manifest.shortHash})${manifestState.changed ? ' CHANGED' : ''}`);
+    console.log('TUI:     disabled (Ask permissions return CONFIRMATION_REQUIRED)');
+    return;
+  }
+
+  const tui = startTui({
+    eventBus: runtime.eventBus,
+    approvalQueue: runtime.approvalQueue,
+    policyManager,
+    version: metadata.version,
+    root,
+    mode: fullAccess ? 'CLOUD · FULL ACCESS (not sandboxed)' : 'CLOUD · restricted',
+    auditPath: audit.filePath,
+    toolManifest: manifest,
+    toolManifestState: manifestState,
+    toolsUrl: credentials.cloudUrl,
+    onQuit: shutdown
+  });
+
+  await tui.waitUntilExit();
+  await shutdown();
+}

package/src/cli/commands/doctor.js

@@ -0,0 +1,18 @@
+import process from 'node:process';
+import { getOption, resolveRoot } from '../options.js';
+import { checkForUpdate, getPackageMetadata } from '../../version.js';
+
+export async function runDoctor(args) {
+  const root = await resolveRoot(getOption(args, '--root', process.cwd()));
+  const metadata = await getPackageMetadata();
+  const versionStatus = await checkForUpdate(metadata.name, metadata.version);
+
+  console.log('Buildifyx Desktop Agent doctor');
+  console.log(`Node:     ${process.version}`);
+  console.log(`Platform: ${process.platform} ${process.arch}`);
+  console.log(`Root:     ${root}`);
+  console.log(`Version:  ${metadata.version}${versionStatus.updateAvailable && versionStatus.latestVersion ? ` (latest: ${versionStatus.latestVersion})` : ''}`);
+  if (versionStatus.error) console.log(`Registry: unavailable (${versionStatus.error})`);
+  else if (!versionStatus.updateAvailable) console.log('Registry: latest');
+  console.log('Status:   OK');
+}

package/src/cli/commands/login.js

@@ -0,0 +1,59 @@
+import os from 'node:os';
+import process from 'node:process';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { loginDevice, DEFAULT_CLOUD_ORIGIN } from '../../transport/cloud.js';
+import { saveCredentials } from '../../utils/credentials.js';
+import { getPackageMetadata } from '../../version.js';
+import { getOption } from '../options.js';
+
+async function promptToken() {
+  if (!process.stdin.isTTY) throw new Error('Login token is required. Use --token or run bdxa login in a terminal.');
+  const rl = readline.createInterface({ input, output });
+  try {
+    return (await rl.question('Login token: ')).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runLogin(args) {
+  const cloudUrl = getOption(args, '--cloud', DEFAULT_CLOUD_ORIGIN);
+  const token = getOption(args, '--token', null) ?? await promptToken();
+  if (!token) throw new Error('Login token cannot be empty.');
+
+  const metadata = await getPackageMetadata();
+  console.log(`Connecting to ${cloudUrl}...`);
+  const response = await loginDevice({
+    cloudUrl,
+    token,
+    device: {
+      name: os.hostname(),
+      hostname: os.hostname(),
+      platform: process.platform,
+      arch: process.arch,
+      agentVersion: metadata.version
+    }
+  });
+
+  const deviceToken = response?.credential?.token ?? response?.deviceToken;
+  const deviceId = response?.device?.id ?? response?.deviceId;
+  const expiresAt = response?.credential?.expiresAt ?? response?.expiresAt ?? null;
+  if (!deviceToken || !deviceId) throw new Error('Cloud login response did not include a device credential.');
+
+  await saveCredentials({
+    cloudUrl,
+    deviceId,
+    deviceName: response?.device?.name ?? os.hostname(),
+    account: response?.user?.email ?? response?.account ?? null,
+    deviceToken,
+    expiresAt,
+    createdAt: new Date().toISOString()
+  });
+
+  console.log('✓ Authentication successful');
+  console.log(`Device:  ${response?.device?.name ?? os.hostname()}`);
+  if (response?.user?.email) console.log(`Account: ${response.user.email}`);
+  if (expiresAt) console.log(`Expires: ${expiresAt}`);
+  console.log('Run `bdxa` to connect this device to Buildifyx Cloud.');
+}

package/src/cli/commands/logout.js

@@ -0,0 +1,20 @@
+import { logoutDevice } from '../../transport/cloud.js';
+import { clearCredentials, loadCredentials } from '../../utils/credentials.js';
+
+export async function runLogout() {
+  const credentials = await loadCredentials();
+  if (!credentials) {
+    console.log('Not logged in.');
+    return;
+  }
+
+  try {
+    await logoutDevice({ cloudUrl: credentials.cloudUrl, deviceToken: credentials.deviceToken });
+  } catch (error) {
+    console.log(`Cloud revoke failed: ${error.message}`);
+    console.log('Removing local credentials anyway.');
+  }
+
+  await clearCredentials();
+  console.log('✓ Logged out');
+}

package/src/cli/commands/remote.js

@@ -0,0 +1,64 @@
+import process from 'node:process';
+import { createAuditLogger } from '../../audit/logger.js';
+import { createRuntime } from '../../core/runtime.js';
+import { createPolicyManager } from '../../permissions/manager.js';
+import { loadPolicy } from '../../permissions/store.js';
+import { startTui } from '../../tui/index.js';
+import { startMcpServer } from '../../transport/mcp/server.js';
+import { getOption, hasFlag, parsePort, resolveRoot } from '../options.js';
+
+export async function runRemote(args) {
+  const root = await resolveRoot(getOption(args, '--root', process.cwd()));
+  const port = parsePort(getOption(args, '--port', '3333'));
+  const fullAccess = hasFlag(args, '--full-access');
+  const useTui = process.stdin.isTTY && process.stdout.isTTY && !hasFlag(args, '--no-tui');
+
+  const policy = await loadPolicy();
+  const policyManager = createPolicyManager(policy);
+  const runtime = createRuntime({ root, fullAccess, policyManager, interactive: useTui });
+  const audit = createAuditLogger({ eventBus: runtime.eventBus });
+  audit.start();
+
+  const server = await startMcpServer({ root, port, fullAccess, runtime, quiet: useTui });
+  let closing = false;
+
+  const shutdown = async () => {
+    if (closing) return;
+    closing = true;
+    audit.stop();
+    await server.close();
+  };
+
+  const onSignal = async () => {
+    await shutdown();
+    process.exit(0);
+  };
+
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  if (!useTui) {
+    console.log(`Audit:   ${audit.filePath}`);
+    console.log(`Tools:   ${server.manifest.count} (${server.manifest.shortHash})${server.manifestState.changed ? ' CHANGED' : ''}`);
+    console.log(`Tools:   ${server.toolsUrl}`);
+    console.log('TUI:     disabled (Ask permissions return CONFIRMATION_REQUIRED)');
+    return;
+  }
+
+  const tui = startTui({
+    eventBus: runtime.eventBus,
+    approvalQueue: runtime.approvalQueue,
+    policyManager,
+    version: server.version,
+    root,
+    mode: fullAccess ? 'FULL ACCESS (not sandboxed)' : 'restricted',
+    auditPath: audit.filePath,
+    toolManifest: server.manifest,
+    toolManifestState: server.manifestState,
+    toolsUrl: server.toolsUrl,
+    onQuit: shutdown
+  });
+
+  await tui.waitUntilExit();
+  await shutdown();
+}

package/src/cli/commands/status.js

@@ -0,0 +1,32 @@
+import { getDeviceMe } from '../../transport/cloud.js';
+import { isCredentialExpired, loadCredentials } from '../../utils/credentials.js';
+
+export async function runStatus() {
+  const credentials = await loadCredentials();
+  console.log('Buildifyx Desktop Agent status');
+
+  if (!credentials) {
+    console.log('Authentication: not logged in');
+    console.log('Run `bdxa login`.');
+    return;
+  }
+
+  console.log(`Cloud:          ${credentials.cloudUrl}`);
+  console.log(`Device:         ${credentials.deviceName ?? credentials.deviceId}`);
+  console.log(`Device ID:      ${credentials.deviceId}`);
+  if (credentials.account) console.log(`Account:        ${credentials.account}`);
+  if (credentials.expiresAt) console.log(`Expires:        ${credentials.expiresAt}`);
+
+  if (isCredentialExpired(credentials)) {
+    console.log('Authentication: expired');
+    return;
+  }
+
+  try {
+    const remote = await getDeviceMe({ cloudUrl: credentials.cloudUrl, deviceToken: credentials.deviceToken });
+    console.log('Authentication: valid');
+    if (remote?.device?.status) console.log(`Cloud status:   ${remote.device.status}`);
+  } catch (error) {
+    console.log(`Authentication: unavailable (${error.message})`);
+  }
+}