vendor wherenow and pilegram

Author: ngalaiko

flake.lock

@@ -16,19 +16,6 @@
       url = "github:nix-community/nixvim/nixos-26.05";
       inputs.nixpkgs.follows = "nixpkgs";
     };
-    # my pi ⇄ Telegram gateway (the assistant's bridge). Deliberately does NOT
-    # follow our nixpkgs, even though both track 26.05: it's a hermetic flake
-    # whose node_modules is a fixed-output derivation pinned to its own nixpkgs'
-    # bun, and repinning bun (even across 26.05 revs) would break that hash.
-    pilegram.url = "github:ngalaiko/pilegram";
-    # wherenow: my self-hosted "Where Now?" location backend. Pure Go, so unlike
-    # pilegram it follows our nixpkgs. Runs as the assistant and writes each
-    # position straight into the Obsidian vault as a note — see
-    # hosts/exedev/users/assistant.nix.
-    wherenow = {
-      url = "github:ngalaiko/wherenow";
-      inputs.nixpkgs.follows = "nixpkgs";
-    };
     # Installs and owns the Homebrew prefix itself, so a fresh Mac doesn't need
     # brew pre-installed — the first darwin-rebuild switch bootstraps it. The
     # nix-darwin `homebrew` module only manages an already-installed brew.

flake.nix

@@ -3,14 +3,14 @@ let
   # pi (the coding agent) is an npm CLI, packaged from its published tarball.
   # MIT, all-JS deps, so it builds against the pinned nixpkgs directly.
   pi = import ../../../packages/pi { inherit pkgs; };
-  # pilegram: my pi ⇄ Telegram gateway (Bun), consumed as a flake input. It's a
+  # pilegram: my pi ⇄ Telegram gateway (Bun), packaged in this repo. It's a
   # hermetic package — it bundles bun, ffmpeg, whisper.cpp and a pinned
   # node_modules that includes its own pi 0.83.0 — so it needs nothing else from
   # this account and survives recreations regardless of backup.
-  pilegram = inputs.pilegram.packages.${pkgs.system}.default;
-  # wherenow: the "Where Now?" location backend (flake input). Pure Go; writes
-  # positions into the vault as notes (no database).
-  wherenow = inputs.wherenow.packages.${pkgs.system}.default;
+  pilegram = import ../../../packages/pilegram { inherit pkgs; };
+  # wherenow: the "Where Now?" location backend, packaged in this repo. Pure Go;
+  # writes positions into the vault as notes (no database).
+  wherenow = import ../../../packages/wherenow { inherit pkgs; };
   # Official Obsidian Sync headless CLI, packaged here so the assistant can run
   # on-demand vault syncs without fetching npm packages at runtime.
   obsidian-headless = import ../../../packages/obsidian-headless { inherit pkgs; };
@@ -220,7 +220,7 @@ in
     '';
   };
 
-  # Telegram bridge for pi, via pilegram (the flake input above). Long-polling
+  # Telegram bridge for pi, via pilegram (packaged above). Long-polling
   # needs only outbound HTTPS, so nothing is exposed on the tailnet or the image.
   # pilegram reads pi's provider keys from ~/.pi and keeps its own state under
   # ~/.config/pilegram; run in the foreground so s6 supervises it.

hosts/exedev/users/assistant.nix

@@ -0,0 +1,3 @@
+# The only secret. Everything else is a CLI flag (see `bun run src/index.ts --help`).
+# Bun auto-loads this .env.
+TELEGRAM_BOT_TOKEN=123456:AA...

packages/pilegram/.env.example

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [master]
+
+jobs:
+  check:
+    name: Typecheck and test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@v31
+        with:
+          nix_path: nixpkgs=channel:nixos-26.05
+
+      - name: Install dependencies
+        run: nix shell nixpkgs#bun -c bun install --frozen-lockfile
+
+      - name: Typecheck
+        run: nix shell nixpkgs#bun -c bun run typecheck
+
+      - name: Test
+        run: nix shell nixpkgs#bun -c bun run test
+
+      - name: Build package
+        run: nix build .#default

packages/pilegram/.github/workflows/ci.yml

@@ -0,0 +1,11 @@
+node_modules/
+.env
+.env.*
+!.env.example
+data/
+*.db
+*.db-wal
+*.db-shm
+dist/
+.DS_Store
+*.log

packages/pilegram/.gitignore

@@ -0,0 +1,126 @@
+# pilegram
+
+<p align="center">
+  <img src="assets/logo.png" alt="pilegram" width="200">
+</p>
+
+A personal [pi](https://github.com/earendil-works/pi) coding agent, over Telegram.
+
+## Features
+
+- **Streaming replies** via an editable provisional message, so you can still send `/stop` or steer the agent mid-turn.
+- **Topics = sessions**: each Telegram topic is its own agent session with its own
+  workspace and context. The agent can list known threads, create threads, and,
+  after explicit confirmation, delete them; it also keeps each topic's **title and
+  icon** relevant on its own.
+- **Markdown → Telegram HTML**: headings, code, lists, tables, links render properly.
+- **Images** in (vision) & out, **documents** in (path + inlined text) & out, **albums** both ways.
+- **Voice**, fully local: voice notes are transcribed with **whisper.cpp**; replies
+  come back as voice notes synthesized with **Supertonic** (in-process ONNX). Text
+  always available as a fallback.
+- **Reactions**: the agent can react to your messages instead of replying in text.
+- **Steering**: a message sent mid-turn is injected into the running turn.
+- **Rich inbound handling**: replies/quotes, forwards, edited messages, stickers,
+  locations, contacts, polls, dice.
+
+The only bot command is **`/stop`** (abort the current turn). Everything else you
+type (or say, or send) is a prompt.
+
+## Prerequisites
+
+pilegram runs on **[Bun](https://bun.sh)** and shells out to three tools for voice:
+
+| Tool            | Why                        | Provides            |
+| --------------- | -------------------------- | ------------------- |
+| **bun** ≥ 1.3   | runtime                    | —                   |
+| **ffmpeg**      | transcode audio ↔ OGG/Opus | `ffmpeg`, `ffprobe` |
+| **whisper.cpp** | speech-to-text             | `whisper-cli`       |
+
+TTS (Supertonic) runs in-process via the `onnxruntime-node` npm dependency — no
+extra system package. Speech model weights download automatically on first use.
+
+## Install
+
+### Without Nix
+
+Install the three tools with your package manager, then the app:
+
+```bash
+# macOS (Homebrew)
+brew install oven-sh/bun/bun ffmpeg whisper-cpp
+
+# Debian/Ubuntu: bun via https://bun.sh; ffmpeg via apt; whisper.cpp from source
+#   (must expose a `whisper-cli` binary on PATH)
+sudo apt install ffmpeg
+
+git clone <this repo> && cd pilegram
+bun install
+export TELEGRAM_BOT_TOKEN=123456:AA...     # the one secret (or put it in .env)
+bun run src/index.ts --allow 111222333     # your Telegram user id(s)
+```
+
+`whisper-cli`, `ffmpeg`, and `ffprobe` must be on your `PATH`. That's the only
+requirement voice has — everything else is handled by `bun install`.
+
+### With Nix
+
+The flake builds a **hermetic** package — pinned toolchain (bun + ffmpeg +
+whisper.cpp) _and_ pinned `node_modules` — so it runs from anywhere, not just the
+repo:
+
+```bash
+# one-shot: builds the package and runs it
+TELEGRAM_BOT_TOKEN=… nix run github:you/pilegram -- --allow 111222333
+
+# or install it onto your PATH
+nix profile install github:you/pilegram
+TELEGRAM_BOT_TOKEN=… pilegram --allow 111222333
+
+# or a dev shell (bun, ffmpeg, whisper-cli), to run from source
+nix develop
+bun install
+bun run src/index.ts --allow 111222333
+```
+
+`node_modules` is a fixed-output derivation: `bun install --frozen-lockfile`
+whose result is pinned by content hash (this keeps the native `onnxruntime-node`
+dylib intact — a real node_modules layout, unlike `bun build --compile`). **When
+you change dependencies**, bump that hash: run `nix build .#node-modules`, copy
+the `got: sha256-…` it prints into `outputHash` in `flake.nix`.
+
+## Telegram setup (BotFather)
+
+1. Create a bot with [@BotFather](https://t.me/BotFather) → copy the **token**.
+2. **Enable topics**: BotFather → `/mybots` → your bot → _Bot Settings_ → turn on
+   **Threaded Mode**. (Without this, pilegram runs a single-session DM.)
+3. Find **your numeric user id** (e.g. via [@userinfobot](https://t.me/userinfobot)).
+
+## Configuration
+
+The one **secret** is `TELEGRAM_BOT_TOKEN` (from the environment / `.env`, never a
+flag — argv is visible in `ps`). Everything else is a **CLI flag** (`--help`):
+
+| Flag                     | Required | Default                                                 | Notes                                                                       |
+| ------------------------ | -------- | ------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `--allow <ids>`          | ✅       | —                                                       | comma-separated Telegram user ids; everyone else is dropped silently        |
+| `--state-dir <path>`     |          | `$XDG_CONFIG_HOME/pilegram` (else `~/.config/pilegram`) | SQLite db                                                                   |
+| `--models-dir <path>`    |          | `$XDG_CACHE_HOME/pilegram` (else `~/.cache/pilegram`)   | downloaded speech models (~2 GB cache)                                      |
+| `--db-path <path>`       |          | `<state-dir>/pilegram.db`                               | override the db path                                                        |
+| `--whisper-model <name>` |          | `large-v3-turbo`                                        | whisper.cpp ggml model (e.g. `base.en` for a fast/small English-only start) |
+| `--voice <id>`           |          | `M1`                                                    | Supertonic voice: `M1`–`M5`, `F1`–`F5`                                      |
+| `--tz <zone>`            |          | `Europe/Stockholm`                                      | local time shown to the agent                                               |
+| `--poll-timeout <sec>`   |          | `30`                                                    | long-poll seconds                                                           |
+| `--log-level <level>`    |          | `info`                                                  | `debug`\|`info`\|`warn`\|`error`                                            |
+
+## Trust model
+
+pilegram is single-user by design. Only the Telegram user ids in `--allow` are
+served; every other update is logged and dropped.
+
+The agent runs with **full trust and no approval gate** — it runs shell commands,
+reads and writes files, and sends messages on your behalf without asking. It runs
+as _your_ user, with the same filesystem and network access you have: its working
+directory is your home directory, **not a sandbox**, and tools such as
+`tg_send_document` accept absolute paths. Only `--allow` ids you
+trust to drive an unsandboxed agent, and run pilegram as a dedicated,
+least-privileged user (or in a container) if that reach concerns you.