talon-agent 1.34.1 → 1.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.34.1",
+  "version": "1.35.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/core/engine/gateway-actions/index.ts

@@ -16,6 +16,7 @@
  *   - `skills`    — markdown workflows
  *   - `plugins`   — plugin hot-reload
  *   - `models`    — model / backend discovery
+ *   - `mesh`      — companion device mesh (presence + location)
  */
 
 import type { ActionResult } from "../../types.js";
@@ -30,6 +31,7 @@ import { scriptHandlers } from "./scripts.js";
 import { skillHandlers } from "./skills.js";
 import { pluginHandlers } from "./plugins.js";
 import { modelHandlers } from "./models.js";
+import { meshHandlers } from "./mesh.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method — `handlers[action]` only
@@ -44,6 +46,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...skillHandlers,
   ...pluginHandlers,
   ...modelHandlers,
+  ...meshHandlers,
 });
 
 export async function handleSharedAction(

package/src/core/engine/gateway-actions/mesh.ts

@@ -0,0 +1,22 @@
+/**
+ * Device mesh — read tools (list_devices, get_device_location,
+ * get_device_history) and command tools (ring, live status).
+ *
+ * Shared actions, so the model has full mesh access from every frontend
+ * (Telegram, Discord, Teams, terminal, native) — not just chats running
+ * through the native bridge. The mesh itself is daemon-wide state
+ * (core/mesh); the native bridge is merely the transport companions
+ * register through and commands travel over.
+ */
+
+import { getMeshService } from "../../mesh/index.js";
+import type { SharedActionHandlers } from "./types.js";
+
+export const meshHandlers: SharedActionHandlers = {
+  list_devices: () => getMeshService().describeDevices(),
+  get_device_location: (body) => getMeshService().locateDevice(body.device),
+  get_device_history: (body) =>
+    getMeshService().deviceHistory(body.device, body.hours),
+  ring_device: (body) => getMeshService().ringDevice(body.device, body.message),
+  get_device_status: (body) => getMeshService().getDeviceStatus(body.device),
+};

package/src/core/mesh/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Device mesh — core module barrel.
+ *
+ * Registry (persistence) + service (policy, locate fan-out, tool surface) +
+ * canonical device/location types. Transports and gateway actions import
+ * from here.
+ */
+
+export { MeshRegistry } from "./registry.js";
+export {
+  MeshService,
+  getMeshService,
+  setMeshService,
+  type MeshTransport,
+  type MeshServiceOptions,
+  type MeshToolResult,
+} from "./service.js";
+export {
+  sanitizeCapabilities,
+  toDeviceInfo,
+  toDeviceLocation,
+  type DeviceCommand,
+  type DeviceCommandResult,
+  type DeviceInfo,
+  type DeviceLocation,
+  type DevicePlatform,
+} from "./types.js";

package/src/core/mesh/registry.ts

@@ -0,0 +1,272 @@
+/**
+ * MeshRegistry — persistent storage for companion devices, last-known
+ * locations, and a bounded per-device location/battery history.
+ *
+ * Pure state: validate, upsert, persist (0600 JSON sidecars under the Talon
+ * root). No transport and no waiting logic — that policy lives in
+ * MeshService, so the registry stays trivially testable.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { dirs } from "../../util/paths.js";
+import {
+  sanitizeCapabilities,
+  toDeviceInfo,
+  toDeviceLocation,
+  type DeviceInfo,
+  type DeviceLocation,
+  type DevicePlatform,
+} from "./types.js";
+
+const PRESENCE_TIMEOUT_MS = 90_000;
+const DEVICE_FILE = resolve(dirs.root, "mesh-devices.json");
+const LOCATION_FILE = resolve(dirs.root, "mesh-locations.json");
+const HISTORY_FILE = resolve(dirs.root, "mesh-history.json");
+/** Newest fixes kept per device (~a day of 5-minute periodic reports). */
+const MAX_HISTORY_PER_DEVICE = 500;
+const PLATFORMS = new Set<DevicePlatform>([
+  "android",
+  "macos",
+  "windows",
+  "linux",
+  "ios",
+]);
+
+export class MeshRegistry {
+  private devices = new Map<string, DeviceInfo>();
+  private locations = new Map<string, DeviceLocation>();
+  private history = new Map<string, DeviceLocation[]>();
+
+  constructor(
+    private readonly files = {
+      devices: DEVICE_FILE,
+      locations: LOCATION_FILE,
+      history: HISTORY_FILE,
+    },
+  ) {}
+
+  async load(): Promise<void> {
+    this.devices = new Map(
+      (await readArray<DeviceInfo>(this.files.devices))
+        .map((d) => sanitizeDevice(d, d.lastSeen, false))
+        .filter((d): d is DeviceInfo => d !== null)
+        .map((d) => [d.id, d]),
+    );
+    this.locations = new Map(
+      (await readArray<DeviceLocation>(this.files.locations))
+        .map(sanitizeLocation)
+        .filter((l): l is DeviceLocation => l !== null)
+        .map((l) => [l.deviceId, l]),
+    );
+    this.history = new Map();
+    for (const fix of (await readArray<DeviceLocation>(this.files.history))
+      .map(sanitizeLocation)
+      .filter((l): l is DeviceLocation => l !== null)) {
+      this.appendHistory(fix);
+    }
+  }
+
+  async register(
+    body: Record<string, unknown>,
+    now = Date.now(),
+  ): Promise<DeviceInfo> {
+    const next = sanitizeDevice(body, now, true);
+    if (!next) throw new Error("Invalid device registration");
+    const prev = this.devices.get(next.id);
+    const device = toDeviceInfo(
+      {
+        ...prev,
+        ...next,
+        online: true,
+        lastSeen: now,
+      },
+      now,
+    );
+    this.devices.set(device.id, device);
+    await this.persistDevices();
+    return device;
+  }
+
+  async storeLocation(
+    body: Record<string, unknown>,
+    now = Date.now(),
+  ): Promise<DeviceLocation> {
+    const loc = sanitizeLocation(body);
+    if (!loc) throw new Error("Invalid device location");
+    this.locations.set(loc.deviceId, loc);
+    const device = this.devices.get(loc.deviceId);
+    if (device) {
+      this.devices.set(
+        loc.deviceId,
+        toDeviceInfo(
+          {
+            ...device,
+            online: true,
+            lastSeen: now,
+            ...(typeof loc.batteryPct === "number"
+              ? { battery: loc.batteryPct }
+              : {}),
+          },
+          now,
+        ),
+      );
+      await this.persistDevices();
+    }
+    this.appendHistory(loc);
+    await this.persistLocations();
+    await this.persistHistory();
+    return loc;
+  }
+
+  /** Fixes for one device since `sinceTs`, oldest first. */
+  getHistory(deviceId: string, sinceTs = 0): DeviceLocation[] {
+    return (this.history.get(deviceId) ?? [])
+      .filter((l) => l.ts >= sinceTs)
+      .map(toDeviceLocation);
+  }
+
+  /** Append one fix to the device's rolling history (dedup on timestamp,
+   *  chronological order, bounded to MAX_HISTORY_PER_DEVICE). */
+  private appendHistory(fix: DeviceLocation): void {
+    const list = this.history.get(fix.deviceId) ?? [];
+    if (list.some((l) => l.ts === fix.ts)) return;
+    list.push(toDeviceLocation(fix));
+    list.sort((a, b) => a.ts - b.ts);
+    if (list.length > MAX_HISTORY_PER_DEVICE) {
+      list.splice(0, list.length - MAX_HISTORY_PER_DEVICE);
+    }
+    this.history.set(fix.deviceId, list);
+  }
+
+  list(now = Date.now()): {
+    devices: DeviceInfo[];
+    locations: DeviceLocation[];
+  } {
+    return {
+      devices: [...this.devices.values()]
+        .map((d) => toDeviceInfo(d, now, PRESENCE_TIMEOUT_MS))
+        .sort((a, b) => b.lastSeen - a.lastSeen),
+      locations: [...this.locations.values()]
+        .map(toDeviceLocation)
+        .sort((a, b) => b.ts - a.ts),
+    };
+  }
+
+  getLocation(deviceId: string): DeviceLocation | undefined {
+    const loc = this.locations.get(deviceId);
+    return loc ? toDeviceLocation(loc) : undefined;
+  }
+
+  private async persistDevices(): Promise<void> {
+    await writePrivateJson(this.files.devices, [...this.devices.values()]);
+  }
+
+  private async persistLocations(): Promise<void> {
+    await writePrivateJson(this.files.locations, [...this.locations.values()]);
+  }
+
+  private async persistHistory(): Promise<void> {
+    await writePrivateJson(
+      this.files.history,
+      [...this.history.values()].flat(),
+    );
+  }
+}
+
+async function readArray<T>(path: string): Promise<T[]> {
+  try {
+    const raw = await readFile(path, "utf8");
+    const parsed = JSON.parse(raw) as unknown;
+    return Array.isArray(parsed) ? (parsed as T[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+async function writePrivateJson(path: string, value: unknown): Promise<void> {
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+}
+
+function sanitizeDevice(
+  body: Record<string, unknown>,
+  now: number,
+  requireCore: boolean,
+): DeviceInfo | null {
+  const id = stringField(body.id);
+  const name = stringField(body.name);
+  const appVersion = stringField(body.appVersion);
+  const platform = stringField(body.platform) as DevicePlatform | undefined;
+  if ((requireCore || id !== undefined) && !id) return null;
+  if ((requireCore || name !== undefined) && !name) return null;
+  if ((requireCore || appVersion !== undefined) && !appVersion) return null;
+  if (
+    (requireCore || platform !== undefined) &&
+    (!platform || !PLATFORMS.has(platform))
+  ) {
+    return null;
+  }
+  return {
+    id: id ?? "",
+    name: name ?? "",
+    platform: platform ?? "linux",
+    appVersion: appVersion ?? "",
+    online: body.online === true,
+    lastSeen: numberField(body.lastSeen) ?? now,
+    ...(numberField(body.battery) !== undefined
+      ? { battery: numberField(body.battery) }
+      : {}),
+    ...(typeof body.charging === "boolean" ? { charging: body.charging } : {}),
+    ...(sanitizeCapabilities(body.capabilities)
+      ? { capabilities: sanitizeCapabilities(body.capabilities) }
+      : {}),
+  };
+}
+
+function sanitizeLocation(
+  body: Record<string, unknown>,
+): DeviceLocation | null {
+  const deviceId = stringField(body.deviceId);
+  const lat = numberField(body.lat);
+  const lon = numberField(body.lon);
+  const ts = numberField(body.ts);
+  if (!deviceId || !Number.isFinite(lat) || !Number.isFinite(lon) || !ts) {
+    return null;
+  }
+  if (lat! < -90 || lat! > 90 || lon! < -180 || lon! > 180) return null;
+  return toDeviceLocation({
+    deviceId,
+    lat: lat!,
+    lon: lon!,
+    ...(numberField(body.accuracyM) !== undefined
+      ? { accuracyM: numberField(body.accuracyM) }
+      : {}),
+    ...(numberField(body.altitudeM) !== undefined
+      ? { altitudeM: numberField(body.altitudeM) }
+      : {}),
+    ...(numberField(body.speedMps) !== undefined
+      ? { speedMps: numberField(body.speedMps) }
+      : {}),
+    ...(numberField(body.headingDeg) !== undefined
+      ? { headingDeg: numberField(body.headingDeg) }
+      : {}),
+    ts,
+    ...(stringField(body.provider)
+      ? { provider: stringField(body.provider) }
+      : {}),
+    ...(numberField(body.batteryPct) !== undefined
+      ? { batteryPct: numberField(body.batteryPct) }
+      : {}),
+  });
+}
+
+function stringField(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function numberField(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}

package/src/core/mesh/service.ts

@@ -0,0 +1,550 @@
+/**
+ * MeshService — the daemon-wide device-mesh facade.
+ *
+ * One instance serves every consumer in the process:
+ *
+ *   - Transports (the native bridge server) feed it registrations, location
+ *     reports, and command results, and plug in a MeshTransport so locate
+ *     requests and device commands reach connected companion apps. The
+ *     service never imports a transport — dependencies point inward.
+ *   - The model reads and drives it through the shared mesh gateway actions
+ *     (list_devices, get_device_location, get_device_history, ring_device,
+ *     get_device_status), so full mesh access works identically from
+ *     Telegram, Discord, Teams, terminal, and native chats — the mesh is
+ *     daemon state, not a native-frontend feature.
+ *
+ * Two request/response flows ride the same SSE-out / HTTP-POST-back loop:
+ *
+ *   locate   → `locate` event   → device POSTs /location            (legacy,
+ *              kept verbatim so pre-command app builds keep working)
+ *   command  → `device_command` → device POSTs /devices/command-result with
+ *              the command's correlation id; sendCommand resolves the
+ *              pending promise or times out.
+ *
+ * With no transport registered (daemon running without the native bridge),
+ * everything degrades gracefully: locate answers from the last persisted
+ * fix immediately, and commands fail fast with a clear explanation.
+ */
+
+import { randomUUID } from "node:crypto";
+import { MeshRegistry } from "./registry.js";
+import type {
+  DeviceCommand,
+  DeviceCommandResult,
+  DeviceInfo,
+  DeviceLocation,
+} from "./types.js";
+
+/** How a transport pushes mesh traffic to connected companion devices. */
+export type MeshTransport = {
+  /** Ask one device (or all, when undefined) for a fresh location fix. */
+  locate(deviceId?: string): void;
+  /** Deliver an on-demand command to its target device. */
+  command(command: DeviceCommand): void;
+};
+
+export type MeshToolResult = { ok: boolean; text: string };
+
+export type MeshServiceOptions = {
+  /** How long a locate waits for a fresh fix before last-known fallback. */
+  freshFixTimeoutMs?: number;
+  /** Upper bound between staleness re-checks while waiting. */
+  pollIntervalMs?: number;
+  /** How long a device command waits for its result before timing out. */
+  commandTimeoutMs?: number;
+};
+
+const DEFAULT_FRESH_FIX_TIMEOUT_MS = 8_000;
+const DEFAULT_POLL_INTERVAL_MS = 1_000;
+const DEFAULT_COMMAND_TIMEOUT_MS = 12_000;
+const MOBILE_PLATFORMS = new Set(["android", "ios"]);
+const DEFAULT_HISTORY_HOURS = 24;
+const MAX_HISTORY_LINES = 24;
+
+export class MeshService {
+  private readonly waiters = new Set<() => void>();
+  private readonly transports = new Set<MeshTransport>();
+  private readonly pendingCommands = new Map<
+    string,
+    (result: DeviceCommandResult) => void
+  >();
+  private readonly freshFixTimeoutMs: number;
+  private readonly pollIntervalMs: number;
+  private readonly commandTimeoutMs: number;
+  private loading: Promise<void> | null = null;
+
+  constructor(
+    private readonly registry = new MeshRegistry(),
+    options: MeshServiceOptions = {},
+  ) {
+    this.freshFixTimeoutMs =
+      options.freshFixTimeoutMs ?? DEFAULT_FRESH_FIX_TIMEOUT_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.commandTimeoutMs =
+      options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+  }
+
+  /** Hydrate persisted devices/locations. Idempotent — safe to await from
+   *  every entry point; the first caller does the read, the rest share it. */
+  load(): Promise<void> {
+    this.loading ??= this.registry.load();
+    return this.loading;
+  }
+
+  /**
+   * Plug a transport in. Returns an unsubscribe so the transport detaches
+   * cleanly on shutdown (no stale broadcasts into a stopped server).
+   */
+  registerTransport(transport: MeshTransport): () => void {
+    this.transports.add(transport);
+    return () => this.transports.delete(transport);
+  }
+
+  /** Fan a locate request out to every transport. True when at least one
+   *  transport is attached (i.e. waiting for a fresh fix can pay off). */
+  requestLocate(deviceId?: string): boolean {
+    for (const transport of this.transports) {
+      try {
+        transport.locate(deviceId);
+      } catch {
+        // One broken transport must not stop the others.
+      }
+    }
+    return this.transports.size > 0;
+  }
+
+  async register(body: Record<string, unknown>): Promise<DeviceInfo> {
+    await this.load();
+    return this.registry.register(body);
+  }
+
+  /** Store a reported fix and wake anyone waiting on a fresh location. */
+  async storeLocation(body: Record<string, unknown>): Promise<DeviceLocation> {
+    await this.load();
+    const loc = await this.registry.storeLocation(body);
+    for (const notify of [...this.waiters]) notify();
+    return loc;
+  }
+
+  async list(): Promise<{
+    devices: DeviceInfo[];
+    locations: DeviceLocation[];
+  }> {
+    await this.load();
+    return this.registry.list();
+  }
+
+  async getLocation(deviceId: string): Promise<DeviceLocation | undefined> {
+    await this.load();
+    return this.registry.getLocation(deviceId);
+  }
+
+  // ── Command channel ────────────────────────────────────────────────────────
+
+  /**
+   * A device answered a command (bridge route POST /devices/command-result).
+   * Resolves the pending sendCommand; false when nothing was waiting (late
+   * or unknown correlation id — harmless, just ignored).
+   */
+  completeCommand(body: Record<string, unknown>): boolean {
+    const commandId = typeof body.commandId === "string" ? body.commandId : "";
+    const resolve = this.pendingCommands.get(commandId);
+    if (!resolve) return false;
+    this.pendingCommands.delete(commandId);
+    resolve({
+      commandId,
+      deviceId: typeof body.deviceId === "string" ? body.deviceId : "",
+      ok: body.ok === true,
+      ...(typeof body.message === "string" && body.message.trim()
+        ? { message: body.message.trim().slice(0, 2_000) }
+        : {}),
+      ...(body.data &&
+      typeof body.data === "object" &&
+      !Array.isArray(body.data)
+        ? { data: body.data as Record<string, unknown> }
+        : {}),
+    });
+    return true;
+  }
+
+  /**
+   * Push one command to a device and await its result (or time out). The
+   * low-level primitive under every command tool; exposed for tests and
+   * future tools.
+   */
+  sendCommand(
+    device: DeviceInfo,
+    name: string,
+    params: Record<string, unknown> = {},
+  ): Promise<DeviceCommandResult> {
+    const command: DeviceCommand = {
+      id: randomUUID(),
+      deviceId: device.id,
+      name,
+      params,
+    };
+    return new Promise<DeviceCommandResult>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingCommands.delete(command.id);
+        resolve({
+          commandId: command.id,
+          deviceId: device.id,
+          ok: false,
+          message: `${device.name} did not answer within ${Math.round(this.commandTimeoutMs / 1000)}s (device ${device.online ? "was online" : "appears offline"}).`,
+        });
+      }, this.commandTimeoutMs);
+      timer.unref?.();
+      this.pendingCommands.set(command.id, (result) => {
+        clearTimeout(timer);
+        resolve(result);
+      });
+      for (const transport of this.transports) {
+        try {
+          transport.command(command);
+        } catch {
+          // One broken transport must not stop the others.
+        }
+      }
+    });
+  }
+
+  // ── Model-facing tool surface ──────────────────────────────────────────────
+
+  /** `list_devices`: every mesh device with presence, battery, last-known
+   *  position, and capabilities — the model's full view of the mesh. */
+  async describeDevices(): Promise<MeshToolResult> {
+    const { devices } = await this.list();
+    if (devices.length === 0) {
+      return { ok: true, text: "No mesh devices have registered yet." };
+    }
+    return {
+      ok: true,
+      text: devices.map((d) => this.deviceLine(d)).join("\n"),
+    };
+  }
+
+  /**
+   * `get_device_location`: resolve the target (id, name fragment, or the
+   * most recent mobile device), push a locate to connected transports, wait
+   * briefly for a fresh fix, then fall back to the last persisted location.
+   */
+  async locateDevice(query?: unknown): Promise<MeshToolResult> {
+    await this.load();
+    const target = this.chooseDevice(query);
+    if (!target) return this.noSuchDevice(query);
+    const requestedAt = Date.now();
+    // Only wait out the fresh-fix window when a transport can actually
+    // deliver the locate — otherwise answer from persistence immediately.
+    const dispatched = this.requestLocate(target.id);
+    const fresh = dispatched
+      ? await this.waitForFreshLocation(target.id, requestedAt)
+      : undefined;
+    const loc = fresh ?? this.registry.getLocation(target.id);
+    if (!loc) {
+      return {
+        ok: false,
+        text: dispatched
+          ? `No location is known for ${target.name}. A locate request was sent, but no fix arrived within ${Math.round(this.freshFixTimeoutMs / 1000)}s.`
+          : `No location is known for ${target.name}, and no companion transport is connected to request one.`,
+      };
+    }
+    return { ok: true, text: this.locationSummary(target, loc) };
+  }
+
+  /** `ring_device`: make the device sound/vibrate so it can be found. */
+  ringDevice(query?: unknown, message?: unknown): Promise<MeshToolResult> {
+    return this.commandTool(query, "ring", {
+      ...(typeof message === "string" && message.trim()
+        ? { message: message.trim().slice(0, 200) }
+        : {}),
+    });
+  }
+
+  /**
+   * `get_device_history`: the device's movement + battery over a window,
+   * computed from the fixes the daemon has been receiving all along —
+   * timeline, distance traveled, and battery trend.
+   */
+  async deviceHistory(
+    query?: unknown,
+    hours?: unknown,
+  ): Promise<MeshToolResult> {
+    await this.load();
+    const target = this.chooseDevice(query);
+    if (!target) return this.noSuchDevice(query);
+    const windowHours = clampHours(hours);
+    const sinceTs = Date.now() - windowHours * 3_600_000;
+    const fixes = this.registry.getHistory(target.id, sinceTs);
+    if (fixes.length === 0) {
+      return {
+        ok: true,
+        text: `No location reports from ${target.name} in the last ${windowHours}h. Enable periodic reporting in the companion app for a movement history.`,
+      };
+    }
+    return { ok: true, text: this.historySummary(target, fixes, windowHours) };
+  }
+
+  /** `get_device_status`: live telemetry straight from the device. */
+  getDeviceStatus(query?: unknown): Promise<MeshToolResult> {
+    return this.commandTool(query, "status", {});
+  }
+
+  /**
+   * Shared command-tool flow: resolve the target, check its advertised
+   * capabilities, require a transport, send, and render the device's answer.
+   */
+  private async commandTool(
+    query: unknown,
+    name: string,
+    params: Record<string, unknown>,
+  ): Promise<MeshToolResult> {
+    await this.load();
+    const target = this.chooseDevice(query);
+    if (!target) return this.noSuchDevice(query);
+    // Devices advertise what they can do; an explicit list that lacks the
+    // command is a clean "can't" — absent list means an older app build, so
+    // attempt it and let the timeout speak.
+    if (target.capabilities && !target.capabilities.includes(name)) {
+      return {
+        ok: false,
+        text: `${target.name} does not support "${name}" (supports: ${target.capabilities.join(", ")}).`,
+      };
+    }
+    if (this.transports.size === 0) {
+      return {
+        ok: false,
+        text: `No companion transport is connected, so "${name}" cannot reach ${target.name}.`,
+      };
+    }
+    const result = await this.sendCommand(target, name, params);
+    return {
+      ok: result.ok,
+      text: this.commandSummary(target, name, result),
+    };
+  }
+
+  /** Resolve a device by exact id, name fragment, or default (most recently
+   *  seen mobile device, falling back to the most recent device overall). */
+  chooseDevice(query?: unknown): DeviceInfo | undefined {
+    const devices = this.registry.list().devices;
+    if (typeof query === "string" && query.trim()) {
+      const q = query.trim().toLowerCase();
+      return devices.find(
+        (d) => d.id.toLowerCase() === q || d.name.toLowerCase().includes(q),
+      );
+    }
+    return devices.find((d) => MOBILE_PLATFORMS.has(d.platform)) ?? devices[0];
+  }
+
+  // ── Formatting ─────────────────────────────────────────────────────────────
+
+  private noSuchDevice(query: unknown): MeshToolResult {
+    const known = this.registry.list().devices;
+    return {
+      ok: false,
+      text:
+        typeof query === "string" && query.trim() && known.length > 0
+          ? `No mesh device matches "${query.trim()}". Known devices:\n${known.map((d) => this.deviceLine(d)).join("\n")}`
+          : "No mesh devices are registered.",
+    };
+  }
+
+  private deviceLine(device: DeviceInfo): string {
+    const parts = [
+      `${device.name} [id: ${device.id}] (${device.platform})`,
+      device.online ? "online" : "offline",
+      `last seen ${age(Date.now() - device.lastSeen)}`,
+    ];
+    if (typeof device.battery === "number") {
+      parts.push(`${device.battery}%${device.charging ? " charging" : ""}`);
+    }
+    const loc = this.registry.getLocation(device.id);
+    if (loc) {
+      parts.push(
+        `at ${loc.lat.toFixed(6)},${loc.lon.toFixed(6)} (fix ${age(Date.now() - loc.ts)})`,
+      );
+    }
+    if (device.capabilities?.length) {
+      parts.push(`can: ${device.capabilities.join(", ")}`);
+    }
+    return `- ${parts.join(" · ")}`;
+  }
+
+  private locationSummary(device: DeviceInfo, loc: DeviceLocation): string {
+    const ageText = age(Date.now() - loc.ts);
+    const accuracy =
+      typeof loc.accuracyM === "number"
+        ? ` Accuracy ${Math.round(loc.accuracyM)}m.`
+        : "";
+    return [
+      `${device.name} is at ${loc.lat.toFixed(6)}, ${loc.lon.toFixed(6)}.`,
+      `${accuracy} Fix age ${ageText}.`,
+      `Reverse-geocode pair: ${loc.lat},${loc.lon}`,
+    ]
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+
+  private commandSummary(
+    device: DeviceInfo,
+    name: string,
+    result: DeviceCommandResult,
+  ): string {
+    if (!result.ok) {
+      return result.message ?? `${device.name} rejected "${name}".`;
+    }
+    const detail = result.message ? ` ${result.message}` : "";
+    switch (name) {
+      case "ring":
+        return `${device.name} is ringing.${detail}`;
+      case "status": {
+        const fields = Object.entries(result.data ?? {})
+          .filter(([, v]) => v !== null && v !== undefined && v !== "")
+          .map(([k, v]) => `${k}: ${String(v)}`);
+        return fields.length
+          ? `${device.name} status — ${fields.join(" · ")}`
+          : `${device.name} answered but reported no status fields.${detail}`;
+      }
+      default:
+        return (
+          result.message ??
+          (result.data
+            ? `${device.name} answered: ${JSON.stringify(result.data)}`
+            : `${device.name} completed "${name}".`)
+        );
+    }
+  }
+
+  /** Render a window of fixes: headline (count, span, distance, battery
+   *  trend) plus a bounded, evenly-sampled timeline oldest-first. */
+  private historySummary(
+    device: DeviceInfo,
+    fixes: DeviceLocation[],
+    windowHours: number,
+  ): string {
+    let distanceM = 0;
+    for (let i = 1; i < fixes.length; i++) {
+      distanceM += haversineM(fixes[i - 1], fixes[i]);
+    }
+    const batteries = fixes
+      .map((f) => f.batteryPct)
+      .filter((b): b is number => typeof b === "number");
+    const headline = [
+      `${device.name}: ${fixes.length} fix${fixes.length === 1 ? "" : "es"} in the last ${windowHours}h`,
+      `moved ~${formatDistance(distanceM)}`,
+      ...(batteries.length >= 2
+        ? [`battery ${batteries[0]}% → ${batteries[batteries.length - 1]}%`]
+        : []),
+    ].join(" · ");
+    const lines = sampleEvenly(fixes, MAX_HISTORY_LINES).map((f) => {
+      const parts = [
+        `${formatWhen(f.ts)} — ${f.lat.toFixed(5)},${f.lon.toFixed(5)}`,
+      ];
+      if (typeof f.accuracyM === "number")
+        parts.push(`±${Math.round(f.accuracyM)}m`);
+      if (typeof f.batteryPct === "number") parts.push(`${f.batteryPct}%`);
+      return `- ${parts.join(" · ")}`;
+    });
+    const omitted = fixes.length - Math.min(fixes.length, MAX_HISTORY_LINES);
+    return [
+      headline,
+      ...lines,
+      ...(omitted > 0
+        ? [`(${omitted} more fixes omitted; timeline sampled evenly)`]
+        : []),
+    ].join("\n");
+  }
+
+  private async waitForFreshLocation(
+    deviceId: string,
+    requestedAt: number,
+  ): Promise<DeviceLocation | undefined> {
+    const existing = this.registry.getLocation(deviceId);
+    if (existing && existing.ts >= requestedAt) return existing;
+    const deadline = Date.now() + this.freshFixTimeoutMs;
+    while (Date.now() < deadline) {
+      const remaining = deadline - Date.now();
+      await new Promise<void>((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          this.waiters.delete(done);
+          resolve();
+        };
+        const timer = setTimeout(
+          done,
+          Math.min(remaining, this.pollIntervalMs),
+        );
+        this.waiters.add(done);
+      });
+      const loc = this.registry.getLocation(deviceId);
+      if (loc && loc.ts >= requestedAt) return loc;
+    }
+    return undefined;
+  }
+}
+
+/** Clamp the requested history window to 1..168 hours (default 24). */
+function clampHours(value: unknown): number {
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_HISTORY_HOURS;
+  return Math.min(168, Math.max(1, Math.round(n)));
+}
+
+/** Great-circle distance between two fixes in meters. */
+function haversineM(a: DeviceLocation, b: DeviceLocation): number {
+  const R = 6_371_000;
+  const rad = (deg: number) => (deg * Math.PI) / 180;
+  const dLat = rad(b.lat - a.lat);
+  const dLon = rad(b.lon - a.lon);
+  const h =
+    Math.sin(dLat / 2) ** 2 +
+    Math.cos(rad(a.lat)) * Math.cos(rad(b.lat)) * Math.sin(dLon / 2) ** 2;
+  return 2 * R * Math.asin(Math.sqrt(h));
+}
+
+function formatDistance(meters: number): string {
+  if (meters < 1_000) return `${Math.round(meters)}m`;
+  return `${(meters / 1_000).toFixed(1)}km`;
+}
+
+/** Local wall-clock stamp for history lines (date + HH:MM). */
+function formatWhen(ts: number): string {
+  const d = new Date(ts);
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+/** Up to `max` items spread evenly across the list, endpoints included. */
+function sampleEvenly<T>(items: T[], max: number): T[] {
+  if (items.length <= max) return items;
+  const out: T[] = [];
+  for (let i = 0; i < max; i++) {
+    out.push(items[Math.round((i * (items.length - 1)) / (max - 1))]);
+  }
+  return out;
+}
+
+function age(ms: number): string {
+  const sec = Math.max(0, Math.round(ms / 1000));
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.round(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hrs = Math.round(min / 60);
+  return `${hrs}h ago`;
+}
+
+// ── Process-wide instance ─────────────────────────────────────────────────────
+
+let instance: MeshService | null = null;
+
+/** The daemon's shared mesh service (lazily created). */
+export function getMeshService(): MeshService {
+  instance ??= new MeshService();
+  return instance;
+}
+
+/** Swap the shared instance — composition/test seam. Pass null to reset. */
+export function setMeshService(service: MeshService | null): void {
+  instance = service;
+}

package/src/core/mesh/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Device-mesh domain types + normalizers.
+ *
+ * The canonical shapes for companion devices and their reported locations.
+ * They live in core (not a frontend) because the mesh is daemon-wide state:
+ * devices register through the native bridge transport, but the model reads
+ * them from ANY frontend via the shared `list_devices` /
+ * `get_device_location` gateway actions. The bridge protocol re-exports
+ * these types so the wire contract is unchanged.
+ */
+
+export type DevicePlatform = "android" | "macos" | "windows" | "linux" | "ios";
+
+export type DeviceInfo = {
+  id: string;
+  name: string;
+  platform: DevicePlatform;
+  appVersion: string;
+  online: boolean;
+  /** Epoch milliseconds. */
+  lastSeen: number;
+  /** Battery percent, 0-100. */
+  battery?: number;
+  charging?: boolean;
+  /**
+   * Command names this device can execute (e.g. "locate", "ring",
+   * "open_url"). Reported by the device at registration; absent for app
+   * versions that predate the command channel — treat as unknown, not
+   * empty.
+   */
+  capabilities?: string[];
+};
+
+/**
+ * An on-demand command pushed to one companion device over the mesh
+ * transport. The device executes it and answers with a DeviceCommandResult
+ * carrying the same `id`.
+ */
+export type DeviceCommand = {
+  /** Correlation id — echoed back as the result's `commandId`. */
+  id: string;
+  deviceId: string;
+  /** Command name (e.g. "ring", "open_url", "clipboard_get", "status"). */
+  name: string;
+  params: Record<string, unknown>;
+};
+
+/** A device's answer to a DeviceCommand. */
+export type DeviceCommandResult = {
+  commandId: string;
+  deviceId: string;
+  ok: boolean;
+  /** Human-readable outcome (shown to the model). */
+  message?: string;
+  /** Structured payload (e.g. clipboard text, status fields). */
+  data?: Record<string, unknown>;
+};
+
+export type DeviceLocation = {
+  deviceId: string;
+  lat: number;
+  lon: number;
+  accuracyM?: number;
+  altitudeM?: number;
+  speedMps?: number;
+  headingDeg?: number;
+  /** Epoch milliseconds. */
+  ts: number;
+  provider?: string;
+  batteryPct?: number;
+};
+
+export function toDeviceInfo(
+  value: DeviceInfo,
+  now = Date.now(),
+  offlineAfterMs = 90_000,
+): DeviceInfo {
+  const battery =
+    typeof value.battery === "number"
+      ? Math.max(0, Math.min(100, Math.round(value.battery)))
+      : undefined;
+  return {
+    id: value.id,
+    name: value.name,
+    platform: value.platform,
+    appVersion: value.appVersion,
+    online: now - value.lastSeen <= offlineAfterMs && value.online,
+    lastSeen: value.lastSeen,
+    ...(battery !== undefined ? { battery } : {}),
+    ...(typeof value.charging === "boolean"
+      ? { charging: value.charging }
+      : {}),
+    ...(value.capabilities?.length
+      ? { capabilities: [...value.capabilities] }
+      : {}),
+  };
+}
+
+/**
+ * Normalize a device's advertised capability list: strings only, trimmed,
+ * lowercased, deduped, and bounded so a misbehaving client can't bloat the
+ * persisted registry. Undefined when nothing valid remains.
+ */
+export function sanitizeCapabilities(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const seen = new Set<string>();
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const cap = item.trim().toLowerCase().slice(0, 32);
+    if (cap) seen.add(cap);
+    if (seen.size >= 16) break;
+  }
+  return seen.size ? [...seen] : undefined;
+}
+
+export function toDeviceLocation(value: DeviceLocation): DeviceLocation {
+  return {
+    deviceId: value.deviceId,
+    lat: value.lat,
+    lon: value.lon,
+    ...(typeof value.accuracyM === "number"
+      ? { accuracyM: value.accuracyM }
+      : {}),
+    ...(typeof value.altitudeM === "number"
+      ? { altitudeM: value.altitudeM }
+      : {}),
+    ...(typeof value.speedMps === "number" ? { speedMps: value.speedMps } : {}),
+    ...(typeof value.headingDeg === "number"
+      ? { headingDeg: value.headingDeg }
+      : {}),
+    ts: value.ts,
+    ...(value.provider ? { provider: value.provider } : {}),
+    ...(typeof value.batteryPct === "number"
+      ? { batteryPct: Math.max(0, Math.min(100, Math.round(value.batteryPct))) }
+      : {}),
+  };
+}

package/src/core/tools/index.ts

@@ -21,6 +21,7 @@ import { skillTools } from "./skills.js";
 import { webTools } from "./web.js";
 import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
+import { meshTools } from "./mesh.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -38,6 +39,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...webTools,
   ...adminTools,
   ...modelTools,
+  ...meshTools,
 ];
 
 /**

package/src/core/tools/mesh.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import type { ToolDefinition } from "./types.js";
+
+/**
+ * Device-mesh tools. Deliberately NOT frontend-restricted: the mesh is
+ * daemon-wide state served by shared gateway actions, so the model can see,
+ * locate, and command companion devices from any chat surface.
+ */
+
+/** Shared device-target parameter: id or name fragment; default = mobile. */
+const deviceParam = z
+  .string()
+  .optional()
+  .describe(
+    "Device id or part of the device name (see list_devices). Defaults to the most recently seen mobile mesh device.",
+  );
+
+export const meshTools: ToolDefinition[] = [
+  {
+    name: "list_devices",
+    description:
+      "List all Talon companion mesh devices with id, platform, online presence, last-seen age, battery state, last-known location, and supported commands.",
+    schema: {},
+    execute: (_params, bridge) => bridge("list_devices", {}),
+    tag: "mesh",
+  },
+  {
+    name: "get_device_location",
+    description:
+      "Get any Talon companion device's current or last-known location. Sends an on-demand locate request first, waits briefly for a fresh GPS fix, then falls back to last-known. With no device, uses the most recently seen mobile device.",
+    schema: { device: deviceParam },
+    execute: (params, bridge) => bridge("get_device_location", params),
+    tag: "mesh",
+  },
+  {
+    name: "get_device_history",
+    description:
+      "Movement and battery history for a Talon companion device: a timeline of its reported locations over a window (default 24h, max 168h), with distance traveled and battery trend. Answers questions like where a device was earlier or how fast its battery is draining.",
+    schema: {
+      device: deviceParam,
+      hours: z
+        .number()
+        .optional()
+        .describe("History window in hours (1-168, default 24)."),
+    },
+    execute: (params, bridge) => bridge("get_device_history", params),
+    tag: "mesh",
+  },
+  {
+    name: "ring_device",
+    description:
+      "Make a Talon companion device ring/vibrate so it can be found (find-my-phone). Optionally include a short message the device may display.",
+    schema: {
+      device: deviceParam,
+      message: z
+        .string()
+        .optional()
+        .describe("Optional short note to show on the device."),
+    },
+    execute: (params, bridge) => bridge("ring_device", params),
+    tag: "mesh",
+  },
+  {
+    name: "get_device_status",
+    description:
+      "Get live status straight from a Talon companion device: battery and charging state, platform/OS details, app version, and mesh sharing settings.",
+    schema: { device: deviceParam },
+    execute: (params, bridge) => bridge("get_device_status", params),
+    tag: "mesh",
+  },
+];

package/src/core/tools/types.ts

@@ -26,7 +26,8 @@ export type ToolTag =
   | "skills"
   | "web"
   | "admin"
-  | "models";
+  | "models"
+  | "mesh";
 
 /** The bridge caller signature — injected into execute(). */
 export type BridgeFunction = (

package/src/frontend/native/actions.ts

@@ -52,6 +52,20 @@ function toButtons(rows: unknown): ClientButton[][] | undefined {
   return mapped.length ? mapped : undefined;
 }
 
+/** Actions this handler owns. Everything else must return null so the
+ *  gateway can try plugin + shared actions (history, web, cron, mesh…) —
+ *  failing early here would swallow actions that aren't native's to answer. */
+const NATIVE_ACTIONS = new Set([
+  "send_message",
+  "send_message_with_buttons",
+  "send_photo",
+  "react",
+  "edit_message",
+  "delete_message",
+  "get_chat_info",
+  "send_chat_action",
+]);
+
 export function createNativeActionHandler(
   deps: NativeActionDeps,
 ): FrontendActionHandler {
@@ -59,6 +73,7 @@ export function createNativeActionHandler(
 
   return async (body, chatId): Promise<ActionResult | null> => {
     const action = typeof body.action === "string" ? body.action : "";
+    if (!NATIVE_ACTIONS.has(action)) return null;
     const entry = chats.byNumeric(chatId);
     if (!entry) return { ok: false, error: "No active native chat" };
 
@@ -126,7 +141,8 @@ export function createNativeActionHandler(
         return { ok: true };
 
       default:
-        // Let the gateway try plugin + shared actions (history, web, cron…).
+        // Unreachable — NATIVE_ACTIONS gates the switch — but keeps the
+        // contract explicit if the set and the cases ever drift.
         return null;
     }
   };

package/src/frontend/native/index.ts

@@ -66,6 +66,7 @@ import { NativeChats, DEFAULT_CHAT_TITLE, type ChatEntry } from "./chats.js";
 import { extractSessionName } from "../../backend/shared/session-name.js";
 import { BridgeServer, type BridgeServerHandlers } from "./server.js";
 import { createNativeActionHandler } from "./actions.js";
+import { getMeshService } from "../../core/mesh/index.js";
 import { removeBridgeDiscovery, writeBridgeDiscovery } from "./discovery.js";
 import { readLogEntries } from "./logs.js";
 import {
@@ -148,6 +149,13 @@ export function createNativeFrontend(
   const startedAt = new Date().toISOString();
   const botName = config.botDisplayName || "Talon";
   const chats = new NativeChats();
+  // Daemon-wide mesh service (core/mesh). This frontend is its transport:
+  // companions register/report/answer through the bridge routes below, and
+  // the SSE transport (wired in init) pushes locate requests and device
+  // commands out. The model's mesh tools are served by the shared gateway
+  // actions, so they work from every frontend.
+  const mesh = getMeshService();
+  let unregisterMeshTransport: (() => void) | null = null;
 
   // Monotonic message-id minter. Seeded from the wall clock so ids stay
   // unique and ascending across restarts (history rows persist their ids).
@@ -732,6 +740,7 @@ export function createNativeFrontend(
     return {
       app: "talon-bridge",
       protocol: BRIDGE_PROTOCOL_VERSION,
+      capabilities: ["mesh", "mesh-commands"],
       botName,
       backend: config.backend,
       model: resolveModel(config.model)?.displayName ?? config.model,
@@ -1161,6 +1170,12 @@ export function createNativeFrontend(
       readLogEntries(files.log, { limit: lines, minLevel, component }),
     liveTurnEvents,
     mediaPath: (id) => media.get(id) ?? null,
+    // Mesh routes are thin transport shims over the shared core service —
+    // storeLocation wakes any pending fresh-fix waiters inside the service.
+    registerDevice: (body) => mesh.register(body),
+    storeLocation: (body) => mesh.storeLocation(body),
+    listDevices: () => mesh.list(),
+    completeCommand: (body) => mesh.completeCommand(body),
   };
 
   const nativeCfg = config.native ?? { port: 19880, host: "127.0.0.1" };
@@ -1202,6 +1217,24 @@ export function createNativeFrontend(
     getBridgePort: () => gateway.getPort(),
 
     async init() {
+      await mesh.load();
+      // Plug this bridge in as the mesh's transport: locates and device
+      // commands (from ANY frontend's mesh tool calls) fan out to every
+      // connected companion client as SSE events; each client filters by
+      // its own device id.
+      unregisterMeshTransport = mesh.registerTransport({
+        locate: (deviceId) => broadcast({ kind: "locate", deviceId }),
+        command: (command) =>
+          broadcast({
+            kind: "device_command",
+            id: command.id,
+            deviceId: command.deviceId,
+            name: command.name,
+            params: command.params,
+          }),
+      });
+      // Mesh tool actions (list_devices / get_device_location) are shared
+      // gateway actions now — no native-only cases here.
       gateway.registerFrontendHandler(
         "native",
         createNativeActionHandler({
@@ -1231,6 +1264,8 @@ export function createNativeFrontend(
     },
 
     async stop() {
+      unregisterMeshTransport?.();
+      unregisterMeshTransport = null;
       await removeBridgeDiscovery();
       await server.stop();
       await gateway.stop();

package/src/frontend/native/protocol.ts

@@ -139,6 +139,8 @@ export type ClientChat = {
 export type BridgeStatus = {
   app: "talon-bridge";
   protocol: number;
+  /** Additive bridge features supported by this daemon. */
+  capabilities?: string[];
   botName: string;
   backend: string;
   /** Display name of the global default model. */
@@ -195,6 +197,18 @@ export type BackendOption = {
   label: string;
 };
 
+// Mesh device shapes are canonical in core (the mesh is daemon-wide state,
+// readable from every frontend); re-exported here so bridge clients keep
+// depending on the protocol module alone.
+export type {
+  DeviceCommand,
+  DeviceCommandResult,
+  DeviceInfo,
+  DeviceLocation,
+  DevicePlatform,
+} from "../../core/mesh/types.js";
+import type { DeviceCommand as MeshDeviceCommand } from "../../core/mesh/types.js";
+
 /**
  * Server → client events, delivered as SSE `data:` lines (one JSON object
  * each). The client switches on `kind`. Streaming text arrives as ephemeral
@@ -233,6 +247,20 @@ export type BridgeEvent =
       durationMs?: number;
       usage?: { input: number; output: number };
     }
+  | { kind: "locate"; deviceId?: string }
+  /**
+   * On-demand device command (ring, open_url, clipboard_*, status, …). The
+   * target device executes it and answers via POST /devices/command-result
+   * with the same `id` as `commandId`. Additive in v1 — app builds that
+   * predate the command channel simply ignore the event.
+   */
+  | {
+      kind: "device_command";
+      id: string;
+      deviceId: string;
+      name: string;
+      params: MeshDeviceCommand["params"];
+    }
   | { kind: "error"; chatId?: string; message: string };
 
 // ── Mappers (Talon internals → wire types) ───────────────────────────────────
@@ -256,3 +284,5 @@ export function historyToClientMessage(
     ts: m.timestamp,
   };
 }
+
+export { toDeviceInfo, toDeviceLocation } from "../../core/mesh/types.js";

package/src/frontend/native/server.ts

@@ -30,6 +30,8 @@ import {
   type BridgeStatus,
   type ClientChat,
   type ClientMessage,
+  type DeviceInfo,
+  type DeviceLocation,
   type LogEntry,
   type LogLevel,
   type ModelOption,
@@ -105,6 +107,16 @@ export type BridgeServerHandlers = {
   liveTurnEvents(): BridgeEvent[];
   /** Resolve a media id to an absolute file path (or null if unknown). */
   mediaPath(id: string): string | null;
+  /** Register/update one mesh device. */
+  registerDevice(body: Record<string, unknown>): Promise<DeviceInfo>;
+  /** Store the last-known location for one mesh device. */
+  storeLocation(body: Record<string, unknown>): Promise<DeviceLocation>;
+  /** List mesh devices and their last-known locations. */
+  listDevices():
+    | { devices: DeviceInfo[]; locations: DeviceLocation[] }
+    | Promise<{ devices: DeviceInfo[]; locations: DeviceLocation[] }>;
+  /** A device answered a device_command; true when a call was waiting. */
+  completeCommand(body: Record<string, unknown>): boolean;
 };
 
 const SSE_PING_MS = 25_000;
@@ -256,6 +268,7 @@ export class BridgeServer {
         backend: s.backend,
         model: s.model,
         activeChats: s.activeChats,
+        capabilities: ["mesh", "mesh-commands"],
       });
     }
 
@@ -356,6 +369,31 @@ export class BridgeServer {
         return this.json(res, 202, { ok: true });
       }
 
+      if (method === "POST" && path === "/devices/register") {
+        const body = await this.readJson(req);
+        const device = await this.handlers.registerDevice(body);
+        return this.json(res, 200, { ok: true, deviceId: device.id });
+      }
+
+      if (method === "POST" && path === "/location") {
+        const body = await this.readJson(req);
+        await this.handlers.storeLocation(body);
+        return this.json(res, 200, { ok: true });
+      }
+
+      if (method === "GET" && path === "/devices") {
+        return this.json(res, 200, await this.handlers.listDevices());
+      }
+
+      if (method === "POST" && path === "/devices/command-result") {
+        const body = await this.readJson(req);
+        // ok:false for a late/unknown correlation id — not an HTTP error,
+        // the device's POST was well-formed; nothing was waiting anymore.
+        return this.json(res, 200, {
+          ok: this.handlers.completeCommand(body),
+        });
+      }
+
       if (method === "POST" && path === "/upload") {
         const filename = url.searchParams.get("filename") ?? "upload";
         const contentType =