@llblab/pi-telegram 0.35.1 → 0.36.0

package/docs/generative-apps.md

@@ -0,0 +1,310 @@
+# Generative Apps Runtime For Telegram
+
+_Status: incremental implementation. Canonical installation and explicit transactional replacement, agent-side method invocation, state/history commits, partial-tail recovery, cross-process transition locking with dead-owner recovery, installation-generation plus revision rejection for direct app-output controls, lifecycle-cancelled worker-isolated methods, the bounded non-shell process port, strict bound-action parsing, pre-model-queue `tgbtn` dispatch, new-message default views, and opt-in in-place bound-action edits with explicit-action send fallback are implemented locally. Agent-mediated initial-surface revision capture, process-birth lock proof, voice delivery, automatic refresh scheduling, removal, and complete lifecycle diagnostics remain open in the backlog._
+
+## Purpose
+
+This document specifies the concrete Generative App runtime implemented by `pi-telegram`. The transport-independent concept, vocabulary, application shapes, hybrid action model, and agent operating workflow belong to the bundled [`generative-apps` Skill](../skills/generative-apps/SKILL.md).
+
+The Telegram implementation provides managed installation, method execution, persistence, button binding, callback routing, and message delivery:
+
+```text
+Telegram control → bound method → state/capability owner
+Telegram view    ← rendered output ← fresh result
+```
+
+This runtime coexists with ordinary prompt buttons, companion-extension callbacks, Sections, and the Delivery API. It ships no application catalog or `examples/` tree; reusable domain scripts remain with their capability owners.
+
+## Ownership Split
+
+- The bundled [`generative-apps` Skill](../skills/generative-apps/SKILL.md) owns the general concept and agent operation: category definition, `generated` versus `generative`, application shapes, hybrid method/prompt surfaces, selection, authorship, review, workflow, safety, and validation judgment.
+- [`architecture.md`](./architecture.md#generative-apps) owns this runtime's place inside the Telegram bridge and its domain boundaries.
+- This document owns only `pi-telegram` implementation contracts: canonical managed identity, executable ABI, Telegram wire syntax, state timeline, installation/replacement, bounded ports, callback routing, delivery, lifecycle, and current limitations.
+- [`generated-control-surface`](../skills/generated-control-surface/SKILL.md) owns the separate ephemeral control-surface operating protocol.
+
+Keep conceptual guidance out of this document and Telegram runtime mechanics out of the Generative Apps Skill.
+
+## Canonical Layout And Identity
+
+Generative Apps live under the active Pi agent directory, never in package installation files or temporary storage:
+
+```text
+<agent-dir>/genapps/
+└── poker/
+    ├── poker.mjs
+    ├── state.json
+    └── states.jsonl
+```
+
+Identity is structural:
+
+```text
+app = directory name = module stem
+poker  = poker          = poker.mjs
+```
+
+No app manifest, per-app `package.json`, duplicated `name`, class registration, or default export is required. The `.mjs` extension supplies ESM semantics directly.
+
+An app name is a unique lowercase ASCII identifier accepted by the runtime's path-safe validation. It must not contain path separators, `..`, `::`, or a native callback namespace delimiter.
+
+## Inference-Bypass Syntax
+
+Compact Matrix Literal and full JSON buttons keep their existing `label + prompt` contract. A bound action is encoded entirely in the prompt string:
+
+```ebnf
+bound-action = app "::" method [ "(" json-value ")" ]
+```
+
+Examples:
+
+```text
+poker::fold
+poker::call(18)
+poker::init({"seed":"abc"})
+media::seek("+30s")
+```
+
+No argument means no decorative empty parentheses. One optional argument is a strict JSON value; the runtime never evaluates JavaScript source from the argument.
+
+CML:
+
+```text
+[{Fold|poker::fold}{Call 18|poker::call(18)}]
+```
+
+Equivalent JSON:
+
+```json
+[
+  [
+    { "label": "Fold", "prompt": "poker::fold" },
+    { "label": "Call 18", "prompt": "poker::call(18)" }
+  ]
+]
+```
+
+`app` is not a button property. Both representations normalize to the same prompt string, and routing happens afterward.
+
+The double colon is the inference-bypass operator: it routes a generated prompt control to a registered deterministic owner before Pi queue admission. Native extension callbacks retain their existing single-colon grammar:
+
+```text
+myext:action:payload   native callback_data namespace
+poker::call(18)        generated prompt routed to a Generative App
+```
+
+These routes do not conflict. Native callbacks are direct by construction. `::` exists only because an ordinary generated button prompt would otherwise enter the model queue.
+
+An absent, stale, or invalid bound app fails closed and never degrades into an accidental model prompt.
+
+## `telegram_bind` Tool
+
+One agent Tool owns installation and deliberate invocation through two mutually exclusive shapes.
+
+Install an external self-contained module and initialize it:
+
+```ts
+telegram_bind({
+  app: "poker",
+  script: "/path/to/poker.mjs",
+  argument: { seed: "abc" }
+})
+```
+
+The runtime copies the module to `<agent-dir>/genapps/poker/poker.mjs`, validates the canonical identity and required exports, transactionally invokes `init(argument)`, and initializes state. Existing installation is never overwritten without explicit replacement authority. Installed canonical modules are discovered directly when a bound action resolves; there is no separate app registry.
+
+Explicitly replace an installed app after editing its script:
+
+```ts
+telegram_bind({
+  app: "poker",
+  script: "/path/to/poker.mjs",
+  replace: true,
+  argument: { seed: "abc" }
+})
+```
+
+Replacement validates and initializes a complete staging app before publishing it under the existing app name. A failed `init` preserves the installed module, state, and timeline. Omitting `replace: true` keeps duplicate installation fail-closed, while setting it for an absent app also fails instead of silently changing replacement into installation.
+
+Discover or reuse an app already written at its canonical path and invoke a named method:
+
+```ts
+telegram_bind({
+  app: "poker",
+  method: "init",
+  argument: { seed: "abc" }
+})
+```
+
+Agent-side diagnostic invocation uses the same shape:
+
+```ts
+telegram_bind({ app: "poker", method: "inspect" })
+```
+
+`script` and `method` are mutually exclusive, and `replace` is valid only with `script`. Script installation or replacement implicitly invokes mandatory `init`; existing-app invocation names its method explicitly. Folder presence supplies durable discoverability across runtime replacement without introducing a manifest.
+
+During an active Telegram turn, `telegram_bind` displays successful app output directly through the current outbound planner and exact turn target by default, including initial `init` output; its Tool result tells the agent not to repeat or reformat the delivered view. Set `display: false` for agent-only diagnosis. Outside an active Telegram turn, the Tool returns bounded output for exact caller-owned presentation rather than choosing a Telegram target implicitly. The same method invoked through `app::method(argument)` routes its rendered output directly to the owning Telegram surface.
+
+## Module Contract
+
+A Generative App exports plain named async or synchronous functions. `init` is mandatory. Classes and default exports are outside the contract.
+
+```js
+export async function init({ argument, run, signal }) {
+  const seed = argument?.seed ?? "default";
+  return {
+    state: { seed, turn: 0 },
+    output: "**Ready**\n\n<!-- telegram_button {Start|poker::start} -->"
+  };
+}
+
+export async function start({ state }) {
+  const nextState = { ...state, turn: state.turn + 1 };
+  return {
+    state: nextState,
+    output: `**Turn:** \`${nextState.turn}\``
+  };
+}
+
+export async function inspect({ state }) {
+  return { output: JSON.stringify(state) };
+}
+```
+
+The runtime context may contain only bounded capabilities required by the contract:
+
+- Current immutable app state, absent for first initialization.
+- Parsed optional JSON argument.
+- Cancellation signal and current app revision.
+- A bounded non-shell process port for coherent CLI adapters.
+- Redacted app/target metadata needed for diagnostics and rendering ownership.
+
+The runtime does not pass a raw Telegram client, bot token, Pi extension context, arbitrary transport operation, or mutable queue/session state.
+
+A method result contains:
+
+```ts
+interface GenerativeAppResult {
+  state?: JsonValue;
+  output: string;
+  viewMode?: "new" | "edit";
+}
+```
+
+`output` is ordinary assistant Markdown plus existing top-level voice/button markup. It passes through the established outbound planner rather than defining a second rendering language. Omitted `viewMode` defaults to `"new"`: the result arrives as a fresh message and the clicked button remains visibly selected on its prior surface. `viewMode: "edit"` opts one result into replacing the callback message and keyboard in place when Telegram permits it; edit failure after that explicit action may fall back to one new message.
+
+Returning `state` requests a committed transition. Omitting `state` makes the method output-only, which supports inspection and live refresh without appending duplicate history. Invalid, oversized, non-serializable, or malformed results fail before state or Telegram effects commit.
+
+## Current State And State Timeline
+
+`state.json` is the compact current projection read by the runtime and, when useful, by the agent:
+
+```json
+{
+  "seed": "abc",
+  "turn": 2
+}
+```
+
+`states.jsonl` is the committed-state timeline. Its first line is the successful initial state; each later state-changing method appends one complete snapshot envelope:
+
+```jsonl
+{"revision":0,"method":"init","argument":{"seed":"abc"},"state":{"seed":"abc","turn":0}}
+{"revision":1,"method":"start","state":{"seed":"abc","turn":1}}
+{"revision":2,"method":"start","state":{"seed":"abc","turn":2}}
+```
+
+The state in `state.json` equals the state in the latest complete journal line. Runtime-owned locking, revision checks, complete-line append, atomic replacement, and recovery preserve that relation across concurrent clicks and interruption. A partial final JSONL line is never treated as committed state.
+
+A successful `init` is a hard new-run boundary. It transactionally clears current state and prior history, writes the new initial snapshot as revision zero, and publishes the initial output. Initialization failure preserves the previous working state and journal unchanged.
+
+Application state is the app's complete persistent checkpoint: it includes interaction/configuration state plus the latest normalized external projection needed to render, diagnose, or reconstruct the current view. An agent reading `state.json` should be able to identify material app reality such as selected track, playback state, queue position, backend, and last observation without executing the app first. This projection is explicitly a last-observed cache, not the external domain authority: before a mutation, explicit status, or refresh, a CLI-backed app re-reads the actual owner, then commits a new complete snapshot only when retained app state materially changes.
+
+## CLI Capability Adapters
+
+A Generative App may compose several existing CLI tools when they belong to one coherent domain or user journey:
+
+```text
+media Generative App → playerctl + mpv + local media library
+git Generative App   → git + gh
+actors Generative App → documented Actor runtime capabilities
+```
+
+A bounded process port uses executable plus argument arrays, an explicit working directory, output limits, timeout, cancellation, and redacted evidence. Shell interpolation is not the default contract.
+
+```js
+const result = await run({
+  command: "playerctl",
+  args: ["metadata", "--format", "{{artist}} — {{title}}"],
+  timeoutMs: 10_000
+});
+```
+
+A generic `exec(arbitrary-shell-command)` Generative App is forbidden. It would turn Telegram into a remote terminal, bypass bounded capability ownership, and violate the mobile companion boundary. A direct button click authorizes only the installed app method and its validated argument, never arbitrary process execution.
+
+## Live Views
+
+A Generative App sends a new message after a successful bound user action by default. This simple mode preserves prior surfaces and their visibly selected buttons, is robust across ordinary Telegram constraints, and remains a first-class behavior rather than a fallback to eliminate. A method may opt into `viewMode: "edit"` to replace the callback message and keyboard in place; if that explicit action cannot edit a deleted or otherwise unavailable message, it may send one fresh view because the click itself supplies recreation authority.
+
+Automatic refresh is not implemented in the current runtime. The intended future contract uses an exported `refresh` method and a bounded scheduling hint; applications must not return or rely on that hint until the backlog item is complete:
+
+```js
+export async function refresh({ state, run }) {
+  return {
+    output: await renderPlayer(state.player, run),
+    refreshAfterMs: 5000
+  };
+}
+```
+
+The runtime contract is:
+
+- Missing `refreshAfterMs` stops automatic refresh.
+- Values below two seconds clamp to two seconds.
+- The next interval starts only after the prior refresh and Telegram edit settle; calls never overlap or accumulate.
+- One refresh schedule exists per app, profile, target, and logical surface.
+- An unchanged normalized frame digest causes no Telegram edit.
+- Telegram `retry_after`, bounded backoff, lifecycle cancellation, target authority, and execution generation remain authoritative.
+- Refresh is session-bound and does not silently resume after process replacement until the surface is opened again.
+- Output-only refresh does not change `state.json` or append `states.jsonl`.
+
+The runtime retains the latest `TelegramDeliveryHandle` in memory for each live app surface. The first frame sends a logical view; later app actions and refreshes edit that same view rather than creating message traffic.
+
+Telegram does not reliably report deletion of every ordinary private bot message. When a supported deletion update identifies the handle, the runtime invalidates it immediately. When edit returns a known message-not-found result, the runtime forgets the handle and stops refresh. It never recreates a user-deleted view automatically; the next explicit user action or app opening may create a fresh view.
+
+## Lifecycle And Safety
+
+Generative Apps are trusted local code and therefore an explicit capability grant, not a sandbox promise. The runtime still narrows accidental authority and operational failure:
+
+- Installation validates canonical paths and rejects traversal, symlinks outside the managed root, identity mismatch, and silent replacement; explicit replacement stages and initializes the new app before swapping it under the same app.
+- App execution cannot own Telegram polling, credentials, raw transport, Pi queue state, or another app's files through the provided contract.
+- Per-app transitions serialize and compare immutable installation generation plus state revision so stale buttons cannot cross replacement or mutate newer state.
+- State commit and Telegram effect ordering are explicit; ambiguous non-idempotent transport outcomes never replay blindly.
+- Time, output, state-size, refresh-rate, and process bounds prevent one app from monopolizing the extension.
+- Session/profile/target generation replacement makes old scheduled work inert.
+- Diagnostics redact secrets and preserve app name, method, revision, failure class, and bounded stderr/result evidence.
+- Removal cancels refresh, invalidates the live binding, and keeps destructive state deletion as a separate explicit operation.
+
+## Application Roles
+
+The runtime supports two ownership roles without shipping application templates:
+
+- A standalone deterministic app owns its complete application state and transition rules. Poker-like games are the reference shape for app-owned state, not a bundled catalog entry.
+- A view/controller adapter owns only validated adapter configuration and a last-observed projection. A music-player remote is the reference shape: the Actor remains authoritative, while the Generative App samples structured status, invokes bounded controls, and renders the next view.
+
+Both roles use the same module, state, bound-action, and safety contracts. Selection and authoring procedure belong to the bundled `generative-apps` Skill.
+
+## Validation Contract
+
+Implementation is not complete until evidence covers:
+
+- Canonical path identity, direct app discovery, copy/install, explicit replacement with failure preservation, removal, and traversal rejection.
+- Mandatory `init`, named method dispatch, no-argument and strict-JSON argument parsing, missing exports, and result validation.
+- Transactional initialization, state/history equality, concurrent/stale actions, partial journal recovery, and output-only methods.
+- CML and full JSON button equivalence, inference bypass before Pi queue admission, absent-owner failure, and unchanged native callback routing.
+- Direct classic, leader, and follower target delivery with generation fencing and no model turn.
+- CLI process timeout, cancellation, output bounds, stderr diagnostics, and arbitrary-shell rejection.
+- Live-view handle retention, unchanged-frame suppression, two-second minimum, non-overlap, coalescing, Telegram backoff, deletion invalidation, message-not-found handling, and lifecycle cancellation.
+- Poker-style internal state and media-style external-state reference applications.
+
+The canonical open implementation work remains in [`../BACKLOG.md`](../BACKLOG.md). This document owns the proposed subsystem contract and its architectural boundaries.

package/docs/multi-instance-bus.md

@@ -316,7 +316,7 @@ Threaded Mode should make follower threads behave like normal Telegram instance
 | Surface                          | Leader behavior                                                                                                                                                                                                                                       | Follower requirement                                                                                                                                                                                                                                            | Routing/ownership invariant                                                                                                                                                                                                                         | Regression evidence                                                                                                       |
 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | Prompt intake                    | Thread prompt queues locally                                                                                                                                                                                                                          | Thread prompt is forwarded and queued by the owning follower                                                                                                                                                                                                    | Target ownership routes by `{ chatId, threadId }` before local handling                                                                                                                                                                             | Routing tests for foreign target message forwarding                                                                       |
-| Queued-message removal reactions | 👎/👻/💔/💩/🗑 removes pending prompt/media turn                                                                                                                                                                                                       | Same reaction on a queued follower prompt removes that follower's pending turn before dispatch                                                                                                                                                                  | When the leader forwards a prompt to a follower, it records `chatId/messageId -> follower instance` because Bot API reaction updates expose chat/message but not thread id                                                                          | Update runtime regression records forwarded message ownership and forwards the later reaction                             |
+| Queued-message removal reactions | 👎/👻/💔/💩/🗑 marks a pending prompt/media turn for deletion when it reaches dispatch                                                                                                                                                                            | Same reaction on a queued follower prompt marks that follower's pending turn for deletion before model dispatch                                                                                                                                                                  | When the leader forwards a prompt to a follower, it records `chatId/messageId -> follower instance` because Bot API reaction updates expose chat/message but not thread id                                                                          | Update runtime regression records forwarded message ownership and forwards the later reaction                             |
 | Queue priority reactions         | 👍/⚡/❤/🕊/🔥 prioritizes queued prompts                                                                                                                                                                                                               | Same reactions prioritize follower queued prompts                                                                                                                                                                                                               | Reaction forwarding uses stored message ownership, then follower mutates its local queue                                                                                                                                                            | Reaction mutation tests plus forwarded-reaction coverage                                                                  |
 | Message edits                    | Edits update matching queued prompt text                                                                                                                                                                                                              | Edits in a follower thread update that follower's queued prompt                                                                                                                                                                                                 | Message target ownership forwards edits to the owning instance; stored message ownership is the fallback when Telegram edit payloads omit thread id                                                                                                 | Update routing tests for foreign target and message-owned edited-message forwarding                                       |
 | Callbacks/buttons/menus          | Callback handled by the owning instance/menu state                                                                                                                                                                                                    | Follower callbacks are forwarded to the owning follower; follower menu sends/edits/deletes route through leader transport                                                                                                                                       | Leader records ownership for follower-sent Bot API messages so callbacks can route by message id even when Telegram omits thread id; Bot API edit/delete lacks thread id, so follower bus allows validated same-chat message operations             | Callback forwarding, generated-button target, bus follower-sent ownership, and bus edit/delete allowlist tests            |

package/docs/outbound.md

@@ -164,11 +164,11 @@ I can continue.
 
 Rules:
 
-- `telegram_button` accepts a JSON object, JSON matrix, [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted HTML-like attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}` or `{label|prompt}`, trims both atoms, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`. Shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
+- `telegram_button` accepts a JSON object, JSON matrix, [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted HTML-like attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. It trims every atom, preserves non-structural printable text, and decodes only `\|`, `\}`, and `\\`. Shorthand, body, paired-comment, unquoted-attribute, and single-quoted-attribute forms are rejected.
 - A colon after either button marker is rejected so every payload form shares one unambiguous action marker.
 - Use `label` plus `prompt`, or the compact `value` key when both strings are identical. Explicit `label` or `prompt` takes precedence over its `value` fallback. Use JSON with `\n` escapes for multiline prompts.
 - The opening marker must start at column zero on a top-level line outside fenced code, quotes, lists, and indented examples; otherwise it remains literal Markdown.
-- Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a second unescaped CML separator, and deeper nesting are rejected atomically. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
+- Prefer one matrix comment for multiple buttons. Each top-level JSON object or CML cell becomes one full-width inline-keyboard row in source order; a nested row groups one or more buttons horizontally. The parser imposes no artificial per-row width cap; empty rows, malformed cells, unknown/trailing CML escapes, a third unescaped CML separator, empty atoms, unknown selected styles, and deeper nesting are rejected atomically. Generated surfaces default to five columns and expand to six through eight only for short position-bearing labels. Repeated singular comments remain valid.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.
 - After Telegram accepts a generated button callback as a queued prompt, the bridge changes that exact button to its configured selection style without changing agent-authored text or emoji. Set `selected_style` to `primary` (blue), `success` (green), or `danger` (red); omitted or invalid values fall back to `primary`. The style never suppresses queue admission. Other choices stay visually unchanged and remain available; the callback acknowledgement remains the fallback on clients that do not render button styles.
 - When generated button markup is the entire assistant reply, the bridge supplies the standard `☑️ **Choose an option:**` heading as visible message text so Telegram has a message to which it can attach the inline keyboard.

package/docs/public-api.md

@@ -61,11 +61,12 @@ This command surface is a mobile companion subset, not a raw terminal-command br
 
 ### Tools and assistant-authored actions
 
+- `telegram_bind({ app, script, argument? } | { app, method, argument? })` installs and initializes one canonical managed Generative App module under `<agent-dir>/genapps/<app>/<app>.mjs`, or invokes one named method on an installed app. Installation rejects silent replacement and noncanonical/symlink sources. Methods receive immutable JSON state, one optional JSON argument, cancellation, revision, and a bounded non-shell process port; successful state changes commit to `state.json` plus `states.jsonl`, while output-only methods leave history unchanged. After one-shot `tgbtn` resolution, a complete `app::method` or `app::method(<strict JSON>)` prompt invokes the installed app before Pi queue admission and sends its planned Markdown/buttons directly; malformed or failed bound actions never fall back to a model prompt. Direct app-output buttons retain hidden source revisions and stale actions fail before method execution; sibling processes serialize transitions and recover dead lock owners. Bound actions send a fresh message by default and retain the clicked button's selected state on its prior surface. A result may opt into `viewMode: "edit"` to replace the callback message and keyboard in place, with one fresh-send fallback only for that explicit action. Agent-mediated initial-surface revisions, process-birth lock proof, automatic refresh, and voice output remain open.
 - `telegram_attach(paths, chat_id?, thread_id?, caption?)` is the stable artifact delivery tool for generated files. During Telegram turns it queues files for the active reply; with `assistant.rendering: "rich"`, exactly one PNG/JPEG, MP4, or MP3 artifact plus non-empty final Markdown can become one reply-anchored Rich Message. HTML mode, multiple/unsupported files, Guest Mode, and voice outputs retain their established paths. Outside Telegram turns the tool sends files directly to the paired/default chat, the registered follower's assigned thread, or an explicit `chat_id` plus optional `thread_id` when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus.
 - `telegram_message(text, chat_id?, thread_id?)` sends a direct Telegram Markdown message when this Pi instance owns `/telegram-connect` or is registered with the multi-instance bus. During an active Telegram turn, omitted targeting and an explicit target equal to that turn are rejected so the ordinary final-reply path remains the sole current-target response; an explicit different chat/thread target remains allowed for requested cross-target delivery. Outside active turns, paired/default local/TUI delivery remains unchanged. Top-level `telegram_button` comments inside `text` are parsed with the same planner used for normal replies and attached to that message; buttons are never standalone Telegram messages.
-- The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, and profile-specific debugging guidance. The regular prompt routes applicable turns to that Skill. `telegram_attach` and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
+- The bundled `telegram-bridge` Skill owns action syntax, target routing, Threaded Mode, formatting, Generative App operation, and profile-specific debugging guidance. The regular prompt routes applicable turns to that Skill. `telegram_attach`, `telegram_bind`, and `telegram_message` remain registered but are model-active only while this instance owns direct transport or holds a live follower registration; disconnect/loss suppresses their schemas and prompt metadata, and recovery restores only the operator's previously active pi-telegram subset.
 - `telegram_voice` hidden comments request Telegram-native voice delivery through either a JSON object or double-quoted attributes. Equivalent `text` or `value` supplies the spoken payload; explicit `text` takes precedence.
-- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. One marker accepts a JSON object, JSON matrix, [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted attributes; `telegram_buttons` is an exact plural alias. Top-level matrix cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}` or `{label|prompt}`, trims atom boundaries, and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.
+- `telegram_button` hidden comments create inline buttons whose taps enqueue prompts. One marker accepts a JSON object, JSON matrix, [Compact Matrix Literal](./compact-matrix-literal.md), or double-quoted attributes; `telegram_buttons` is an exact plural alias. Top-level matrix cells become full-width rows, while nested rows group one or more buttons horizontally without an artificial parser-width cap. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires a prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries and supports only the minimal escapes `\|`, `\}`, and `\\`. Prefer one matrix comment for multiple buttons. Use JSON `label` plus `prompt`, or `value` when both strings are identical. Action markers are colon-free; colon-prefixed payloads are rejected. Use top-level column-zero comments outside code, quotes, lists, and indented examples; do not emit standalone button actions.
 
 Prompt guidance is context-aware: local/TUI prompts see only explicit direct-delivery guidance, while Telegram-originated turns receive the full action-comment syntax and phone-width output contract.
 

package/docs/ui-style.md

@@ -54,7 +54,7 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 | `➡️` | Choose replacement target | Thread replace/restore target buttons that select which Pi instance should move to the current thread | Use inside the second replace/restore chooser, not for ordinary reroutes. |
 | `☑️` | Activate / choose this item | Model detail activation action, generated button-only choice heading | Positive selection cue; use `🟢 Active` for already-current state. |
 | `❌` | No / cancel | Confirmation cancel buttons | Use for safe cancellation, not destructive removal. |
-| `🗑` | Delete / suppress | Queue delete actions, destructive confirmations, suppression reaction | The explicit queue button deletes; the reaction reversibly suppresses a waiting turn. |
+| `🗑` | Delete / defer removal | Destructive confirmations and removal reaction | In the queue menu, reversible Keep/Skip selectors replace immediate deletion. |
 
 ### State Indicators And Button Grammars
 
@@ -68,7 +68,14 @@ Use emoji as stable semantic markers, not decoration. Emoji carry transportable
 
 ### Queue Reaction Shortcuts
 
-Queue reactions are shortcut controls for waiting turns. Preserve their semantics across Telegram reactions, queue-menu rows, status previews, and tests.
+Queue reactions are shortcut controls for waiting turns. Preserve their semantics across Telegram reactions, queue-menu rows, status previews, and tests. Positive emoji control the Priority/Normal lane; negative emoji control Keep/Skip. These categories are independent, may coexist, and mutate only their own dimension. Crossing lanes appends the prompt at the destination FIFO tail; changing Keep/Skip or changing emoji within one category preserves lane position. Skip wins only when dispatch reaches the prompt.
+
+Queue item detail renders two independent selector rows:
+
+- `🟡 Priority` / `⚫️ Normal` or `⚫️ Priority` / `🟣 Normal` selects the lane.
+- `🟢 Keep` / `⚫️ Skip` or `⚫️ Keep` / `🟡 Skip` selects dispatch disposition.
+
+The menu may clear internal Skip but cannot remove a reaction created by the user through Telegram's Bot API.
 
 | Emoji | Meaning | Canonical surfaces | Notes |
 | --- | --- | --- | --- |
@@ -77,11 +84,11 @@ Queue reactions are shortcut controls for waiting turns. Preserve their semantic
 | `❤` / `❤️` | Promote to priority | Queue reaction shortcut | Normalize display consistently where code normalizes reactions. |
 | `🕊` / `🕊️` | Promote to priority | Queue reaction shortcut | Soft/peaceful promotion gesture. |
 | `🔥` | Promote to priority | Queue reaction shortcut | Urgent/hot promotion gesture. |
-| `👎` | Suppress waiting turn | Queue reaction shortcut and suppressed queue badge | Suppression is reversible and is not negative feedback to the agent. |
-| `👻` | Suppress waiting turn | Queue reaction shortcut and suppressed queue badge | Disappear/suppress metaphor. |
-| `💔` | Suppress waiting turn | Queue reaction shortcut and suppressed queue badge | Reversible cancel metaphor. |
-| `💩` | Suppress waiting turn | Queue reaction shortcut and suppressed queue badge | Reversible reject metaphor. |
-| `🗑` | Suppress or explicitly delete | Queue reaction shortcut, suppressed queue badge, and queue delete UI | The reaction is reversible suppression; only the explicit queue button is destructive. |
+| `👎` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Reversible until the marked turn reaches dispatch; not negative feedback to the agent. |
+| `👻` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Disappear/remove metaphor. |
+| `💔` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Reversible cancel metaphor. |
+| `💩` | Defer removal of waiting turn | Queue reaction shortcut and queue emoji marker | Reversible reject metaphor. |
+| `🗑` | Defer removal | Queue reaction shortcut and queue emoji marker | Like Skip, the reaction remains reversible until dispatch reaches the marked turn. |
 
 ### Decorative Or Local-Example Emoji
 

package/index.ts

@@ -228,6 +228,8 @@ export default function (pi: Pi.ExtensionAPI) {
   const proactivePushChatIdGetter =
     Config.createTelegramProactivePushChatIdGetter(proactivePushTargetGetter);
   const buttonActionStore = Outbound.createTelegramButtonActionStore();
+  const planGenerativeAppOutput =
+    Outbound.createTelegramOutboundReplyPlanner(buttonActionStore);
   const pendingModelSwitchStore =
     Model.createPendingModelSwitchStore<
       Model.ScopedTelegramModel<ActivePiModel>
@@ -502,6 +504,16 @@ export default function (pi: Pi.ExtensionAPI) {
       getHandlers: configStore.getOutboundHandlers,
       recordRuntimeEvent,
     });
+  const invokeGenerativeAppBoundButtonAction =
+    Bindings.createTelegramGenerativeAppBoundButtonActionInvoker({
+      agentDir: Paths.resolveAgentDir(),
+      assertExecutionCurrent: Updates.assertTelegramUpdateExecutionCurrent,
+      getExecutionFence: Updates.getTelegramUpdateExecutionFence,
+      planOutput: planGenerativeAppOutput,
+      sendMarkdownReply,
+      editInteractiveMessage,
+      recordRuntimeEvent,
+    });
   const {
     activityRuntime,
     activityVerbosityRuntime,
@@ -760,6 +772,7 @@ export default function (pi: Pi.ExtensionAPI) {
     settingsMenuCallbackHandler: settingsMenuRuntime.handleCallbackQuery,
     sectionRegistry,
     buttonActionStore,
+    invokeBoundButtonAction: invokeGenerativeAppBoundButtonAction,
     inboundHandlerRuntime,
     threadStore,
     updateStatus,
@@ -1219,6 +1232,7 @@ export default function (pi: Pi.ExtensionAPI) {
 
   Bindings.registerTelegramCommandsAndTools({
     pi,
+    agentDir: Paths.resolveAgentDir(),
     configStore,
     persistConfig: persistTelegramConfigWithSync,
     setup,

package/lib/bindings.ts

@@ -26,6 +26,7 @@ import * as Setup from "./setup.ts";
 import * as Status from "./status.ts";
 import * as TelegramApi from "./telegram-api.ts";
 import type { TelegramTarget } from "./target.ts";
+import * as GenerativeApps from "./generative-apps.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 
@@ -53,10 +54,7 @@ export interface TelegramQueueBindingRuntime<TContext> {
 
 export function createTelegramQueueBindingRuntime<TContext>(deps: {
   store: Queue.TelegramQueueStateStore<TContext>;
-  queue: Pick<
-    Runtime.TelegramBridgeRuntime["queue"],
-    "getNextPriorityReactionOrder" | "incrementNextPriorityReactionOrder"
-  >;
+  queue: Pick<Runtime.TelegramBridgeRuntime["queue"], "allocateItemOrder">;
   lifecycle: Pick<
     Runtime.TelegramBridgeRuntime["lifecycle"],
     "isCompactionInProgress" | "hasDispatchPending"
@@ -95,9 +93,7 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
 }): TelegramQueueBindingRuntime<TContext> {
   const mutation = Queue.createTelegramQueueMutationController({
     ...deps.store,
-    getNextPriorityReactionOrder: deps.queue.getNextPriorityReactionOrder,
-    incrementNextPriorityReactionOrder:
-      deps.queue.incrementNextPriorityReactionOrder,
+    allocateLaneOrder: deps.queue.allocateItemOrder,
     onItemsDiscarded(items, ctx) {
       deps.admission.getSettlement()?.onItemsDiscarded(items, ctx);
     },
@@ -146,6 +142,108 @@ export function createTelegramQueueBindingRuntime<TContext>(deps: {
   };
 }
 
+export function createTelegramGenerativeAppBoundButtonActionInvoker<
+  TQuery extends {
+    message?: { chat?: { id?: number }; message_id?: number };
+  },
+>(deps: {
+  agentDir: string;
+  assertExecutionCurrent: (query: TQuery) => void;
+  getExecutionFence: (query: TQuery) => GenerativeApps.GenerativeAppExecutionFence | undefined;
+  planOutput: ReturnType<typeof OutboundHandlers.createTelegramOutboundReplyPlanner>;
+  sendMarkdownReply: (
+    chatId: number,
+    replyToMessageId: number,
+    markdown: string,
+    options?: { replyMarkup?: OutboundHandlers.TelegramOutboundButtonMarkup },
+  ) => Promise<unknown>;
+  editInteractiveMessage?: (
+    chatId: number,
+    messageId: number,
+    markdown: string,
+    mode: "markdown",
+    replyMarkup: OutboundHandlers.TelegramOutboundButtonMarkup,
+  ) => Promise<void>;
+  recordRuntimeEvent: TelegramRuntimeEventRecorder;
+}): (
+  action: OutboundHandlers.TelegramOutboundButtonAction,
+  query: TQuery,
+) => Promise<false | "new" | "edit"> {
+  return async (action, query) => {
+    let boundAction: GenerativeApps.GenerativeAppBoundAction | undefined;
+    try {
+      boundAction = GenerativeApps.parseGenerativeAppBoundAction(action.prompt);
+      if (!boundAction) return false;
+      deps.assertExecutionCurrent(query);
+      const result = await GenerativeApps.invokeGenerativeApp({
+        agentDir: deps.agentDir,
+        ...(deps.getExecutionFence(query)
+          ? { execution: deps.getExecutionFence(query) }
+          : {}),
+        ...(boundAction.argument !== undefined
+          ? { argument: boundAction.argument }
+          : {}),
+        ...(action.binding?.app === boundAction.app
+          ? {
+              expectedGeneration: action.binding.generation,
+              expectedRevision: action.binding.revision,
+            }
+          : {}),
+        method: boundAction.method,
+        app: boundAction.app,
+      });
+      deps.assertExecutionCurrent(query);
+      const chatId = query.message?.chat?.id;
+      const messageId = query.message?.message_id;
+      if (typeof chatId !== "number" || typeof messageId !== "number") {
+        throw new Error("Generative App callback target is unavailable.");
+      }
+      const reply = deps.planOutput(result.output, {
+        binding: {
+          generation: result.generation,
+          app: result.app,
+          revision: result.revision,
+        },
+      });
+      if (result.viewMode === "edit" && deps.editInteractiveMessage) {
+        let editFailed = false;
+        try {
+          await deps.editInteractiveMessage(
+            chatId,
+            messageId,
+            reply.markdown,
+            "markdown",
+            reply.replyMarkup ?? { inline_keyboard: [] },
+          );
+        } catch (error) {
+          editFailed = true;
+          deps.recordRuntimeEvent("generative-app", error, {
+            phase: "bound-action-edit-fallback",
+            app: boundAction.app,
+            method: boundAction.method,
+          });
+        }
+        deps.assertExecutionCurrent(query);
+        if (!editFailed) return "edit";
+      }
+      deps.assertExecutionCurrent(query);
+      await deps.sendMarkdownReply(chatId, messageId, reply.markdown, {
+        replyMarkup: reply.replyMarkup,
+      });
+      deps.assertExecutionCurrent(query);
+      return "new";
+    } catch (error) {
+      deps.recordRuntimeEvent("generative-app", error, {
+        phase: "bound-action",
+        ...(boundAction
+          ? { app: boundAction.app, method: boundAction.method }
+          : {}),
+      });
+      throw error;
+    }
+  };
+}
+
 export interface TelegramAgentMessageToolRoutingRuntime {
   resolveAgentTarget: TelegramAgentTargetResolver;
   routeAgentMessage: TelegramAgentMessageRouter;
@@ -331,6 +429,7 @@ export function createTelegramActivityBindingRuntime<TTransportStamp>(deps: {
 
 interface TelegramCommandsAndToolsBindingDeps {
   pi: Pi.ExtensionAPI;
+  agentDir: string;
   configStore: Config.TelegramConfigStore;
   persistConfig: (config?: Config.TelegramConfig) => Promise<void>;
   setup: Setup.TelegramSetupGuard;
@@ -348,7 +447,10 @@ interface TelegramCommandsAndToolsBindingDeps {
     chatId: number,
     replyToMessageId: number | undefined,
     markdown: string,
-    options?: { replyMarkup?: unknown },
+    options?: {
+      replyMarkup?: unknown;
+      target?: { chatId: number; threadId?: number };
+    },
   ) => Promise<number | undefined>;
   callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
   getDefaultChatId: () => number | undefined;
@@ -362,6 +464,7 @@ interface TelegramCommandsAndToolsBindingDeps {
 
 export function registerTelegramCommandsAndTools({
   pi,
+  agentDir,
   configStore,
   persistConfig,
   setup,
@@ -383,6 +486,13 @@ export function registerTelegramCommandsAndTools({
   recordRuntimeEvent,
   updateStatus,
 }: TelegramCommandsAndToolsBindingDeps): void {
+  GenerativeApps.registerTelegramBindTool(pi, {
+    agentDir,
+    getActiveTurn: activeTurnRuntime.get,
+    planOutput: OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore),
+    sendMarkdownReply,
+    recordRuntimeEvent,
+  });
   OutboundAttachments.registerTelegramOutboundAttachmentTool(pi, {
     getActiveTurn: activeTurnRuntime.get,
     getDefaultChatId,