@agentprojectcontext/apx 1.81.0 → 1.89.1

package/src/core/mobility/osm-route.js

@@ -0,0 +1,282 @@
+import { listTasksAcrossProjects } from "#core/stores/tasks.js";
+
+const USER_AGENT = "APX mobility assistant/1.0";
+const RADIUS_METERS = 700;
+
+const NEEDS = [
+  {
+    id: "stationery",
+    query: "papelería",
+    match: /cartulina|papeler[ií]a|cuaderno|l[aá]piz|lapicera|fibra|marcador|impresi[oó]n/i,
+    selectors: ['["shop"~"stationery|books|convenience|kiosk"]'],
+  },
+  {
+    id: "supermarket",
+    query: "supermercado",
+    // "en el súper" is what anyone actually writes, and it matched nothing —
+    // the vocabulary only knew the full word. Article-anchored on purpose:
+    // a bare /súper/ would fire on "súper importante".
+    match: /an[oó]nima|supermercado|mercado|(?:al|el|del) s[uú]per\b|hacer (?:las )?compras|comprar comida|almac[eé]n|\bpan\b|pan lactal/i,
+    selectors: ['["shop"~"supermarket|convenience"]'],
+  },
+  {
+    id: "bakery",
+    query: "panadería",
+    // Bread is the clearest case of an errand with no single answer: the
+    // bakery on the corner and both supermarkets all satisfy it, which is why
+    // it deliberately overlaps the supermarket need above. The trip plan keeps
+    // every candidate and settles on one — see core/mobility/geofence.js.
+    // "pan lactal" is the exception: it is a packaged supermarket product and
+    // a bakery does not carry it, so a bare /\bpan\b/ sent the owner to
+    // panaderías for an errand only a súper can satisfy. Everything else about
+    // bread still overlaps the supermarket need on purpose.
+    match: /\bpan\b(?! *lactal)|panader[ií]a|factura[s]?\b|medialunas?/i,
+    selectors: ['["shop"~"bakery|pastry"]'],
+  },
+  {
+    id: "pharmacy",
+    query: "farmacia",
+    match: /farmacia|medicamento|remedio|receta/i,
+    selectors: ['["amenity"="pharmacy"]'],
+  },
+  {
+    id: "hardware",
+    query: "ferretería",
+    match: /ferreter[ií]a|tornillo|herramienta|pintura/i,
+    selectors: ['["shop"~"hardware|doityourself|paint"]'],
+  },
+  {
+    id: "fuel",
+    query: "estación de servicio",
+    match: /nafta|combustible|cargar tanque|estaci[oó]n de servicio/i,
+    selectors: ['["amenity"="fuel"]'],
+  },
+];
+
+export function activeTasks(projects) {
+  const entries = [];
+  for (const entry of projects?.list?.() || []) {
+    let project;
+    try { project = projects.get(entry.id); } catch { continue; }
+    if (!project?.storagePath) continue;
+    entries.push({ ...entry, storagePath: project.storagePath });
+  }
+  const { tasks } = listTasksAcrossProjects(entries, { limit: 100 });
+  return tasks.filter((task) => !["done", "dropped", "cancelled"].includes(task.status));
+}
+
+export function taskNeeds(task) {
+  const text = `${task.title || ""} ${task.body || ""} ${(task.tags || []).join(" ")}`;
+  return NEEDS.filter((need) => need.match.test(text)).map((need) => ({
+    ...need,
+    query: need.id === "supermarket" && /an[oó]nima/i.test(text) ? "La Anónima" : need.query,
+  }));
+}
+
+async function getJson(url, options = {}, fetchFn = fetch) {
+  const response = await fetchFn(url, {
+    ...options,
+    headers: { "user-agent": USER_AGENT, accept: "application/json", ...(options.headers || {}) },
+    signal: options.signal || AbortSignal.timeout(8_000),
+  });
+  if (!response.ok) throw new Error(`map service HTTP ${response.status}`);
+  return response.json();
+}
+
+export async function geocodeDestination(query, origin, fetchFn = fetch) {
+  if (!query) return null;
+  const params = new URLSearchParams({ format: "jsonv2", limit: "1", countrycodes: "ar", q: query });
+  if (origin) {
+    const delta = 1.5;
+    params.set("viewbox", `${origin.longitude - delta},${origin.latitude + delta},${origin.longitude + delta},${origin.latitude - delta}`);
+    params.set("bounded", "0");
+  }
+  const rows = await getJson(`https://nominatim.openstreetmap.org/search?${params}`, {}, fetchFn);
+  if (!rows?.length) return null;
+  return { latitude: Number(rows[0].lat), longitude: Number(rows[0].lon), label: rows[0].display_name || query };
+}
+
+export async function drivingRoute(origin, destination, fetchFn = fetch) {
+  try {
+    const request = {
+      locations: [
+        { lat: origin.latitude, lon: origin.longitude },
+        { lat: destination.latitude, lon: destination.longitude },
+      ],
+      costing: "auto",
+      directions_options: { units: "kilometers" },
+    };
+    const data = await getJson(`https://valhalla1.openstreetmap.de/route?json=${encodeURIComponent(JSON.stringify(request))}`, {}, fetchFn);
+    const summary = data?.trip?.summary;
+    const shape = data?.trip?.legs?.[0]?.shape;
+    if (summary && shape) {
+      return {
+        distance_m: Number(summary.length) * 1000,
+        duration_s: Number(summary.time),
+        points: decodePolyline(shape),
+      };
+    }
+  } catch { /* fall through to public OSRM endpoints */ }
+  const coords = `${origin.longitude},${origin.latitude};${destination.longitude},${destination.latitude}`;
+  const bases = [
+    "https://routing.openstreetmap.de/routed-car/route/v1/driving",
+    "https://router.project-osrm.org/route/v1/driving",
+  ];
+  for (const base of bases) {
+    try {
+      const data = await getJson(`${base}/${coords}?overview=full&geometries=geojson`, {}, fetchFn);
+      const route = data?.routes?.[0];
+      if (!route?.geometry?.coordinates?.length) continue;
+      return {
+        distance_m: route.distance,
+        duration_s: route.duration,
+        points: route.geometry.coordinates.map(([longitude, latitude]) => ({ latitude, longitude })),
+      };
+    } catch { /* try the next public OSRM endpoint */ }
+  }
+  return null;
+}
+
+export function decodePolyline(encoded, precision = 6) {
+  const factor = 10 ** precision;
+  const points = [];
+  let index = 0;
+  let latitude = 0;
+  let longitude = 0;
+  while (index < encoded.length) {
+    const read = () => {
+      let result = 0;
+      let shift = 0;
+      let byte;
+      do {
+        byte = encoded.charCodeAt(index++) - 63;
+        result |= (byte & 0x1f) << shift;
+        shift += 5;
+      } while (byte >= 0x20 && index <= encoded.length);
+      return (result & 1) ? ~(result >> 1) : result >> 1;
+    };
+    latitude += read();
+    longitude += read();
+    points.push({ latitude: latitude / factor, longitude: longitude / factor });
+  }
+  return points;
+}
+
+/**
+ * Nominatim `viewbox` string (left,top,right,bottom) around a set of points.
+ *
+ * `padDegrees` exists because the live geofence (./geofence.js) searches around
+ * ONE point — the phone's current position — and a box built from a single
+ * point has zero area, which Nominatim answers with nothing at all. A route has
+ * its own extent and needs no padding.
+ */
+export function boundingBox(points, padDegrees = 0) {
+  const latitudes = points.map((point) => point.latitude);
+  const longitudes = points.map((point) => point.longitude);
+  const left = Math.min(...longitudes) - padDegrees;
+  const right = Math.max(...longitudes) + padDegrees;
+  const top = Math.max(...latitudes) + padDegrees;
+  const bottom = Math.min(...latitudes) - padDegrees;
+  return `${left},${top},${right},${bottom}`;
+}
+
+export async function nearbyPois(route, needs, fetchFn = fetch, { padDegrees = 0 } = {}) {
+  if (!route?.points?.length || !needs.length) return [];
+  const viewbox = boundingBox(route.points, padDegrees);
+  const seen = new Set();
+  const rows = [];
+  for (const [index, need] of needs.slice(0, 3).entries()) {
+    if (index > 0 && fetchFn === fetch) await new Promise((resolve) => setTimeout(resolve, 1_100));
+    const params = new URLSearchParams({
+      format: "jsonv2", limit: "15", countrycodes: "ar", bounded: "1", viewbox, q: need.query,
+    });
+    const data = await getJson(`https://nominatim.openstreetmap.org/search?${params}`, {}, fetchFn);
+    for (const element of data || []) {
+      const latitude = Number(element.lat);
+      const longitude = Number(element.lon);
+      if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) continue;
+      const key = `${need.id}:${latitude.toFixed(5)},${longitude.toFixed(5)}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      // Nominatim's display_name is "<name>, <street>, <number>, <city>, …".
+       // The first segment is the name; the REST is the street address, and it
+       // used to be discarded. At the wheel "Farmacia del Puente" is not enough
+       // to find a door — the address is what tells you which corner it is on,
+       // and it is the one thing a spoken alert has to say.
+      const parts = String(element.display_name || need.query).split(",");
+      rows.push({
+        name: parts[0].trim(),
+        address: parts.slice(1).join(",").trim() || null,
+        latitude,
+        longitude,
+        tags: { need_id: need.id },
+      });
+    }
+  }
+  return rows;
+}
+
+export function haversineMeters(a, b) {
+  const radians = (value) => value * Math.PI / 180;
+  const dLat = radians(b.latitude - a.latitude);
+  const dLon = radians(b.longitude - a.longitude);
+  const lat1 = radians(a.latitude);
+  const lat2 = radians(b.latitude);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLon / 2) ** 2;
+  return 6_371_000 * 2 * Math.atan2(Math.sqrt(h), Math.sqrt(1 - h));
+}
+
+function distanceToRoute(poi, route) {
+  return Math.min(...route.points.map((point) => haversineMeters(poi, point)));
+}
+
+function mapLink(poi) {
+  return `https://www.google.com/maps/search/?api=1&query=${poi.latitude},${poi.longitude}`;
+}
+
+function needMatchesPoi(need, poi) {
+  if (poi.tags.need_id) return poi.tags.need_id === need.id;
+  const shop = poi.tags.shop || "";
+  const amenity = poi.tags.amenity || "";
+  if (need.id === "stationery") return /stationery|books|convenience|kiosk/.test(shop);
+  if (need.id === "supermarket") return /supermarket|convenience/.test(shop);
+  if (need.id === "pharmacy") return amenity === "pharmacy";
+  if (need.id === "hardware") return /hardware|doityourself|paint/.test(shop);
+  if (need.id === "fuel") return amenity === "fuel";
+  return false;
+}
+
+export async function enrichMobilityEvent(event, ctx, fetchFn = fetch) {
+  if (!event.origin || !event.destination) return { checked: false, reason: "missing-endpoint", candidates: [] };
+  const tasks = activeTasks(ctx.projects).map((task) => ({ task, needs: taskNeeds(task) })).filter((row) => row.needs.length);
+  if (!tasks.length) return { checked: true, reason: "no-physical-needs", candidates: [] };
+  try {
+    const destination = await geocodeDestination(event.destination, event.origin, fetchFn);
+    if (!destination) return { checked: false, reason: "destination-not-geocoded", candidates: [] };
+    const route = await drivingRoute(event.origin, destination, fetchFn);
+    if (!route) return { checked: false, reason: "route-not-found", candidates: [] };
+    const needs = [...new Map(tasks.flatMap((row) => row.needs).map((need) => [`${need.id}:${need.query}`, need])).values()];
+    const pois = await nearbyPois(route, needs, fetchFn);
+    const candidates = [];
+    for (const row of tasks) {
+      const compatible = pois.filter((poi) => row.needs.some((need) => needMatchesPoi(need, poi)));
+      for (const poi of compatible) {
+        const distance_m = Math.round(distanceToRoute(poi, route));
+        if (distance_m > RADIUS_METERS) continue;
+        candidates.push({ task_id: row.task.id, task: row.task.title, place: poi.name, distance_m, maps_url: mapLink(poi) });
+      }
+    }
+    candidates.sort((a, b) => a.distance_m - b.distance_m);
+    const unique = candidates.filter((candidate, index, all) => all.findIndex((other) => other.task_id === candidate.task_id && other.place === candidate.place) === index);
+    return {
+      checked: true,
+      origin: event.origin,
+      destination,
+      route: { distance_m: route.distance_m, duration_s: route.duration_s },
+      radius_m: RADIUS_METERS,
+      candidates: unique.slice(0, 3),
+    };
+  } catch (error) {
+    return { checked: false, reason: error?.message || String(error), candidates: [] };
+  }
+}

package/src/core/mobility/preferences.js

@@ -0,0 +1,91 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MOBILITY_PATH } from "#core/config/paths.js";
+
+function dayKey(date = new Date()) {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+
+function read() {
+  try {
+    const value = JSON.parse(fs.readFileSync(MOBILITY_PATH, "utf8"));
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function write(value) {
+  fs.mkdirSync(path.dirname(MOBILITY_PATH), { recursive: true });
+  fs.writeFileSync(MOBILITY_PATH, JSON.stringify(value, null, 2));
+}
+
+export function silenceMobilityToday(now = new Date()) {
+  const state = read();
+  state.silent_day = dayKey(now);
+  write(state);
+  return state.silent_day;
+}
+
+export function isMobilitySilentToday(now = new Date()) {
+  return read().silent_day === dayKey(now);
+}
+
+export function isMobilitySilenceCommand(text = "") {
+  const normalized = String(text).toLowerCase().normalize("NFD").replace(/\p{M}+/gu, "");
+  return /(?:no me (?:comentes|avises|molestes)|no (?:comentes|avises)|silencio).*(?:por )?hoy/.test(normalized);
+}
+
+export function _resetMobilityPreferencesForTest() {
+  try { fs.rmSync(MOBILITY_PATH, { force: true }); } catch { /* nothing to remove */ }
+}
+
+// ── where a mobility reminder is delivered ──────────────────────────────────
+//
+// It used to be "Telegram, always", because Telegram was the only surface that
+// could draw a card with buttons. That is no longer true: the alert is its own
+// frame on the events socket and the phone renders it natively, so the Telegram
+// copy became a second notification for the same event — which is how a chat
+// used for everything else fills up with driving reminders.
+//
+// APP IS THE DEFAULT. The reminder is for someone at the wheel, and the surface
+// they are looking at is the phone in the cradle or the head unit, not a chat.
+
+/** Every delivery surface a mobility reminder can use. */
+export const MOBILITY_SURFACES = Object.freeze(["app", "telegram"]);
+
+/** What ships when nothing is configured. */
+export const DEFAULT_MOBILITY_SURFACES = Object.freeze(["app"]);
+
+/**
+ * Which surfaces this install delivers mobility reminders on.
+ *
+ * Accepts what a person would plausibly write in config.json or type at the
+ * CLI: a list, a single string, "both", or "none" to turn reminders off
+ * without unpairing anything.
+ *
+ *   config.mobility.notify = "app" | "telegram" | "both" | "none" | [..]
+ *
+ * Anything unrecognised falls back to the default rather than delivering
+ * nowhere — a typo in a config file must not silently disable the alerts.
+ *
+ * @returns {{app: boolean, telegram: boolean}}
+ */
+export function mobilitySurfaces(globalConfig) {
+  const raw = globalConfig?.mobility?.notify;
+  if (raw === "none" || (Array.isArray(raw) && raw.length === 0)) {
+    return { app: false, telegram: false };
+  }
+  const list = raw === "both"
+    ? MOBILITY_SURFACES
+    : Array.isArray(raw)
+      ? raw
+      : typeof raw === "string" && raw.trim()
+        ? [raw]
+        : DEFAULT_MOBILITY_SURFACES;
+  const wanted = list
+    .map((s) => String(s || "").trim().toLowerCase())
+    .filter((s) => MOBILITY_SURFACES.includes(s));
+  const chosen = wanted.length ? wanted : DEFAULT_MOBILITY_SURFACES;
+  return { app: chosen.includes("app"), telegram: chosen.includes("telegram") };
+}

package/src/core/mobility/state.js

@@ -0,0 +1,245 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MOBILITY_PATH } from "#core/config/paths.js";
+
+const RECENT_QUESTION_MS = 20 * 60_000;
+
+let current = null;
+let lastQuestion = null;
+let lastResponse = null;
+let alerts = [];
+let loadedPath = null;
+
+// A proximity alert outlives the trip that produced it: the follow-up ("did you
+// actually stop there?") is asked once the driving is over. So the log is
+// persisted, not just held in memory — a daemon restart mid-trip must not
+// re-announce a place the owner was already told about. Bounded, because this
+// is a reminder log and not a location history.
+const MAX_ALERTS = 50;
+
+function clean(value, max = 900) {
+  return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+
+function readFile() {
+  try {
+    const value = JSON.parse(fs.readFileSync(MOBILITY_PATH, "utf8"));
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function ensureLoaded() {
+  if (loadedPath === MOBILITY_PATH) return;
+  const file = readFile();
+  const saved = file.mobility_context || {};
+  current = saved.trip || null;
+  lastQuestion = saved.last_question || null;
+  lastResponse = saved.last_response || null;
+  alerts = Array.isArray(file.mobility_alerts) ? file.mobility_alerts : [];
+  loadedPath = MOBILITY_PATH;
+}
+
+function persist() {
+  const state = readFile();
+  state.mobility_context = {
+    trip: current,
+    last_question: lastQuestion,
+    last_response: lastResponse,
+  };
+  state.mobility_alerts = alerts.slice(-MAX_ALERTS);
+  fs.mkdirSync(path.dirname(MOBILITY_PATH), { recursive: true });
+  fs.writeFileSync(MOBILITY_PATH, JSON.stringify(state, null, 2));
+}
+
+export function observeMobilityEvent(event, now = Date.now()) {
+  ensureLoaded();
+  if (!event || event.duplicate) return;
+  if (event.type === "trip.ended") {
+    if (!current || !event.trip_id || current.trip_id === event.trip_id) {
+      current = current ? { ...current, active: false, ended_at: event.occurred_at } : null;
+    }
+    persist();
+    return;
+  }
+  if (event.type !== "trip.started") return;
+  current = {
+    active: true,
+    trip_id: clean(event.trip_id, 100),
+    destination: clean(event.destination, 300),
+    origin: event.origin || null,
+    started_at: clean(event.occurred_at, 50) || new Date(now).toISOString(),
+    observed_at: new Date(now).toISOString(),
+  };
+  persist();
+}
+
+export function recordMobilityQuestion(message, now = Date.now()) {
+  ensureLoaded();
+  lastQuestion = { text: clean(message), at: new Date(now).toISOString(), at_ms: now };
+  persist();
+}
+
+export function recordMobilityResponse(action, now = Date.now()) {
+  ensureLoaded();
+  lastResponse = { action: clean(action, 40), at: new Date(now).toISOString(), at_ms: now };
+  persist();
+}
+
+export function mobilityQuestionIsRecent(now = Date.now()) {
+  ensureLoaded();
+  return Boolean(lastQuestion && now - lastQuestion.at_ms < RECENT_QUESTION_MS);
+}
+
+export function mobilityContext() {
+  ensureLoaded();
+  return {
+    trip: current ? { ...current } : null,
+    last_question: lastQuestion ? { text: lastQuestion.text, at: lastQuestion.at } : null,
+    last_response: lastResponse ? { action: lastResponse.action, at: lastResponse.at } : null,
+  };
+}
+
+export function mobilityContextBlock() {
+  const state = mobilityContext();
+  if (!state.trip && !state.last_question && !state.last_response) return "";
+  const lines = [
+    "[CONTEXTO DE MOVILIDAD]",
+    state.trip
+      ? `Viaje: ${state.trip.active ? "activo" : "finalizado"}; destino: ${state.trip.destination || "desconocido"}; inicio: ${state.trip.started_at || "desconocido"}.`
+      : "Viaje: sin datos.",
+  ];
+  if (state.last_question) lines.push(`Última pregunta de Roby: ${state.last_question.text} (${state.last_question.at}).`);
+  if (state.last_response) lines.push(`Última respuesta del usuario: ${state.last_response.action} (${state.last_response.at}).`);
+  lines.push("Usá este estado como contexto de secretaria. No anuncies el viaje ni repitas preguntas solo porque el estado cambió.");
+  return lines.join("\n");
+}
+
+/**
+ * The identity of a proximity alert: one ERRAND, on one trip.
+ *
+ * Deliberately NOT keyed on the place. "Buy ibuprofen at a pharmacy" is one
+ * errand; the nearest pharmacy is its answer, not thirteen separate reminders.
+ * A drive through Bariloche found fifteen matching shops for two tasks and sent
+ * eight Telegram messages in ninety seconds — the per-place key was the bug.
+ * Once the owner has been told where to stop for something, they have been
+ * told.
+ */
+export function mobilityAlertKey(tripId, taskId) {
+  return `${clean(tripId, 100)}|${clean(taskId, 100)}`;
+}
+
+/**
+ * Has this errand already been announced on this trip?
+ *
+ * One exception, and it is the owner's own doing: an alert answered "next"
+ * ("avisar en la siguiente") does not count as having announced the errand. It
+ * declined ONE shop, not the errand — so the errand is owed another reminder if
+ * a different shop that satisfies it turns up later in the drive.
+ *
+ * That does not re-open the spam this key exists to close. The default is
+ * unchanged: told once, done. Every extra reminder past the first costs a
+ * deliberate button press, one at a time, and only ever names a place the owner
+ * has not already waved past (see declinedMobilityPlaces).
+ */
+export function mobilityAlertFired(tripId, taskId) {
+  ensureLoaded();
+  const key = mobilityAlertKey(tripId, taskId);
+  return alerts.some((alert) => alert.key === key && alert.answer !== "next");
+}
+
+/**
+ * The shops the owner has waved past for this errand on this trip.
+ *
+ * "Avisar en la siguiente" only means something if the NEXT one is a different
+ * one: without this the re-armed errand would re-rank onto the same nearest
+ * branch and ask about it again, which is the same message twice with extra
+ * steps.
+ *
+ * Coordinates, not names: two branches of one chain share a name, and the
+ * search that produced them is the same one that will produce them again.
+ */
+export function declinedMobilityPlaces(tripId, taskId) {
+  ensureLoaded();
+  const key = mobilityAlertKey(tripId, taskId);
+  return alerts
+    .filter((alert) => alert.key === key && alert.answer === "next")
+    .map((alert) => ({ latitude: alert.latitude, longitude: alert.longitude, place: alert.place }));
+}
+
+/**
+ * Record an alert the daemon is about to deliver. Written BEFORE the send, so a
+ * failed Telegram call still burns the one-shot: a delivery that errored is not
+ * a reason to try the same reminder again on the next GPS sample two seconds
+ * later. Returns the stored record (with its id).
+ */
+export function recordMobilityAlert(alert, now = Date.now()) {
+  ensureLoaded();
+  const record = {
+    id: `mb${Math.random().toString(36).slice(2, 8)}`,
+    key: mobilityAlertKey(alert.trip_id, alert.task_id),
+    trip_id: clean(alert.trip_id, 100),
+    task_id: clean(alert.task_id, 100),
+    task: clean(alert.task, 200),
+    project_id: clean(String(alert.project_id ?? ""), 100),
+    place: clean(alert.place, 200),
+    // The exact street address. Kept on the record, not only in the rendered
+    // message, so a card rebuilt later (a phone that reconnects, the car app
+    // asking again) says the same thing the first one did.
+    address: alert.address ? clean(alert.address, 300) : null,
+    latitude: Number(alert.latitude),
+    longitude: Number(alert.longitude),
+    distance_m: Number(alert.distance_m) || 0,
+    fired_at: new Date(now).toISOString(),
+    answer: null,
+    answered_at: null,
+    followup_at: null,
+    outcome: null,
+  };
+  alerts = [...alerts, record].slice(-MAX_ALERTS);
+  persist();
+  return record;
+}
+
+/** Every recorded alert, newest last. Read-only copies. */
+export function listMobilityAlerts() {
+  ensureLoaded();
+  return alerts.map((alert) => ({ ...alert }));
+}
+
+export function getMobilityAlert(id) {
+  ensureLoaded();
+  const found = alerts.find((alert) => alert.id === id);
+  return found ? { ...found } : null;
+}
+
+export function updateMobilityAlert(id, patch, now = Date.now()) {
+  ensureLoaded();
+  const index = alerts.findIndex((alert) => alert.id === id);
+  if (index < 0) return null;
+  alerts[index] = { ...alerts[index], ...patch, updated_at: new Date(now).toISOString() };
+  persist();
+  return { ...alerts[index] };
+}
+
+/**
+ * Alerts the owner said yes to and has not been asked back about. This is the
+ * whole point of keeping the log: "voy" is a promise, and the assistant that
+ * never asks how it went is a notification, not a secretary.
+ */
+export function pendingMobilityFollowups(tripId = null) {
+  ensureLoaded();
+  return alerts
+    .filter((alert) => alert.answer === "go" && !alert.followup_at && !alert.outcome)
+    .filter((alert) => !tripId || alert.trip_id === tripId)
+    .map((alert) => ({ ...alert }));
+}
+
+export function _resetMobilityStateForTest() {
+  ensureLoaded();
+  current = null;
+  lastQuestion = null;
+  lastResponse = null;
+  alerts = [];
+}