@blunking/codexlink 0.1.0 → 0.1.2

package/README.md

@@ -1,127 +1,245 @@
-<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.
-
+<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.
 
-## 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
-```
-
-## Commands
-
-Normal startup:
-
-```powershell
-blun-codex
-```
-
-Alias:
-
-```powershell
-codexlink
-```
-
-Telegram mode:
-
-```powershell
-blun-codex telegram-plugin
-```
-
-Legacy equivalent:
-
-```powershell
-blun-codex --telegram plugin
-```
-
-Status:
-
-```powershell
-blun-codex telegram-status
+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
+
+## 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
+- erlaubte Chat ID(s)
+
+Die Werte werden automatisch lokal an die richtige Stelle geschrieben. Du musst keine `.env`-Datei suchen.
+
+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
+```
+
+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
 ```
 
-Doctor:
+Example:
 
 ```powershell
-blun-codex telegram-doctor
+blun-codex --profile frida telegram-plugin
 ```
 
-Dry run:
+looks for:
 
-```powershell
-blun-codex telegram-plugin --print-only
+```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/`
+
+## 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
-
-## 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
+
+## 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
+2. ask for missing Bot Token or allowed Chat ID(s)
+3. save everything automatically into the local Telegram state folder
+4. continue into Telegram mode
+
+If something is missing later, `blun-codex telegram-doctor` tells you exactly what is missing and what to run next.
+
+## 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

package/blun-codex.ps1

@@ -1,110 +1,140 @@
-$ErrorActionPreference = "Stop"
-
-$runtimeRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
-$profile = "default"
-$telegramMode = "inherit"
-$workspace = ""
-$remoteControl = $false
-$printOnly = $false
-$promptParts = @()
-$parsedArgs = @($args)
-
-if ($parsedArgs.Count -gt 0) {
-  switch ($parsedArgs[0]) {
-    "telegram-status" {
-      $commandArgs = @()
-      if ($parsedArgs.Count -gt 1) {
-        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
-      }
-      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-status.ps1") @commandArgs
-      exit $LASTEXITCODE
-    }
-    "telegram-doctor" {
-      $commandArgs = @()
-      if ($parsedArgs.Count -gt 1) {
-        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
-      }
-      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-doctor.ps1") @commandArgs
-      exit $LASTEXITCODE
-    }
-    "doctor" {
-      $commandArgs = @()
-      if ($parsedArgs.Count -gt 1) {
-        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
-      }
-      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-doctor.ps1") @commandArgs
-      exit $LASTEXITCODE
-    }
-    "telegram-plugin" {
-      $telegramMode = "plugin"
-      if ($parsedArgs.Count -gt 1) {
-        $parsedArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
-      } else {
-        $parsedArgs = @()
-      }
-    }
-  }
-}
-
-for ($i = 0; $i -lt $parsedArgs.Count; $i++) {
-  $arg = $parsedArgs[$i]
-  switch ($arg) {
-    "--profile" {
-      $i++
-      if ($i -ge $parsedArgs.Count) { throw "--profile requires a value" }
-      $profile = $parsedArgs[$i]
-      continue
-    }
-    "--telegram" {
-      $i++
-      if ($i -ge $parsedArgs.Count) { throw "--telegram requires a value" }
-      $telegramMode = $parsedArgs[$i]
-      continue
-    }
-    "--workspace" {
-      $i++
-      if ($i -ge $parsedArgs.Count) { throw "--workspace requires a value" }
-      $workspace = $parsedArgs[$i]
-      continue
-    }
-    "--remote-control" {
-      $remoteControl = $true
-      continue
-    }
-    "--print-only" {
-      $printOnly = $true
-      continue
-    }
-    default {
-      $promptParts += $arg
-    }
-  }
-}
-
-$invokeArgs = @(
-  "-ExecutionPolicy", "Bypass",
-  "-File", (Join-Path $runtimeRoot "start-codex-agent.ps1"),
-  "-Agent", $profile,
-  "-TelegramMode", $telegramMode
-)
-
-if ($workspace) {
-  $invokeArgs += "-Workspace"
-  $invokeArgs += $workspace
-}
-
-if ($remoteControl) {
-  $invokeArgs += "-RemoteControl"
-}
-
-if ($printOnly) {
-  $invokeArgs += "-PrintOnly"
-}
-
-if ($promptParts.Count -gt 0) {
-  $invokeArgs += "-Prompt"
-  $invokeArgs += ($promptParts -join " ")
-}
-
-& powershell @invokeArgs
-exit $LASTEXITCODE
+$ErrorActionPreference = "Stop"
+
+$runtimeRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$profile = "default"
+$telegramMode = "inherit"
+$workspace = ""
+$remoteControl = $false
+$printOnly = $false
+$skipTelegramSetup = $false
+$promptParts = @()
+$parsedArgs = @($args)
+
+if ($parsedArgs.Count -gt 0) {
+  switch ($parsedArgs[0]) {
+    "telegram-status" {
+      $commandArgs = @()
+      if ($parsedArgs.Count -gt 1) {
+        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
+      }
+      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-status.ps1") @commandArgs
+      exit $LASTEXITCODE
+    }
+    "telegram-doctor" {
+      $commandArgs = @()
+      if ($parsedArgs.Count -gt 1) {
+        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
+      }
+      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-doctor.ps1") @commandArgs
+      exit $LASTEXITCODE
+    }
+    "telegram-setup" {
+      $commandArgs = @()
+      if ($parsedArgs.Count -gt 1) {
+        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
+      }
+      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-setup.ps1") @commandArgs
+      exit $LASTEXITCODE
+    }
+    "doctor" {
+      $commandArgs = @()
+      if ($parsedArgs.Count -gt 1) {
+        $commandArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
+      }
+      & powershell -ExecutionPolicy Bypass -File (Join-Path $runtimeRoot "telegram-doctor.ps1") @commandArgs
+      exit $LASTEXITCODE
+    }
+    "telegram-plugin" {
+      $telegramMode = "plugin"
+      if ($parsedArgs.Count -gt 1) {
+        $parsedArgs = @($parsedArgs[1..($parsedArgs.Count - 1)])
+      } else {
+        $parsedArgs = @()
+      }
+    }
+  }
+}
+
+for ($i = 0; $i -lt $parsedArgs.Count; $i++) {
+  $arg = $parsedArgs[$i]
+  switch ($arg) {
+    "--profile" {
+      $i++
+      if ($i -ge $parsedArgs.Count) { throw "--profile requires a value" }
+      $profile = $parsedArgs[$i]
+      continue
+    }
+    "--telegram" {
+      $i++
+      if ($i -ge $parsedArgs.Count) { throw "--telegram requires a value" }
+      $telegramMode = $parsedArgs[$i]
+      continue
+    }
+    "--workspace" {
+      $i++
+      if ($i -ge $parsedArgs.Count) { throw "--workspace requires a value" }
+      $workspace = $parsedArgs[$i]
+      continue
+    }
+    "--remote-control" {
+      $remoteControl = $true
+      continue
+    }
+    "--print-only" {
+      $printOnly = $true
+      continue
+    }
+    "--skip-telegram-setup" {
+      $skipTelegramSetup = $true
+      continue
+    }
+    "telegram-plugin" {
+      $telegramMode = "plugin"
+      continue
+    }
+    default {
+      $promptParts += $arg
+    }
+  }
+}
+
+if ($telegramMode -eq "plugin" -and -not $skipTelegramSetup -and -not $printOnly) {
+  $setupArgs = @(
+    "-ExecutionPolicy", "Bypass",
+    "-File", (Join-Path $runtimeRoot "telegram-setup.ps1"),
+    "-Profile", $profile,
+    "-EnsureConfigured"
+  )
+  & powershell @setupArgs
+  if ($LASTEXITCODE -ne 0) {
+    exit $LASTEXITCODE
+  }
+}
+
+$invokeArgs = @(
+  "-ExecutionPolicy", "Bypass",
+  "-File", (Join-Path $runtimeRoot "start-codex-agent.ps1"),
+  "-Agent", $profile,
+  "-TelegramMode", $telegramMode
+)
+
+if ($workspace) {
+  $invokeArgs += "-Workspace"
+  $invokeArgs += $workspace
+}
+
+if ($remoteControl) {
+  $invokeArgs += "-RemoteControl"
+}
+
+if ($printOnly) {
+  $invokeArgs += "-PrintOnly"
+}
+
+if ($promptParts.Count -gt 0) {
+  $invokeArgs += "-Prompt"
+  $invokeArgs += ($promptParts -join " ")
+}
+
+& powershell @invokeArgs
+exit $LASTEXITCODE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blunking/codexlink",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "BLUN CLI launcher with Telegram channel support for one visible session.",
   "license": "MIT",
   "private": false,
@@ -10,7 +10,7 @@
   },
   "files": [
     "bin/",
-    "profiles/",
+    "profiles/default.json",
     "telegram-plugin/",
     "README.md",
     "LICENSE",
@@ -19,7 +19,8 @@
     "start-codex-agent.ps1",
     "start-codex.cmd",
     "telegram-status.ps1",
-    "telegram-doctor.ps1"
+    "telegram-doctor.ps1",
+    "telegram-setup.ps1"
   ],
   "keywords": [
     "blun",