@llblab/pi-telegram 0.30.0 → 0.31.0

package/AGENTS.md

@@ -43,7 +43,7 @@ Keep each fact in one authoritative layer:
 - `/lib/*.ts`: Flat, cohesive runtime domains; package-private unless re-exported through `/api`.
 - `/tests/*.test.ts`: Domain-mirrored suites; `tests/integration.test.ts` owns cross-domain runtime flows.
 - `/skills/telegram-bridge`: Stable agent operating protocol for Telegram turns, delivery, actions, Threaded Mode, and diagnosis.
-- `/skills/control-surface`: Optional agent-generated cybernetic control surface over truthful domain evidence, workflows, and choices; it remains independent from the bridge skill and owns no parallel state.
+- `/skills/generated-control-surface`: Optional state-derived, late-bound interface over truthful domain evidence, capabilities, workflows, and choices; it remains renderer-neutral, independent from the bridge skill, and owns no parallel state.
 - `/.agents/skills/telegram-bot`: Bot API lookup guidance and vendored `api.md`; keep the reference intact.
 - `/.agents/skills/domain-dag`: Repository architecture guidance and validator.
 

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.31.0: State-Derived Generated Control Surfaces
+
+- `Generated Control Surface`: Renamed the optional `control-surface` Skill to `generated-control-surface`, aligned its identity with the architectural primitive, and made Telegram routing evaluate it proactively when controls can materially shorten likely feedback without waiting for an explicit button request; decorative UI still resolves to zero controls.
+- `Late-Bound Interface`: Defined generated surfaces as `interface = f(state, capabilities, intent)`: ephemeral renderer projections that expose domain-owned state and agency under constitutional constraints without absorbing parallel state. Telegram remains the first renderer rather than the capability boundary.
+
+## 0.30.1: Priority Button Queue Hotfix
+
+- `Priority Queue`: Assistant-authored button callbacks now enter the sorted priority lane ahead of already queued default prompts, aligning the visible lightning marker with actual dispatch order while preserving callback deduplication and FIFO ordering within each lane.
+
 ## 0.30.0: Generated Control Surfaces
 
 - `Generated Control Surface`: Replaced the CLI-bound Button Console with a transport-aware Control Surface Skill that proactively generates truthful contextual controls when they shorten feedback for workflows, stateful systems, navigation, Actor supervision, and decisions while preserving domain ownership, ordinary prompt authority, confirmation boundaries, and stateless regeneration.

package/README.md

@@ -257,7 +257,7 @@ Durable inbound admission is a **process-crash recovery** guarantee. Atomic priv
 
 Telegram is a companion surface around a live Pi runtime, not a second runtime. It can compact the current session, but it cannot create, resume, fork, browse, or switch sessions until Pi exposes safe public extension APIs for those operations.
 
-A Telegram prompt is a normal model turn in the active Pi session and therefore inherits that session's active post-compaction context; the bridge does not make token cost proportional only to the new mobile message. The bundled `telegram-bridge` Skill owns agent operation and `control-surface` provides optional evidence-backed controls for workflows, stateful systems, navigation, supervision, and decisions—not only terminal operations. Disconnecting removes pi-telegram's delivery tools and transient routing guidance from later requests until direct ownership or follower registration returns, without changing other active Pi tools. Pi session JSONL contains model history; profile-scoped pi-telegram `logs*.jsonl` contains redacted operational events and is never model context.
+A Telegram prompt is a normal model turn in the active Pi session and therefore inherits that session's active post-compaction context; the bridge does not make token cost proportional only to the new mobile message. The bundled `telegram-bridge` Skill owns agent operation and `generated-control-surface` proactively compiles optional evidence-backed, ephemeral controls from current state, available capabilities, and user intent when they materially shorten likely feedback for workflows, stateful systems, navigation, supervision, and decisions—not only terminal operations. Disconnecting removes pi-telegram's delivery tools and transient routing guidance from later requests until direct ownership or follower registration returns, without changing other active Pi tools. Pi session JSONL contains model history; profile-scoped pi-telegram `logs*.jsonl` contains redacted operational events and is never model context.
 
 ## Documentation Map
 

package/docs/architecture.md

@@ -362,7 +362,7 @@ Complete intermediate assistant text blocks from Telegram-originated activity ar
 
 `assistant.activity` is an independent bridge-owned projection over normalized Activity events. Each process reloads the shared file-backed setting at `agent-start` before activity admission, so multi-instance mode cannot continue projecting a stale broader process-local selection. Omitted values resolve to `verbose`, while invalid values fail closed to `quiet`; `thinking` and `tools` select one technical class, while `verbose` enables both. Provider-exposed thinking uses persistent ordinary HTML containing only a standard expandable blockquote with a bounded redacted latest-text window and inline Markdown rendered as Telegram HTML. Completed executed tools use native Rich Messages: each closed `<Tool>: <status>` root details node renders snake-case names as title words while preserving an uppercase two- or three-letter repeated prefix per word, then the native disclosure chevron reveals an open-by-default `arguments` child plus closed retained `update N` and `result`/`error` child details with lowercase monospaced, marker-free summaries and JSON pre blocks; known-safe Rich rejections fall back to the previous HTML disclosure. The projection captures the exact target and transport stamp at activity admission, serializes updates, preserves tool-start order, closes coalescing across assistant/thinking boundaries, bounds retained text/update memory plus edit frames and message/tool size, disables previews and HTTP(S) auto-link recognition inside technical evidence, and never replays a possibly committed send. Session generations own independent queues, so replacement drops queued old work without waiting on an old call. Both proactive prose and active-turn final delivery wait for the admitted activity queue inside their extension-owned delivery tasks, preserving technical-before-semantic ordering without delaying Pi lifecycle completion. Settlement, replacement, disconnect, failure, or stale authority clears only local ownership; already-sent activity messages remain in chat.
 
-Telegram prompt guidance is context- and authority-aware. The package and source-checkout extension both contribute `telegram-bridge` plus the optional `control-surface` Skill through Pi resource discovery. The latter generates transient evidence-backed controls over domain-owned workflows, systems, navigation, supervision, and decisions without creating parallel application state. Only an exact direct owner or live registered follower exposes the two pi-telegram delivery tools, their active-tool metadata, and the compact routing suffix. Disconnect or authority loss removes those tool surfaces for subsequent requests without touching foreign tools; reconnect/recovery restores only the pi-telegram subset that was active before suspension, including across same-process reload. Telegram-originated turns route to the stable Skill contract and retain dynamic blocks such as `[voice] delivery: automatic voice`; the Skill and public documentation own syntax, target routing, Threaded Mode behavior, and diagnostics.
+Telegram prompt guidance is context- and authority-aware. The package and source-checkout extension both contribute `telegram-bridge` plus the optional `generated-control-surface` Skill through Pi resource discovery. The latter treats `interface = f(state, capabilities, intent)` as a renderer-neutral primitive, compiling transient evidence-backed controls over domain-owned workflows, systems, navigation, supervision, and decisions without creating parallel application state. Only an exact direct owner or live registered follower exposes the two pi-telegram delivery tools, their active-tool metadata, and the compact routing suffix. Disconnect or authority loss removes those tool surfaces for subsequent requests without touching foreign tools; reconnect/recovery restores only the pi-telegram subset that was active before suspension, including across same-process reload. Telegram-originated turns route to the stable Skill contract and retain dynamic blocks such as `[voice] delivery: automatic voice`; the Skill and public documentation own syntax, target routing, Threaded Mode behavior, and diagnostics.
 
 ## In-Flight Model Switching
 

package/lib/queue.ts

@@ -821,7 +821,10 @@ export function appendTelegramPromptTurnOnce<TContext = unknown>(
         isDuplicateTelegramPromptTurn(item, turn),
     );
   if (duplicate) return { items, appended: false };
-  return { items: [...items, turn], appended: true };
+  return {
+    items: [...items, turn].sort(compareTelegramQueueItems),
+    appended: true,
+  };
 }
 
 export function compareTelegramQueueItems<TContext = unknown>(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/skills/{control-surface → generated-control-surface}/SKILL.md

@@ -1,24 +1,31 @@
 ---
-name: control-surface
-description: Generates contextual, evidence-backed prompt-button interfaces as transient control surfaces for workflows, tools, stateful systems, choices, navigation, and operator actions—not only terminals. Use when a user asks the agent to generate buttons or a contextual operating surface through Telegram or another prompt-button transport. Existing transport menus and callback interfaces remain with their runtime owners.
+name: generated-control-surface
+description: Proactively compiles current state, available capabilities, and user intent into contextual, evidence-backed, ephemeral prompt-button interfaces. Use on Telegram turns and other prompt-button transports whenever controls materially shorten likely feedback, without requiring an explicit user request, while omitting decorative UI and preserving domain ownership; fixed transport menus and callbacks remain with their runtime owners.
 ---
 
-# Control Surface
+# Generated Control Surface
 
-Generate a temporary, truthful interface that turns the agent's current understanding and available capabilities into useful controls. The agent remains the interpreter, authority boundary, and interface generator; buttons are contextual prompts, not a second application, hidden daemon, or direct grant of capability.
+Compile a temporary, truthful interface from current state, available capabilities, and user intent. The agent remains the interpreter and authority boundary; the generated surface remains an ephemeral renderer projection, not a second application, hidden daemon, state owner, or direct grant of capability.
 
-## Concept
+## Primitive
 
 ```text
-User intent + current evidence → compact state projection → contextual controls
+interface = f(state, capabilities, intent)
+
+current evidence + available acts + user intent
+→ compact state projection → contextual controls
 → next prompt → authorized act → fresh projection
 ```
 
-Each response is one generated control surface. Reinspect mutable reality after actions and regenerate the surface instead of maintaining a parallel UI model.
+This is late-bound UI rather than a fixed frontend for one backend. Each response is one generated control surface whose renderer may be Telegram, another prompt-button transport, or a numbered fallback. Reinspect mutable reality after actions and regenerate instead of maintaining a parallel UI model.
+
+The primitive belongs to the Surface plane: it projects State, exposes Agency capabilities, and preserves Constitution constraints without absorbing any of those owners. Its reusable competence lives in this Skill so quality depends less on rediscovering interface policy in each turn.
 
 ## Scope
 
-Use this Skill only to synthesize an agent-generated prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, or runtime-owned control stays with that subsystem and does not route here merely because it contains buttons.
+Use this Skill only to synthesize a state-derived prompt-button surface. Operating or modifying an existing Telegram bridge menu, callback interface, fixed frontend, or runtime-owned control stays with that subsystem and does not route here merely because it contains buttons.
+
+On Telegram turns, evaluate this Skill proactively rather than waiting for the user to ask for buttons. Load and apply it when a likely next decision, approval, navigation step, inspection, or bounded action can be made materially easier through controls; its correct output may still contain zero buttons when the admission test fails.
 
 A control surface may expose:
 

package/skills/telegram-bridge/SKILL.md

@@ -46,6 +46,8 @@ Use `telegram_attach` outside Telegram turns only when the user explicitly reque
 
 ## Assistant-Authored Actions
 
+On Telegram turns, proactively load `generated-control-surface` when a likely next decision or action may benefit from prompt buttons; do not wait for an explicit button request, and accept zero controls when its admission rules reject decorative or low-value UI.
+
 `telegram_button` and `telegram_voice` are hidden top-level HTML comments, not tools. Emit them at column zero, outside lists, quotes, code blocks, and indentation.
 
 Button forms: