pi-lxmf 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-24
+
+### Added
+
+- z.ai GLM quota watcher + peak-hours warning (`src/quota.js`, work doc #3):
+  when the active model is a z.ai GLM model (`provider === "zai"`), the
+  bridge watches the z.ai quota endpoint (`pi-glm-usage`'s) and delivers
+  exactly one LXMF message to the owner the moment the 5h quota bucket
+  recovers after a quota-exhausted run failure. Also warns the owner at
+  run start (and when the window opens mid-run) during z.ai peak hours
+  (Mon–Fri 14:00–18:00 SGT / UTC+8, 3× token cost). Entirely gated on
+  the active model being `zai` — nothing fires for Cortecs/Anthropic/etc.
+  A missing `zai.key` disables the watcher gracefully.
+
+### Fixed
+
+- Pi session pointer is now scoped to the resolved `workdir` (work doc #4):
+  pointers live at `dataDir/sessions/<sha256(workdir)[:16]>.json` so
+  distinct repos keep distinct sessions. Previously the single
+  `dataDir/session` file was shared across every repo, so starting the
+  daemon in a different cwd resumed the previous repo's conversation.
+  One-time migration: the legacy `dataDir/session` is adopted for the
+  first workdir that reads it, then removed. Foundational to the
+  multi-repo `/cd` work (doc #2).
+
+- Initial implementation of the `pi-lxmf` bridge: an LXMF ↔ Pi RPC daemon per
+  `SPEC.md`.
+  - `PiRpcClient` (`src/rpc.js`): spawns and supervises `pi --mode rpc`,
+    strict-JSONL framing (LF-only, `\r`-tolerant), id-correlated requests,
+    readiness probing, crash-restart with backoff and a crash-loop guard.
+  - Mesh side (`src/lxmf.js`): persistent Reticulum identity, shared-instance →
+    AutoInterface → TCP interface fallback, `LXMRouter` with periodic
+    announcing, optional propagation-node sync, chunked outbound delivery. A
+    `skipSharedInstance` config option bypasses the local rnsd shared instance
+    entirely in favour of own interfaces (AutoInterface + the `rnsHost`/
+    `rnsPort` TCP client) — for shared instances that do not forward routed,
+    multi-hop traffic to their local clients (observed on a Termux↔Columba
+    setup where the daemon's announces reached the mesh but every inbound link
+    request died at the rnsd, so senders never got delivery proofs). The
+    startup banner now also lists the attached interfaces.
+  - Bridge (`src/bridge.js`): owner-only access by configured Reticulum
+    identity hash (no first-contact pairing; derivation cross-validated
+    against @reticulum/core), serialized inbound pipeline, prompts (steer/follow-up mid-run), assistant
+    reply delivery with empty-tail recovery, extension-dialog auto-dismissal.
+  - Chat commands (`src/commands.js`): `/help`, `/status`, `/session`, `/new`,
+    `/name`, `/compact`, `/model`, `/think`, `/abort`, `/quit`, and the bare
+    `!` interrupt.
+  - Configuration and state (`src/config.js`): XDG-based config file with the
+    required `owner` identity hash, Pi session pointer persistence.
+  - End-to-end smoketest (`scripts/smoke.mjs` + `scripts/fake-pi.mjs`): runs
+    the real daemon against a fake `pi --mode rpc` and a second in-process
+    LXMF owner over a local rnsd shared instance.
+  - Inbound LXMF diagnostics (`attachInboundDiagnostics` in `src/lxmf.js`):
+    surfaces the inbound failure mode the bridge itself can't see — a
+    packet that decrypts but never dispatches. When the sender's identity
+    is unknown the router parks the message until an announce arrives (the
+    most common reason a sender sees its packet acknowledged but the bridge
+    never receives anything), and that is now logged; unparseable packets
+    are logged too. The peer-learn (`"peer"` event) log is filtered to the
+    configured owner identity only — routine mesh peers are no longer
+    logged.
+    Successfully-dispatched owner traffic is intentionally silent here —
+    the bridge logs its disposition (ignored / command / prompt) where the
+    decision is made. Ported from signalk-reticulum where this
+    instrumentation proved out the identity-parking failure mode.
+  - Outbound reply fallback: a failed reply over the arrival link is now
+    retried once more without the link (fresh DIRECT link, then
+    opportunistic packet). Battery-conscious mobile clients tear their
+    link down right after their own message is acknowledged, so the arrival
+    link is frequently gone by reply time. The same `LXMessage` object is
+    re-sent so every wire copy shares one message id and a deduplicating
+    client (Sideband, NomadNet) renders the reply once.
+  - Run-start acknowledgement via LXMF reaction: when a run starts and no
+    reply lands within a 2 s debounce window, the bridge sends a 🤔
+    reaction (LXMF `FIELD_REACTION`, §5.9.8) targeting the message that
+    triggered the run, so the owner sees their message acknowledged while
+    the agent works. A fast run whose reply beats the window sends no
+    extra message. The reaction is carried solely by the reaction field
+    (Sideband/NomadNet render it natively; no separate chat bubble is
+    emitted alongside it). The internal empty-reply recovery run is never
+    acknowledged. Added
+    `sendReaction(destinationHex, targetMessageId, emoji, opts)` to the
+    mesh adapter (`src/lxmf.js`), reusing the same retry path as
+    `sendText`.
+- Fixed bzip2 compression provider (`src/bz2.js`): the wasm `compress()`
+  defaults its output buffer to the input length, so an LXMF reply that
+  compressed worse than its input (incompressible / small / already-
+  compressed data) threw `BZ_OUTBUFF_FULL` and failed delivery. The adapter
+  now sizes the output buffer with bzip2's documented worst-case headroom
+  (`input + 1% + 600` bytes).
+- Security: the bridge now signature-verifies every inbound owner message
+  itself, closing a gap on the propagation-sync path. The router verifies
+  signatures on direct delivery, but a message pulled in via
+  `syncFromPropagationNode` whose sender identity is not yet recalled is
+  dispatched WITHOUT verification (mirroring Python's `SOURCE_UNKNOWN`
+  handling) — and the bridge's owner-hash check alone is forgeable there
+  (a 16-byte hash, no private key needed). The bridge now calls
+  `verifySender(message)` on the mesh adapter (recalls the sender identity
+  and checks the signature) and drops anything that isn't cryptographically
+  proven, including `unknown` (parked) results, so a synced message is only
+  admitted once the owner's identity has been learned. This makes the
+  SPEC.md §11 / README "signature-verified" claim hold for every path.
+- GitHub Actions CI: tests (with lint and type checks) on every push, and
+  OIDC-based npm publishing on tag pushes (no registry token stored).

package/README.md

@@ -0,0 +1,202 @@
+# pi-lxmf
+
+Drive the [Pi](https://pi.dev) coding agent **entirely from an LXMF messaging
+client** — [Sideband](https://github.com/markqvist/Sideband),
+[Nomad Network](https://github.com/markqvist/NomadNet), or any other
+[LXMF](https://github.com/markqvist/LXMF) peer — over the
+[Reticulum](https://reticulum.network) mesh. Built on
+[reticulum-js](https://reticulum.js.org/).
+
+`pi-lxmf` is a small daemon for headless servers: your chat messages become
+prompts, finished assistant replies are delivered back as chat messages, and
+the usual Pi controls (`/new`, `/compact`, `/abort`, model and thinking
+switches) work from chat. Exactly one configured owner — identified by their
+**Reticulum identity hash** — controls the agent; everyone else is ignored.
+Architecture and internals: [SPEC.md](SPEC.md).
+
+```text
+Sideband / NomadNet ◄──LXMF──► pi-lxmf daemon ◄──RPC──► pi --mode rpc
+                              (identity, announce,     (supervised child,
+                               session)                 restartable)
+```
+
+## Requirements
+
+- Node.js ≥ 20
+- `pi` on `PATH`, logged into a provider
+- A Reticulum transport: a local `rnsd` (recommended), or AutoInterface
+  (IPv6 multicast), or an `rnsd` reachable over TCP
+
+## Install
+
+```bash
+npm install -g pi-lxmf
+# or from a checkout:
+git clone … && cd pi-lxmf && npm install
+node src/bin.js --help
+```
+
+## Quick start
+
+1. **Configure** — create `~/.config/pi-lxmf/config.json` (override with
+   `--config <path>` or `$PI_LXMF_CONFIG`) and `chmod 600` it:
+
+   ```json
+   {
+     "name": "pi on myserver",
+     "workdir": "/srv/myproject",
+     "model": "anthropic/claude-sonnet-4-5",
+     "owner": "<your Reticulum identity hash, 32 hex chars>"
+   }
+   ```
+
+   `owner` is **required** and takes your **Reticulum identity hash** — the
+   32-hex identifier of your Ed25519 identity, *not* the `lxmf.delivery`
+   destination hash ("LXMF Address") your client displays. The identity hash
+   is protocol-agnostic (the same you across LXMF, Nomadnet, …) and is what a
+   future DACAR-style permission system would grant to; the daemon derives
+   the wire form internally.
+
+2. **Run the daemon** in the project directory (or set `workdir`):
+
+   ```bash
+   pi-lxmf
+   ```
+
+   The startup banner prints the node's identity and LXMF address:
+
+   ```text
+   pi-lxmf: pi on myserver starting
+     identity   6bd23ddae42b6ab1b90ef1ce62a41f31
+     lxmf       92b5be0e43370f01de77126b0eb11b53
+     announce   pi on myserver
+     owner (identity) 3f9dd04e9216c0a3b8c7e5f1d2a60b44
+   pi-lxmf: ready — listening for LXMF messages
+   ```
+
+3. **Say hello** — in Sideband, start a conversation with the daemon's LXMF
+   address (scan the announce or enter the hash manually) and send a message.
+   Only the configured owner is answered; everyone else is dropped.
+
+4. **Trust the project once** — Pi's project trust cannot be prompted over
+   LXMF. Run `pi` interactively once in `workdir` (or preconfigure trust) so
+   project-local `.pi` resources load in RPC mode.
+
+## Chat commands
+
+| You send | Action |
+|---|---|
+| plain text | a prompt to the agent (steered into a running turn by default) |
+| `/help` | bridge commands + Pi commands available via prompt |
+| `/status` | model, thinking, session, uptime, node + owner identity hashes |
+| `/session` | message counts, tokens, cost, context usage |
+| `/new` | fresh Pi session |
+| `/name [name]` | show / set the session display name |
+| `/compact [instructions]` | compact the conversation context |
+| `/model [query]` | list models, or switch (`/model sonnet`) |
+| `/think <level>` | set thinking level (`off`…`max`) |
+| `/abort` | abort the run **and** drop queued messages |
+| `!` | quick interrupt — abort only, queue intact |
+| `/quit` | shut down the daemon and Pi |
+| any other `/…` | passed to Pi (extension commands, `/skill:…`, templates) |
+
+Replies are delivered per finished assistant message, chunked to fit
+`chunkChars`. A run that ends without any reply triggers one recovery attempt,
+then a `✅ done (no reply)` nudge. Extension dialogs raised inside Pi are
+auto-declined (nobody is at a terminal) and reported to you.
+
+## Configuration
+
+`~/.config/pi-lxmf/config.json` (XDG env vars respected). A missing file runs
+on defaults.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `owner` | *(required)* | the owner's 32-hex **Reticulum identity hash** (not the LXMF address); the daemon derives the `lxmf.delivery` destination hash for wire comparison |
+| `name` | `pi-lxmf <version>` | announce display name |
+| `workdir` | daemon cwd | project directory Pi runs in (also where `AGENTS.md` is found) |
+| `model` | Pi default | `--model` pattern passed to Pi |
+| `piBin` | `pi` | Pi binary |
+| `dataDir` | `~/.local/share/pi-lxmf` | state root (see below) |
+| `rnsHost` / `rnsPort` | — | rnsd TCP interface, used when no local shared instance is found |
+| `propagationNode` | — | `lxmf.propagation` hash for outbound submits + optional sync |
+| `syncIntervalSec` | `0` (off) | pull messages from the propagation node on this cadence |
+| `midRunBehavior` | `steer` | how prompts arriving mid-run are delivered: `steer` or `followUp` |
+| `chunkChars` | `2500` | max characters per outbound LXMF message |
+| `announceIntervalSec` | router default | re-announce cadence |
+
+### State (`dataDir`)
+
+- `storage/` — the node's persistent Reticulum identity and caches. **This key
+  is the node's address; back it up and keep it secret.** Deleting it changes
+  your LXMF address.
+- `session` — pointer to the current Pi session file. Sessions survive daemon
+  restarts (`pi --session`); `/new` starts a fresh one.
+
+### Mesh connectivity
+
+The daemon attaches to a local `rnsd` shared instance when available (the
+recommended setup — rnsd owns the radio/network interfaces), and otherwise
+falls back to AutoInterface, optionally plus a TCP interface via
+`rnsHost`/`rnsPort`. It announces itself periodically so peers can find it and
+cached paths stay fresh.
+
+If you configure a `propagationNode`, replies can be submitted for
+store-and-forward delivery while you are unreachable, and `syncIntervalSec`
+retrieves messages that arrived while the daemon was down.
+
+## Security
+
+- Every inbound owner message is **signature-verified by the bridge**
+  (recalling the sender identity and checking the LXMF signature) before
+  it is processed; only messages from the configured owner's identity get
+  through (matched via the derived `lxmf.delivery` destination hash),
+  everyone else is dropped silently — the daemon never answers strangers.
+  The router itself only verifies signatures on direct delivery, so the
+  bridge re-checks every path (including propagation-node sync, where the
+  router dispatches unverified when the sender identity is unknown) — the
+  owner source hash alone is forgeable, so the cryptographic proof is what
+  actually authenticates the sender.
+- The owner is **configured, never learned**: there is no first-contact
+  pairing, so a stray message can never seize control.
+- Access is keyed by **identity hash**, so it can later be delegated to a
+  DACAR-style permission system without reconfiguration.
+- The bridge never executes chat text locally — everything goes through Pi's
+  RPC protocol. Approval-gated tools stay gated (dialogs are declined).
+- `/quit` and full agent control are available to the owner only.
+
+## Running as a service
+
+Example systemd unit (adjust paths):
+
+```ini
+[Unit]
+Description=pi-lxmf bridge
+After=network-online.target rnsd.service
+
+[Service]
+ExecStart=/usr/bin/pi-lxmf --config /etc/pi-lxmf/config.json
+Restart=on-failure
+User=pi
+
+[Install]
+WantedBy=multi-user.target
+```
+
+The daemon supervises Pi itself: an unexpected Pi exit triggers a restart
+(with the session resumed) and is reported to you over LXMF; a crash loop
+gives up and says so.
+
+## Development
+
+```bash
+npm test          # unit tests (node --test)
+npm run types     # tsc --noEmit over the JSDoc-typed sources
+npm run lint      # biome
+npm run smoke     # end-to-end against a local rnsd: daemon + fake pi +
+                  #   a second in-process LXMF node as the owner
+```
+
+## License
+
+EUPL-1.2