Persist message history to SQLite with 1s poller (#15) (#19)

AGENTS.md

@@ -17,8 +17,8 @@
 ## API
 
 1. **Live base URL** — `http://bot.dev.kkhost.pl` (Traefik → docker-compose stack on this host; container port 3000 via external network dev_net, no published ports).
-2. **Endpoints** — all under the `/api` global prefix: `GET /api/status` (`{ connected, myNodeNum, host, port }`), `POST /api/send` (body `{ "text": "...", "to"?: <node number | node name | "!b" | "broadcast"> }` — numbers pass through as-is (integer 1..0xffffffff), names resolve like `GET /api/nodes/:id`, omitted/""/"!b"/"broadcast" → broadcast; unknown or ambiguous targets are a 400. Returns `{ id }`), `GET /api/channels` (the device's Meshtastic channels as `{ index, name, uplinkEnabled, downlinkEnabled }[]`; psk/keys redacted), `GET /api/device` (device info captured during the initial sync: `{ myNodeNum, firmwareVersion?, metadata?, localConfig: {<section>: ...}, moduleConfig: {<module>: ...} }` — DeviceMetadata as-is plus per-section Config/ModuleConfig messages; security publicKey/privateKey/adminKey and network wifiPsk redacted to `"REDACTED"`; in-memory, reset on reconnect), `GET /api/messages` (message history newest first: rx text with `from`, tx sends with `to` + `status` pending→delivered/failed via routing ACKs — broadcasts stay pending because firmware strips want_ack; last 100, in-memory, reset on reconnect), `GET /api/nodes` (known nodes sorted by num as `{ num, longName?, shortName?, hwModel?, batteryLevel?, lastHeard: number|null, position?: { lat, lon, alt? }, snr?, hopsAway?, viaMqtt? }[]`, from the initial sync plus live POSITION_APP updates; reset on reconnect) and `GET /api/nodes/:id` (lookup by exact node number/numeric string, then case-insensitive exact long/short name, else unique substring; 404 when ambiguous or missing). Scalar API docs are served at `/` (OpenAPI JSON at `/docs-json`). Keep this list in sync with the controller. All `POST /api/send` traffic targets channel index 3 (`test`) on purpose — never the primary channel; override via `MESH_SEND_CHANNEL` (default `3`).
+2. **Endpoints** — all under the `/api` global prefix: `GET /api/status` (`{ connected, myNodeNum, host, port }`), `POST /api/send` (body `{ "text": "...", "to"?: <node number | node name | "!b" | "broadcast"> }` — numbers pass through as-is (integer 1..0xffffffff), names resolve like `GET /api/nodes/:id`, omitted/""/"!b"/"broadcast" → broadcast; unknown or ambiguous targets are a 400. Returns `{ id }`), `GET /api/channels` (the device's Meshtastic channels as `{ index, name, uplinkEnabled, downlinkEnabled }[]`; psk/keys redacted), `GET /api/device` (device info captured during the initial sync: `{ myNodeNum, firmwareVersion?, metadata?, localConfig: {<section>: ...}, moduleConfig: {<module>: ...} }` — DeviceMetadata as-is plus per-section Config/ModuleConfig messages; security publicKey/privateKey/adminKey and network wifiPsk redacted to `"REDACTED"`; in-memory, reset on reconnect), `GET /api/messages` (message history newest first: rx text with `from`, tx sends with `to` + `status` pending→delivered/failed via routing ACKs — broadcasts stay pending because firmware strips want_ack; last 100 in memory (seeded from SQLite on startup) — backed by SQLite: re-upserted every MESH_POLL_MS and pruned to the newest 1000 rows, so it survives process restarts and bridge reconnects), `POST /api/messages` (body `{ "text": "...", "from"?: <node number> }`, returns `{ id }`; synthetic inbox injection for external triggers — records an rx entry in the history as if received on the mesh (channel 0) so external systems can push messages to trigger communication later; NOT transmitted over RF, nothing goes to the bridge or air; appears in `GET /api/messages` like any other rx message), `GET /api/telemetry` (telemetry history newest first as `{ from, at /* epoch ms */, kind, data }[]`: live TELEMETRY_APP packets — device metrics and environment sensor readings where nodes have them; kind is the meshtastic.Telemetry oneof case name (deviceMetrics/environmentMetrics/airQualityMetrics/powerMetrics/localStats/healthMetrics/hostMetrics/trafficManagementStats), data that variant's payload with proto uint64 fields as decimal strings; last 100, in-memory, reset on reconnect), `GET /api/nodes` (known nodes sorted by num as `{ num, longName?, shortName?, hwModel?, batteryLevel?, lastHeard: number|null, position?: { lat, lon, alt? }, snr?, hopsAway?, viaMqtt? }[]`, from the initial sync plus live POSITION_APP updates; reset on reconnect) and `GET /api/nodes/:id` (lookup by exact node number/numeric string, then case-insensitive exact long/short name, else unique substring; 404 when ambiguous or missing). Scalar API docs are served at `/` (OpenAPI JSON at `/docs-json`). Keep this list in sync with the controller. All `POST /api/send` traffic targets channel index 3 (`test`) on purpose — never the primary channel; override via `MESH_SEND_CHANNEL` (default `3`). Message history is persisted to SQLite: file path from `MESH_DB_PATH` (default `./data/mesh-bot.db`, parent dir auto-created), poller re-upserts every `MESH_POLL_MS` ms (default 1000) and prunes the table to the newest 1000 rows.
-3. **MCP endpoint** — `POST /mcp` (excluded from the `/api` prefix in main.ts, like Scalar at `/`): an in-process MCP server over the official SDK's Streamable HTTP transport in stateless mode (`sessionIdGenerator: undefined`, fresh `McpServer` + transport per request). Tools map 1:1 to MeshService methods: `mesh_status`, `send_message(text, to?)` (same resolution as `POST /api/send`; errors surface as tool errors with the same messages), `list_channels`, `list_nodes`, `get_node(id)` (tool error when missing/ambiguous), `get_messages`, `device_info` (same redaction as `GET /api/device`). Results are JSON in a text content block; sends ride channel index 3 like everything else. Note: the SDK's root entry is broken upstream (#2273) — import via subpaths (`@modelcontextprotocol/sdk/server/mcp.js` etc.).
+3. **MCP endpoint** — `POST /mcp` (excluded from the `/api` prefix in main.ts, like Scalar at `/`): an in-process MCP server over the official SDK's Streamable HTTP transport in stateless mode (`sessionIdGenerator: undefined`, fresh `McpServer` + transport per request). Tools map 1:1 to MeshService methods: `mesh_status`, `send_message(text, to?)` (same resolution as `POST /api/send`; errors surface as tool errors with the same messages), `list_channels`, `list_nodes`, `get_node(id)` (tool error when missing/ambiguous), `get_messages`, `inject_message(text, from?)` (synthetic inbox injection for external triggers — records an rx entry in the history as if received on the mesh; NOT sent over RF; same validation as `POST /api/messages`), `get_telemetry` (same bounded recent window as `GET /api/telemetry`), `device_info` (same redaction as `GET /api/device`). Results are JSON in a text content block; sends ride channel index 3 like everything else. Note: the SDK's root entry is broken upstream (#2273) — import via subpaths (`@modelcontextprotocol/sdk/server/mcp.js` etc.).
 
 ## Other
 

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## v0.10.0 — 2026-09-25 00:30
+
+- Message history is now persisted to SQLite via the stdlib `node:sqlite` `DatabaseSync` (zero new dependencies). DB file path from env `MESH_DB_PATH` (default `./data/mesh-bot.db`, parent dir auto-created); poller interval from env `MESH_POLL_MS` (default `1000` ms — "frequent pooling, configurable"). Schema: one table `messages(id INTEGER PRIMARY KEY, dir TEXT NOT NULL, to_node INTEGER, from_node INTEGER, text TEXT NOT NULL, channel INTEGER NOT NULL, at INTEGER NOT NULL, status TEXT, ack_error TEXT)`, keyed by packet id.
+- Write path (the "pooling"): a `setInterval` poller started in `onModuleInit` re-upserts the ENTIRE current in-memory history buffer (≤100 rows) every tick with `INSERT OR REPLACE INTO messages ...`, then enforces retention with one statement keeping only the newest 1000 rows. Deliberately zero bookkeeping — trivial load at this scale.
+- Read path: on startup (before the bridge connect) the service seeds the history buffer from the database (`SELECT ... ORDER BY at DESC LIMIT 100`), so message history SURVIVES PROCESS RESTARTS. On bridge reconnect the node/channel/device/telemetry capture state resets exactly as before, but the message history is no longer cleared — it's now an append-only log backed by SQLite (tx records that were still `pending` at disconnect stay pending).
+- Testability: `MeshService` takes an optional `DatabaseSync` constructor argument (`null` = persistence disabled) so all 42 pre-existing specs construct without a database and touch no disk; new specs use `new DatabaseSync(':memory:')`. `flushHistory()` is public so tests can drive a poller tick without real timers.
+- Production wiring: `MeshModule` now provides `MeshService` through a factory that opens the file DB from env (mkdir -p on the parent dir + idempotent table init). `docker-compose.yml` adds a named volume (`mesh_data:/app/data`, matching the Dockerfile WORKDIR `/app`) so the DB survives container recreation, and passes through `MESH_DB_PATH`/`MESH_POLL_MS`.
+- Docs: README (new env vars + persistence note), AGENTS.md endpoint list, Swagger description of `GET /api/messages`, and the MCP `get_messages` tool description all updated from "in-memory only, reset on reconnect" to the SQLite-backed wording.
+- Tests: five new specs in a `MeshService SQLite persistence` block — poller tick persists an injected row without any manual flush; an ACK status mutation reaches the DB after the next tick; startup seeding loads the newest 100 of 150 pre-populated rows into `messages()`; retention prunes a 1200-row table to the newest 1000; and history survives a bridge reconnect (unlike channels/nodes/telemetry).
+
+## v0.9.0 — 2026-09-24 23:45
+
+- New `POST /api/messages` endpoint (and matching MCP tool `inject_message`, now nine tools): synthetic inbox injection for external triggers. Body `{ "text": "...", "from"?: <node number> }` records an rx entry in the message history as if received on the mesh (channel 0), so external systems can push messages into the bot's inbox to trigger communication later. NOT transmitted over RF — nothing is written to the bridge or air; the record appears in `GET /api/messages` like any other rx message and is subject to the same last-100 cap. Returns `{ id }` with a random uint32 packet id (same generation as tx sends).
+- New service method `MeshService.injectMessage(text, from?)`: pushes an rx record through the existing `pushHistory` cap pattern; `from` is optional and omitted from the record when absent (integer in 1..0xffffffff when provided — invalid values throw like `resolveDest`). Packet-id generation extracted from `buildTextToRadio` into a shared `randomPacketId()` helper so tx sends and injected records use one source of truth.
+- Validation: empty/missing text → 400 `text must be a non-empty string`; invalid `from` (non-integer, <1 or >0xffffffff) → 400 `invalid node number '<n>'`. Same messages surface as MCP tool errors for `inject_message`.
+- Swagger: `POST /api/messages` documented with the synthetic-injection caveat and an example. README + AGENTS.md endpoint/tool lists updated.
+- Tests: new service specs (injected rx records newest-first via `messages()`, `from` omitted when absent, empty-text/invalid-from rejection, cap at 100 dropping the oldest, shared buffer with captured packets); MCP spec updated to nine tools incl. an `inject_message` call check asserting nothing reaches the bridge socket (no ToRadio 'packet' variant on the wire).
+
+## v0.8.0 — 2026-09-24 21:40
+
+- New `GET /api/telemetry` endpoint (and matching MCP tool `get_telemetry`, now eight tools): the telemetry stream captured from live `TELEMETRY_APP` packets (portnum 67) — device metrics (uptime/battery/voltage/channel+air utilization) and environment sensor readings where nodes have them. Records are `{ from, at /* epoch ms */, kind, data }[]` newest first: `kind` is the `meshtastic.Telemetry` oneof case name (`deviceMetrics`, `environmentMetrics`, `airQualityMetrics`, `powerMetrics`, `localStats`, `healthMetrics`, `hostMetrics` or `trafficManagementStats`) and `data` is that variant's payload. In-memory only, last 100 (same bounded pattern as message history), reset on every bridge reconnect.
+- `MeshService.telemetry()` captures the new portnum in the existing packet handler: the `Data.payload` is decoded as a `meshtastic.Telemetry`, and packets without a variant payload are ignored. The variant payload goes through the same module-scope `jsonSafe` converter added in v0.7.1 — telemetry variants carry proto `uint64` fields (e.g. host-metrics byte counters) that decode to native bigint and would 500 Express' `res.json` otherwise, so they come back as decimal strings; unset optional fields are omitted from `data`.
+- Verified against the installed `@meshtastic/protobufs` 2.8.0: `PortNum.TELEMETRY_APP = 67`; `Telemetry` is a `fixed32 time` plus oneof variant with exactly those eight cases; `DeviceMetrics` fields are batteryLevel/voltage/channelUtilization/airUtilTx/uptimeSeconds and `EnvironmentMetrics` the full sensor set (temperature, relativeHumidity, barometricPressure, gasResistance, voltage, current, iaq, distance, lux variants, wind/rainfall/soil/lightning, adc channels).
+- Swagger: `GET /api/telemetry` documented with the kind values and an example carrying one record per kind. README + AGENTS.md endpoint/tool lists updated.
+- Tests: fake-bridge gains a shared `telemetryPacketFrame` builder; new telemetry specs (device-metrics + environment variants → correct from/kind/data, cap at 100 dropping the oldest, reset on reconnect); MCP spec updated to eight tools incl. a `get_telemetry` call check.
+
 ## v0.7.1 — 2026-09-24 21:10
 
 - Fix `GET /api/device` and MCP `device_info` crashing with `TypeError: Do not know how to serialize a BigInt` on live hardware (fw 2.7.15): protobuf-es decodes proto `uint64` fields as native JS `bigint`, which Express' `res.json`/`JSON.stringify` reject, and `MeshService.deviceInfo()` passed raw decoded proto objects through unconverted. Known affected fields: `Config.PowerConfig.powermonEnables` (in `localConfig.power`) and host-metrics byte counters (`freememBytes`/`diskfree*`).

README.md

@@ -29,7 +29,9 @@ All API endpoints live under the `/api` prefix:
 - `POST /api/send` — body `{ "text": "...", "to"?: <node number | node name | "!b" | "broadcast"> }`, returns `{ id }`. Numbers pass through as-is (integer in 1..0xffffffff); names resolve like `GET /api/nodes/:id` (exact long/short name, then unique substring) — unknown or ambiguous targets are a 400
 - `GET /api/channels` — the device's Meshtastic channels as `{ index, name, uplinkEnabled, downlinkEnabled }[]` (psk/keys are redacted; empty until the initial sync completes)
 - `GET /api/device` — device info captured during the initial sync: `{ myNodeNum, firmwareVersion?, metadata?, localConfig: {<section>: ...}, moduleConfig: {<module>: ...} }`. Key material is never exposed (security publicKey/privateKey/adminKey and network wifiPsk are replaced with `"REDACTED"`); in-memory only, reset on every bridge reconnect
-- `GET /api/messages` — message history, newest first: inbound text (`dir:'rx'`, with `from`) and our sends (`dir:'tx'`, with `to` + `status`). tx records start `pending` and move to `delivered`/`failed` (with human-readable `ackError`) when the routing ACK/NACK arrives; broadcasts stay `pending` because firmware strips want_ack before TX. In-memory only, last 100, reset on every bridge reconnect
+- `GET /api/messages` — message history, newest first: inbound text (`dir:'rx'`, with `from`) and our sends (`dir:'tx'`, with `to` + `status`). tx records start `pending` and move to `delivered`/`failed` (with human-readable `ackError`) when the routing ACK/NACK arrives; broadcasts stay `pending` because firmware strips want_ack before TX. Backed by SQLite: the in-memory buffer (last 100) is seeded from the database on startup and re-upserted every second, so history survives process restarts and bridge reconnects; the database keeps the newest 1000 rows
+- `POST /api/messages` — body `{ "text": "...", "from"?: <node number> }`, returns `{ id }`. Synthetic inbox injection for external triggers: records an rx entry in the history as if received on the mesh (channel 0) so external systems can push messages to trigger communication later. NOT transmitted over RF; appears in `GET /api/messages` like any other rx message
+- `GET /api/telemetry` — telemetry history, newest first: live `TELEMETRY_APP` packets from any node as `{ from, at /* epoch ms */, kind, data }[]`. `kind` is the `meshtastic.Telemetry` oneof case name (`deviceMetrics`, `environmentMetrics`, `airQualityMetrics`, `powerMetrics`, `localStats`, `healthMetrics`, `hostMetrics` or `trafficManagementStats`) and `data` carries that variant's payload (proto uint64 fields as decimal strings; unset optional fields omitted). In-memory only, last 100, reset on every bridge reconnect
 - `GET /api/nodes` — known mesh nodes as `{ num, longName?, shortName?, hwModel?, batteryLevel?, lastHeard: number|null, position?: { lat, lon, alt? }, snr?, hopsAway?, viaMqtt? }[]`, sorted by node number. Collected during the initial sync plus live position updates; names/hwModel/battery appear only when reported, `lastHeard` is epoch seconds (null = never heard), `position` only when both coordinates are known, and snr/hopsAway/viaMqtt only when carried by the NodeInfo
 - `GET /api/nodes/:id` — one node looked up by exact node number (numbers or numeric strings), then case-insensitive exact long/short name, else the unique case-insensitive substring match; 404 when nothing or more than one node matches
 
@@ -43,6 +45,8 @@ curl -X POST http://localhost:3000/api/send -H 'content-type: application/json'
 curl http://localhost:3000/api/channels
 curl http://localhost:3000/api/device
 curl http://localhost:3000/api/messages
+curl -X POST http://localhost:3000/api/messages -H 'content-type: application/json' -d '{"text":"external trigger"}'
+curl http://localhost:3000/api/telemetry
 curl http://localhost:3000/api/nodes
 curl http://localhost:3000/api/nodes/kamil
 ```
@@ -68,6 +72,8 @@ endpoints — no new logic, same channel pinning:
 - `list_nodes` — known nodes as lean summaries
 - `get_node(id)` — one node by number or name; tool error when missing/ambiguous
 - `get_messages` — message history, newest first (last 100, tx records carry delivery status)
+- `inject_message(text, from?)` — synthetic inbox injection for external triggers: records an rx entry in the history as if received on the mesh; NOT sent over RF; appears in `get_messages` like any other rx record
+- `get_telemetry` — telemetry history, newest first (last 100): device metrics and environment sensor readings from any node; `kind` is the Telemetry oneof case name
 - `device_info` — device info from the initial sync: node number, firmware version, metadata and per-section config/module-config (key material redacted as `"REDACTED"`)
 
 Point any MCP client at it (Streamable HTTP URL):
@@ -89,6 +95,8 @@ curl -X POST http://localhost:3000/mcp \
 - `MESH_PORT` (default `4403`) — bridge port
 - `MESH_RECONNECT_MS` (default `5000`) — reconnect interval in ms
 - `MESH_SEND_CHANNEL` (default `3`) — channel index all sends target (`test`; never the primary channel)
+- `MESH_DB_PATH` (default `./data/mesh-bot.db`) — SQLite file backing the message history (parent dir created if missing; in Docker, mounted at `/app/data` via a named volume so it survives container recreation)
+- `MESH_POLL_MS` (default `1000`) — how often the poller re-upserts the message history into SQLite and prunes rows beyond the newest 1000
 - `PORT` (default `3000`) — HTTP listen port
 
 Note: the serial bridge accepts only ONE client at a time — if another app is

docker-compose.yml

@@ -4,6 +4,10 @@ services:
     environment:
       MESH_HOST: 192.168.1.4
       MESH_PORT: '4403'
+      MESH_DB_PATH: ./data/mesh-bot.db
+      MESH_POLL_MS: '1000'
+    volumes:
+      - mesh_data:/app/data
     restart: unless-stopped
     networks:
       - dev_net
@@ -13,6 +17,9 @@ services:
       - 'traefik.http.routers.mesh-bot.entrypoints=web'
       - 'traefik.http.services.mesh-bot.loadbalancer.server.port=3000'
 
+volumes:
+  mesh_data:
+
 networks:
   dev_net:
     external: true

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mesh-bot",
-  "version": "0.7.1",
+  "version": "0.10.0",
   "description": "",
   "author": "",
   "private": true,

src/mesh/codec.ts

@@ -14,6 +14,8 @@ export const PORT_TEXT_MESSAGE_APP = 1;
 export const PORT_POSITION_APP = 3;
 // verified against installed @meshtastic/protobufs Portnums.PortNum.ROUTING_APP
 export const PORT_ROUTING_APP = 5;
+// verified against installed @meshtastic/protobufs Portnums.PortNum.TELEMETRY_APP
+export const PORT_TELEMETRY_APP = 67;
 
 const START1 = 0x94;
 const START2 = 0xc3;
@@ -81,6 +83,14 @@ export async function decodeRouting(
   return fromBinary(P.Mesh.RoutingSchema, bytes);
 }
 
+/** TELEMETRY_APP packets carry a serialized meshtastic.Telemetry in Data.payload. */
+export async function decodeTelemetry(
+  bytes: Uint8Array,
+): Promise<import('@meshtastic/protobufs').Telemetry.Telemetry> {
+  const P = await loadProto();
+  return fromBinary(P.Telemetry.TelemetrySchema, bytes);
+}
+
 /** Human-readable name for a Routing.Error code (from the installed @meshtastic/protobufs enum), `reason <n>` fallback. */
 export async function describeRoutingError(code: number): Promise<string> {
   const P = await loadProto();
@@ -105,14 +115,20 @@ export async function loadHwModelNames(): Promise<Map<number, string>> {
   return hwModelNames;
 }
 
+/** Random non-zero uint32 packet id. */
+export function randomPacketId(): number {
+  let id = Math.floor(Math.random() * 0x100000000) >>> 0;
+  if (id === 0) id = 1; // non-zero uint32
+  return id;
+}
+
 export async function buildTextToRadio(
   to: number,
   text: string,
   channelIndex: number,
 ): Promise<{ bytes: Uint8Array; id: number }> {
   const P = await loadProto();
-  let id = Math.floor(Math.random() * 0x100000000) >>> 0;
+  const id = randomPacketId();
-  if (id === 0) id = 1; // non-zero uint32
   const meshPacket = create(P.Mesh.MeshPacketSchema, {
     to,
     id,

src/mesh/fake-bridge.ts

@@ -121,6 +121,33 @@ export function nodeInfoFrame(
   );
 }
 
+/** TELEMETRY_APP packet frame with a serialized Telemetry in Data.payload (live telemetry from any node). */
+export function telemetryPacketFrame(
+  from: number,
+  variant: P.Telemetry.Telemetry['variant'],
+): Uint8Array {
+  const data = create(P.Mesh.DataSchema, {
+    portnum: P.Portnums.PortNum.TELEMETRY_APP,
+    payload: toBinary(
+      P.Telemetry.TelemetrySchema,
+      create(P.Telemetry.TelemetrySchema, { variant }),
+    ),
+  });
+  const pkt = create(P.Mesh.MeshPacketSchema, {
+    from,
+    id: 1,
+    payloadVariant: { case: 'decoded', value: data },
+  });
+  return frame(
+    toBinary(
+      P.Mesh.FromRadioSchema,
+      create(P.Mesh.FromRadioSchema, {
+        payloadVariant: { case: 'packet', value: pkt },
+      }),
+    ),
+  );
+}
+
 export const KAMIL_NUM = 123456789;
 
 export function kamilNodeInfo(): NodeInfoFields {

src/mesh/mcp.controller.spec.ts

@@ -1,13 +1,16 @@
+import { fromBinary } from '@bufbuild/protobuf';
+import * as P from '@meshtastic/protobufs';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import type * as net from 'node:net';
 import { describe, expect, it } from 'vitest';
-import { BROADCAST_ADDR } from './codec.js';
+import { BROADCAST_ADDR, extractFrames } from './codec.js';
 import {
   KAMIL_NUM,
   kamilNodeInfo,
   nodeInfoFrame,
   startBridge,
+  telemetryPacketFrame,
   waitFor,
 } from './fake-bridge.js';
 import { createMeshMcpServer } from './mcp.controller.js';
@@ -64,7 +67,7 @@ async function connectMcp(svc: MeshService): Promise<{
 }
 
 describe('MCP server tools', () => {
-  it('lists all seven tools with descriptions and input schemas', async () => {
+  it('lists all nine tools with descriptions and input schemas', async () => {
     const env = await connectedService();
     try {
       const mcp = await connectMcp(env.svc);
@@ -74,6 +77,8 @@ describe('MCP server tools', () => {
           'device_info',
           'get_messages',
           'get_node',
+          'get_telemetry',
+          'inject_message',
           'list_channels',
           'list_nodes',
           'mesh_status',
@@ -87,6 +92,13 @@ describe('MCP server tools', () => {
           'text',
           'to',
         ]);
+
+        const inject = tools.find((t) => t.name === 'inject_message')!;
+        expect(inject.inputSchema.required).toEqual(['text']);
+        expect(Object.keys(inject.inputSchema.properties ?? {})).toEqual([
+          'text',
+          'from',
+        ]);
       } finally {
         await mcp.close();
       }
@@ -183,6 +195,68 @@ describe('MCP server tools', () => {
     }
   });
 
+  it('inject_message records an rx entry without sending over RF', async () => {
+    const env = await connectedService();
+    try {
+      const mcp = await connectMcp(env.svc);
+      try {
+        // capture outbound bytes: the only frame ever written on connect is want_config,
+        // so any 'packet' variant after this point would be an RF transmission
+        const out: Uint8Array[] = [];
+        env.sockets[0].on('data', (c) => out.push(c));
+
+        const r1 = await mcp.client.callTool({
+          name: 'inject_message',
+          arguments: { text: 'trigger' },
+        });
+        expect(r1.isError).not.toBe(true);
+        const inj = JSON.parse(toolText(r1)) as { id: number };
+        expect(inj.id).toBeGreaterThan(0);
+        expect(env.svc.messages()[0]).toMatchObject({
+          dir: 'rx',
+          text: 'trigger',
+          channel: 0,
+        });
+
+        const r2 = await mcp.client.callTool({
+          name: 'inject_message',
+          arguments: { text: 'from kamil', from: KAMIL_NUM },
+        });
+        expect(r2.isError).not.toBe(true);
+        expect(env.svc.messages()[0]).toMatchObject({
+          dir: 'rx',
+          from: KAMIL_NUM,
+          text: 'from kamil',
+        });
+
+        const r3 = await mcp.client.callTool({
+          name: 'inject_message',
+          arguments: { text: 'x', from: 0 },
+        });
+        expect(r3.isError).toBe(true);
+        expect(toolText(r3)).toContain('invalid node number');
+
+        // nothing went over the wire — synthetic inbox injection only.
+        // The want_config frame (written on connect) may or may not have been captured;
+        // what matters is that no ToRadio 'packet' variant ever made it to the bridge.
+        const merged = new Uint8Array(out.reduce((n, c) => n + c.length, 0));
+        let off = 0;
+        for (const c of out) {
+          merged.set(c, off);
+          off += c.length;
+        }
+        for (const p of extractFrames(merged).packets) {
+          const tr = fromBinary(P.Mesh.ToRadioSchema, p);
+          expect(tr.payloadVariant?.case).not.toBe('packet');
+        }
+      } finally {
+        await mcp.close();
+      }
+    } finally {
+      env.close();
+    }
+  });
+
   it('get_node resolves by name and errors when missing', async () => {
     const env = await connectedService();
     try {
@@ -263,6 +337,25 @@ describe('MCP server tools', () => {
           ),
         ) as { dir: string; to?: number }[];
         expect(msgs[0]).toMatchObject({ dir: 'tx', to: BROADCAST_ADDR }); // newest first
+
+        env.sockets[0].write(
+          telemetryPacketFrame(KAMIL_NUM, {
+            case: 'deviceMetrics',
+            value: { batteryLevel: 87 },
+          }),
+        );
+        await waitFor(() => env.svc.telemetry().length === 1);
+        const tel = JSON.parse(
+          toolText(
+            await mcp.client.callTool({ name: 'get_telemetry', arguments: {} }),
+          ),
+        ) as { from: number; kind: string; data: object }[];
+        expect(tel).toHaveLength(1);
+        expect(tel[0]).toMatchObject({
+          from: KAMIL_NUM,
+          kind: 'deviceMetrics',
+        });
+        expect(tel[0].data).toEqual({ batteryLevel: 87 });
       } finally {
         await mcp.close();
       }

src/mesh/mcp.controller.ts

@@ -72,11 +72,28 @@ export function createMeshMcpServer(mesh: MeshService): McpServer {
   server.registerTool(
     'get_messages',
     {
-      description: `Message history, newest first (last 100): inbound text (dir "rx", with from) and our sends (dir "tx", with to + status pending→delivered/failed; broadcasts stay pending because firmware strips want_ack). In-memory only, reset on every bridge reconnect.${CHANNEL_NOTE}`,
+      description: `Message history, newest first (last 100): inbound text (dir "rx", with from) and our sends (dir "tx", with to + status pending→delivered/failed; broadcasts stay pending because firmware strips want_ack). Backed by SQLite — seeded on startup and re-upserted every second, so it survives restarts and bridge reconnects (the database keeps the newest 1000 rows).${CHANNEL_NOTE}`,
     },
     async () => jsonResult(mesh.messages()),
   );
 
+  server.registerTool(
+    'inject_message',
+    {
+      description: `Synthetic inbox injection for external triggers: records an rx entry in the message history as if received on the mesh — NOT sent over RF, nothing goes to the bridge or air. Appears in get_messages like any other rx record (channel 0). from is optional (integer in 1..0xffffffff); empty text or invalid from are tool errors.${CHANNEL_NOTE}`,
+      inputSchema: { text: z.string(), from: z.number().int().optional() },
+    },
+    async ({ text, from }) => jsonResult(mesh.injectMessage(text, from)),
+  );
+
+  server.registerTool(
+    'get_telemetry',
+    {
+      description: `Telemetry history, newest first (bounded recent window, last 100): TELEMETRY_APP packets from any node — device metrics (uptime/battery/voltage/channel+air utilization) and environment sensor readings where nodes have them. kind is the meshtastic.Telemetry oneof case name; data carries that variant's payload (proto uint64 fields as decimal strings). In-memory only, reset on every bridge reconnect.${CHANNEL_NOTE}`,
+    },
+    async () => jsonResult(mesh.telemetry()),
+  );
+
   server.registerTool(
     'device_info',
     {

src/mesh/mesh.controller.ts

@@ -16,6 +16,18 @@ import {
 import type { DeviceInfo } from './mesh.service.js';
 import { MeshService } from './mesh.service.js';
 
+export class InjectMessageDto {
+  @ApiProperty({ description: 'Message text', example: 'external trigger' })
+  text!: string;
+  @ApiProperty({
+    required: false,
+    description:
+      'Sender node number (integer in 1..0xffffffff); omitted when the external source has no mesh identity.',
+    example: 987654321,
+  })
+  from?: number;
+}
+
 export class SendTextDto {
   @ApiProperty({ description: 'Message text', example: 'hello' })
   text!: string;
@@ -154,7 +166,7 @@ export class MeshController {
   @ApiOperation({
     summary: 'Message history (last 100)',
     description:
-      'Inbound text messages and our sends, newest first. tx records start "pending" and move to "delivered"/"failed" when the routing ACK/NACK arrives; broadcasts stay "pending" because firmware strips want_ack before TX. History is in-memory only (last 100) and resets on every bridge reconnect.',
+      'Inbound text messages and our sends, newest first. tx records start "pending" and move to "delivered"/"failed" when the routing ACK/NACK arrives; broadcasts stay "pending" because firmware strips want_ack before TX. History is backed by SQLite: the in-memory buffer (last 100) is seeded from the database on startup and re-upserted every second, so it survives process restarts and bridge reconnects; the database keeps the newest 1000 rows.',
   })
   @ApiResponse({
     status: 200,
@@ -183,6 +195,62 @@ export class MeshController {
     return this.mesh.messages();
   }
 
+  @Post('messages')
+  @ApiOperation({
+    summary: 'Inject a synthetic inbound message into the history',
+    description:
+      'Synthetic inbox injection for external triggers: records an rx entry in the message history as if received on the mesh, so external systems can push messages to trigger communication later. NOT transmitted over RF — nothing is sent to the bridge or air. The record appears in GET /api/messages like any other rx message (dir "rx", channel 0). Returns { id } with a random uint32 packet id.',
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'Record injected',
+    example: { id: 123456789 },
+  })
+  @ApiResponse({ status: 400, description: 'Invalid text or from' })
+  injectMessage(@Body() body: InjectMessageDto) {
+    try {
+      return this.mesh.injectMessage(body?.text, body?.from);
+    } catch (err) {
+      throw new BadRequestException(
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  @Get('telemetry')
+  @ApiOperation({
+    summary: 'Telemetry history (last 100)',
+    description:
+      "TELEMETRY_APP packets from any node, newest first. Device metrics (uptime/battery/voltage/channel+air utilization) and environment sensor readings where nodes have them; kind is the meshtastic.Telemetry oneof case name — deviceMetrics, environmentMetrics, airQualityMetrics, powerMetrics, localStats, healthMetrics, hostMetrics or trafficManagementStats — and data carries that variant's payload (proto uint64 fields as decimal strings). In-memory only (last 100), reset on every bridge reconnect.",
+  })
+  @ApiResponse({
+    status: 200,
+    description: 'Telemetry records newest first',
+    example: [
+      {
+        from: 987654321,
+        at: 1758000123456,
+        kind: 'deviceMetrics',
+        data: {
+          batteryLevel: 87,
+          voltage: 4.1,
+          channelUtilization: 12.5,
+          airUtilTx: 3.2,
+          uptimeSeconds: 86400,
+        },
+      },
+      {
+        from: 123456789,
+        at: 1758000000000,
+        kind: 'environmentMetrics',
+        data: { temperature: 21.5, relativeHumidity: 48 },
+      },
+    ],
+  })
+  telemetry() {
+    return this.mesh.telemetry();
+  }
+
   @Get('nodes')
   @ApiOperation({
     summary: 'Known mesh nodes (lean summaries)',

src/mesh/mesh.module.ts

@@ -1,10 +1,27 @@
 import { Module } from '@nestjs/common';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
 import { McpController } from './mcp.controller.js';
 import { MeshController } from './mesh.controller.js';
-import { MeshService } from './mesh.service.js';
+import { initMessagesTable, MeshService } from './mesh.service.js';
+
+// SQLite-backed message history: file path from MESH_DB_PATH (default ./data/mesh-bot.db), parent dir created if missing.
+function openMessageDb(): DatabaseSync {
+  const path = process.env.MESH_DB_PATH ?? './data/mesh-bot.db';
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new DatabaseSync(path);
+  initMessagesTable(db);
+  return db;
+}
 
 @Module({
   controllers: [MeshController, McpController],
-  providers: [MeshService],
+  providers: [
+    {
+      provide: MeshService,
+      useFactory: () => new MeshService(openMessageDb()),
+    },
+  ],
 })
 export class MeshModule {}

src/mesh/mesh.service.spec.ts

@@ -1,5 +1,6 @@
 import { create, fromBinary, toBinary } from '@bufbuild/protobuf';
 import * as P from '@meshtastic/protobufs';
+import { DatabaseSync } from 'node:sqlite';
 import { describe, expect, it } from 'vitest';
 import { BROADCAST_ADDR, extractFrames, frame } from './codec.js';
 import {
@@ -10,9 +11,10 @@ import {
   moduleConfigSectionFrame,
   nodeInfoFrame,
   startBridge,
+  telemetryPacketFrame,
   waitFor,
 } from './fake-bridge.js';
-import { MeshService } from './mesh.service.js';
+import { initMessagesTable, MeshService } from './mesh.service.js';
 
 // live position update: POSITION_APP packet with a serialized Position in Data.payload
 function positionPacketFrame(
@@ -560,6 +562,209 @@ describe('MeshService message history', () => {
   });
 });
 
+describe('MeshService injectMessage', () => {
+  it('injects rx records that appear newest-first in messages()', () => {
+    const svc = new MeshService();
+    expect(svc.messages()).toEqual([]);
+
+    const r1 = svc.injectMessage('first');
+    const r2 = svc.injectMessage('second', KAMIL_NUM);
+    expect(r1.id).toBeGreaterThan(0); // random non-zero uint32, like tx ids
+    expect(r2.id).toBeGreaterThan(0);
+
+    expect(svc.messages()).toEqual([
+      {
+        id: r2.id,
+        dir: 'rx',
+        from: KAMIL_NUM,
+        text: 'second',
+        channel: 0,
+        at: expect.any(Number),
+      },
+      {
+        id: r1.id,
+        dir: 'rx',
+        text: 'first',
+        channel: 0,
+        at: expect.any(Number),
+      },
+    ]);
+  });
+
+  it('omits from when not provided and rejects empty text or invalid from', () => {
+    const svc = new MeshService();
+    const rec = svc.injectMessage('no sender');
+    expect(svc.messages()[0]).toEqual({
+      id: rec.id,
+      dir: 'rx',
+      text: 'no sender',
+      channel: 0,
+      at: expect.any(Number),
+    });
+    expect(svc.messages()[0]).not.toHaveProperty('from');
+
+    for (const bad of ['', undefined]) {
+      expect(() => svc.injectMessage(bad as unknown as string)).toThrow(
+        'text must be a non-empty string',
+      );
+    }
+    for (const bad of [0, -1, 42.5, BROADCAST_ADDR + 1]) {
+      expect(() => svc.injectMessage('x', bad)).toThrow(/invalid node number/);
+    }
+    expect(svc.messages()).toHaveLength(1); // rejected calls add nothing
+  });
+
+  it('caps history at 100 records, dropping the oldest', () => {
+    const svc = new MeshService();
+    for (let i = 0; i < 105; i++) svc.injectMessage(`m-${i}`);
+    expect(svc.messages()).toHaveLength(100);
+    expect(svc.messages()[0]?.text).toBe('m-104'); // newest first
+    expect(svc.messages()[99]?.text).toBe('m-5'); // m-0..m-4 dropped
+  });
+
+  it('shares the history buffer with captured packets', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    const svc = new MeshService();
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      svc.injectMessage('injected');
+      bridge.sockets[0].write(textPacketFrame(KAMIL_NUM, 42, 'real', 2));
+
+      await waitFor(() => svc.messages().length === 2);
+      expect(svc.messages()[0]).toMatchObject({ dir: 'rx', text: 'real' }); // newest first
+      expect(svc.messages()[1]).toMatchObject({
+        dir: 'rx',
+        text: 'injected',
+        channel: 0,
+      });
+    } finally {
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+});
+
+describe('MeshService telemetry', () => {
+  it('captures device metrics and environment variants with from/kind/data', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    const svc = new MeshService();
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      expect(svc.telemetry()).toEqual([]); // nothing before the first packet
+
+      bridge.sockets[0].write(
+        telemetryPacketFrame(KAMIL_NUM, {
+          case: 'deviceMetrics',
+          value: { batteryLevel: 87, voltage: 4.1, uptimeSeconds: 3600 },
+        }),
+      );
+      bridge.sockets[0].write(
+        telemetryPacketFrame(987654321, {
+          case: 'environmentMetrics',
+          value: { temperature: 21.5, relativeHumidity: 48 },
+        }),
+      );
+
+      await waitFor(() => svc.telemetry().length === 2);
+      expect(svc.telemetry()).toEqual([
+        {
+          from: 987654321, // newest first
+          at: expect.any(Number),
+          kind: 'environmentMetrics',
+          // the deprecated repeated one_wire_temperature field decodes as an empty list even when unset
+          data: {
+            temperature: 21.5,
+            relativeHumidity: 48,
+            oneWireTemperature: [],
+          },
+        },
+        {
+          from: KAMIL_NUM,
+          at: expect.any(Number),
+          kind: 'deviceMetrics',
+          // proto float is IEEE-754 single precision — 4.1 widens to this exact double
+          data: {
+            batteryLevel: 87,
+            voltage: 4.099999904632568,
+            uptimeSeconds: 3600,
+          },
+        },
+      ]);
+    } finally {
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+
+  it('caps telemetry at 100 records, dropping the oldest', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    const svc = new MeshService();
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      for (let i = 0; i < 105; i++)
+        bridge.sockets[0].write(
+          telemetryPacketFrame(42, {
+            case: 'deviceMetrics',
+            value: { batteryLevel: i },
+          }),
+        );
+
+      await waitFor(() => svc.telemetry().length === 100, 10000);
+      expect(svc.telemetry()[0]?.data).toEqual({ batteryLevel: 104 }); // newest first
+      expect(svc.telemetry()[99]?.data).toEqual({ batteryLevel: 5 }); // i=0..4 dropped
+    } finally {
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+
+  it('resets telemetry on reconnect (no stale data)', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    process.env.MESH_RECONNECT_MS = '50';
+    const svc = new MeshService();
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      bridge.sockets[0].write(
+        telemetryPacketFrame(KAMIL_NUM, { case: 'deviceMetrics', value: {} }),
+      );
+      await waitFor(() => svc.telemetry().length === 1);
+
+      // drop the connection; bot reconnects and must start with an empty history
+      bridge.sockets[0].destroy();
+      await waitFor(() => bridge.sockets.length >= 2 && svc.status().connected);
+      await waitFor(() => svc.telemetry().length === 0);
+    } finally {
+      delete process.env.MESH_RECONNECT_MS;
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+});
+
 describe('MeshService resolveDest', () => {
   it('resolves broadcast sentinels, numbers and names to node numbers', async () => {
     const bridge = await startBridge();
@@ -783,3 +988,197 @@ describe('MeshService device info', () => {
     }
   });
 });
+
+describe('MeshService SQLite persistence', () => {
+  it('persists an injected message row on poller tick (no manual flush)', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    process.env.MESH_POLL_MS = '50';
+    const db = new DatabaseSync(':memory:');
+    initMessagesTable(db);
+    const svc = new MeshService(db);
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      svc.injectMessage('hello db', KAMIL_NUM);
+
+      // the poller tick must pick it up — no flushHistory() call here
+      await waitFor(
+        () =>
+          (
+            db.prepare('SELECT COUNT(*) AS n FROM messages').get() as {
+              n: number;
+            }
+          ).n === 1,
+      );
+      const row = db
+        .prepare('SELECT * FROM messages WHERE text = ?')
+        .get('hello db') as Record<string, unknown>;
+      expect(row.dir).toBe('rx');
+      expect(row.from_node).toBe(KAMIL_NUM);
+      expect(row.to_node).toBeNull(); // rx rows carry no destination
+      expect(row.channel).toBe(0);
+      expect(row.status).toBeNull();
+    } finally {
+      delete process.env.MESH_POLL_MS;
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+
+  it('reflects the ACK status update in the database after the next tick', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    process.env.MESH_POLL_MS = '50';
+    const db = new DatabaseSync(':memory:');
+    initMessagesTable(db);
+    const svc = new MeshService(db);
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      const id = await svc.sendText(42, 'ack me');
+      expect(svc.messages()[0]?.status).toBe('pending');
+
+      bridge.sockets[0].write(routingFrame(id, P.Mesh.Routing_Error.NONE));
+      await waitFor(() => svc.messages()[0]?.status === 'delivered');
+
+      // the in-place status mutation must reach SQLite on the next poller tick
+      // (the row may not exist before the first tick — waitFor re-checks, so stay null-safe)
+      await waitFor(
+        () =>
+          (
+            db.prepare('SELECT status FROM messages WHERE id = ?').get(id) as
+              | {
+                  status: string | null;
+                }
+              | undefined
+          )?.status === 'delivered',
+      );
+    } finally {
+      delete process.env.MESH_POLL_MS;
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+
+  it('seeds the history buffer from a pre-populated database on startup', () => {
+    const db = new DatabaseSync(':memory:');
+    initMessagesTable(db);
+    const ins = db.prepare(
+      'INSERT INTO messages(id, dir, to_node, from_node, text, channel, at, status, ack_error) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    );
+    for (let i = 0; i < 150; i++)
+      ins.run(
+        1000 + i,
+        'rx',
+        null,
+        42,
+        `seed-${i}`,
+        0,
+        1_700_000_000_000 + i * 1000,
+        null,
+        null,
+      );
+
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = '1'; // closed port — no real bridge needed for seeding
+    const svc = new MeshService(db);
+    try {
+      svc.onModuleInit();
+      expect(svc.messages()).toHaveLength(100); // newest 100 of the 150 rows
+      expect(svc.messages()[0]).toMatchObject({
+        id: 1149,
+        dir: 'rx',
+        from: 42,
+        text: 'seed-149',
+        channel: 0,
+      }); // newest first
+      expect(svc.messages()[99]).toMatchObject({ id: 1050, text: 'seed-50' });
+      expect(svc.messages()[0]).not.toHaveProperty('status'); // rx rows carry no status
+    } finally {
+      delete process.env.MESH_HOST;
+      delete process.env.MESH_PORT;
+      svc.onModuleDestroy();
+    }
+  });
+
+  it('prunes database rows beyond the retention limit (newest 1000)', () => {
+    const db = new DatabaseSync(':memory:');
+    initMessagesTable(db);
+    const ins = db.prepare(
+      'INSERT INTO messages(id, dir, to_node, from_node, text, channel, at, status, ack_error) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    );
+    for (let i = 0; i < 1200; i++)
+      ins.run(
+        5000 + i,
+        'rx',
+        null,
+        42,
+        `old-${i}`,
+        0,
+        1_700_000_000_000 + i * 1000,
+        null,
+        null,
+      );
+
+    const svc = new MeshService(db); // no onModuleInit — flushHistory() is the unit under test
+    try {
+      svc.flushHistory(); // empty buffer: upserts nothing, retention still applies
+      expect(
+        (
+          db.prepare('SELECT COUNT(*) AS n FROM messages').get() as {
+            n: number;
+          }
+        ).n,
+      ).toBe(1000);
+      expect(
+        db.prepare('SELECT text FROM messages WHERE id = ?').get(6199),
+      ).toMatchObject({ text: 'old-1199' }); // newest kept
+      expect(
+        db.prepare('SELECT text FROM messages WHERE id = ?').get(5199),
+      ).toBeUndefined(); // oldest 200 pruned (i=0..199)
+    } finally {
+      svc.onModuleDestroy();
+    }
+  });
+
+  it('keeps the message history across a bridge reconnect', async () => {
+    const bridge = await startBridge();
+    process.env.MESH_HOST = '127.0.0.1';
+    process.env.MESH_PORT = String(bridge.port);
+    process.env.MESH_RECONNECT_MS = '50';
+    const db = new DatabaseSync(':memory:');
+    initMessagesTable(db);
+    const svc = new MeshService(db);
+    try {
+      svc.onModuleInit();
+      await waitFor(
+        () => bridge.sockets.length === 1 && svc.status().connected,
+      );
+
+      svc.injectMessage('survives reconnect', KAMIL_NUM);
+      expect(svc.messages()).toHaveLength(1);
+
+      // drop the connection; bot reconnects and must keep the history (unlike channels/nodes/telemetry)
+      bridge.sockets[0].destroy();
+      await waitFor(() => bridge.sockets.length >= 2 && svc.status().connected);
+      expect(svc.messages()).toHaveLength(1);
+      expect(svc.messages()[0]).toMatchObject({
+        dir: 'rx',
+        text: 'survives reconnect',
+      });
+    } finally {
+      delete process.env.MESH_RECONNECT_MS;
+      svc.onModuleDestroy();
+      bridge.close();
+    }
+  });
+});

src/mesh/mesh.service.ts

@@ -6,21 +6,26 @@ import {
   ServiceUnavailableException,
 } from '@nestjs/common';
 import * as net from 'node:net';
+// type-only import: node:sqlite is only required at runtime by whoever opens a database (mesh.module.ts / tests)
+import type { DatabaseSync } from 'node:sqlite';
 import type * as Proto from '@meshtastic/protobufs';
 import {
   BROADCAST_ADDR,
   PORT_POSITION_APP,
   PORT_ROUTING_APP,
+  PORT_TELEMETRY_APP,
   PORT_TEXT_MESSAGE_APP,
   buildTextToRadio,
   buildWantConfigToRadio,
   decodeFromRadio,
   decodePosition,
   decodeRouting,
+  decodeTelemetry,
   describeRoutingError,
   extractFrames,
   frame,
   loadHwModelNames,
+  randomPacketId,
 } from './codec.js';
 
 /** One entry in the message history: an inbound text (dir 'rx') or one of our sends (dir 'tx'). */
@@ -41,8 +46,40 @@ export interface MessageRecord {
   ackError?: string;
 }
 
-// bounded history: keep the newest N records, in-memory only
+/** One entry in the telemetry history: a TELEMETRY_APP packet from some node. */
+export interface TelemetryRecord {
+  /** sender node num */
+  from: number;
+  /** epoch ms */
+  at: number;
+  /** meshtastic.Telemetry oneof case name (e.g. "deviceMetrics", "environmentMetrics") */
+  kind: string;
+  /** the variant payload, JSON-safe (proto uint64 fields as decimal strings); unset optional fields omitted */
+  data: object;
+}
+
+// bounded in-memory buffer: keep the newest N records (SQLite keeps more — see MESSAGES_DDL)
 const HISTORY_LIMIT = 100;
+/** Rows kept in SQLite across restarts; older rows are pruned on every poller tick. */
+const DB_RETENTION = 1000;
+
+// one row per MessageRecord, keyed by packet id (tx ids and injected ids are random uint32, rx uses the wire id)
+export const MESSAGES_DDL = `CREATE TABLE IF NOT EXISTS messages(
+  id INTEGER PRIMARY KEY,
+  dir TEXT NOT NULL,
+  to_node INTEGER,
+  from_node INTEGER,
+  text TEXT NOT NULL,
+  channel INTEGER NOT NULL,
+  at INTEGER NOT NULL,
+  status TEXT,
+  ack_error TEXT
+)`;
+
+/** Create the messages table if missing (idempotent — safe on every startup). */
+export function initMessagesTable(db: DatabaseSync): void {
+  db.exec(MESSAGES_DDL);
+}
 
 /** What we know about a node so far: full NodeInfo after sync, possibly just {num}+position for live-only nodes. */
 type NodeEntry = Pick<Proto.Mesh.NodeInfo, 'num'> &
@@ -77,13 +114,15 @@ export interface DeviceInfo {
 }
 
 // protobuf-es decodes proto uint64 fields as native bigint, which JSON.stringify rejects;
-// recursively convert so deviceInfo() output is always JSON-safe (bigint -> decimal string)
+// recursively convert so deviceInfo()/telemetry() output is always JSON-safe (bigint -> decimal string).
+// $-prefixed keys are protobuf-es internals ($typeName/$unknown), not device data — dropped.
 function jsonSafe<T>(value: T): T {
   if (typeof value === 'bigint') return String(value) as T;
   if (Array.isArray(value)) return value.map(jsonSafe) as T;
   if (value !== null && typeof value === 'object') {
     const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value)) out[k] = jsonSafe(v);
+    for (const [k, v] of Object.entries(value))
+      if (!k.startsWith('$')) out[k] = jsonSafe(v);
     return out as T;
   }
   return value; // primitives + undefined pass through
@@ -118,6 +157,16 @@ export class MeshService implements OnModuleInit, OnModuleDestroy {
     process.env.MESH_SEND_CHANNEL ?? '3',
     10,
   );
+  // how often the poller re-upserts the history buffer into SQLite (ms)
+  private readonly pollMs = parseInt(process.env.MESH_POLL_MS ?? '1000', 10);
+
+  /** SQLite database backing the message history; null = persistence disabled (tests construct without one). */
+  private db: DatabaseSync | null = null;
+  private pollTimer: NodeJS.Timeout | null = null;
+
+  constructor(db?: DatabaseSync) {
+    this.db = db ?? null;
+  }
 
   private socket: net.Socket | null = null;
   private buffer: Uint8Array = new Uint8Array(0);
@@ -137,17 +186,27 @@ export class MeshService implements OnModuleInit, OnModuleDestroy {
   // message history (newest kept, capped at HISTORY_LIMIT) + pending tx records awaiting their routing ACK/NACK
   private history: MessageRecord[] = [];
   private pendingTx = new Map<number, MessageRecord>();
+  // telemetry history (newest kept, capped at HISTORY_LIMIT)
+  private telemetryHistory: TelemetryRecord[] = [];
   private reconnectTimer: NodeJS.Timeout | null = null;
   private shuttingDown = false;
 
   onModuleInit(): void {
+    if (this.db) {
+      initMessagesTable(this.db);
+      this.seedHistory(); // history survives process restarts
+      // ponytail: full re-upsert of the ≤100-row buffer every tick — trivial load, zero bookkeeping
+      this.pollTimer = setInterval(() => this.flushHistory(), this.pollMs);
+    }
     this.connect();
   }
 
   onModuleDestroy(): void {
     this.shuttingDown = true;
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    if (this.pollTimer) clearInterval(this.pollTimer);
     this.socket?.destroy();
+    this.db?.close();
   }
 
   /** Bridge connection state: `{ connected, myNodeNum, host, port }`. */
@@ -279,12 +338,101 @@ export class MeshService implements OnModuleInit, OnModuleDestroy {
   /**
    * Message history, newest first: inbound TEXT_MESSAGE_APP packets (dir 'rx') and our sends (dir 'tx').
    * tx records start 'pending' and move to 'delivered'/'failed' when the routing ACK/NACK arrives;
-   * broadcasts stay 'pending' because firmware strips want_ack before TX. In-memory only, last 100, reset on reconnect.
+   * broadcasts stay 'pending' because firmware strips want_ack before TX. Backed by SQLite: the buffer is
+   * seeded from the database on startup (newest 100) and re-upserted every MESH_POLL_MS, so history
+   * survives process restarts and bridge reconnects; the DB keeps the newest 1000 rows.
    */
   messages(): MessageRecord[] {
     return [...this.history].reverse();
   }
 
+  /**
+   * Re-upsert the entire in-memory history buffer into SQLite (INSERT OR REPLACE per row) and enforce
+   * retention: only the newest DB_RETENTION rows survive. Called by the poller every MESH_POLL_MS;
+   * public so tests can drive a tick without real timers. No-op when no database is configured.
+   */
+  flushHistory(): void {
+    const db = this.db;
+    if (!db) return;
+    const upsert = db.prepare(
+      'INSERT OR REPLACE INTO messages(id, dir, to_node, from_node, text, channel, at, status, ack_error) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    );
+    for (const r of this.history) {
+      upsert.run(
+        r.id,
+        r.dir,
+        r.to ?? null,
+        r.from ?? null,
+        r.text,
+        r.channel,
+        r.at,
+        r.status ?? null,
+        r.ackError ?? null,
+      );
+    }
+    db.exec(
+      `DELETE FROM messages WHERE id NOT IN (SELECT id FROM messages ORDER BY at DESC LIMIT ${DB_RETENTION})`,
+    );
+  }
+
+  /** Load the newest HISTORY_LIMIT rows from SQLite into the buffer (oldest-first) so history survives restarts. */
+  private seedHistory(): void {
+    const rows = this.db!.prepare(
+      'SELECT id, dir, to_node, from_node, text, channel, at, status, ack_error FROM messages ORDER BY at DESC LIMIT ?',
+    ).all(HISTORY_LIMIT) as Array<Record<string, unknown>>;
+    // rows come back newest first — the buffer is oldest-first
+    for (const row of [...rows].reverse()) {
+      const rec: MessageRecord = {
+        id: Number(row.id),
+        dir: row.dir === 'tx' ? 'tx' : 'rx',
+        text: String(row.text),
+        channel: Number(row.channel),
+        at: Number(row.at),
+      };
+      if (row.to_node != null) rec.to = Number(row.to_node);
+      if (row.from_node != null) rec.from = Number(row.from_node);
+      if (row.status != null)
+        rec.status = row.status as MessageRecord['status'];
+      if (row.ack_error != null) rec.ackError = String(row.ack_error);
+      this.history.push(rec);
+    }
+  }
+
+  /**
+   * Inject a synthetic inbound (rx) record into the message history — as if received on the mesh.
+   * NOT transmitted over RF: nothing is written to the bridge or air; the record exists so external
+   * systems can push messages into the bot's inbox to trigger communication later. `from` is optional
+   * (integer in 1..0xffffffff when provided) and omitted from the record when absent. The record rides
+   * channel 0 like a primary-channel capture and appears in messages() newest first, subject to the
+   * same HISTORY_LIMIT cap as real captures. Returns { id } with a random uint32 packet id (same
+   * generation as tx sends). Throws on empty text or an invalid `from`.
+   */
+  injectMessage(text: string, from?: number): { id: number } {
+    if (typeof text !== 'string' || text.length === 0)
+      throw new Error('text must be a non-empty string');
+    if (from !== undefined) this.assertNodeNum(from);
+    const rec: MessageRecord = {
+      id: randomPacketId(),
+      dir: 'rx',
+      ...(from !== undefined ? { from } : {}),
+      text,
+      channel: 0,
+      at: Date.now(),
+    };
+    this.pushHistory(rec);
+    return { id: rec.id };
+  }
+
+  /**
+   * Telemetry records, newest first: TELEMETRY_APP packets from any node — device metrics
+   * (battery/voltage/uptime/channel+air utilization) and environment sensor readings where nodes have them.
+   * `kind` is the meshtastic.Telemetry oneof case name; `data` is that variant's payload with proto uint64
+   * fields as decimal strings, unset optional fields omitted. In-memory only, last 100, reset on reconnect.
+   */
+  telemetry(): TelemetryRecord[] {
+    return [...this.telemetryHistory].reverse();
+  }
+
   /** Send `text` to node `to` on the pinned test channel; returns the packet id. Throws ServiceUnavailable when the bridge is down. */
   async sendText(to: number, text: string): Promise<number> {
     if (!this.connected || !this.socket)
@@ -311,6 +459,13 @@ export class MeshService implements OnModuleInit, OnModuleDestroy {
     if (this.history.length > HISTORY_LIMIT) this.history.shift();
   }
 
+  private pushTelemetry(rec: TelemetryRecord): void {
+    this.telemetryHistory.push(rec);
+    // ponytail: shift on a ≤100 array is fine; true ring buffer only if this ever gets hot
+    if (this.telemetryHistory.length > HISTORY_LIMIT)
+      this.telemetryHistory.shift();
+  }
+
   private summarize(n: NodeEntry, names: Map<number, string>): NodeSummary {
     const s: NodeSummary = { num: n.num, lastHeard: n.lastHeard || null };
     if (n.user?.longName) s.longName = n.user.longName;
@@ -340,13 +495,14 @@ export class MeshService implements OnModuleInit, OnModuleDestroy {
     this.socket = socket;
     socket.on('connect', () => {
       this.connected = true;
-      // fresh sync on every (re)connect — drop stale channels/nodes/device info/history from the old session
+      // fresh sync on every (re)connect — drop stale channels/nodes/device info/telemetry from the old session;
+      // message history is NOT reset: it's an append-only log backed by SQLite and survives reconnects
       this.channelMap = new Map();
       this.nodeMap = new Map();
       this.metadata = null;
       this.configSections.clear();
       this.moduleConfigSections.clear();
-      this.history = [];
+      this.telemetryHistory = [];
       this.pendingTx.clear();
       this.logger.log(`bridge connected ${this.host}:${this.port}`);
       const nonce = Math.floor(Math.random() * 0xffffffff) || 1;
@@ -481,6 +637,23 @@ export class MeshService implements OnModuleInit, OnModuleDestroy {
               this.pendingTx.delete(decoded.requestId);
             }
           }
+        } else if (decoded && decoded.portnum === PORT_TELEMETRY_APP) {
+          // live telemetry: the Telemetry is serialized in Data.payload
+          let tel: Proto.Telemetry.Telemetry | undefined;
+          try {
+            tel = await decodeTelemetry(decoded.payload);
+          } catch {
+            tel = undefined; // malformed payload — skip
+          }
+          const variant = tel?.variant;
+          if (variant?.case) {
+            this.pushTelemetry({
+              from: pkt.from,
+              at: Date.now(),
+              kind: variant.case,
+              data: jsonSafe(variant.value),
+            });
+          }
         }
         break;
       }