granclaw 0.0.1-beta.0

package/dist/backend/providers-config.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listProviders = listProviders;
+exports.getProvider = getProvider;
+exports.getProviderApiKey = getProviderApiKey;
+exports.saveProvider = saveProvider;
+exports.removeProvider = removeProvider;
+exports.clearProvider = clearProvider;
+exports.getSearchApiKey = getSearchApiKey;
+exports.saveSearch = saveSearch;
+exports.clearSearch = clearSearch;
+// packages/backend/src/providers-config.ts
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const config_js_1 = require("./config.js");
+/** Resolved on every call so PROVIDERS_CONFIG_PATH can be set per-test. */
+function configPath() {
+    const envPath = process.env.PROVIDERS_CONFIG_PATH?.trim();
+    if (envPath)
+        return path_1.default.resolve(envPath);
+    return path_1.default.join(config_js_1.GRANCLAW_HOME, 'providers.config.json');
+}
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function readConfig() {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(configPath(), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+/** Returns providers map, transparently migrating from legacy `active` format. */
+function getProvidersMap(cfg) {
+    if (cfg.providers)
+        return { ...cfg.providers };
+    if (cfg.active) {
+        return { [cfg.active.provider]: { model: cfg.active.model, apiKey: cfg.active.apiKey } };
+    }
+    return {};
+}
+function writeConfig(cfg, providers) {
+    // Always write in the new format — drop legacy `active` field
+    const { active: _removed, ...rest } = cfg;
+    const dir = path_1.default.dirname(configPath());
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const tmp = configPath() + '.tmp';
+    fs_1.default.writeFileSync(tmp, JSON.stringify({ ...rest, providers }, null, 2));
+    fs_1.default.renameSync(tmp, configPath());
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/** List all configured providers. Never includes apiKey. */
+function listProviders() {
+    const cfg = readConfig();
+    const map = getProvidersMap(cfg);
+    return Object.entries(map).map(([provider, entry]) => ({ provider, model: entry.model }));
+}
+/**
+ * Returns { provider, model } for a specific provider, or the first one if no arg.
+ * Never returns the apiKey.
+ */
+function getProvider(provider) {
+    const cfg = readConfig();
+    const map = getProvidersMap(cfg);
+    if (provider) {
+        const entry = map[provider];
+        return entry ? { provider, model: entry.model } : null;
+    }
+    const first = Object.entries(map)[0];
+    return first ? { provider: first[0], model: first[1].model } : null;
+}
+/** Server-side only — returns the raw API key for a specific provider (or first). */
+function getProviderApiKey(provider) {
+    const cfg = readConfig();
+    const map = getProvidersMap(cfg);
+    if (provider)
+        return map[provider]?.apiKey ?? null;
+    return Object.values(map)[0]?.apiKey ?? null;
+}
+/** Upsert a provider entry. */
+function saveProvider(provider, model, apiKey) {
+    const cfg = readConfig();
+    const map = getProvidersMap(cfg);
+    map[provider] = { model, apiKey };
+    writeConfig(cfg, map);
+}
+/** Remove a specific provider. No-op if not found. */
+function removeProvider(provider) {
+    const cfg = readConfig();
+    const map = getProvidersMap(cfg);
+    delete map[provider];
+    writeConfig(cfg, map);
+}
+/** Remove all provider configs. */
+function clearProvider() {
+    const cfg = readConfig();
+    writeConfig(cfg, {});
+}
+/** Returns the Brave Search API key, or null if not configured. */
+function getSearchApiKey() {
+    try {
+        const raw = fs_1.default.readFileSync(configPath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed.search?.apiKey ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveSearch(apiKey) {
+    let existing = {};
+    try {
+        existing = JSON.parse(fs_1.default.readFileSync(configPath(), 'utf8'));
+    }
+    catch { /* first write */ }
+    const dir = path_1.default.dirname(configPath());
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const tmp = configPath() + '.tmp';
+    fs_1.default.writeFileSync(tmp, JSON.stringify({ ...existing, search: { provider: 'brave', apiKey } }, null, 2));
+    fs_1.default.renameSync(tmp, configPath());
+}
+function clearSearch() {
+    let existing = {};
+    try {
+        existing = JSON.parse(fs_1.default.readFileSync(configPath(), 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const { search: _removed, ...rest } = existing;
+    const dir = path_1.default.dirname(configPath());
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const tmp = configPath() + '.tmp';
+    fs_1.default.writeFileSync(tmp, JSON.stringify(rest, null, 2));
+    fs_1.default.renameSync(tmp, configPath());
+}

package/dist/backend/routes/logs.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const express_1 = require("express");
+const logs_db_js_1 = require("../logs-db.js");
+const router = (0, express_1.Router)();
+// GET /logs?agentId=&type=&search=&from=<epoch_ms>&to=<epoch_ms>&limit=50&offset=0
+router.get('/', (req, res) => {
+    const { agentId, type, search, from, to, limit = '50', offset = '0' } = req.query;
+    const result = (0, logs_db_js_1.queryActions)({
+        agentId: agentId,
+        type: type,
+        search: search,
+        from: from ? Number(from) : undefined,
+        to: to ? Number(to) : undefined,
+        limit: Number(limit),
+        offset: Number(offset),
+    });
+    res.json({ ...result, limit: Number(limit), offset: Number(offset) });
+});
+exports.default = router;

package/dist/backend/scheduler.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * scheduler.ts
+ *
+ * Runs inside the orchestrator process. Every 60 seconds, checks all
+ * active schedules across all agents. When a schedule is due, enqueues
+ * the message into the agent's job queue.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startScheduler = startScheduler;
+exports.stopScheduler = stopScheduler;
+const cron_parser_1 = require("cron-parser");
+const path_1 = __importDefault(require("path"));
+const agent_manager_js_1 = require("./orchestrator/agent-manager.js");
+const schedules_db_js_1 = require("./schedules-db.js");
+const agent_db_js_1 = require("./agent-db.js");
+const config_js_1 = require("./config.js");
+const POLL_INTERVAL_MS = 60_000;
+function getNextRun(cronExpr, timezone) {
+    const interval = (0, cron_parser_1.parseExpression)(cronExpr, { tz: timezone });
+    return interval.next().getTime();
+}
+function tick() {
+    const agents = (0, agent_manager_js_1.getManagedAgents)();
+    for (const managed of agents) {
+        const agentId = managed.config.id;
+        let due;
+        try {
+            due = (0, schedules_db_js_1.getDueSchedules)(agentId);
+        }
+        catch {
+            continue; // DB not yet created for this agent
+        }
+        for (const schedule of due) {
+            const workspaceDir = path_1.default.resolve(config_js_1.REPO_ROOT, managed.config.workspaceDir);
+            (0, agent_db_js_1.enqueue)(workspaceDir, agentId, schedule.message, 'schedule');
+            console.log(`[scheduler] triggered "${schedule.name}" for agent "${agentId}"`);
+            let nextRun;
+            try {
+                nextRun = getNextRun(schedule.cron, schedule.timezone);
+            }
+            catch {
+                console.error(`[scheduler] invalid cron "${schedule.cron}" for schedule ${schedule.id}, pausing`);
+                (0, schedules_db_js_1.updateSchedule)(agentId, schedule.id, { status: 'paused' });
+                continue;
+            }
+            (0, schedules_db_js_1.updateSchedule)(agentId, schedule.id, { lastRun: Date.now(), nextRun });
+        }
+    }
+}
+let intervalHandle = null;
+function startScheduler() {
+    if (intervalHandle)
+        return;
+    console.log(`[scheduler] started (polling every ${POLL_INTERVAL_MS / 1000}s)`);
+    intervalHandle = setInterval(tick, POLL_INTERVAL_MS);
+}
+function stopScheduler() {
+    if (intervalHandle) {
+        clearInterval(intervalHandle);
+        intervalHandle = null;
+    }
+}

package/dist/backend/schedules-db.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * schedules-db.ts
+ *
+ * Per-agent SQLite store for cron schedules.
+ * Backed by <workspaceDir>/agent.sqlite (shared via workspace-pool).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSchedules = listSchedules;
+exports.getSchedule = getSchedule;
+exports.createSchedule = createSchedule;
+exports.updateSchedule = updateSchedule;
+exports.deleteSchedule = deleteSchedule;
+exports.getDueSchedules = getDueSchedules;
+exports.createScheduleRun = createScheduleRun;
+exports.listScheduleRuns = listScheduleRuns;
+exports.closeSchedulesDb = closeSchedulesDb;
+const path_1 = __importDefault(require("path"));
+const crypto_1 = require("crypto");
+const config_js_1 = require("./config.js");
+const workspace_pool_js_1 = require("./workspace-pool.js");
+// ── Internal DB accessor ──────────────────────────────────────────────────
+function getDb(agentId) {
+    const agent = (0, config_js_1.getAgent)(agentId);
+    if (!agent)
+        throw new Error(`Agent "${agentId}" not found in config`);
+    return (0, workspace_pool_js_1.getWorkspaceDb)(path_1.default.resolve(config_js_1.REPO_ROOT, agent.workspaceDir));
+}
+// ── Row mapper ────────────────────────────────────────────────────────────
+function rowToSchedule(r) {
+    return {
+        id: r.id,
+        agentId: r.agent_id,
+        name: r.name,
+        message: r.message,
+        cron: r.cron,
+        timezone: r.timezone,
+        status: r.status,
+        nextRun: r.next_run ?? null,
+        lastRun: r.last_run ?? null,
+        createdAt: r.created_at,
+    };
+}
+// ── ID generation ─────────────────────────────────────────────────────────
+function nextScheduleId(db) {
+    const row = db.prepare(`SELECT COALESCE(MAX(CAST(SUBSTR(id, 5) AS INTEGER)), 0) + 1 AS next FROM schedules`).get();
+    return `SCH-${String(row.next).padStart(3, '0')}`;
+}
+// ── CRUD ──────────────────────────────────────────────────────────────────
+function listSchedules(agentId) {
+    const db = getDb(agentId);
+    return db.prepare(`SELECT * FROM schedules WHERE agent_id = ? ORDER BY created_at DESC`).all(agentId).map(rowToSchedule);
+}
+function getSchedule(agentId, scheduleId) {
+    const db = getDb(agentId);
+    const row = db.prepare(`SELECT * FROM schedules WHERE id = ? AND agent_id = ?`).get(scheduleId, agentId);
+    return row ? rowToSchedule(row) : null;
+}
+function createSchedule(agentId, data) {
+    const db = getDb(agentId);
+    const id = nextScheduleId(db);
+    const now = Date.now();
+    db.prepare(`
+    INSERT INTO schedules (id, agent_id, name, message, cron, timezone, status, next_run, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, 'active', ?, ?)
+  `).run(id, agentId, data.name, data.message, data.cron, data.timezone ?? 'Asia/Singapore', data.nextRun, now);
+    return getSchedule(agentId, id);
+}
+function updateSchedule(agentId, scheduleId, data) {
+    const db = getDb(agentId);
+    const existing = getSchedule(agentId, scheduleId);
+    if (!existing)
+        return null;
+    db.prepare(`
+    UPDATE schedules SET name = ?, message = ?, cron = ?, timezone = ?, status = ?, next_run = ?, last_run = ?
+    WHERE id = ? AND agent_id = ?
+  `).run(data.name ?? existing.name, data.message ?? existing.message, data.cron ?? existing.cron, data.timezone ?? existing.timezone, data.status ?? existing.status, data.nextRun ?? existing.nextRun, data.lastRun ?? existing.lastRun, scheduleId, agentId);
+    return getSchedule(agentId, scheduleId);
+}
+function deleteSchedule(agentId, scheduleId) {
+    const db = getDb(agentId);
+    const result = db.prepare(`DELETE FROM schedules WHERE id = ? AND agent_id = ?`).run(scheduleId, agentId);
+    return result.changes > 0;
+}
+function getDueSchedules(agentId) {
+    const db = getDb(agentId);
+    const now = Date.now();
+    return db.prepare(`SELECT * FROM schedules WHERE agent_id = ? AND status = 'active' AND next_run IS NOT NULL AND next_run <= ?`).all(agentId, now).map(rowToSchedule);
+}
+// ── Schedule Runs ─────────────────────────────────────────────────────────
+function createScheduleRun(agentId, scheduleId) {
+    const db = getDb(agentId);
+    const id = (0, crypto_1.randomUUID)();
+    const channelId = `sch-${id}`;
+    const startedAt = Date.now();
+    db.prepare(`
+    INSERT INTO schedule_runs (id, schedule_id, agent_id, channel_id, started_at)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(id, scheduleId, agentId, channelId, startedAt);
+    return { id, scheduleId, agentId, channelId, startedAt };
+}
+function listScheduleRuns(agentId, scheduleId, limit = 20) {
+    const db = getDb(agentId);
+    const rows = db.prepare(`
+    SELECT id, schedule_id, agent_id, channel_id, started_at
+    FROM schedule_runs
+    WHERE schedule_id = ? AND agent_id = ?
+    ORDER BY started_at DESC
+    LIMIT ?
+  `).all(scheduleId, agentId, limit);
+    return rows.map(r => ({
+        id: r.id, scheduleId: r.schedule_id, agentId: r.agent_id,
+        channelId: r.channel_id, startedAt: r.started_at,
+    }));
+}
+// ── Lifecycle ─────────────────────────────────────────────────────────────
+function closeSchedulesDb(agentId) {
+    const agent = (0, config_js_1.getAgent)(agentId);
+    if (!agent)
+        return;
+    (0, workspace_pool_js_1.closeWorkspaceDb)(path_1.default.resolve(config_js_1.REPO_ROOT, agent.workspaceDir));
+}

package/dist/backend/secrets-vault.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * secrets-vault.ts
+ *
+ * Per-agent secrets store.
+ * Backed by data/system.sqlite (shared global DB via getDataDb()).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSecretNames = listSecretNames;
+exports.getSecrets = getSecrets;
+exports.setSecret = setSecret;
+exports.deleteSecret = deleteSecret;
+exports.deleteAllSecrets = deleteAllSecrets;
+const data_db_js_1 = require("./data-db.js");
+function listSecretNames(agentId) {
+    return (0, data_db_js_1.getDataDb)().prepare(`SELECT name FROM secrets WHERE agent_id = ? ORDER BY created_at`).all(agentId).map((r) => r.name);
+}
+function getSecrets(agentId) {
+    const rows = (0, data_db_js_1.getDataDb)().prepare(`SELECT name, value FROM secrets WHERE agent_id = ?`).all(agentId);
+    return Object.fromEntries(rows.map((r) => [r.name, r.value]));
+}
+function setSecret(agentId, name, value) {
+    (0, data_db_js_1.getDataDb)().prepare(`
+    INSERT INTO secrets (agent_id, name, value) VALUES (?, ?, ?)
+    ON CONFLICT(agent_id, name) DO UPDATE SET value = excluded.value
+  `).run(agentId, name, value);
+}
+function deleteSecret(agentId, name) {
+    (0, data_db_js_1.getDataDb)().prepare(`DELETE FROM secrets WHERE agent_id = ? AND name = ?`).run(agentId, name);
+}
+function deleteAllSecrets(agentId) {
+    (0, data_db_js_1.getDataDb)().prepare(`DELETE FROM secrets WHERE agent_id = ?`).run(agentId);
+}

package/dist/backend/takeover-messages.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * takeover-messages.ts
+ *
+ * System messages sent back to the agent when a human browser takeover
+ * finishes. Two paths:
+ *
+ *   1. User clicked Completed — may include an optional note describing
+ *      what they did. Built by `formatTakeoverResumeMessage`.
+ *   2. 10-minute timeout — user never clicked Done. See TAKEOVER_TIMEOUT_MESSAGE
+ *      re-exported here for a single "where takeover messages live" home.
+ *
+ * Extracted so tests can pin the exact wire format — agents parse these
+ * strings (or their prompts do), so format drift is a silent regression.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAKEOVER_TIMEOUT_MESSAGE = void 0;
+exports.formatTakeoverResumeMessage = formatTakeoverResumeMessage;
+var takeover_timeout_js_1 = require("./takeover-timeout.js");
+Object.defineProperty(exports, "TAKEOVER_TIMEOUT_MESSAGE", { enumerable: true, get: function () { return takeover_timeout_js_1.TAKEOVER_TIMEOUT_MESSAGE; } });
+/** Hard cap on note length — prevents abuse from a long submission. */
+const MAX_NOTE_LENGTH = 2000;
+/**
+ * Build the system message sent to the agent when the user clicks
+ * "Completed" on the takeover page.
+ *
+ * The agent sees this message in its conversation stream and can decide
+ * what to do next. The format is:
+ *
+ *   [User completed browser takeover. Note: "they typed this"]
+ *
+ * or, if no note:
+ *
+ *   [User completed browser takeover with no note]
+ *
+ * The note is JSON-encoded so quote characters inside the note can't
+ * confuse prompt parsing.
+ */
+function formatTakeoverResumeMessage(rawNote) {
+    const stringNote = typeof rawNote === 'string' ? rawNote.trim() : '';
+    const note = stringNote.slice(0, MAX_NOTE_LENGTH);
+    return note
+        ? `[User completed browser takeover. Note: ${JSON.stringify(note)}]`
+        : '[User completed browser takeover with no note]';
+}

package/dist/backend/takeover-state.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAKEOVER_TIMEOUT_MS = void 0;
+exports.getTakeoverByTokenFromDb = getTakeoverByTokenFromDb;
+exports.clearTakeoverFromDb = clearTakeoverFromDb;
+exports.setTakeover = setTakeover;
+exports.getTakeover = getTakeover;
+exports.getTakeoverByToken = getTakeoverByToken;
+exports.hasTakeover = hasTakeover;
+exports.cancelTakeoverTimer = cancelTakeoverTimer;
+exports.clearTakeover = clearTakeover;
+exports.updateTakeoverTimer = updateTakeoverTimer;
+const data_db_js_1 = require("./data-db.js");
+exports.TAKEOVER_TIMEOUT_MS = 10 * 60 * 1000; // 10 minutes
+// ── In-memory state (agent process only — handle + timer can't be serialized) ──
+const byAgent = new Map();
+const byToken = new Map(); // token → agentId
+// ── SQLite helpers (cross-process) ─────────────────────────────────────────────
+function dbInsert(entry) {
+    try {
+        (0, data_db_js_1.getDataDb)().prepare(`
+      INSERT OR REPLACE INTO takeovers (token, agent_id, channel_id, session_id, reason, url, requested_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(entry.token, entry.agentId, entry.channelId, entry.handle.sessionId, entry.reason, entry.url ?? null, entry.requestedAt);
+    }
+    catch (err) {
+        console.error('[takeover-state] dbInsert failed', err);
+    }
+}
+function dbDeleteByAgent(agentId) {
+    try {
+        (0, data_db_js_1.getDataDb)().prepare(`DELETE FROM takeovers WHERE agent_id = ?`).run(agentId);
+    }
+    catch (err) {
+        console.error('[takeover-state] dbDeleteByAgent failed', err);
+    }
+}
+/** Look up a takeover by token from SQLite — usable from any process. */
+function getTakeoverByTokenFromDb(token) {
+    try {
+        const row = (0, data_db_js_1.getDataDb)().prepare(`SELECT token, agent_id, channel_id, session_id, reason, url, requested_at FROM takeovers WHERE token = ?`).get(token);
+        return row ?? null;
+    }
+    catch (err) {
+        console.error('[takeover-state] getTakeoverByTokenFromDb failed', err);
+        return null;
+    }
+}
+/** Delete a takeover by agent ID from SQLite — usable from any process. */
+function clearTakeoverFromDb(agentId) {
+    dbDeleteByAgent(agentId);
+}
+// ── In-memory API (agent process only) ─────────────────────────────────────────
+function setTakeover(agentId, entry) {
+    const existing = byAgent.get(agentId);
+    if (existing) {
+        if (existing.timer)
+            clearTimeout(existing.timer);
+        byToken.delete(existing.token);
+    }
+    byAgent.set(agentId, { ...entry, timer: null });
+    byToken.set(entry.token, agentId);
+    dbInsert(entry);
+}
+function getTakeover(agentId) {
+    return byAgent.get(agentId) ?? null;
+}
+function getTakeoverByToken(token) {
+    const agentId = byToken.get(token);
+    if (!agentId)
+        return null;
+    return byAgent.get(agentId) ?? null;
+}
+function hasTakeover(agentId) {
+    return byAgent.has(agentId);
+}
+function cancelTakeoverTimer(agentId) {
+    const entry = byAgent.get(agentId);
+    if (entry?.timer) {
+        clearTimeout(entry.timer);
+        entry.timer = null;
+    }
+}
+function clearTakeover(agentId) {
+    const entry = byAgent.get(agentId);
+    if (!entry)
+        return;
+    if (entry.timer)
+        clearTimeout(entry.timer);
+    byToken.delete(entry.token);
+    byAgent.delete(agentId);
+    dbDeleteByAgent(agentId);
+}
+function updateTakeoverTimer(agentId, timer) {
+    const entry = byAgent.get(agentId);
+    if (entry) {
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.timer = timer;
+    }
+}

package/dist/backend/takeover-timeout.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * takeover-timeout.ts
+ *
+ * Helper for the human-browser-takeover 10-minute timeout path.
+ *
+ * Extracted from agent/process.ts so it can be unit tested without spinning
+ * up an agent subprocess. The timer itself is still armed by process.ts —
+ * this module only owns the callback body: the set of side effects that
+ * should happen when the user walks away from the takeover tab.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TAKEOVER_TIMEOUT_MESSAGE = void 0;
+exports.handleTakeoverTimeout = handleTakeoverTimeout;
+const takeover_state_js_1 = require("./takeover-state.js");
+const session_manager_js_1 = require("./browser/session-manager.js");
+const agent_db_js_1 = require("./agent-db.js");
+exports.TAKEOVER_TIMEOUT_MESSAGE = '[System] The user did not take any browser action within 10 minutes. ' +
+    'The browser session has been closed. Please proceed to the next step or finish gracefully.';
+const defaultDeps = {
+    getTakeover: takeover_state_js_1.getTakeover,
+    clearTakeover: takeover_state_js_1.clearTakeover,
+    finalizeSession: session_manager_js_1.finalizeSession,
+    enqueue: agent_db_js_1.enqueue,
+};
+/**
+ * Run the takeover timeout side effects. Called from the `setTimeout` in
+ * process.ts after TAKEOVER_TIMEOUT_MS elapses.
+ *
+ * Behaviour:
+ *   1. If the takeover has already been resolved (user clicked Done), return
+ *      early — no-op.
+ *   2. Otherwise: clear the takeover, finalize the browser session (best
+ *      effort), and enqueue a system message telling the agent to move on.
+ *
+ * The function is idempotent: calling it twice for the same agent is safe,
+ * the second call finds no entry and returns early.
+ */
+async function handleTakeoverTimeout(agentId, workspaceDir, deps = defaultDeps) {
+    const current = deps.getTakeover(agentId);
+    if (!current)
+        return; // already resolved by user reply
+    deps.clearTakeover(agentId);
+    try {
+        await deps.finalizeSession(current.handle, 'closed');
+    }
+    catch {
+        // best effort — recording cleanup failure shouldn't block the system message
+    }
+    deps.enqueue(workspaceDir, agentId, exports.TAKEOVER_TIMEOUT_MESSAGE, current.channelId);
+}