@phnx-labs/agents-cli 1.14.2 → 1.14.4

package/dist/lib/browser/service.js

@@ -0,0 +1,404 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { CDPClient, discoverBrowserWsUrl } from './cdp.js';
+import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir } from './profiles.js';
+import { killChrome, getRunningChromeInfo } from './chrome.js';
+import { connectLocal } from './drivers/local.js';
+import { connectSSH } from './drivers/ssh.js';
+import { generateTaskId, isValidTaskId, } from './types.js';
+import { getRefs, resolveRefToCoords } from './refs.js';
+import { clickAtCoords, hoverAtCoords, typeText, pressKey, focusNode } from './input.js';
+export class BrowserService {
+    connections = new Map();
+    async start(profileName, taskId) {
+        const profile = await getProfile(profileName);
+        if (!profile) {
+            throw new Error(`Profile "${profileName}" not found`);
+        }
+        const finalTaskId = taskId || generateTaskId();
+        if (!isValidTaskId(finalTaskId)) {
+            throw new Error(`Invalid task ID "${finalTaskId}". Must be lowercase alphanumeric with hyphens.`);
+        }
+        let conn = this.connections.get(profileName);
+        if (!conn) {
+            conn = await this.connectProfile(profile);
+            this.connections.set(profileName, conn);
+        }
+        if (conn.tasks.has(finalTaskId)) {
+            const task = conn.tasks.get(finalTaskId);
+            return { task: finalTaskId, windowTargetId: task.windowTargetId };
+        }
+        const { windowTargetId } = await this.createTaskWindow(conn.cdp, finalTaskId);
+        const task = {
+            id: finalTaskId,
+            profile: profileName,
+            windowTargetId,
+            tabIds: [],
+            createdAt: Date.now(),
+            pid: conn.pid,
+        };
+        conn.tasks.set(finalTaskId, task);
+        await this.saveTaskState(profileName, conn.tasks);
+        return { task: finalTaskId, windowTargetId };
+    }
+    async stop(taskId) {
+        for (const [profileName, conn] of this.connections) {
+            const task = conn.tasks.get(taskId);
+            if (task) {
+                await Promise.all(task.tabIds.map((tabId) => conn.cdp.send('Target.closeTarget', { targetId: tabId }).catch(() => {
+                    // Tab already closed
+                })));
+                for (const tabId of task.tabIds) {
+                    conn.sessionCache.delete(tabId);
+                }
+                this.invalidateTargetCache(conn);
+                if (task.windowTargetId) {
+                    try {
+                        await conn.cdp.send('Target.closeTarget', { targetId: task.windowTargetId });
+                    }
+                    catch {
+                        // Window already closed
+                    }
+                }
+                conn.tasks.delete(taskId);
+                await this.saveTaskState(profileName, conn.tasks);
+                return { ok: true, profile: profileName };
+            }
+        }
+        return { ok: false };
+    }
+    async stopProfile(profileName) {
+        const conn = this.connections.get(profileName);
+        if (conn) {
+            conn.cdp.close();
+            killChrome(conn.pid);
+            this.connections.delete(profileName);
+        }
+        const runtimeDir = getProfileRuntimeDir(profileName);
+        const pidFile = path.join(runtimeDir, 'pid');
+        const portFile = path.join(runtimeDir, 'port');
+        if (fs.existsSync(pidFile)) {
+            const pid = parseInt(fs.readFileSync(pidFile, 'utf-8').trim(), 10);
+            killChrome(pid);
+            fs.unlinkSync(pidFile);
+        }
+        if (fs.existsSync(portFile)) {
+            fs.unlinkSync(portFile);
+        }
+    }
+    async navigate(taskId, url, profileName) {
+        const { conn, task } = await this.findTask(taskId, profileName);
+        const result = (await conn.cdp.send('Target.createTarget', {
+            url,
+        }));
+        const tabId = result.targetId;
+        task.tabIds.push(tabId);
+        this.invalidateTargetCache(conn);
+        await this.saveTaskState(task.profile, conn.tasks);
+        return { tabId, url };
+    }
+    async tabs(taskId, profileName) {
+        if (taskId) {
+            const { conn, task } = await this.findTask(taskId, profileName);
+            return this.getTabsForTask(conn.cdp, task);
+        }
+        const allTabs = [];
+        for (const [, conn] of this.connections) {
+            for (const [, task] of conn.tasks) {
+                const tabs = await this.getTabsForTask(conn.cdp, task);
+                allTabs.push(...tabs);
+            }
+        }
+        return allTabs;
+    }
+    async close(taskId, tabId) {
+        const { conn, task } = await this.findTask(taskId);
+        if (tabId !== undefined) {
+            await conn.cdp.send('Target.closeTarget', { targetId: tabId });
+            task.tabIds = task.tabIds.filter((id) => id !== tabId);
+            conn.sessionCache.delete(tabId);
+        }
+        else {
+            await Promise.all(task.tabIds.map((id) => conn.cdp.send('Target.closeTarget', { targetId: id }).catch(() => { })));
+            for (const id of task.tabIds) {
+                conn.sessionCache.delete(id);
+            }
+            task.tabIds = [];
+        }
+        this.invalidateTargetCache(conn);
+        await this.saveTaskState(task.profile, conn.tasks);
+    }
+    async evaluate(taskId, tabId, expression) {
+        const { conn } = await this.findTask(taskId);
+        const target = await this.getTarget(conn, tabId);
+        if (!target) {
+            throw new Error(`Tab ${tabId} not found`);
+        }
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const result = (await conn.cdp.send('Runtime.evaluate', { expression, returnByValue: true }, sessionId));
+        return result.result.value;
+    }
+    async screenshot(taskId, tabId, outputPath) {
+        const { conn, task } = await this.findTask(taskId);
+        const targetTabId = tabId ?? task.tabIds[task.tabIds.length - 1];
+        if (targetTabId === undefined) {
+            throw new Error('No tabs open for this task');
+        }
+        const target = await this.getTarget(conn, targetTabId);
+        if (!target) {
+            throw new Error(`Tab ${targetTabId} not found`);
+        }
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const { data } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 }, sessionId));
+        let buffer = Buffer.from(data, 'base64');
+        const MAX_SIZE = 100 * 1024;
+        if (buffer.length > MAX_SIZE) {
+            let quality = 50;
+            while (buffer.length > MAX_SIZE && quality > 10) {
+                const { data: resized } = (await conn.cdp.send('Page.captureScreenshot', { format: 'jpeg', quality }, sessionId));
+                buffer = Buffer.from(resized, 'base64');
+                quality -= 10;
+            }
+        }
+        const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', taskId);
+        const finalPath = outputPath || path.join(sessionsDir, `${Date.now()}.jpg`);
+        await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
+        await fs.promises.writeFile(finalPath, buffer);
+        return finalPath;
+    }
+    refsCache = new Map();
+    async refs(taskId, tabId, opts = {}) {
+        const { conn, task } = await this.findTask(taskId);
+        const targetTabId = tabId || task.tabIds[task.tabIds.length - 1];
+        if (!targetTabId)
+            throw new Error('No tabs open for this task');
+        const target = await this.getTarget(conn, targetTabId);
+        if (!target)
+            throw new Error(`Tab ${targetTabId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        return getRefs(conn.cdp, sessionId, opts);
+    }
+    async click(taskId, tabId, ref) {
+        const { conn } = await this.findTask(taskId);
+        const target = await this.getTarget(conn, tabId);
+        if (!target)
+            throw new Error(`Tab ${tabId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
+        const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, ref);
+        await clickAtCoords(conn.cdp, sessionId, x, y);
+    }
+    async type(taskId, tabId, ref, text) {
+        const { conn } = await this.findTask(taskId);
+        const target = await this.getTarget(conn, tabId);
+        if (!target)
+            throw new Error(`Tab ${tabId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
+        const node = nodeMap.get(ref);
+        if (!node)
+            throw new Error(`Ref ${ref} not found`);
+        if (node.backendNodeId) {
+            await focusNode(conn.cdp, sessionId, node.backendNodeId);
+        }
+        await typeText(conn.cdp, sessionId, text);
+    }
+    async press(taskId, tabId, key) {
+        const { conn } = await this.findTask(taskId);
+        const target = await this.getTarget(conn, tabId);
+        if (!target)
+            throw new Error(`Tab ${tabId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        await pressKey(conn.cdp, sessionId, key);
+    }
+    async hover(taskId, tabId, ref) {
+        const { conn } = await this.findTask(taskId);
+        const target = await this.getTarget(conn, tabId);
+        if (!target)
+            throw new Error(`Tab ${tabId} not found`);
+        const sessionId = await this.getSessionId(conn, target.targetId);
+        const { nodeMap } = await getRefs(conn.cdp, sessionId, { interactive: false, limit: 1000 });
+        const { x, y } = await resolveRefToCoords(conn.cdp, sessionId, nodeMap, ref);
+        await hoverAtCoords(conn.cdp, sessionId, x, y);
+    }
+    async status(profileName) {
+        const statuses = [];
+        if (profileName) {
+            const status = await this.getProfileStatus(profileName);
+            if (status)
+                statuses.push(status);
+        }
+        else {
+            for (const name of this.connections.keys()) {
+                const status = await this.getProfileStatus(name);
+                if (status)
+                    statuses.push(status);
+            }
+        }
+        return statuses;
+    }
+    async shutdown() {
+        for (const [, conn] of this.connections) {
+            conn.cdp.close();
+        }
+        this.connections.clear();
+    }
+    async connectProfile(profile) {
+        const existingInfo = getRunningChromeInfo(profile.name);
+        if (existingInfo) {
+            const wsUrl = await discoverBrowserWsUrl(existingInfo.port);
+            const cdp = new CDPClient();
+            await cdp.connect(wsUrl);
+            await this.enableDomains(cdp);
+            const tasks = this.loadTaskState(profile.name);
+            return {
+                cdp,
+                port: existingInfo.port,
+                pid: existingInfo.pid,
+                tasks,
+                sessionCache: new Map(),
+            };
+        }
+        for (const endpoint of profile.endpoints) {
+            try {
+                const conn = await this.connectEndpoint(profile, endpoint);
+                if (conn)
+                    return conn;
+            }
+            catch {
+                // Try next endpoint
+            }
+        }
+        throw new Error(`Could not connect to any endpoint for profile "${profile.name}"`);
+    }
+    async connectEndpoint(profile, endpoint) {
+        const url = new URL(endpoint);
+        if (url.protocol === 'cdp:') {
+            const conn = await connectLocal(endpoint, profile);
+            await this.enableDomains(conn.cdp);
+            return {
+                cdp: conn.cdp,
+                port: conn.port,
+                pid: conn.pid,
+                tasks: conn.pid === 0 ? this.loadTaskState(profile.name) : new Map(),
+                sessionCache: new Map(),
+            };
+        }
+        if (url.protocol === 'ssh:') {
+            const conn = await connectSSH(endpoint, profile);
+            await this.enableDomains(conn.cdp);
+            return {
+                cdp: conn.cdp,
+                port: conn.port,
+                pid: conn.pid,
+                tasks: new Map(),
+                sessionCache: new Map(),
+            };
+        }
+        return null;
+    }
+    async enableDomains(cdp) {
+        await cdp.send('Target.setDiscoverTargets', { discover: true });
+    }
+    async createTaskWindow(cdp, _taskId) {
+        const result = (await cdp.send('Target.createTarget', {
+            url: 'about:blank',
+            newWindow: true,
+        }));
+        return { windowTargetId: result.targetId };
+    }
+    async findTask(taskId, profileName) {
+        if (profileName) {
+            const conn = this.connections.get(profileName);
+            if (!conn) {
+                throw new Error(`Profile "${profileName}" not connected`);
+            }
+            const task = conn.tasks.get(taskId);
+            if (!task) {
+                throw new Error(`Task "${taskId}" not found on profile "${profileName}"`);
+            }
+            return { conn, task };
+        }
+        for (const [, conn] of this.connections) {
+            const task = conn.tasks.get(taskId);
+            if (task) {
+                return { conn, task };
+            }
+        }
+        throw new Error(`Task "${taskId}" not found`);
+    }
+    async getTabsForTask(cdp, task) {
+        const targets = (await cdp.send('Target.getTargets'));
+        return task.tabIds
+            .map((id) => {
+            const target = targets.targetInfos.find((t) => t.targetId === id);
+            if (!target)
+                return null;
+            return {
+                id,
+                url: target.url,
+                title: target.title,
+                task: task.id,
+            };
+        })
+            .filter((t) => t !== null);
+    }
+    async getProfileStatus(profileName) {
+        const conn = this.connections.get(profileName);
+        if (!conn)
+            return null;
+        const tasks = [];
+        for (const [, task] of conn.tasks) {
+            tasks.push({
+                id: task.id,
+                tabCount: task.tabIds.length,
+                createdAt: task.createdAt,
+            });
+        }
+        return {
+            name: profileName,
+            running: true,
+            port: conn.port,
+            pid: conn.pid,
+            tasks,
+        };
+    }
+    async getTarget(conn, tabId) {
+        const now = Date.now();
+        if (!conn.targetCache || now - conn.targetCache.ts > 1000) {
+            const { targetInfos } = (await conn.cdp.send('Target.getTargets'));
+            conn.targetCache = { targets: targetInfos, ts: now };
+        }
+        return conn.targetCache.targets.find((target) => target.targetId === tabId);
+    }
+    async getSessionId(conn, tabId) {
+        const cachedSessionId = conn.sessionCache.get(tabId);
+        if (cachedSessionId) {
+            return cachedSessionId;
+        }
+        const { sessionId } = (await conn.cdp.send('Target.attachToTarget', {
+            targetId: tabId,
+            flatten: true,
+        }));
+        conn.sessionCache.set(tabId, sessionId);
+        return sessionId;
+    }
+    invalidateTargetCache(conn) {
+        conn.targetCache = undefined;
+    }
+    async saveTaskState(profileName, tasks) {
+        const runtimeDir = getProfileRuntimeDir(profileName);
+        await fs.promises.mkdir(runtimeDir, { recursive: true });
+        const state = Object.fromEntries(tasks);
+        await fs.promises.writeFile(path.join(runtimeDir, 'tasks.json'), JSON.stringify(state, null, 2));
+    }
+    loadTaskState(profileName) {
+        const runtimeDir = getProfileRuntimeDir(profileName);
+        const tasksFile = path.join(runtimeDir, 'tasks.json');
+        if (!fs.existsSync(tasksFile)) {
+            return new Map();
+        }
+        const state = JSON.parse(fs.readFileSync(tasksFile, 'utf-8'));
+        return new Map(Object.entries(state));
+    }
+}

package/dist/lib/browser/types.d.ts

@@ -0,0 +1,73 @@
+export type BrowserType = 'chrome' | 'comet' | 'chromium' | 'brave' | 'edge';
+export interface BrowserProfile {
+    name: string;
+    description?: string;
+    browser: BrowserType;
+    endpoints: string[];
+    chrome?: ChromeOptions;
+    secrets?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+}
+export interface ChromeOptions {
+    headless?: boolean;
+    args?: string[];
+}
+export interface Task {
+    id: string;
+    profile: string;
+    windowTargetId?: string;
+    tabIds: string[];
+    createdAt: number;
+    pid: number;
+}
+export interface TabInfo {
+    id: string;
+    url: string;
+    title: string;
+    task: string;
+}
+export interface ProfileStatus {
+    name: string;
+    running: boolean;
+    port?: number;
+    pid?: number;
+    tasks: TaskStatus[];
+}
+export interface TaskStatus {
+    id: string;
+    tabCount: number;
+    createdAt: number;
+}
+export type IPCAction = 'start' | 'stop' | 'status' | 'navigate' | 'tabs' | 'close' | 'evaluate' | 'screenshot' | 'refs' | 'click' | 'type' | 'press' | 'hover';
+export interface IPCRequest {
+    action: IPCAction;
+    task?: string;
+    profile?: string;
+    url?: string;
+    tabId?: string;
+    expr?: string;
+    path?: string;
+    ref?: number;
+    text?: string;
+    key?: string;
+    interactive?: boolean;
+    limit?: number;
+}
+export interface IPCResponse {
+    ok: boolean;
+    error?: string;
+    task?: string;
+    tabId?: string;
+    windowTargetId?: string;
+    tabs?: TabInfo[];
+    profiles?: ProfileStatus[];
+    result?: unknown;
+    path?: string;
+    refs?: string;
+}
+export declare const TASK_ID_REGEX: RegExp;
+export declare function isValidTaskId(id: string): boolean;
+export declare function generateTaskId(): string;

package/dist/lib/browser/types.js

@@ -0,0 +1,7 @@
+export const TASK_ID_REGEX = /^[a-z0-9][a-z0-9-]*$/;
+export function isValidTaskId(id) {
+    return TASK_ID_REGEX.test(id) && id.length <= 64;
+}
+export function generateTaskId() {
+    return crypto.randomUUID().slice(0, 8);
+}

package/dist/lib/cloud/codex.js

@@ -107,7 +107,7 @@ export class CodexCloudProvider {
     async dispatch(options) {
         const env = options.providerOptions?.env ?? this.defaultEnv;
         if (!env) {
-            throw new Error('Codex Cloud requires --env <id>. Set a default in ~/.agents-system/agents.yaml under cloud.providers.codex.env.');
+            throw new Error('Codex Cloud requires --env <id>. Set a default in ~/.agents/agents.yaml under cloud.providers.codex.env.');
         }
         // Codex envs bundle their own repo list — the repos a task can touch are
         // fixed at env-creation time, not per-dispatch. Passing 2+ repos here is

package/dist/lib/cloud/registry.js

@@ -10,8 +10,8 @@ import * as yaml from 'yaml';
 import { RushCloudProvider } from './rush.js';
 import { CodexCloudProvider } from './codex.js';
 import { FactoryCloudProvider } from './factory.js';
-import { getAgentsDir } from '../state.js';
-const META_FILE = path.join(getAgentsDir(), 'agents.yaml');
+import { getUserAgentsDir } from '../state.js';
+const META_FILE = path.join(getUserAgentsDir(), 'agents.yaml');
 let _config = null;
 /** Parse the `cloud` section from agents.yaml, caching the result for the process lifetime. */
 function loadCloudConfig() {

package/dist/lib/cloud/rush.js

@@ -9,7 +9,7 @@ import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import * as yaml from 'yaml';
-import { getAgentsDir } from '../state.js';
+import { getUserAgentsDir } from '../state.js';
 import { resolveDispatchRepos } from './types.js';
 import { parseSSE } from './stream.js';
 import { listInstalledVersions, getVersionHomePath } from '../versions.js';
@@ -20,7 +20,7 @@ const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
 // Created on first explicit consent (env var or flag); subsequent dispatches
 // see it and proceed without re-prompting.
-const RUSH_CONSENT_PATH = path.join(getAgentsDir(), 'cloud', 'rush-consent.json');
+const RUSH_CONSENT_PATH = path.join(getUserAgentsDir(), 'cloud', 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
 function hasRushUploadConsent(opts) {
     if (process.env[RUSH_CONSENT_ENV] === '1')

package/dist/lib/cloud/store.js

@@ -8,8 +8,8 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import Database from '../sqlite.js';
-import { getAgentsDir } from '../state.js';
-const CLOUD_DIR = path.join(getAgentsDir(), 'cloud');
+import { getUserAgentsDir } from '../state.js';
+const CLOUD_DIR = path.join(getUserAgentsDir(), 'cloud');
 const DB_PATH = path.join(CLOUD_DIR, 'tasks.db');
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS tasks (

package/dist/lib/daemon.d.ts

@@ -14,7 +14,7 @@ export declare function writeDaemonPid(pid: number): void;
 export declare function removeDaemonPid(): void;
 /** Check if the daemon process is alive by sending signal 0 to the stored PID. */
 export declare function isDaemonRunning(): boolean;
-/** Append a timestamped log line to the daemon log file (owner-only permissions). */
+/** Append a JSONL log entry to the daemon log file (owner-only permissions). */
 export declare function log(level: string, message: string): void;
 /** Main daemon loop: load jobs, schedule crons, monitor runs, and handle signals. */
 export declare function runDaemon(): Promise<void>;

package/dist/lib/daemon.js

@@ -14,16 +14,26 @@ import { getAgentsDir } from './state.js';
 import { listJobs as listAllJobs } from './routines.js';
 import { JobScheduler } from './scheduler.js';
 import { executeJobDetached, monitorRunningJobs } from './runner.js';
+import { BrowserService } from './browser/service.js';
+import { BrowserIPCServer } from './browser/ipc.js';
+const DAEMON_DIR = 'helpers/daemon';
 const PID_FILE = 'daemon.pid';
 const LOCK_FILE = 'daemon.lock';
-const LOG_FILE = 'daemon.log';
+const LOG_FILE = 'logs.jsonl';
+const LOG_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
+const LOG_ROTATE_COUNT = 3;
 const PLIST_NAME = 'com.phnx-labs.agents-daemon';
 const SYSTEMD_UNIT = 'agents-daemon.service';
+function getDaemonDir() {
+    const dir = path.join(getAgentsDir(), DAEMON_DIR);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 function getPidPath() {
-    return path.join(getAgentsDir(), PID_FILE);
+    return path.join(getDaemonDir(), PID_FILE);
 }
 function getLockPath() {
-    return path.join(getAgentsDir(), LOCK_FILE);
+    return path.join(getDaemonDir(), LOCK_FILE);
 }
 /**
  * Acquire an exclusive start lock. Returns a release function on success,
@@ -67,7 +77,7 @@ function acquireStartLock() {
     }
 }
 function getLogPath() {
-    return path.join(getAgentsDir(), LOG_FILE);
+    return path.join(getDaemonDir(), LOG_FILE);
 }
 function getLaunchdPlistPath() {
     return path.join(os.homedir(), 'Library', 'LaunchAgents', `${PLIST_NAME}.plist`);
@@ -122,12 +132,28 @@ function redactSecrets(message) {
     safe = safe.replace(/(ANTHROPIC_API_KEY|OPENAI_API_KEY|API_KEY|SECRET|TOKEN|PASSWORD)=\S+/gi, '$1=[REDACTED]');
     return safe;
 }
-/** Append a timestamped log line to the daemon log file (owner-only permissions). */
+function rotateLogsIfNeeded(logPath) {
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size < LOG_MAX_SIZE)
+            return;
+        for (let i = LOG_ROTATE_COUNT - 1; i >= 1; i--) {
+            const older = `${logPath}.${i}`;
+            const newer = i === 1 ? logPath : `${logPath}.${i - 1}`;
+            if (fs.existsSync(newer))
+                fs.renameSync(newer, older);
+        }
+        if (fs.existsSync(logPath))
+            fs.renameSync(logPath, `${logPath}.1`);
+    }
+    catch { }
+}
+/** Append a JSONL log entry to the daemon log file (owner-only permissions). */
 export function log(level, message) {
-    const timestamp = new Date().toISOString();
-    const line = `[${timestamp}] [${level.toUpperCase()}] ${redactSecrets(message)}\n`;
     const logPath = getLogPath();
-    fs.appendFileSync(logPath, line, 'utf-8');
+    rotateLogsIfNeeded(logPath);
+    const entry = { ts: new Date().toISOString(), level: level.toUpperCase(), message: redactSecrets(message) };
+    fs.appendFileSync(logPath, JSON.stringify(entry) + '\n', 'utf-8');
     try {
         fs.chmodSync(logPath, 0o600);
     }
@@ -153,6 +179,15 @@ export async function runDaemon() {
     for (const job of scheduled) {
         log('INFO', `  ${job.name} -> next: ${job.nextRun?.toISOString() || 'unknown'}`);
     }
+    const browserService = new BrowserService();
+    const browserIPC = new BrowserIPCServer(browserService);
+    try {
+        await browserIPC.start();
+        log('INFO', 'Browser IPC server started');
+    }
+    catch (err) {
+        log('ERROR', `Browser IPC failed to start: ${err.message}`);
+    }
     const monitorInterval = setInterval(() => {
         monitorRunningJobs();
     }, 60_000);
@@ -162,16 +197,17 @@ export async function runDaemon() {
         const reloaded = scheduler.listScheduled();
         log('INFO', `Reloaded ${reloaded.length} jobs`);
     };
-    const handleShutdown = () => {
+    const handleShutdown = async () => {
         log('INFO', 'Daemon shutting down');
         scheduler.stopAll();
+        await browserIPC.stop();
         clearInterval(monitorInterval);
         removeDaemonPid();
         process.exit(0);
     };
     process.on('SIGHUP', handleReload);
-    process.on('SIGTERM', handleShutdown);
-    process.on('SIGINT', handleShutdown);
+    process.on('SIGTERM', () => handleShutdown());
+    process.on('SIGINT', () => handleShutdown());
     await new Promise(() => { });
 }
 /** Generate a macOS launchd plist for auto-starting the daemon. */

package/dist/lib/diff-text.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tiny unified-diff helpers for human-readable doctor output.
+ *
+ * Wraps the `diff` package's createPatch into one call that returns a
+ * pre-coloured unified diff (red = removed, green = added, dim = context).
+ * Used by `agents doctor --diff`.
+ */
+export interface UnifiedDiffOptions {
+    /** Number of context lines around each change (default: 3). */
+    context?: number;
+    /** Filename label shown in the patch header for the "expected" side. */
+    fromLabel?: string;
+    /** Filename label shown in the patch header for the "actual" side. */
+    toLabel?: string;
+}
+/**
+ * Build a unified-diff text comparing two strings. Returns an empty string
+ * when contents are identical.
+ */
+export declare function unifiedDiff(expected: string, actual: string, options?: UnifiedDiffOptions): string;
+/**
+ * Colour a unified-diff string for terminal output. Indents each line with
+ * a constant prefix so it nests cleanly under a header.
+ */
+export declare function colorizeUnifiedDiff(patch: string, indent?: string): string;