pi-braid-telegram 0.0.0-stage → 0.1.4

package/docs/turn-complete-notify.md

@@ -0,0 +1,110 @@
+# Turn-Complete Auto-Notify: Design Decisions
+
+<!-- status: current -->
+
+Status: **pending owner sign-off**. This list is the deliverable-1 surface; the
+fixture tests in `packages/telegram/test/notify.test.mjs` pin the implemented
+defaults. Any owner change to a default below is a config/env change, not code.
+
+## Feature recap
+
+When the agent finishes a turn with a completed plain-text answer (no trailing
+tool call), a SECOND LLM call (the "crafting model") distills the answer into
+an owner update capped at `braid.telegram.notifyMaxChars` (default 1200) and
+sends it over Telegram through the SAME
+outbound seam as `telegram_send` / `/telegram send`. The `[tg-end]` marker is
+an INBOUND parse boundary only and never appears on outbound.
+
+## Decision 1: which turns notify
+
+**Implemented: completed-answer turns only.**
+`shouldNotifyTurnEnd(event)` notifies iff the `turn_end` message is an assistant
+message with non-empty text AND `stopReason !== "toolUse"`. A `toolUse`
+stopReason means the model's last action was a trailing tool call (work
+continues next turn) → no notify. This satisfies the brief's "NO crafting when
+last tool call trailing".
+Rejected alternatives:
+
+- _Always_ (every turn, including mid-work tool turns) - would spam the owner.
+- _Quiet-window_ (only during owner-defined quiet hours) - no owner-supplied
+  quiet-hours config exists; OBE once the owner defines one.
+- _Per-session opt-in_ (agent decides each session) - the agent is the one
+  being notified about; it should not be the gatekeeper.
+
+## Decision 2: opt-in vs always-on
+
+**Implemented: opt-in via `BRAID_TG_NOTIFY_ENABLED=1` (default OFF).**
+No unsolicited messages until the owner enables it. The telegram extension
+already requires `BRAID_TG_BOT_TOKEN`, so this is the only extra flag. When the
+flag is off, the `turn_end` listener is NOT registered at all (verified by
+`test/index.test.mjs`).
+
+## Decision 3: utility vs max-power model
+
+**Implemented: session model by default, env override wins.**
+`resolveNotifyModel()` (notify/model.ts): `BRAID_TG_NOTIFY_MODEL`
+(`provider/model-id`) → else `ctx.model` (session model) → else first available
+registry model. The call is key-ring-backed: the API key comes from
+`ctx.modelRegistry.getApiKeyForProvider(provider)`, which
+pi-braid-providers wires to the key-ring (`ring-lifecycle.ts` auth.resolve →
+`getActiveKey`) - never the bot token.
+Note: core's `/utility-model` role key (`/max-power-model` is a deprecated
+alias of it) lives in core's global-state (unreachable from the standalone
+telegram package without a cross-package import). The env override is the
+telegram-native equivalent.
+Owner call: if honoring the /utility-model role key is required, that needs the
+core-extension placement (Architecture B) instead - documented as a follow-up.
+
+## Decision 4: rate limit
+
+**Implemented: sliding window, max 4/min by default.**
+`SlidingWindowLimiter` (notify/rate-limit.ts), override via
+`BRAID_TG_NOTIFY_MAX_PER_MIN`. Deterministic by explicit-timestamp `try(now)`.
+Sliding window (vs fixed minute) so a turn at 59.9s does not immediately reset.
+
+## Decision 5: content template
+
+**Implemented: distilling prompt** (`buildNotifyPrompts` in notify/craft.ts):
+"state what was done / key result, ≤ `braid.telegram.notifyMaxChars` chars
+(default 1200), plain text, no greetings/no
+sign-off/no markdown; reply DONE if no actionable content." The crafting model
+produces the message; `truncateGuard` (same cap, ellipsis) is the guard-fallback
+when crafting fails or returns something malformed. The model's output budget
+scales with the cap (`craftMaxTokensFor`) so a long target is not cut mid-sentence.
+
+## Decision 6: telegram_send / /telegram send reuse the same seam
+
+`runTelegramSend` gained an optional `craft` hook. When text exceeds the
+settings-driven send cap (`braid.telegram.sendMaxChars`, default 4096), the
+crafting model produces the message (replacing the old dumb truncation);
+the cap stays as the guard threshold. Short text skips crafting
+(no model call). `/telegram send` now routes through `runTelegramSend` -
+the exact same outbound path - so crafting, cap fallback, and
+no-[tg-end] behavior are shared.
+
+## Placement decision (why telegram, not a new core extension)
+
+The brief leaned "a new small extension under packages/core/src/extensions/"
+but allowed "or a new extension" with "read how existing extensions register
+listeners and mirror it". Chosen: the notify feature lives in the TELEGRAM
+package because:
+
+- It owns the outbound seam + client/token/chatId - deliverable 3 ("same
+  outbound seam") is literal, with zero cross-package coupling.
+- It already registers pi.on listeners in its factory (16f pattern); a
+  `turn_end` listener mirrors it exactly.
+- The alternative (core notify extension + delivery sink registered by
+  telegram) requires a telegram→core import. It works today via the workspace
+  symlink but is a phantom dependency and makes the telegram test chain depend
+  on core's dist being freshly built - fragile under the "no package-lock diff"
+  gate. Avoided.
+- The crafting LLM call reuses "our systems": `completeSimple` from
+  `@earendil-works/pi-ai/compat` (the exact path core's llm-call.ts wraps at
+  llm-call.ts:50) + `ctx.modelRegistry` for model + key-ring key.
+
+## Forbidden-files check
+
+- No packages/providers source changes by this task (a pre-existing,
+  unrelated working-tree modification was left untouched).
+- No package-lock.json diff, no npm install, no git checkout/reset/stash.
+- No changes to packages/core or packages/providers source.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "pi-braid-telegram",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.4",
+  "description": "Bidirectional Telegram channel for pi-braid: telegram_send tool (outbound) + inbound long-poll injector (backward channel)",
+  "type": "module",
+  "files": [
+    "src/",
+    "docs/",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "bot",
+    "extension",
+    "telegram",
+    "channel",
+    "messaging"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "prepublishOnly": "npm run typecheck",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node test/run-tests.mjs",
+    "check:doc-index": "node ../../packages/core/scripts/check-doc-index.mjs",
+    "publish:local": "node ../../packages/core/scripts/publish-local.mjs telegram",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "6.0.2",
+    "typebox": "1.1.38"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "author": "kifirkin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kifirkin/pi-braid.git",
+    "directory": "packages/telegram"
+  },
+  "bugs": {
+    "url": "https://github.com/kifirkin/pi-braid/issues"
+  },
+  "homepage": "https://github.com/kifirkin/pi-braid/tree/main/packages/telegram",
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}