@piecemaker-legal/piecemaker 1.0.0

package/scripts/release/prepare-desktop-app.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { loadProductConfig } from '../../shared/product-config.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '..', '..');
+const stageDir = path.join(rootDir, '.desktop-build', 'desktop-app');
+const product = loadProductConfig();
+
+const packageJson = JSON.parse(
+  await fs.readFile(path.join(rootDir, 'package.json'), 'utf8'),
+);
+
+function getElectronVersion() {
+  try {
+    return JSON.parse(
+      readFileSync(path.join(rootDir, 'node_modules', 'electron', 'package.json'), 'utf8'),
+    ).version;
+  } catch {
+    try {
+      return JSON.parse(
+        readFileSync(path.join(rootDir, 'package-lock.json'), 'utf8'),
+      ).packages['node_modules/electron'].version;
+    } catch {
+      throw new Error('Could not resolve an exact Electron version for desktop packaging.');
+    }
+  }
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyRequired(relativePath) {
+  const from = path.join(rootDir, relativePath);
+  const to = path.join(stageDir, relativePath);
+  if (!(await pathExists(from))) {
+    throw new Error(`Required desktop build input is missing: ${relativePath}`);
+  }
+  await fs.cp(from, to, { recursive: true });
+}
+
+async function copyIfExists(relativePath) {
+  const from = path.join(rootDir, relativePath);
+  if (!(await pathExists(from))) return false;
+  await fs.cp(from, path.join(stageDir, relativePath), { recursive: true });
+  return true;
+}
+
+async function copyNodeModule(packageName) {
+  const parts = packageName.split('/');
+  const source = path.join(rootDir, 'node_modules', ...parts);
+  if (!(await pathExists(source))) return false;
+
+  const target = path.join(stageDir, 'node_modules', ...parts);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  await fs.cp(source, target, { recursive: true });
+  return true;
+}
+
+function buildDesktopPackageJson(copiedOptionalDependencies) {
+  return {
+    name: `${packageJson.name}-desktop`,
+    version: packageJson.version,
+    productName: product.name,
+    description: `${product.name} desktop shell`,
+    author: packageJson.author,
+    license: packageJson.license,
+    type: 'module',
+    main: 'electron/main.js',
+    dependencies: packageJson.dependencies,
+    optionalDependencies: copiedOptionalDependencies,
+    build: {
+      appId: product.appId,
+      productName: product.name,
+      executableName: product.shortName,
+      asar: packageJson.build.asar,
+      artifactName: `${product.slug}-desktop-\${version}-\${os}-\${arch}.\${ext}`,
+      electronVersion: getElectronVersion(),
+      directories: {
+        output: '../../release/desktop',
+      },
+      extraMetadata: {
+        main: 'electron/main.js',
+      },
+      files: [
+        'electron/**',
+        'public/**',
+        'dist/**',
+        'dist-server/**',
+        'shared/**',
+        'product.config.json',
+        'node_modules/**',
+        'package.json',
+      ],
+      protocols: [{ name: product.name, schemes: [product.protocol] }],
+      mac: {
+        ...packageJson.build.mac,
+        extendInfo: {
+          ...packageJson.build.mac.extendInfo,
+          CFBundleName: product.name,
+          CFBundleDisplayName: product.name,
+          CFBundleURLTypes: [{ CFBundleURLName: product.name, CFBundleURLSchemes: [product.protocol] }],
+        },
+      },
+      win: packageJson.build.win,
+      nsis: packageJson.build.nsis,
+    },
+  };
+}
+
+await fs.rm(stageDir, { recursive: true, force: true });
+await fs.mkdir(stageDir, { recursive: true });
+
+await copyRequired('electron');
+await copyRequired('dist');
+await copyRequired('public');
+await copyRequired('product.config.json');
+await copyRequired('shared/product-config.mjs');
+
+const copiedOptionalDependencies = {};
+for (const [name, version] of Object.entries(packageJson.optionalDependencies || {})) {
+  if (await copyNodeModule(name)) {
+    copiedOptionalDependencies[name] = version;
+  }
+}
+
+for (const name of [
+  '@nut-tree-fork/default-clipboard-provider',
+  '@nut-tree-fork/libnut',
+  '@nut-tree-fork/provider-interfaces',
+  '@nut-tree-fork/shared',
+  'jimp',
+  'node-abort-controller',
+  'temp',
+]) {
+  await copyNodeModule(name);
+}
+
+await fs.writeFile(
+  path.join(stageDir, 'package.json'),
+  `${JSON.stringify(buildDesktopPackageJson(copiedOptionalDependencies), null, 2)}\n`,
+  'utf8',
+);
+
+// Install the full dependency tree (including transitive deps and native
+// bindings like better-sqlite3, bcrypt, node-pty) into the staged app.
+// electron-builder packages whatever is on disk here, so this must be a
+// complete, resolvable node_modules rather than a hand-picked subset.
+console.log('Installing desktop app dependencies (npm install --omit=dev)…');
+execFileSync('npm', ['install', '--omit=dev', '--no-audit', '--no-fund'], {
+  cwd: stageDir,
+  stdio: 'inherit',
+});
+
+console.log(`Prepared thin desktop app at ${path.relative(rootDir, stageDir)}`);
+if (Object.keys(copiedOptionalDependencies).length) {
+  console.log(`Pre-copied optional dependencies: ${Object.keys(copiedOptionalDependencies).join(', ')}`);
+}

package/server/index.ts

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+// Load environment variables before other imports execute.
+import './load-env.js';
+import fs, { promises as fsPromises } from 'fs';
+import path from 'path';
+import http from 'http';
+
+import express, { type NextFunction, type Request, type Response } from 'express';
+import cors from 'cors';
+
+import { AppError, findApplicationRoot, getApplicationDataRoot, getModuleDirectory, IS_PLATFORM, terminalTextStyles } from '@/shared/utils.js';
+import {
+    closeSessionsWatcher,
+    initializeSessionsWatcher,
+    providerRuntimeService,
+} from '@/modules/providers/index.js';
+import { createWebSocketServer } from '@/modules/websocket/index.js';
+
+import { getConnectableHost } from '../shared/networkHosts.js';
+
+import { createGitModule } from './modules/git/index.js';
+import {
+    authenticateToken,
+    authenticateWebSocket,
+    authRoutes,
+    validateApiKey,
+} from './modules/auth/index.js';
+import { taskmasterRoutes } from './modules/taskmaster/index.js';
+import { commandsRoutes } from './modules/commands/index.js';
+import { settingsRoutes } from './modules/settings/index.js';
+import { createSystemModule } from './modules/system/index.js';
+import { createAgentModule } from './modules/agent/index.js';
+import { createPieceMakerRouter } from './piecemaker/index.js';
+import projectModuleRoutes from './modules/projects/projects.routes.js';
+import notificationRoutes from './modules/notifications/notifications.routes.js';
+import { userRoutes } from './modules/user/index.js';
+import {
+    getPluginPort,
+    pluginsRoutes,
+    startEnabledPluginServers,
+    stopAllPlugins,
+} from './modules/plugins/index.js';
+import providerRoutes from './modules/providers/provider.routes.js';
+import { voiceRoutes } from './modules/voice/index.js';
+import {
+    closeScheduledMessageDispatcher,
+    initializeScheduledMessageDispatcher,
+    scheduledMessagesRoutes,
+} from './modules/scheduled-messages/index.js';
+import browserUseRoutes from './modules/browser-use/browser-use.routes.js';
+import { assetsRoutes } from './modules/assets/index.js';
+import { fileTreeRoutes } from './modules/file-tree/index.js';
+import { worktreesRoutes } from './modules/worktrees/index.js';
+import browserUseMcpRoutes from './modules/browser-use/browser-use-mcp.routes.js';
+import { browserUseService } from './modules/browser-use/browser-use.service.js';
+import { initializeDatabase, sessionsDb } from './modules/database/index.js';
+import { configureWebPush } from './modules/notifications/index.js';
+
+const __dirname = getModuleDirectory(import.meta.url);
+// The server source runs from /server, while the compiled output runs from /dist-server/server.
+// Resolving the app root once keeps every repo-level lookup below aligned across both layouts.
+const APP_ROOT = findApplicationRoot(__dirname);
+const installMode = fs.existsSync(path.join(APP_ROOT, '.git')) ? 'git' : 'npm';
+// Version of the code that is actually running, captured once at process
+// startup. This intentionally does NOT re-read package.json per request: after
+// an update replaces the files on disk, package.json reflects the NEW version
+// while this long-lived process still runs the OLD code. The frontend bundle is
+// rebuilt on update, so a mismatch between this value and the frontend's
+// build-time version means the server was updated but not restarted.
+const RUNNING_VERSION = (() => {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(APP_ROOT, 'package.json'), 'utf8')).version || null;
+    } catch {
+        return null;
+    }
+})();
+const systemRoutes = createSystemModule({
+    appRoot: APP_ROOT,
+    installMode,
+    isPlatform: IS_PLATFORM,
+});
+console.log('SERVER_PORT from env:', process.env.SERVER_PORT);
+
+const app = express();
+const server = http.createServer(app);
+const queryClaude = providerRuntimeService.getRunner('claude');
+const queryCursor = providerRuntimeService.getRunner('cursor');
+const queryCodex = providerRuntimeService.getRunner('codex');
+const queryOpenCode = providerRuntimeService.getRunner('opencode');
+const gitRoutes = createGitModule({
+    queryClaude,
+    queryCursor,
+});
+const agentRoutes = createAgentModule({
+    queryClaude,
+    queryCursor,
+    queryCodex,
+    queryOpenCode,
+});
+
+// Single WebSocket server that handles chat, shell, and plugin proxy paths.
+createWebSocketServer(server, {
+    verifyClient: {
+        isPlatform: IS_PLATFORM,
+        authenticateWebSocket,
+    },
+    chat: {
+        runtime: providerRuntimeService,
+    },
+    shell: {
+        resolveProviderSessionId: (sessionId, provider) => {
+            const dbSession = sessionsDb.getSessionById(sessionId);
+            if (dbSession) {
+                return dbSession.provider_session_id ?? null;
+            }
+
+            return null;
+        },
+    },
+    getPluginPort,
+});
+
+app.use(cors({ exposedHeaders: ['X-Refreshed-Token', 'X-Auth-Error'] }));
+app.use(express.json({
+    limit: '50mb',
+    type: (req) => {
+        // Skip multipart/form-data requests (for file uploads like images)
+        const contentType = req.headers['content-type'] || '';
+        if (contentType.includes('multipart/form-data')) {
+            return false;
+        }
+        return contentType.includes('json');
+    }
+}));
+app.use(express.urlencoded({ limit: '50mb', extended: true }));
+
+// Public health check endpoint (no authentication required)
+app.get('/health', (req, res) => {
+    res.json({
+        status: 'ok',
+        timestamp: new Date().toISOString(),
+        installMode,
+        version: RUNNING_VERSION
+    });
+});
+
+// Optional API key validation (if configured)
+app.use('/api', validateApiKey);
+
+// Authentication routes (public)
+app.use('/api/auth', authRoutes);
+
+// File Tree API Routes (protected)
+app.use('/api/file-tree', authenticateToken, fileTreeRoutes);
+
+// Projects API Routes (protected)
+app.use('/api/projects', authenticateToken, projectModuleRoutes);
+
+// Chat attachment upload/serving (global ~/.cloudcli/assets store, protected)
+app.use('/api/assets', authenticateToken, assetsRoutes);
+
+// Git API Routes (protected)
+app.use('/api/git', authenticateToken, gitRoutes);
+
+// Git worktree management (protected)
+app.use('/api/worktrees', authenticateToken, worktreesRoutes);
+
+// TaskMaster API Routes (protected)
+app.use('/api/taskmaster', authenticateToken, taskmasterRoutes);
+
+// Commands API Routes (protected)
+app.use('/api/commands', authenticateToken, commandsRoutes);
+
+// Settings API Routes (protected)
+app.use('/api/settings', authenticateToken, settingsRoutes);
+
+app.use('/api/system', authenticateToken, systemRoutes);
+
+app.use('/api/notifications', authenticateToken, notificationRoutes);
+
+// User API Routes (protected)
+app.use('/api/user', authenticateToken, userRoutes);
+
+// Plugins API Routes (protected)
+app.use('/api/plugins', authenticateToken, pluginsRoutes);
+
+// PieceMaker API Routes (protected)
+app.use('/api/piecemaker', authenticateToken, createPieceMakerRouter());
+
+// Browser MCP bridge API (local token protected)
+app.use('/api/browser-use-mcp', browserUseMcpRoutes);
+
+// Browser API Routes (protected)
+app.use('/api/browser-use', authenticateToken, browserUseRoutes);
+
+// Unified provider MCP routes (protected)
+app.use('/api/providers', authenticateToken, providerRoutes);
+app.use('/api/scheduled-messages', authenticateToken, scheduledMessagesRoutes);
+
+// Agent API Routes (uses API key authentication)
+app.use('/api/agent', agentRoutes);
+
+app.use('/api/voice', authenticateToken, voiceRoutes);
+
+// Serve public files (like api-docs.html)
+app.use(express.static(path.join(APP_ROOT, 'public')));
+
+// Static files served after API routes
+// Add cache control: HTML files should not be cached, but assets can be cached
+app.use(express.static(path.join(APP_ROOT, 'dist'), {
+    setHeaders: (res, filePath) => {
+        if (filePath.endsWith('.html')) {
+            // Prevent HTML caching to avoid service worker issues after builds
+            res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+            res.setHeader('Pragma', 'no-cache');
+            res.setHeader('Expires', '0');
+        } else if (filePath.match(/\.(js|css|woff2?|ttf|eot|svg|png|jpg|jpeg|gif|ico)$/)) {
+            // Cache static assets for 1 year (they have hashed names)
+            res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+        }
+    }
+}));
+
+// API Routes (protected)
+// /api/config endpoint removed - no longer needed
+// Frontend now uses window.location for WebSocket URLs
+
+// Chat uploads live under /api/assets (server/modules/assets), which stores
+// images and general files in the global ~/.cloudcli/assets folder.
+
+// Serve React app for all other routes (excluding static files)
+app.get('*', (req, res) => {
+    // Skip requests for static assets (files with extensions)
+    if (path.extname(req.path)) {
+        return res.status(404).send('Not found');
+    }
+
+    // Only serve index.html for HTML routes, not for static assets
+    // Static assets should already be handled by express.static middleware above
+    const indexPath = path.join(APP_ROOT, 'dist', 'index.html');
+
+    // Check if dist/index.html exists (production build available)
+    if (fs.existsSync(indexPath)) {
+        // Set no-cache headers for HTML to prevent service worker issues
+        res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+        res.setHeader('Pragma', 'no-cache');
+        res.setHeader('Expires', '0');
+        res.sendFile(indexPath);
+    } else {
+        // In development, redirect to Vite dev server only if dist doesn't exist
+        const redirectHost = getConnectableHost(req.hostname);
+        res.redirect(`${req.protocol}://${redirectHost}:${VITE_PORT}`);
+    }
+});
+
+// global error middleware must be last
+app.use((err: unknown, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof AppError) {
+    return res.status(err.statusCode).json({
+      success: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details,
+      },
+    });
+  }
+
+  console.error(err);
+
+  return res.status(500).json({
+    success: false,
+    error: {
+      code: 'INTERNAL_ERROR',
+      message: 'Internal server error',
+    },
+  });
+});
+
+const SERVER_PORT = Number.parseInt(process.env.SERVER_PORT || '3001', 10);
+const HOST = process.env.HOST || '0.0.0.0';
+const DISPLAY_HOST = getConnectableHost(HOST);
+const VITE_PORT = process.env.VITE_PORT || 5173;
+const LOCAL_SERVER_MARKER_PATH = path.join(getApplicationDataRoot(), 'local-server.json');
+
+function getErrorCode(error: unknown): string | undefined {
+    if (typeof error !== 'object' || error === null || !('code' in error)) {
+        return undefined;
+    }
+    return String(error.code);
+}
+
+function getErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+async function writeLocalServerMarker() {
+    const marker = {
+        pid: process.pid,
+        host: HOST,
+        port: Number.parseInt(String(SERVER_PORT), 10),
+        url: `http://${DISPLAY_HOST}:${SERVER_PORT}`,
+        installMode,
+        appRoot: APP_ROOT,
+        updatedAt: new Date().toISOString(),
+    };
+
+    await fsPromises.mkdir(path.dirname(LOCAL_SERVER_MARKER_PATH), { recursive: true });
+    await fsPromises.writeFile(LOCAL_SERVER_MARKER_PATH, JSON.stringify(marker, null, 2), 'utf8');
+}
+
+async function removeLocalServerMarker() {
+    try {
+        const raw = await fsPromises.readFile(LOCAL_SERVER_MARKER_PATH, 'utf8');
+        const marker = JSON.parse(raw);
+        if (marker.pid && marker.pid !== process.pid) return;
+    } catch (error) {
+        if (getErrorCode(error) === 'ENOENT') return;
+    }
+
+    try {
+        await fsPromises.unlink(LOCAL_SERVER_MARKER_PATH);
+    } catch (error) {
+        if (getErrorCode(error) !== 'ENOENT') {
+            console.warn('[WARN] Could not remove local server marker:', getErrorMessage(error));
+        }
+    }
+}
+
+// Initialize database and start server
+async function startServer() {
+    try {
+        // Initialize authentication database
+        await initializeDatabase();
+
+        // Configure Web Push (VAPID keys)
+        configureWebPush();
+
+        // Check if running in production mode (dist folder exists)
+        const distIndexPath = path.join(APP_ROOT, 'dist', 'index.html');
+        const isProduction = fs.existsSync(distIndexPath);
+
+        // Log Claude implementation mode
+        console.log(`${terminalTextStyles.info('[INFO]')} Using Claude Agents SDK for Claude integration`);
+        console.log('');
+
+        if (isProduction) {
+            console.log(`${terminalTextStyles.info('[INFO]')} To run in production mode, go to http://${DISPLAY_HOST}:${SERVER_PORT}`);
+        }
+
+        console.log(`${terminalTextStyles.info('[INFO]')} To run in development mode with hot-module replacement, go to http://${DISPLAY_HOST}:${VITE_PORT}`);
+   
+        server.listen(SERVER_PORT, HOST, async () => {
+            const appInstallPath = APP_ROOT;
+            await writeLocalServerMarker().catch((error) => {
+                console.warn('[WARN] Could not write local server marker:', error.message);
+            });
+
+            console.log('');
+            console.log(terminalTextStyles.dim('═'.repeat(63)));
+            console.log(`  ${terminalTextStyles.bright('CloudCLI Server - Ready')}`);
+            console.log(terminalTextStyles.dim('═'.repeat(63)));
+            console.log('');
+            console.log(`${terminalTextStyles.info('[INFO]')} Server URL:  ${terminalTextStyles.bright('http://' + DISPLAY_HOST + ':' + SERVER_PORT)}`);
+            console.log(`${terminalTextStyles.info('[INFO]')} Installed at: ${terminalTextStyles.dim(appInstallPath)}`);
+            console.log(`${terminalTextStyles.tip('[TIP]')}  Run "cloudcli status" for full configuration details`);
+            console.log('');
+
+            // Start watching the projects folder for changes
+            await initializeSessionsWatcher();
+            // Sends anything that came due while the server was not running,
+            // then keeps polling.
+            initializeScheduledMessageDispatcher(providerRuntimeService);
+
+            // Start server-side plugin processes for enabled plugins
+            startEnabledPluginServers().catch(err => {
+                console.error('[Plugins] Error during startup:', err.message);
+            });
+        });
+
+        await closeSessionsWatcher();
+        closeScheduledMessageDispatcher();
+        // Clean up plugin processes on shutdown
+        const shutdownRuntimeServices = async () => {
+            try {
+                await browserUseService.stopAllSessions();
+            } catch (err) {
+                console.error('[Browser] Error stopping sessions during shutdown:', getErrorMessage(err));
+            }
+            try {
+                await stopAllPlugins();
+            } catch (err) {
+                console.error('[Plugins] Error stopping plugins during shutdown:', getErrorMessage(err));
+            }
+            try {
+                await removeLocalServerMarker();
+            } catch (err) {
+                console.error('[Local Server] Error removing server marker during shutdown:', getErrorMessage(err));
+            }
+            process.exit(0);
+        };
+        process.on('SIGTERM', () => void shutdownRuntimeServices());
+        process.on('SIGINT', () => void shutdownRuntimeServices());
+    } catch (error) {
+        console.error('[ERROR] Failed to start server:', error);
+        process.exit(1);
+    }
+}
+
+startServer();

package/server/load-env.ts

@@ -0,0 +1,48 @@
+// Load environment variables from .env before other imports execute.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+// This bootstrap cannot import shared/utils.ts: that module reads environment
+// defaults during evaluation, before this file has loaded `.env`.
+function getBootstrapApplicationRoot(importMetaUrl: string) {
+  const moduleDirectory = path.dirname(fileURLToPath(importMetaUrl));
+  let serverRoot = moduleDirectory;
+  while (path.basename(serverRoot) !== 'server') {
+    const parent = path.dirname(serverRoot);
+    if (parent === serverRoot) throw new Error('Could not resolve server root');
+    serverRoot = parent;
+  }
+  const parent = path.dirname(serverRoot);
+  return path.basename(parent) === 'dist-server' ? path.dirname(parent) : parent;
+}
+
+// Resolve the repo/app root via the nearest /server folder so this file keeps finding the
+// same top-level .env file from both /server/load-env.ts and /dist-server/server/load-env.js.
+const APP_ROOT = getBootstrapApplicationRoot(import.meta.url);
+
+try {
+  const envPath = path.join(APP_ROOT, '.env');
+  const envFile = fs.readFileSync(envPath, 'utf8');
+  envFile.split('\n').forEach(line => {
+    const trimmedLine = line.trim();
+    if (trimmedLine && !trimmedLine.startsWith('#')) {
+      const [key, ...valueParts] = trimmedLine.split('=');
+      if (key && valueParts.length > 0 && !process.env[key]) {
+        process.env[key] = valueParts.join('=').trim();
+      }
+    }
+  });
+} catch (e: any) {
+  console.error('No .env file found or error reading it:', e.message);
+}
+
+// Keep the default database in a stable user-level location so rebuilding dist-server
+// never changes where the backend stores auth.db when DATABASE_PATH is not set explicitly.
+const applicationDataRoot = process.env.CLOUDCLI_HOME || path.join(os.homedir(), '.cloudcli');
+const DEFAULT_DATABASE_PATH = path.join(applicationDataRoot, 'auth.db');
+
+if (!process.env.DATABASE_PATH) {
+  process.env.DATABASE_PATH = DEFAULT_DATABASE_PATH;
+}

package/server/modules/agent/agent.module.ts

@@ -0,0 +1,52 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import os from 'node:os';
+
+import { Octokit } from '@octokit/rest';
+import spawn from 'cross-spawn';
+
+import {
+  apiKeysDb,
+  githubTokensDb,
+  projectsDb,
+  userDb,
+} from '@/modules/database/index.js';
+import { providerModelsService } from '@/modules/providers/index.js';
+import { IS_PLATFORM } from '@/shared/utils.js';
+
+import { createAgentRouter } from './agent.routes.js';
+
+type AgentExternalDependencies = Pick<
+  Parameters<typeof createAgentRouter>[0],
+  'queryClaude' | 'queryCursor' | 'queryCodex' | 'queryOpenCode'
+>;
+
+/**
+ * Assembles the production Agent router while accepting provider runners from
+ * the centralized provider runtime service.
+ */
+export function createAgentModule(externalDependencies: AgentExternalDependencies) {
+  return createAgentRouter({
+    fileSystem: fs,
+    crypto,
+    homeDirectory: os.homedir,
+    spawnProcess: spawn,
+    platformMode: IS_PLATFORM,
+    users: {
+      getFirstUser: () => userDb.getFirstUser(),
+    },
+    apiKeys: {
+      validateApiKey: (apiKey) => apiKeysDb.validateApiKey(apiKey),
+    },
+    githubTokens: {
+      getActiveGithubToken: (userId) => githubTokensDb.getActiveGithubToken(userId),
+    },
+    projects: {
+      createProjectPath: (projectPath, customName) =>
+        projectsDb.createProjectPath(projectPath, customName),
+    },
+    models: providerModelsService,
+    GithubClient: Octokit,
+    ...externalDependencies,
+  });
+}