@blunking/codexlink 0.1.18 → 0.1.20

package/README.md

@@ -1,110 +1,110 @@
-<div align="center">
-
-# CodexLink
-
-**Your agent in your pocket.**
-
-[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Powered by BLUN](https://img.shields.io/badge/Powered%20by-BLUN-22D3EE.svg)](https://blun.ai)
-
-</div>
-
-CodexLink is the BLUN launcher for one visible CLI session with optional Telegram delivery.
-
-It keeps transport and queueing around the operator, without spinning up a hidden second session.
-
-Telegram delivery is serial by default:
-
-- inbound messages land in queue first
-- active work is not interrupted immediately
-- direct messages wait until the visible session is quiet
-- ambient group noise stays queued until it is relevant or manually drained
-- escalation-style messages can still jump the line
-- stale pending replies time out automatically, so the queue cannot block forever
-
-## Install
-
-From GitHub:
-
-```powershell
-npm install -g github:maykbiletti/codexlink
-```
-
-From npm:
-
-```powershell
-npm install -g @blunking/codexlink
-```
-
-Local development:
-
-```powershell
-cd codexlink
-npm install
-npm link
-```
-
-## Schnellstart
-
-Normal starten:
-
-```powershell
-blun-codex
-```
-
-Telegram aktivieren:
-
-```powershell
-blun-codex telegram-plugin
-```
-
+<div align="center">
+
+# CodexLink
+
+**Your agent in your pocket.**
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Powered by BLUN](https://img.shields.io/badge/Powered%20by-BLUN-22D3EE.svg)](https://blun.ai)
+
+</div>
+
+CodexLink is the BLUN launcher for one visible CLI session with optional Telegram delivery.
+
+It keeps transport and queueing around the operator, without spinning up a hidden second session.
+
+Telegram delivery is serial by default:
+
+- inbound messages land in queue first
+- active work is not interrupted immediately
+- direct messages wait until the visible session is quiet
+- ambient group noise stays queued until it is relevant or manually drained
+- escalation-style messages can still jump the line
+- stale pending replies time out automatically, so the queue cannot block forever
+
+## Install
+
+From GitHub:
+
+```powershell
+npm install -g github:maykbiletti/codexlink
+```
+
+From npm:
+
+```powershell
+npm install -g @blunking/codexlink
+```
+
+Local development:
+
+```powershell
+cd codexlink
+npm install
+npm link
+```
+
+## Schnellstart
+
+Normal starten:
+
+```powershell
+blun-codex
+```
+
+Telegram aktivieren:
+
+```powershell
+blun-codex telegram-plugin
+```
+
 Wenn Telegram noch nicht eingerichtet ist, startet automatisch ein kurzer Setup-Flow und fragt:
 
 - Telegram Bot Token
 
 Danach oeffnest du Telegram und sendest eine Nachricht an den Bot. CodexLink erkennt Chat oder Gruppe automatisch und schreibt alles lokal an die richtige Stelle. Du musst keine Chat-ID suchen und keine `.env`-Datei bearbeiten.
-
-Pruefen:
-
-```powershell
-blun-codex telegram-doctor
-```
-
-## Commands
-
-Normal startup:
-
-```powershell
-blun-codex
-```
-
-Alias:
-
-```powershell
-codexlink
-```
-
-Telegram mode:
-
-```powershell
-blun-codex telegram-plugin
-```
-
-Manual setup:
-
-```powershell
-blun-codex telegram-setup
-```
-
-Legacy equivalent:
-
-```powershell
-blun-codex --telegram plugin
-```
-
-Status:
-
-```powershell
+
+Pruefen:
+
+```powershell
+blun-codex telegram-doctor
+```
+
+## Commands
+
+Normal startup:
+
+```powershell
+blun-codex
+```
+
+Alias:
+
+```powershell
+codexlink
+```
+
+Telegram mode:
+
+```powershell
+blun-codex telegram-plugin
+```
+
+Manual setup:
+
+```powershell
+blun-codex telegram-setup
+```
+
+Legacy equivalent:
+
+```powershell
+blun-codex --telegram plugin
+```
+
+Status:
+
+```powershell
 blun-codex telegram-status
 ```
 
@@ -114,6 +114,8 @@ Der automatische Progress-Hinweis ist bewusst defensiv: standardmaessig sendet T
 
 CodexLink injiziert Nachrichten standardmaessig ueber den App-Server in den aktiven Thread. Der alte Windows-Tastaturmodus, der Text sichtbar ins Eingabefeld schreibt, ist absichtlich deaktiviert, weil einzelne Terminals Enter nicht zuverlaessig absenden. Wer ihn fuer Debugging trotzdem erzwingen will, muss explizit `BLUN_TELEGRAM_VISIBLE_CONSOLE_INJECT=force` setzen.
 
+Kurze Namens-Pings wie `Otto` oder `Alfred` werden standardmaessig ebenfalls als echte Nachricht in den aktiven Thread injiziert. Das macht Reachability-Tests sichtbar und vermeidet, dass Telegram wie ein separater Hintergrundbot wirkt. Wer den alten Ack-only-Modus fuer solche Pings braucht, kann `BLUN_TELEGRAM_PING_ACK_ONLY=1` setzen.
+
 Wichtig bei mehreren Profilen: ein Telegram-Bot-Token darf nicht gleichzeitig von alten oder fremden Pollern abgefragt werden. Sonst meldet Telegram `Conflict: terminated by other getUpdates request`, und Nachrichten koennen verspaetet oder gar nicht in der sichtbaren CLI landen. Aktuelle Versionen pollen non-blocking und schneller; wenn trotzdem Conflicts auftauchen, alle alten `blun-codex telegram-plugin` Fenster fuer denselben Bot schliessen und genau eine aktuelle Session starten.
 
 Wenn mehrere Agents denselben Gruppenchat nutzen, kann ein Agent andere Agent-Namen als Fremdroute markieren. Dann werden Owner-Nachrichten wie `Frida mach weiter` nicht in Ottos Session gezogen:
@@ -124,126 +126,133 @@ BLUN_TELEGRAM_OTHER_AGENT_NAMES=frida,angel,dieter,alfred
 ```
 
 Doctor:
-
-```powershell
-blun-codex telegram-doctor
-```
-
-JSON doctor output:
-
-```powershell
-blun-codex telegram-doctor --json
-```
-
-Dry run:
-
-```powershell
-blun-codex telegram-plugin --print-only
-```
-
-## Eigene Profile
-
-Der normale Start braucht kein eigenes Profil.
-
-Wenn du nur einen Slot auf deinem Rechner brauchst, reicht:
-
-```powershell
-blun-codex telegram-plugin
-```
-
-Ein eigenes Profil brauchst du nur fuer Fortgeschrittene oder Parallelbetrieb, zum Beispiel wenn mehrere Operatoren auf demselben Rechner laufen.
-
-Beispiel:
-
-```powershell
-blun-codex --profile alfred telegram-plugin
-```
-
-## Private internal profiles
-
-If you run more than one internal operator on the same machine, do not start all of them on the shared `default` slot.
-
-Use a dedicated private profile per operator:
-
-```powershell
-blun-codex --profile frida telegram-plugin
-```
-
-Why this matters:
-
-- `blun-codex telegram-plugin` without `--profile` uses the shared `default` runtime slot
-- starting a second operator on `default` will replace the first `default` runtime
-- a private profile gives that operator a separate runtime slot, state directory, and Mnemo binding
-
-For internal/private profiles:
-
-- keep the profile local on the machine
-- give it its own `agent_name`
-- give it its own Telegram state directory
-- do not ship internal agent profiles in the public package
-
-Local private profiles are loaded from:
-
-```text
-%USERPROFILE%\.codex\profiles\codexlink\<name>.json
-```
-
-Example:
-
-```powershell
-blun-codex --profile frida telegram-plugin
-```
-
-looks for:
-
-```text
-%USERPROFILE%\.codex\profiles\codexlink\frida.json
-```
-
-## What it does
-
-- starts one consistent local CLI runtime
-- writes a launch record into `.codex/runtimes/default/`
-- keeps Telegram queue state under `.codex/channels/telegram-default/`
-- attaches Telegram delivery to the same visible session
-- defers automatic Telegram delivery until the foreground session is idle
-- keeps poller, dispatcher, and reply relay separate from the foreground operator
-
-## What it does not do
-
-- no hidden autonomous answer bot
-- no second shadow session
-- no per-agent internal company presets in the public package
-
-## Public profile
-
-The shipped default profile is intentionally generic:
-
-- display name: `CodexLink`
-- lane: `general`
-- workspace: current directory by default
-- model: inherited from the local host unless explicitly set
-
-If you need custom paths or lane rules, add your own profile JSON next to `profiles/default.json`.
-
-## Telegram plugin folder
-
-The bundled plugin lives under `telegram-plugin/` and contains:
-
-- `.codex-plugin/plugin.json`
-- `.mcp.json`
-- `server.js`
-- sidecars and bridge helpers
-
-## Requirements
-
-- Windows PowerShell
-- Node.js 20+
-- a working local `codex` command in `PATH`
-- a Telegram bot token when Telegram mode is enabled
-
-## First-run behavior
-
+
+```powershell
+blun-codex telegram-doctor
+```
+
+Runtime automatisch bereinigen, wenn mehrere Threads geladen sind oder eine alte Bindung klemmt:
+
+```powershell
+blun-codex telegram-doctor --fix
+blun-codex telegram-plugin
+```
+
+JSON doctor output:
+
+```powershell
+blun-codex telegram-doctor --json
+```
+
+Dry run:
+
+```powershell
+blun-codex telegram-plugin --print-only
+```
+
+## Eigene Profile
+
+Der normale Start braucht kein eigenes Profil.
+
+Wenn du nur einen Slot auf deinem Rechner brauchst, reicht:
+
+```powershell
+blun-codex telegram-plugin
+```
+
+Ein eigenes Profil brauchst du nur fuer Fortgeschrittene oder Parallelbetrieb, zum Beispiel wenn mehrere Operatoren auf demselben Rechner laufen.
+
+Beispiel:
+
+```powershell
+blun-codex --profile alfred telegram-plugin
+```
+
+## Private internal profiles
+
+If you run more than one internal operator on the same machine, do not start all of them on the shared `default` slot.
+
+Use a dedicated private profile per operator:
+
+```powershell
+blun-codex --profile frida telegram-plugin
+```
+
+Why this matters:
+
+- `blun-codex telegram-plugin` without `--profile` uses the shared `default` runtime slot
+- starting a second operator on `default` will replace the first `default` runtime
+- a private profile gives that operator a separate runtime slot, state directory, and Mnemo binding
+
+For internal/private profiles:
+
+- keep the profile local on the machine
+- give it its own `agent_name`
+- give it its own Telegram state directory
+- do not ship internal agent profiles in the public package
+
+Local private profiles are loaded from:
+
+```text
+%USERPROFILE%\.codex\profiles\codexlink\<name>.json
+```
+
+Example:
+
+```powershell
+blun-codex --profile frida telegram-plugin
+```
+
+looks for:
+
+```text
+%USERPROFILE%\.codex\profiles\codexlink\frida.json
+```
+
+## What it does
+
+- starts one consistent local CLI runtime
+- writes a launch record into `.codex/runtimes/default/`
+- keeps Telegram queue state under `.codex/channels/telegram-default/`
+- attaches Telegram delivery to the same visible session
+- defers automatic Telegram delivery until the foreground session is idle
+- keeps poller, dispatcher, and reply relay separate from the foreground operator
+
+## What it does not do
+
+- no hidden autonomous answer bot
+- no second shadow session
+- no per-agent internal company presets in the public package
+
+## Public profile
+
+The shipped default profile is intentionally generic:
+
+- display name: `CodexLink`
+- lane: `general`
+- workspace: current directory by default
+- model: inherited from the local host unless explicitly set
+
+If you need custom paths or lane rules, add your own profile JSON next to `profiles/default.json`.
+
+## Telegram plugin folder
+
+The bundled plugin lives under `telegram-plugin/` and contains:
+
+- `.codex-plugin/plugin.json`
+- `.mcp.json`
+- `server.js`
+- sidecars and bridge helpers
+
+## Requirements
+
+- Windows PowerShell
+- Node.js 20+
+- a working local `codex` command in `PATH`
+- a Telegram bot token when Telegram mode is enabled
+
+## First-run behavior
+
 `blun-codex telegram-plugin` now behaves like a guided setup for normal users:
 
 1. check whether Telegram is already configured
@@ -256,8 +265,8 @@ Allowed Chat ID(s) are no longer typed by hand. To pair a different chat or grou
 
 ```powershell
 blun-codex telegram-setup
-```
-
+```
+
 If something is missing later, `blun-codex telegram-doctor` tells you exactly what is missing and what to run next.
 
 Inbound Telegram messages are mirrored into the visible Codex console by default,
@@ -265,9 +274,9 @@ so the operator can see that the message arrived. Queue summaries and outbound
 reply notices stay out of the console to avoid input-line spam. Set
 `BLUN_TELEGRAM_CONSOLE_UI_NOTICES=off` to disable console mirroring, or `all` to
 also mirror outbound notices for debugging.
-
-## Notes
-
-- the package currently targets local Windows operators first
-- the package is installable from GitHub before registry publishing
-- once an npm token is available, the same package can be published without changing the command shape
+
+## Notes
+
+- the package currently targets local Windows operators first
+- the package is installable from GitHub before registry publishing
+- once an npm token is available, the same package can be published without changing the command shape