@inetafrica/open-claudia 3.5.19 → 3.5.20

package/core/browser-control.js

@@ -0,0 +1,540 @@
+// Take over (SPEC "Bot apps v1", contracts C2, C3, C6, and the HTTP side of C4): a person drives
+// the bot's own browser from Kazee Chat's Browser app, through Agent Space (the front door).
+//
+// core/browser-view.js stays watch-only; driving lives here:
+//   - take / renew / release a driver lock (core/browser-lock.js). While it is live the bot's own
+//     agent-browser commands are refused (core/tool-guard.js) and only the driver's input reaches
+//     the browser. It lasts 120 s; the page's heartbeat and every accepted input extend it.
+//   - one input WebSocket per agent-browser session (ws://127.0.0.1:<port>/?maxFps=2): events
+//     are checked strictly, field by field, and forwarded in order. The same socket keeps the
+//     latest frame, which Teach me saves as a click's picture.
+//   - hand back (release, a closed panel, or a lock found expired by the 30 s sweeper): the lock
+//     goes, the socket closes, any recording stops, and the bot is woken in the person's own chat
+//     to carry on (C6). A recording stopped at the same time folds into one wake-up.
+//
+// Every route answers { status, body }; web.js writes it. Agent Space reaches these routes with
+// the control token only.
+
+const WebSocket = require("ws");
+const lockFile = require("./browser-lock");
+const view = require("./browser-view");
+const teach = require("./browser-teach");
+
+const LOCK_TTL_MS = lockFile.LOCK_TTL_MS;
+// Inputs extend the lock; the file (fsynced) is rewritten at most this often, so the lock ends
+// within a second of 120 s after the last input.
+const LOCK_REWRITE_MS = 1000;
+const SWEEP_INTERVAL_MS = 30 * 1000;
+const SOCKET_OPEN_TIMEOUT_MS = 3000;
+const INPUT_MAX_FPS = 2;
+const MAX_EVENTS = 50;
+const MAX_PENDING_EVENTS = 1000;
+const COORD_MAX = 10000;
+const ID_RE = /^[A-Za-z0-9._:-]{1,100}$/;
+
+const HAND_BACK_REASONS = {
+  closed: " (they closed the Browser)",
+  expired: " (their Browser went quiet for 2 minutes, so control came back on its own)",
+};
+
+let deps = {
+  now: () => Date.now(),
+  listSessions: () => view.listSessions(),
+  connect: (url) => new WebSocket(url),
+  scheduler: null, // core/scheduler by default (through core/cards.js wakeOrigin)
+  runFor: null, // the chat's provider, settings and live session; activeRun() by default
+};
+
+function reply(status, body) {
+  return { status, body };
+}
+
+function iso(ms) {
+  return new Date(ms).toISOString();
+}
+
+function validSession(name) {
+  return typeof name === "string" && view.SESSION_NAME.test(name);
+}
+
+function validId(value) {
+  return (typeof value === "string" || typeof value === "number") && ID_RE.test(String(value));
+}
+
+function validWho(who, { needChat = false } = {}) {
+  if (!who || typeof who !== "object" || !validId(who.userId)) return false;
+  return !needChat || validId(who.chatId);
+}
+
+function sameUser(lock, who) {
+  return !!lock && !!who && String(lock.userId) === String(who.userId);
+}
+
+// ---------------------------------------------------------------------------
+// C3: input events, checked field by field. Only the listed fields are forwarded.
+
+const MOUSE_EVENTS = new Set(["mousePressed", "mouseReleased", "mouseMoved", "mouseWheel"]);
+const MOUSE_BUTTONS = new Set(["none", "left", "middle", "right"]);
+const KEY_EVENTS = new Set(["keyDown", "keyUp", "char"]);
+const TOUCH_EVENTS = new Set(["touchStart", "touchMove", "touchEnd", "touchCancel"]);
+
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const inRange = (v, lo, hi) => isNumber(v) && v >= lo && v <= hi;
+const intIn = (v, lo, hi) => Number.isInteger(v) && v >= lo && v <= hi;
+
+// The event to forward, or null when anything about it is wrong.
+function checkEvent(ev) {
+  if (!ev || typeof ev !== "object" || Array.isArray(ev)) return null;
+  const optional = (out, key, ok) => {
+    if (ev[key] === undefined) return true;
+    if (!ok(ev[key])) return false;
+    out[key] = ev[key];
+    return true;
+  };
+  const modifiers = (v) => intIn(v, 0, 15);
+  if (ev.type === "input_mouse") {
+    if (!MOUSE_EVENTS.has(ev.eventType) || !inRange(ev.x, 0, COORD_MAX) || !inRange(ev.y, 0, COORD_MAX)) return null;
+    const out = { type: "input_mouse", eventType: ev.eventType, x: ev.x, y: ev.y };
+    if (!optional(out, "button", (v) => MOUSE_BUTTONS.has(v))) return null;
+    if (!optional(out, "clickCount", (v) => intIn(v, 0, 3))) return null;
+    if (!optional(out, "modifiers", modifiers)) return null;
+    if (!optional(out, "deltaX", (v) => inRange(v, -COORD_MAX, COORD_MAX))) return null;
+    if (!optional(out, "deltaY", (v) => inRange(v, -COORD_MAX, COORD_MAX))) return null;
+    if (ev.eventType === "mouseWheel") {
+      // The browser wants both deltas on a wheel event; a missing one is no scroll that way.
+      out.deltaX = out.deltaX || 0;
+      out.deltaY = out.deltaY || 0;
+    }
+    return out;
+  }
+  if (ev.type === "input_keyboard") {
+    if (!KEY_EVENTS.has(ev.eventType)) return null;
+    const out = { type: "input_keyboard", eventType: ev.eventType };
+    const short = (max) => (v) => typeof v === "string" && v.length <= max;
+    if (!optional(out, "key", short(32))) return null;
+    if (!optional(out, "code", short(32))) return null;
+    if (!optional(out, "text", short(8))) return null;
+    if (!optional(out, "modifiers", modifiers)) return null;
+    if (!optional(out, "windowsVirtualKeyCode", (v) => intIn(v, 0, 255))) return null;
+    return out;
+  }
+  if (ev.type === "input_touch") {
+    if (!TOUCH_EVENTS.has(ev.eventType) || !Array.isArray(ev.touchPoints) || ev.touchPoints.length > 5) return null;
+    const touchPoints = [];
+    for (const p of ev.touchPoints) {
+      if (!p || typeof p !== "object" || Array.isArray(p) || !isNumber(p.x) || !isNumber(p.y)) return null;
+      const point = { x: p.x, y: p.y };
+      // A touch's identifier keeps fingers apart; Safari's are large integers.
+      if (p.id !== undefined) {
+        if (!intIn(p.id, 0, Number.MAX_SAFE_INTEGER)) return null;
+        point.id = p.id;
+      }
+      touchPoints.push(point);
+    }
+    const out = { type: "input_touch", eventType: ev.eventType, touchPoints };
+    if (!optional(out, "modifiers", modifiers)) return null;
+    return out;
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Input sockets: one per agent-browser session, opened on take (or on the first input after a
+// restart), closed on hand back.
+
+const sockets = new Map();
+
+function sessionInfo(name) {
+  try {
+    return deps.listSessions().find((s) => s.name === name) || null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function openInputSocket(name) {
+  const existing = sockets.get(name);
+  if (existing && !existing.closed) return existing;
+  const info = sessionInfo(name);
+  if (!info) return null;
+  const entry = { name: info.name, dir: info.dir || null, port: info.port, ws: null, open: false, closed: false, frame: null, ready: null };
+  const finish = () => {
+    entry.closed = true;
+    entry.open = false;
+    if (sockets.get(name) === entry) sockets.delete(name);
+  };
+  let ws;
+  try {
+    ws = deps.connect(`ws://127.0.0.1:${info.port}/?maxFps=${INPUT_MAX_FPS}`);
+  } catch (_) {
+    return null;
+  }
+  entry.ws = ws;
+  entry.ready = new Promise((resolve) => {
+    ws.on("open", () => { entry.open = !entry.closed; resolve(entry.open); });
+    ws.on("close", () => { finish(); resolve(false); });
+    ws.on("error", () => {
+      finish();
+      resolve(false);
+      try { ws.terminate(); } catch (_) { /* already down */ }
+    });
+  });
+  // Frames only: the newest one is kept for Teach me's pictures. Page addresses and the rest
+  // are not needed here.
+  ws.on("message", (data) => {
+    let msg;
+    try { msg = JSON.parse(String(data)); } catch (_) { return; }
+    if (msg && msg.type === "frame" && typeof msg.data === "string") {
+      entry.frame = { data: msg.data, metadata: msg.metadata || {}, at: deps.now() };
+    }
+  });
+  sockets.set(name, entry);
+  return entry;
+}
+
+function closeInputSocket(name) {
+  const entry = sockets.get(name);
+  if (!entry) return;
+  sockets.delete(name);
+  entry.closed = true;
+  entry.open = false;
+  entry.frame = null;
+  try { entry.ws.close(); } catch (_) { /* already closed */ }
+}
+
+function socketReady(entry) {
+  if (entry.open) return Promise.resolve(true);
+  if (entry.closed) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve(false), SOCKET_OPEN_TIMEOUT_MS);
+    if (timer.unref) timer.unref();
+    entry.ready.then((ok) => { clearTimeout(timer); resolve(ok); });
+  });
+}
+
+// One queue per session: input batches, and the recording changes that must not cut a batch
+// in half (stop, cancel, hand back), run strictly in arrival order.
+const queues = new Map();
+
+function runQueued(name, count, fn) {
+  let q = queues.get(name);
+  if (!q) {
+    q = { tail: Promise.resolve(), pending: 0 };
+    queues.set(name, q);
+  }
+  if (count > 0 && q.pending + count > MAX_PENDING_EVENTS) return null;
+  q.pending += count;
+  const job = q.tail.then(() => fn());
+  q.tail = job.then(() => {}, () => {}).then(() => { q.pending -= count; });
+  return job;
+}
+
+// ---------------------------------------------------------------------------
+// C6: waking the bot in the person's direct chat
+
+function kazeeAdapterId() {
+  try {
+    const adapter = require("./adapter-registry").getAdapters().find((a) => a && a.type === "kazee");
+    return adapter ? adapter.id : "";
+  } catch (_) {
+    return "";
+  }
+}
+
+// The provider this chat runs on now (the room's choice, else the person's), its settings, and
+// the chat's live session, so the wake-up carries on the same conversation.
+function activeRun({ chatId, userId, canonicalUserId, project }) {
+  const { runInChat } = require("./context");
+  const state = require("./state");
+  return runInChat({ channelId: String(chatId), canonicalUserId, userId: String(userId), transport: "kazee", conversationKey: project, roomKey: project }, () => {
+    const st = state.getUserState(canonicalUserId);
+    let provider = state.getActiveProvider(st);
+    if (!provider) {
+      try { provider = require("./providers").selectDefaultProvider().providerId || null; } catch (_) { provider = null; }
+    }
+    let providerSettings = {};
+    let sessionId = null;
+    if (provider) {
+      try { providerSettings = structuredClone(state.resolveProviderSettings(st, provider) || {}); } catch (_) { providerSettings = {}; }
+      try { sessionId = state.getProviderSession(st, provider, project) || null; } catch (_) { sessionId = null; }
+    }
+    return { provider, providerSettings, sessionId };
+  });
+}
+
+function chatOrigin({ chatId, userId }) {
+  const { conversationKeyFor, canonicalForChannel } = require("./identity");
+  const project = conversationKeyFor("kazee", chatId, null);
+  const canonicalUserId = canonicalForChannel("kazee", userId);
+  const run = (deps.runFor || activeRun)({ chatId: String(chatId), userId: String(userId), canonicalUserId, project }) || {};
+  return {
+    adapter: kazeeAdapterId(),
+    adapterType: "kazee",
+    channelId: String(chatId),
+    threadId: null,
+    canonicalUserId,
+    userId: String(userId),
+    provider: run.provider || null,
+    providerSettings: run.providerSettings || {},
+    project,
+    sessionId: run.sessionId || null,
+  };
+}
+
+function wakeChat({ chatId, userId }, prompt, label) {
+  try {
+    const origin = chatOrigin({ chatId, userId });
+    const opts = { source: "browser" };
+    if (deps.scheduler) opts.scheduler = deps.scheduler;
+    return require("./cards").wakeOrigin(origin, prompt, label, opts);
+  } catch (e) {
+    console.error(`[browser] could not wake the bot in chat ${chatId}: ${e.message}`);
+    return null;
+  }
+}
+
+function handBackLine(name, reason) {
+  const who = teach.cleanName(name) || "Someone";
+  return `[Browser] ${who} handed the browser back${HAND_BACK_REASONS[reason] || ""}. If you were waiting on them, check the page first (it may have changed) and carry on; otherwise just note it.`;
+}
+
+// ---------------------------------------------------------------------------
+// C2: take, renew, release, status
+
+function lockBody(lock) {
+  return { driving: true, driver: { name: lock.name } };
+}
+
+async function take({ session, who } = {}) {
+  if (!validSession(session) || !validWho(who, { needChat: true })) return reply(400, { error: "bad-request" });
+  // A lock that ran out but has not been swept yet is handed back first, the sweeper's way: its
+  // driver's chat is woken and their recording stopped, whoever takes over now.
+  const stale = lockFile.readLock();
+  if (stale && lockFile.lockExpiresAt(stale) <= deps.now()) await handBack(stale, { reason: "expired" });
+  const now = deps.now();
+  const current = lockFile.liveLock(now);
+  if (current && !sameUser(current, who)) return reply(409, lockBody(current));
+  if (!sessionInfo(session)) return reply(404, { driving: false, driver: null, error: "not-running" });
+  if (current && current.session !== session) closeInputSocket(current.session);
+  const lock = {
+    session,
+    userId: String(who.userId),
+    name: teach.cleanName(who.name) || "Someone",
+    chatId: String(who.chatId),
+    since: current && current.session === session ? current.since : iso(now),
+    expiresAt: iso(now + LOCK_TTL_MS),
+  };
+  lockFile.writeLock(lock);
+  openInputSocket(session);
+  return reply(200, lockBody(lock));
+}
+
+function renew({ session, who } = {}) {
+  if (!validWho(who) || (session !== undefined && !validSession(session))) return reply(400, { error: "bad-request" });
+  const now = deps.now();
+  const current = lockFile.liveLock(now);
+  if (!current || !sameUser(current, who) || (session !== undefined && current.session !== session)) {
+    return reply(409, { driving: false, driver: current ? { name: current.name } : null, error: "not-driving" });
+  }
+  current.expiresAt = iso(now + LOCK_TTL_MS);
+  lockFile.writeLock(current);
+  openInputSocket(current.session); // after a restart the socket comes back here
+  return reply(200, lockBody(current));
+}
+
+// Hand the browser back: claim the lock (synchronously, so a release and the sweeper never both
+// act on one lock), close the socket and stop any recording after the input already queued, then
+// wake the bot once.
+async function handBack(expected, { reason = null } = {}) {
+  const current = lockFile.readLock();
+  if (!current || current.userId !== expected.userId || current.session !== expected.session || current.since !== expected.since) return false;
+  lockFile.removeLock();
+  const info = sessionInfo(current.session);
+  let stopped = null;
+  await runQueued(current.session, 0, async () => {
+    closeInputSocket(current.session);
+    try {
+      stopped = await teach.stopRecording(current.userId, { session: info });
+    } catch (e) {
+      console.error(`[browser] stopping the recording on hand back failed: ${e.message}`);
+    }
+  });
+  const line = handBackLine(current.name, reason);
+  if (stopped && !stopped.discarded) wakeChat(current, teach.teachPrompt(stopped, { handBack: line }), "Teach me");
+  else wakeChat(current, line, "Browser");
+  console.log(`[browser] ${current.userId} handed the browser back${reason ? ` (${reason})` : ""}`);
+  return true;
+}
+
+async function release({ session, who, reason } = {}) {
+  if (!validWho(who) || (session !== undefined && !validSession(session))) return reply(400, { error: "bad-request" });
+  const current = lockFile.readLock();
+  if (current && sameUser(current, who) && (session === undefined || current.session === session)) {
+    await handBack(current, { reason: typeof reason === "string" ? reason : null });
+  }
+  return reply(200, { driving: false });
+}
+
+async function control(body = {}) {
+  if (body.action === "take") return take(body);
+  if (body.action === "renew") return renew(body);
+  if (body.action === "release") return release(body);
+  return reply(400, { error: "bad-action" });
+}
+
+function status() {
+  const lock = lockFile.liveLock(deps.now());
+  return reply(200, {
+    driving: !!lock,
+    driver: lock ? { name: lock.name, userId: lock.userId } : null,
+    recording: teach.activeSummary(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// C3: input
+
+async function input({ session, events, who } = {}) {
+  if (!validSession(session) || !validWho(who)) return reply(400, { error: "bad-request" });
+  if (!Array.isArray(events) || events.length > MAX_EVENTS) return reply(400, { error: "bad-events" });
+  const messages = [];
+  for (let i = 0; i < events.length; i += 1) {
+    const msg = checkEvent(events[i]);
+    if (!msg) return reply(400, { error: "bad-event", index: i });
+    messages.push(msg);
+  }
+  const now = deps.now();
+  const lock = lockFile.liveLock(now);
+  if (!lock || lock.session !== session || !sameUser(lock, who)) return reply(409, { error: "not-driving" });
+  // Every accepted input extends the lock; the file is rewritten only every few seconds.
+  if (lockFile.lockExpiresAt(lock) - now < LOCK_TTL_MS - LOCK_REWRITE_MS) {
+    lock.expiresAt = iso(now + LOCK_TTL_MS);
+    lockFile.writeLock(lock);
+  }
+  if (!messages.length) return reply(200, { ok: true, accepted: 0 });
+  const entry = openInputSocket(session);
+  if (!entry) return reply(404, { error: "not-running" });
+  const job = runQueued(session, messages.length, async () => {
+    if (!(await socketReady(entry))) return reply(503, { error: "browser-unavailable", accepted: 0 });
+    const recorder = teach.recorderFor(session, who.userId);
+    let sent = 0;
+    for (const msg of messages) {
+      if (recorder) {
+        try {
+          await recorder.onEvent(msg, { session: { name: entry.name, dir: entry.dir }, frame: entry.frame });
+        } catch (e) {
+          console.error(`[browser] recording a step failed: ${e.message}`);
+        }
+      }
+      if (!entry.open || entry.closed) return reply(503, { error: "browser-unavailable", accepted: sent });
+      entry.ws.send(JSON.stringify(msg));
+      sent += 1;
+    }
+    return reply(200, { ok: true, accepted: sent });
+  });
+  if (!job) return reply(429, { error: "busy" });
+  return job;
+}
+
+// ---------------------------------------------------------------------------
+// C4: Teach me, start / stop / cancel
+
+async function teachAction({ session, action, title, who } = {}) {
+  if (!validWho(who)) return reply(400, { error: "bad-request" });
+  if (action === "start") {
+    if (!validSession(session) || (title !== undefined && title !== null && typeof title !== "string")) return reply(400, { error: "bad-request" });
+    const lock = lockFile.liveLock(deps.now());
+    if (!lock || lock.session !== session || !sameUser(lock, who)) return reply(409, { error: "not-driving" });
+    return runQueued(session, 0, () => {
+      try {
+        const rec = teach.startRecording({
+          session,
+          userId: lock.userId,
+          name: who.name || lock.name,
+          chatId: lock.chatId,
+          title,
+        });
+        console.log(`[browser] ${rec.userId} started recording ${rec.id}`);
+        return reply(200, { recording: teach.summary(rec) });
+      } catch (e) {
+        if (e.code === "already-recording") return reply(409, { error: "already-recording", recording: e.recording || null });
+        throw e;
+      }
+    });
+  }
+  if (action === "stop" || action === "cancel") {
+    const mine = teach.activeOf(who.userId);
+    if (!mine) return reply(404, action === "cancel" ? { cancelled: false, error: "not-recording" } : { error: "not-recording" });
+    if (action === "cancel") {
+      const cancelled = await runQueued(mine.session, 0, () => teach.cancelActive(who.userId));
+      if (cancelled) console.log(`[browser] ${who.userId} cancelled recording ${mine.id}`);
+      return cancelled ? reply(200, { cancelled: true }) : reply(404, { cancelled: false, error: "not-recording" });
+    }
+    const info = sessionInfo(mine.session);
+    const stopped = await runQueued(mine.session, 0, () => teach.stopRecording(who.userId, { session: info }));
+    if (!stopped) return reply(404, { error: "not-recording" });
+    const body = { recording: { id: stopped.id, title: stopped.title, steps: stopped.steps.length } };
+    if (stopped.discarded) body.discarded = true;
+    else wakeChat({ chatId: stopped.chatId, userId: stopped.userId }, teach.teachPrompt(stopped), "Teach me");
+    console.log(`[browser] ${who.userId} stopped recording ${stopped.id} (${stopped.steps.length} steps${stopped.discarded ? ", discarded" : ""})`);
+    return reply(200, body);
+  }
+  return reply(400, { error: "bad-action" });
+}
+
+// ---------------------------------------------------------------------------
+// The sweeper: a lock nobody renewed for 120 s is handed back.
+
+async function sweepLock(now = deps.now()) {
+  const lock = lockFile.readLock();
+  if (!lock || lockFile.lockExpiresAt(lock) > now) return false;
+  return handBack(lock, { reason: "expired" });
+}
+
+let sweepTimer = null;
+function startSweeper({ intervalMs = SWEEP_INTERVAL_MS } = {}) {
+  if (sweepTimer) return sweepTimer;
+  sweepTimer = setInterval(() => {
+    sweepLock().catch((e) => console.error(`[browser] lock sweep failed: ${e.message}`));
+  }, intervalMs);
+  if (sweepTimer.unref) sweepTimer.unref();
+  return sweepTimer;
+}
+
+// Tests swap the clock, the session list, the socket factory, the scheduler and the run lookup.
+function _setDeps(overrides = {}) {
+  deps = { ...deps, ...overrides };
+}
+function _reset() {
+  for (const name of [...sockets.keys()]) closeInputSocket(name);
+  queues.clear();
+  if (sweepTimer) { clearInterval(sweepTimer); sweepTimer = null; }
+  deps = {
+    now: () => Date.now(),
+    listSessions: () => view.listSessions(),
+    connect: (url) => new WebSocket(url),
+    scheduler: null,
+    runFor: null,
+  };
+}
+
+module.exports = {
+  LOCK_TTL_MS,
+  MAX_EVENTS,
+  SWEEP_INTERVAL_MS,
+  checkEvent,
+  chatOrigin,
+  control,
+  handBackLine,
+  input,
+  release,
+  renew,
+  startSweeper,
+  status,
+  sweepLock,
+  take,
+  teachAction,
+  wakeChat,
+  _reset,
+  _setDeps,
+};

package/core/browser-lock.js

@@ -0,0 +1,51 @@
+// The Browser app's driver lock (SPEC contract C2): while a person drives the bot's browser from
+// Kazee Chat, <configDir>/browser-driver.json says who, on which agent-browser session, until
+// when. It is a file because the bot's own agent-browser commands are refused by the tool-guard
+// hook (core/tool-guard.js, C7), which runs as a separate process for every tool call and
+// re-reads it each time, like the tooling-mode switch (core/tooling-mode.js).
+//
+// { session, userId, name, chatId, since, expiresAt }   (ISO times; written atomically, 0600)
+//
+// An expired lock is no lock: it never blocks the bot, and the sweeper in
+// core/browser-control.js hands the browser back.
+
+const fs = require("fs");
+const path = require("path");
+const { atomicWriteFileSync } = require("./fsutil");
+
+const LOCK_TTL_MS = 120 * 1000;
+
+function driverFile() {
+  return process.env.OC_BROWSER_DRIVER_FILE || path.join(require("../config-dir"), "browser-driver.json");
+}
+
+function readLock() {
+  try {
+    const lock = JSON.parse(fs.readFileSync(driverFile(), "utf8"));
+    if (!lock || typeof lock !== "object" || !lock.userId || !lock.session) return null;
+    return lock;
+  } catch (_) {
+    return null;
+  }
+}
+
+function lockExpiresAt(lock) {
+  if (!lock) return 0;
+  const at = typeof lock.expiresAt === "number" ? lock.expiresAt : Date.parse(lock.expiresAt);
+  return Number.isFinite(at) ? at : 0;
+}
+
+function liveLock(now = Date.now()) {
+  const lock = readLock();
+  return lock && lockExpiresAt(lock) > now ? lock : null;
+}
+
+function writeLock(lock) {
+  atomicWriteFileSync(driverFile(), `${JSON.stringify(lock)}\n`, { mode: 0o600 });
+}
+
+function removeLock() {
+  try { fs.rmSync(driverFile(), { force: true }); } catch (_) { /* already gone */ }
+}
+
+module.exports = { LOCK_TTL_MS, driverFile, readLock, lockExpiresAt, liveLock, writeLock, removeLock };