@agentconnect/host 0.2.0

package/dist/host.js

@@ -0,0 +1,920 @@
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import { spawn } from 'child_process';
+import fs from 'fs';
+import { promises as fsp } from 'fs';
+import net from 'net';
+import path from 'path';
+import { listModels, listRecentModels, providers, resolveProviderForModel } from './providers/index.js';
+import { debugLog } from './providers/utils.js';
+import { createObservedTracker } from './observed.js';
+function send(socket, payload) {
+    socket.send(JSON.stringify(payload));
+}
+function buildProviderList(statuses) {
+    return Object.values(providers).map((provider) => {
+        const info = statuses[provider.id] || {};
+        return {
+            id: provider.id,
+            name: provider.name,
+            installed: info.installed ?? false,
+            loggedIn: info.loggedIn ?? false,
+            version: info.version,
+            updateAvailable: info.updateAvailable,
+            latestVersion: info.latestVersion,
+            updateCheckedAt: info.updateCheckedAt,
+            updateSource: info.updateSource,
+            updateCommand: info.updateCommand,
+            updateMessage: info.updateMessage,
+            updateInProgress: info.updateInProgress,
+        };
+    });
+}
+function resolveLoginExperience(mode) {
+    const raw = process.env.AGENTCONNECT_LOGIN_EXPERIENCE ||
+        process.env.AGENTCONNECT_CLAUDE_LOGIN_EXPERIENCE;
+    if (raw) {
+        const normalized = raw.trim().toLowerCase();
+        if (normalized === 'terminal' || normalized === 'manual')
+            return 'terminal';
+        if (normalized === 'embedded' || normalized === 'pty')
+            return 'embedded';
+    }
+    return mode === 'dev' ? 'terminal' : 'embedded';
+}
+function createHostRuntime(options) {
+    const mode = options.mode ?? options.modeDefault;
+    process.env.AGENTCONNECT_HOST_MODE ||= mode;
+    const basePath = options.basePath || process.cwd();
+    const manifest = options.appManifest ?? readManifest(basePath);
+    const appId = manifest?.id || (mode === 'dev' ? 'agentconnect-dev-app' : 'agentconnect-app');
+    const requestedCapabilities = Array.isArray(manifest?.capabilities) ? manifest.capabilities : [];
+    const observedTracker = createObservedTracker({
+        basePath,
+        appId,
+        requested: requestedCapabilities,
+    });
+    const sessions = new Map();
+    const activeRuns = new Map();
+    const updatingProviders = new Map();
+    const processTable = new Map();
+    const backendState = new Map();
+    const statusCache = new Map();
+    const statusCacheTtlMs = 8000;
+    const statusInFlight = new Map();
+    const hostAddress = options.host || '127.0.0.1';
+    const hostPort = options.port || 9630;
+    const providerDefaults = options.providerConfig || {};
+    const hostId = options.hostId || (mode === 'dev' ? 'agentconnect-dev' : 'agentconnect-host');
+    const hostName = options.hostName || (mode === 'dev' ? 'AgentConnect Dev Host' : 'AgentConnect Host');
+    const hostVersion = options.hostVersion || '0.1.0';
+    function resolveAppPathInternal(input) {
+        if (!input)
+            return basePath;
+        const value = String(input);
+        return path.isAbsolute(value) ? value : path.resolve(basePath, value);
+    }
+    function mapFileType(stat) {
+        if (stat.isFile())
+            return 'file';
+        if (stat.isDirectory())
+            return 'dir';
+        if (stat.isSymbolicLink())
+            return 'link';
+        return 'other';
+    }
+    async function allocatePort() {
+        return new Promise((resolve, reject) => {
+            const socket = net.createServer();
+            socket.listen(0, hostAddress, () => {
+                const address = socket.address();
+                if (!address || typeof address === 'string') {
+                    socket.close();
+                    reject(new Error('Failed to allocate port.'));
+                    return;
+                }
+                const portValue = address.port;
+                socket.close(() => resolve(portValue));
+            });
+            socket.on('error', reject);
+        });
+    }
+    async function waitForHealthcheck(url, timeoutMs = 15000) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            try {
+                const res = await fetch(url, { method: 'GET' });
+                if (res.ok)
+                    return true;
+            }
+            catch {
+                // ignore
+            }
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+        return false;
+    }
+    function readManifest(root) {
+        try {
+            const raw = fs.readFileSync(path.join(root, 'agentconnect.app.json'), 'utf8');
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    function recordCapability(capability) {
+        observedTracker.record(capability);
+    }
+    function recordModelCapability(model) {
+        const providerId = resolveProviderForModel(model);
+        if (!providerId)
+            return;
+        recordCapability(`model.${providerId}`);
+    }
+    async function getCachedStatus(provider, options = {}) {
+        const cached = statusCache.get(provider.id);
+        const now = Date.now();
+        if (cached && now - cached.at < statusCacheTtlMs) {
+            return cached.status;
+        }
+        const existing = statusInFlight.get(provider.id);
+        if (existing)
+            return existing;
+        if (options.allowFast && provider.fastStatus) {
+            try {
+                const fast = await provider.fastStatus();
+                const startedAt = Date.now();
+                const promise = provider
+                    .status()
+                    .then((status) => {
+                    debugLog('Providers', 'status-check', {
+                        providerId: provider.id,
+                        durationMs: Date.now() - startedAt,
+                        completedAt: new Date().toISOString(),
+                    });
+                    statusCache.set(provider.id, { status, at: Date.now() });
+                    return status;
+                })
+                    .finally(() => {
+                    statusInFlight.delete(provider.id);
+                });
+                statusInFlight.set(provider.id, promise);
+                return fast;
+            }
+            catch {
+                // fall through to full status
+            }
+        }
+        const startedAt = Date.now();
+        const promise = provider
+            .status()
+            .then((status) => {
+            debugLog('Providers', 'status-check', {
+                providerId: provider.id,
+                durationMs: Date.now() - startedAt,
+                completedAt: new Date().toISOString(),
+            });
+            statusCache.set(provider.id, { status, at: Date.now() });
+            return status;
+        })
+            .finally(() => {
+            statusInFlight.delete(provider.id);
+        });
+        statusInFlight.set(provider.id, promise);
+        return promise;
+    }
+    function invalidateStatus(providerId) {
+        if (!providerId)
+            return;
+        statusCache.delete(providerId);
+    }
+    function emitSessionEvent(responder, sessionId, type, data) {
+        if (process.env.AGENTCONNECT_DEBUG?.trim()) {
+            try {
+                console.log(`[AgentConnect][Session ${sessionId}] ${type} ${JSON.stringify(data)}`);
+            }
+            catch {
+                console.log(`[AgentConnect][Session ${sessionId}] ${type}`);
+            }
+        }
+        responder.emit({
+            jsonrpc: '2.0',
+            method: 'acp.session.event',
+            params: { sessionId, type, data },
+        });
+    }
+    async function handleRpc(payload, responder) {
+        if (!payload || payload.jsonrpc !== '2.0' || payload.id === undefined) {
+            return;
+        }
+        const id = payload.id;
+        const method = payload.method;
+        const params = (payload.params ?? {});
+        if (typeof method === 'string' && method.startsWith('acp.')) {
+            recordCapability('agent.connect');
+        }
+        if (method === 'acp.hello') {
+            const loginExperience = resolveLoginExperience(mode);
+            responder.reply(id, {
+                hostId,
+                hostName,
+                hostVersion,
+                protocolVersion: '0.1',
+                mode: 'local',
+                capabilities: [],
+                providers: Object.keys(providers),
+                loginExperience,
+            });
+            return;
+        }
+        if (method === 'acp.providers.list') {
+            const statusEntries = await Promise.all(Object.values(providers).map(async (provider) => {
+                try {
+                    return [provider.id, await getCachedStatus(provider, { allowFast: true })];
+                }
+                catch {
+                    return [provider.id, { installed: false, loggedIn: false }];
+                }
+            }));
+            const statuses = Object.fromEntries(statusEntries);
+            const list = buildProviderList(statuses).map((entry) => ({
+                ...entry,
+                updateInProgress: updatingProviders.has(entry.id),
+            }));
+            responder.reply(id, { providers: list });
+            return;
+        }
+        if (method === 'acp.providers.status') {
+            const providerId = params.provider;
+            const provider = providers[providerId];
+            if (!provider) {
+                responder.error(id, 'AC_ERR_UNSUPPORTED', 'Unknown provider');
+                return;
+            }
+            const status = await getCachedStatus(provider, { allowFast: true });
+            responder.reply(id, {
+                provider: {
+                    id: provider.id,
+                    name: provider.name,
+                    installed: status.installed,
+                    loggedIn: status.loggedIn,
+                    version: status.version,
+                    updateAvailable: status.updateAvailable,
+                    latestVersion: status.latestVersion,
+                    updateCheckedAt: status.updateCheckedAt,
+                    updateSource: status.updateSource,
+                    updateCommand: status.updateCommand,
+                    updateMessage: status.updateMessage,
+                    updateInProgress: updatingProviders.has(provider.id) || status.updateInProgress,
+                },
+            });
+            return;
+        }
+        if (method === 'acp.providers.update') {
+            const providerId = params.provider;
+            const provider = providers[providerId];
+            if (!provider) {
+                responder.error(id, 'AC_ERR_UNSUPPORTED', 'Unknown provider');
+                return;
+            }
+            debugLog('Providers', 'update-start', { providerId });
+            if (!updatingProviders.has(providerId)) {
+                const promise = provider.update().finally(() => {
+                    updatingProviders.delete(providerId);
+                    invalidateStatus(providerId);
+                });
+                updatingProviders.set(providerId, promise);
+            }
+            try {
+                const status = await updatingProviders.get(providerId);
+                debugLog('Providers', 'update-complete', {
+                    providerId,
+                    updateAvailable: status.updateAvailable,
+                    latestVersion: status.latestVersion,
+                    updateMessage: status.updateMessage,
+                });
+                responder.reply(id, {
+                    provider: {
+                        id: provider.id,
+                        name: provider.name,
+                        installed: status.installed,
+                        loggedIn: status.loggedIn,
+                        version: status.version,
+                        updateAvailable: status.updateAvailable,
+                        latestVersion: status.latestVersion,
+                        updateCheckedAt: status.updateCheckedAt,
+                        updateSource: status.updateSource,
+                        updateCommand: status.updateCommand,
+                        updateMessage: status.updateMessage,
+                        updateInProgress: false,
+                    },
+                });
+            }
+            catch (err) {
+                debugLog('Providers', 'update-error', {
+                    providerId,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                responder.error(id, 'AC_ERR_INTERNAL', err?.message || 'Update failed');
+            }
+            return;
+        }
+        if (method === 'acp.providers.ensureInstalled') {
+            const providerId = params.provider;
+            const provider = providers[providerId];
+            if (!provider) {
+                responder.error(id, 'AC_ERR_UNSUPPORTED', 'Unknown provider');
+                return;
+            }
+            const result = await provider.ensureInstalled();
+            invalidateStatus(provider.id);
+            responder.reply(id, result);
+            return;
+        }
+        if (method === 'acp.providers.login') {
+            const providerId = params.provider;
+            const provider = providers[providerId];
+            if (!provider) {
+                responder.error(id, 'AC_ERR_UNSUPPORTED', 'Unknown provider');
+                return;
+            }
+            try {
+                const defaults = providerDefaults[providerId];
+                const incoming = params.options;
+                const result = await provider.login({
+                    ...(defaults || {}),
+                    ...(incoming || {}),
+                });
+                invalidateStatus(provider.id);
+                responder.reply(id, result);
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_INTERNAL', err?.message || 'Provider login failed.');
+            }
+            return;
+        }
+        if (method === 'acp.providers.logout') {
+            const providerId = params.provider;
+            const provider = providers[providerId];
+            if (!provider) {
+                responder.error(id, 'AC_ERR_UNSUPPORTED', 'Unknown provider');
+                return;
+            }
+            await provider.logout();
+            invalidateStatus(provider.id);
+            responder.reply(id, {});
+            return;
+        }
+        if (method === 'acp.models.list') {
+            const models = await listModels();
+            const providerId = params.provider;
+            if (providerId) {
+                responder.reply(id, { models: models.filter((m) => m.provider === providerId) });
+            }
+            else {
+                responder.reply(id, { models });
+            }
+            return;
+        }
+        if (method === 'acp.models.recent') {
+            const providerId = params.provider;
+            const models = await listRecentModels(providerId);
+            responder.reply(id, { models });
+            return;
+        }
+        if (method === 'acp.models.info') {
+            const modelId = params.model;
+            const model = (await listModels()).find((m) => m.id === modelId);
+            if (!model) {
+                responder.error(id, 'AC_ERR_INVALID_ARGS', 'Unknown model');
+                return;
+            }
+            responder.reply(id, { model });
+            return;
+        }
+        if (method === 'acp.sessions.create') {
+            const sessionId = `sess_${Math.random().toString(36).slice(2, 10)}`;
+            const model = params.model || 'claude-opus';
+            const reasoningEffort = params.reasoningEffort || null;
+            const cwd = params.cwd ? resolveAppPathInternal(params.cwd) : undefined;
+            const repoRoot = params.repoRoot ? resolveAppPathInternal(params.repoRoot) : undefined;
+            const providerDetailLevel = params.providerDetailLevel || undefined;
+            const providerId = resolveProviderForModel(model);
+            recordModelCapability(model);
+            sessions.set(sessionId, {
+                id: sessionId,
+                providerId,
+                model,
+                providerSessionId: null,
+                reasoningEffort,
+                cwd,
+                repoRoot,
+                providerDetailLevel: providerDetailLevel === 'raw' || providerDetailLevel === 'minimal'
+                    ? providerDetailLevel
+                    : undefined,
+            });
+            responder.reply(id, { sessionId });
+            return;
+        }
+        if (method === 'acp.sessions.resume') {
+            const sessionId = params.sessionId;
+            const existing = sessions.get(sessionId);
+            if (!existing) {
+                const model = params.model || 'claude-opus';
+                const reasoningEffort = params.reasoningEffort || null;
+                const cwd = params.cwd ? resolveAppPathInternal(params.cwd) : undefined;
+                const repoRoot = params.repoRoot ? resolveAppPathInternal(params.repoRoot) : undefined;
+                const providerDetailLevel = params.providerDetailLevel || undefined;
+                recordModelCapability(model);
+                sessions.set(sessionId, {
+                    id: sessionId,
+                    providerId: resolveProviderForModel(model),
+                    model,
+                    providerSessionId: params.providerSessionId || null,
+                    reasoningEffort,
+                    cwd,
+                    repoRoot,
+                    providerDetailLevel: providerDetailLevel === 'raw' || providerDetailLevel === 'minimal'
+                        ? providerDetailLevel
+                        : undefined,
+                });
+            }
+            else {
+                if (params.providerSessionId) {
+                    existing.providerSessionId = String(params.providerSessionId);
+                }
+                if (params.cwd) {
+                    existing.cwd = resolveAppPathInternal(params.cwd);
+                }
+                if (params.repoRoot) {
+                    existing.repoRoot = resolveAppPathInternal(params.repoRoot);
+                }
+                if (params.providerDetailLevel) {
+                    const level = String(params.providerDetailLevel);
+                    if (level === 'raw' || level === 'minimal') {
+                        existing.providerDetailLevel = level;
+                    }
+                }
+                recordModelCapability(existing.model);
+            }
+            responder.reply(id, { sessionId });
+            return;
+        }
+        if (method === 'acp.sessions.send') {
+            const sessionId = params.sessionId;
+            const message = params.message?.content || '';
+            const session = sessions.get(sessionId);
+            if (!session) {
+                responder.error(id, 'AC_ERR_INVALID_ARGS', 'Unknown session');
+                return;
+            }
+            recordModelCapability(session.model);
+            const provider = providers[session.providerId];
+            if (!provider) {
+                responder.error(id, 'AC_ERR_UNSUPPORTED', 'Unknown provider');
+                return;
+            }
+            if (updatingProviders.has(session.providerId)) {
+                responder.error(id, 'AC_ERR_BUSY', 'Provider update in progress.');
+                return;
+            }
+            const status = await provider.status();
+            if (!status.installed) {
+                const installed = await provider.ensureInstalled();
+                if (!installed.installed) {
+                    responder.error(id, 'AC_ERR_NOT_INSTALLED', 'Provider CLI is not installed.');
+                    return;
+                }
+            }
+            const controller = new AbortController();
+            const cwd = params.cwd ? resolveAppPathInternal(params.cwd) : session.cwd || basePath;
+            const repoRoot = params.repoRoot
+                ? resolveAppPathInternal(params.repoRoot)
+                : session.repoRoot || basePath;
+            const providerDetailLevel = params.providerDetailLevel === 'raw' || params.providerDetailLevel === 'minimal'
+                ? params.providerDetailLevel
+                : session.providerDetailLevel || 'minimal';
+            activeRuns.set(sessionId, controller);
+            let sawError = false;
+            provider
+                .runPrompt({
+                prompt: message,
+                resumeSessionId: session.providerSessionId,
+                model: session.model,
+                reasoningEffort: session.reasoningEffort,
+                repoRoot,
+                cwd,
+                providerDetailLevel,
+                signal: controller.signal,
+                onEvent: (event) => {
+                    if (event.type === 'error') {
+                        sawError = true;
+                    }
+                    if (sawError && event.type === 'final') {
+                        return;
+                    }
+                    emitSessionEvent(responder, sessionId, event.type, { ...event });
+                },
+            })
+                .then((result) => {
+                if (result?.sessionId) {
+                    session.providerSessionId = result.sessionId;
+                }
+            })
+                .catch((err) => {
+                if (!sawError) {
+                    emitSessionEvent(responder, sessionId, 'error', {
+                        message: err?.message || 'Provider error',
+                    });
+                }
+            })
+                .finally(() => {
+                activeRuns.delete(sessionId);
+            });
+            responder.reply(id, { accepted: true });
+            return;
+        }
+        if (method === 'acp.sessions.cancel') {
+            const sessionId = params.sessionId;
+            const controller = activeRuns.get(sessionId);
+            if (controller) {
+                controller.abort();
+                activeRuns.delete(sessionId);
+            }
+            responder.reply(id, { cancelled: true });
+            return;
+        }
+        if (method === 'acp.sessions.close') {
+            const sessionId = params.sessionId;
+            sessions.delete(sessionId);
+            responder.reply(id, { closed: true });
+            return;
+        }
+        if (method === 'acp.fs.read') {
+            recordCapability('fs.read');
+            try {
+                const filePath = resolveAppPathInternal(params.path);
+                const encoding = params.encoding || 'utf8';
+                const content = await fsp.readFile(filePath, encoding);
+                responder.reply(id, { content, encoding });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_FS_READ', err?.message || 'Failed to read file.');
+            }
+            return;
+        }
+        if (method === 'acp.fs.write') {
+            recordCapability('fs.write');
+            try {
+                const filePath = resolveAppPathInternal(params.path);
+                const encoding = params.encoding || 'utf8';
+                const content = params.content ?? '';
+                await fsp.mkdir(path.dirname(filePath), { recursive: true });
+                await fsp.writeFile(filePath, content, {
+                    encoding,
+                    mode: params.mode,
+                });
+                const bytes = Buffer.byteLength(String(content), encoding);
+                responder.reply(id, { bytes });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_FS_WRITE', err?.message || 'Failed to write file.');
+            }
+            return;
+        }
+        if (method === 'acp.fs.list') {
+            recordCapability('fs.read');
+            try {
+                const dirPath = resolveAppPathInternal(params.path);
+                const entries = await fsp.readdir(dirPath, { withFileTypes: true });
+                const results = [];
+                for (const entry of entries) {
+                    const entryPath = path.join(dirPath, entry.name);
+                    let size = 0;
+                    let type = 'other';
+                    try {
+                        const stat = await fsp.lstat(entryPath);
+                        type = mapFileType(stat);
+                        if (type === 'file')
+                            size = stat.size;
+                    }
+                    catch {
+                        type = entry.isDirectory() ? 'dir' : entry.isFile() ? 'file' : 'other';
+                    }
+                    results.push({
+                        name: entry.name,
+                        path: entryPath,
+                        type,
+                        size,
+                    });
+                }
+                responder.reply(id, { entries: results });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_FS_LIST', err?.message || 'Failed to list directory.');
+            }
+            return;
+        }
+        if (method === 'acp.fs.stat') {
+            recordCapability('fs.read');
+            try {
+                const filePath = resolveAppPathInternal(params.path);
+                const stat = await fsp.lstat(filePath);
+                responder.reply(id, {
+                    type: mapFileType(stat),
+                    size: stat.size,
+                    mtime: stat.mtime.toISOString(),
+                });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_FS_STAT', err?.message || 'Failed to stat file.');
+            }
+            return;
+        }
+        if (method === 'acp.process.spawn') {
+            recordCapability('process.spawn');
+            try {
+                const command = String(params.command || '');
+                const args = Array.isArray(params.args) ? params.args.map(String) : [];
+                const cwd = params.cwd ? resolveAppPathInternal(params.cwd) : basePath;
+                const env = { ...process.env, ...(params.env || {}) };
+                const useTty = Boolean(params.tty);
+                const child = spawn(command, args, {
+                    cwd,
+                    env,
+                    stdio: useTty ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+                });
+                if (!useTty) {
+                    child.stdout?.on('data', () => undefined);
+                    child.stderr?.on('data', () => undefined);
+                }
+                if (typeof params.stdin === 'string' && child.stdin) {
+                    child.stdin.write(params.stdin);
+                    child.stdin.end();
+                }
+                if (child.pid) {
+                    processTable.set(child.pid, child);
+                    child.on('close', () => {
+                        if (child.pid)
+                            processTable.delete(child.pid);
+                    });
+                }
+                responder.reply(id, { pid: child.pid });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_PROCESS', err?.message || 'Failed to spawn process.');
+            }
+            return;
+        }
+        if (method === 'acp.process.kill') {
+            recordCapability('process.kill');
+            const pid = Number(params.pid);
+            const signal = params.signal || 'SIGTERM';
+            const child = processTable.get(pid);
+            try {
+                const success = child ? child.kill(signal) : process.kill(pid, signal);
+                responder.reply(id, { success: Boolean(success) });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_PROCESS', err?.message || 'Failed to kill process.');
+            }
+            return;
+        }
+        if (method === 'acp.net.request') {
+            recordCapability('network.request');
+            try {
+                if (typeof fetch !== 'function') {
+                    responder.error(id, 'AC_ERR_NET', 'Fetch is not available.');
+                    return;
+                }
+                const controller = new AbortController();
+                const timeout = params.timeoutMs;
+                let timer = null;
+                if (timeout) {
+                    timer = setTimeout(() => controller.abort(), Number(timeout));
+                }
+                const res = await fetch(String(params.url), {
+                    method: params.method || 'GET',
+                    headers: params.headers || {},
+                    body: params.body,
+                    signal: controller.signal,
+                });
+                if (timer)
+                    clearTimeout(timer);
+                const body = await res.text();
+                const headers = {};
+                res.headers.forEach((value, key) => {
+                    headers[key] = value;
+                });
+                responder.reply(id, { status: res.status, headers, body });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_NET', err?.message || 'Network request failed.');
+            }
+            return;
+        }
+        if (method === 'acp.backend.start') {
+            recordCapability('backend.run');
+            if (!manifest?.backend) {
+                responder.reply(id, { status: 'disabled' });
+                return;
+            }
+            const backendConfig = manifest.backend;
+            const existing = backendState.get(appId);
+            if (existing?.status === 'running') {
+                responder.reply(id, { status: 'running', url: existing.url });
+                return;
+            }
+            try {
+                let assignedPort = null;
+                const declaredPort = backendConfig.env?.PORT;
+                if (declaredPort === undefined || String(declaredPort) === '0') {
+                    assignedPort = await allocatePort();
+                }
+                else if (!Number.isNaN(Number(declaredPort))) {
+                    assignedPort = Number(declaredPort);
+                }
+                const env = {
+                    ...process.env,
+                    ...(backendConfig.env || {}),
+                    AGENTCONNECT_HOST: `ws://${hostAddress}:${hostPort}`,
+                    AGENTCONNECT_APP_ID: appId,
+                };
+                if (assignedPort) {
+                    env.PORT = String(assignedPort);
+                    env.AGENTCONNECT_APP_PORT = String(assignedPort);
+                }
+                const cwd = backendConfig.cwd ? resolveAppPathInternal(backendConfig.cwd) : basePath;
+                const args = backendConfig.args || [];
+                const child = spawn(backendConfig.command, args, {
+                    cwd,
+                    env,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                child.stdout?.on('data', () => undefined);
+                child.stderr?.on('data', () => undefined);
+                const url = assignedPort ? `http://${hostAddress}:${assignedPort}` : undefined;
+                const record = { status: 'starting', pid: child.pid, url };
+                backendState.set(appId, record);
+                child.on('exit', () => {
+                    backendState.set(appId, { status: 'stopped' });
+                });
+                if (backendConfig.healthcheck?.type === 'http' && assignedPort) {
+                    const healthUrl = `http://${hostAddress}:${assignedPort}${backendConfig.healthcheck.path}`;
+                    const ok = await waitForHealthcheck(healthUrl);
+                    if (!ok) {
+                        child.kill('SIGTERM');
+                        backendState.set(appId, { status: 'error' });
+                        responder.reply(id, { status: 'error' });
+                        return;
+                    }
+                }
+                backendState.set(appId, { status: 'running', pid: child.pid, url });
+                responder.reply(id, { status: 'running', url });
+            }
+            catch (err) {
+                responder.error(id, 'AC_ERR_BACKEND', err?.message || 'Failed to start backend.');
+            }
+            return;
+        }
+        if (method === 'acp.backend.stop') {
+            recordCapability('backend.run');
+            const current = backendState.get(appId);
+            if (!current?.pid) {
+                backendState.set(appId, { status: 'stopped' });
+                responder.reply(id, { status: 'stopped' });
+                return;
+            }
+            try {
+                process.kill(current.pid, 'SIGTERM');
+            }
+            catch {
+                // ignore
+            }
+            backendState.set(appId, { status: 'stopped' });
+            responder.reply(id, { status: 'stopped' });
+            return;
+        }
+        if (method === 'acp.backend.status') {
+            recordCapability('backend.run');
+            const current = backendState.get(appId) || { status: 'stopped' };
+            responder.reply(id, { status: current.status, url: current.url });
+            return;
+        }
+        if (method === 'acp.capabilities.observed') {
+            responder.reply(id, { ...observedTracker.snapshot() });
+            return;
+        }
+        responder.reply(id, {});
+    }
+    return {
+        handleRpc,
+        flush: () => {
+            observedTracker.flush();
+        },
+    };
+}
+export function startDevHost({ host = '127.0.0.1', port = 9630, appPath, uiUrl, ...options } = {}) {
+    const basePath = options.basePath || appPath || process.cwd();
+    const runtime = createHostRuntime({
+        ...options,
+        basePath,
+        host,
+        port,
+        modeDefault: 'dev',
+    });
+    const server = http.createServer();
+    const wss = new WebSocketServer({ server });
+    const logger = options.log?.info || console.log;
+    wss.on('connection', (socket) => {
+        socket.on('message', async (raw) => {
+            let payload;
+            try {
+                payload = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            const responder = {
+                reply: (id, result) => {
+                    send(socket, { jsonrpc: '2.0', id, result });
+                },
+                error: (id, code, message) => {
+                    send(socket, {
+                        jsonrpc: '2.0',
+                        id,
+                        error: { code, message },
+                    });
+                },
+                emit: (notification) => {
+                    send(socket, notification);
+                },
+            };
+            await runtime.handleRpc(payload, responder);
+        });
+    });
+    server.listen(port, host, () => {
+        logger(`AgentConnect dev host running at ws://${host}:${port}`);
+        if (appPath)
+            logger(`App path: ${appPath}`);
+        if (uiUrl)
+            logger(`UI dev server: ${uiUrl}`);
+    });
+    process.on('SIGINT', () => {
+        try {
+            runtime.flush();
+        }
+        catch {
+            // ignore flush errors
+        }
+        server.close(() => process.exit(0));
+    });
+}
+export function createHostBridge(options = {}) {
+    const runtime = createHostRuntime({
+        ...options,
+        basePath: options.basePath || process.cwd(),
+        modeDefault: 'embedded',
+    });
+    const handlers = new Set();
+    let nextId = 1;
+    const emit = (notification) => {
+        for (const handler of handlers) {
+            try {
+                handler(notification);
+            }
+            catch (err) {
+                options.log?.error?.('AgentConnect bridge handler error', {
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    };
+    return {
+        request: async (method, params) => {
+            return new Promise((resolve, reject) => {
+                const payload = {
+                    jsonrpc: '2.0',
+                    id: nextId++,
+                    method,
+                    params,
+                };
+                const responder = {
+                    reply: (_id, result) => resolve(result),
+                    error: (_id, code, message) => reject(new Error(`${code}: ${message}`)),
+                    emit,
+                };
+                runtime.handleRpc(payload, responder).catch((err) => {
+                    reject(err instanceof Error ? err : new Error(String(err)));
+                });
+            });
+        },
+        onEvent: (handler) => {
+            handlers.add(handler);
+            return () => {
+                handlers.delete(handler);
+            };
+        },
+    };
+}