@llblab/pi-telegram 0.35.2 → 0.36.1

package/skills/generative-apps/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: generative-apps
+description: Design, author, review, install, replace, invoke, or debug reusable Generative Apps that combine generated button interfaces, deterministic bound methods, and optional model-mediated prompts. Use for standalone applications and bounded view/controller adapters rendered through pi-telegram; prefer Generated Control Surface when no reusable deterministic program is earned.
+---
+
+# Generative Apps
+
+## Concept
+
+A Generative App is a reusable application authored by the model for a concrete task. It combines persistent state, named methods, textual output, and a generated button interface. The model acts primarily as author/compiler; the installed program then renders evolving views and executes routine transitions without requiring inference on every click.
+
+```text
+intent → model authors app → reusable state + methods + generated views
+```
+
+One surface may deliberately mix two action planes:
+
+```text
+bound method  → deterministic local transition
+ordinary prompt → model interpretation, explanation, teaching, or adaptation
+```
+
+This is broader than one Telegram implementation. Telegram is the first renderer; a future TUI or web renderer may reuse the concept once a second implementation proves the common contract. Keep renderer-specific wire and lifecycle details with the owning runtime.
+
+Generative Apps complement `generated-control-surface`:
+
+```text
+Generated Control Surface → current context → model → one ephemeral surface
+Generative App             → model → reusable program → many evolving surfaces
+```
+
+Both Skills use the same logical button matrix and `label + prompt` interaction model. The Telegram runtime owns its full JSON/CML notation and callback routing; this Skill owns reusable program judgment, while `generated-control-surface` owns ephemeral agent-authored composition. Shared rendering needs no third button Skill and does not collapse those responsibilities.
+
+An app may mix deterministic `app::method` controls and ordinary prompts in one view. Compile only the stable transitions that benefit from inference bypass; keep explanation, interpretation, teaching, and adaptation on the model-mediated plane. When no reusable state or deterministic loop earns a script, load and use `generated-control-surface` instead.
+
+The `generated` / `generative` distinction is intentional. Do not rename `generated-control-surface` to a competing generative term.
+
+## Ownership
+
+This Skill owns agent operating judgment:
+
+- Whether a Generative App is warranted.
+- Standalone versus adapter selection.
+- Authoring and capability review.
+- Install, replace, invoke, and validation workflow.
+- Safety boundaries and stop decisions.
+
+This Skill also owns the transport-independent concept, vocabulary, application shapes, hybrid action model, and relationship to Generated Control Surface.
+
+[`../../docs/generative-apps.md`](../../docs/generative-apps.md) owns only the concrete `pi-telegram` runtime reference: Telegram wire syntax, managed layout, executable ABI, state timeline, generation/revision fencing, worker execution, locking, installation transactions, callback routing, lifecycle behavior, and current limitations. Do not duplicate those implementation details here.
+
+## When To Use
+
+Use a Generative App when:
+
+- Interaction repeats or contains several stable transitions.
+- State and valid actions fit a small auditable contract.
+- Direct methods materially improve latency, cost, reliability, or UX.
+- Model judgment remains optional rather than required for every action.
+- One clear owner exists for application or external domain state.
+
+Prefer `generated-control-surface` for one-shot, interpretive, rapidly changing, or wholly model-mediated interaction. Do not create decorative apps, generic remote terminals, arbitrary command runners, or deterministic facades over ambiguous high-impact decisions.
+
+## Choose The Shape
+
+### Standalone deterministic application
+
+The app owns a closed state machine such as a game, form, selector, simulation, or compact workflow. Its state must reconstruct the current view and explain the previous transition.
+
+### View/controller adapter
+
+Another capability remains the authoritative real owner. The app stores validated adapter configuration and a last-observed projection only. Re-read the owner before mutation or explicit status; never promote cached view state into domain authority.
+
+## Authoring Workflow
+
+1. Identify the repeated feedback loop, real state owner, and actions that are truly deterministic.
+2. Choose one stable lowercase app and one self-contained `<app>.mjs` source outside the managed installation directory.
+3. Keep `init` and every exported method small, named, bounded, shell-free, and capability-specific.
+4. Render one complete next view after each action.
+5. Mix action planes intentionally:
+
+```text
+app::method(argument) → bounded method without a model turn
+ordinary prompt          → model-mediated interpretation or explanation
+```
+
+6. Review state fields, arguments, process calls, rendered values, secrets, destructive effects, and failure paths.
+7. Install with `telegram_bind({ app, script, argument })`.
+8. Replace the same logical app only with explicit `replace: true`; never create `-v2` identities merely to reload code.
+9. Invoke read-only diagnostics with `telegram_bind({ app, method, argument, display: false })` when agent-side evidence is needed.
+10. Keep the maintained source with its capability owner; managed `genapps/` state is runtime installation, not source ownership.
+
+## Safety Rules
+
+- A direct click authorizes only its exact installed method and validated JSON argument.
+- Use exact executable plus argv through the bounded process port; never expose generic `exec` or shell text.
+- Keep credentials and unrelated private state out of source, state, output, and diagnostics.
+- Route consequences requiring contextual judgment through an ordinary model prompt.
+- Fail closed on unavailable owners, stale actions, malformed state, absent methods, process failures, or uncertain effects.
+- Do not claim automatic refresh, removal, voice output, or other behavior still marked incomplete in the runtime document.
+
+## Validation
+
+Before presenting an app as working:
+
+- Confirm app, source stem, installed identity, and bound prompts agree.
+- Inspect the installed initial view and persisted bounded state.
+- Exercise at least one real bound action and prove it bypasses Pi queue/model admission.
+- Exercise at least one ordinary prompt when the app intentionally uses the model plane.
+- Verify replacement rejects stale buttons and failed initialization preserves the prior app.
+- For adapters, prove fresh external status and terminal mutation evidence.
+- Confirm failures are bounded, redacted, and do not silently render success.
+
+Stop and return to ordinary model interaction when the workflow cannot be represented safely as reviewed bounded methods plus explicit model prompts.

package/skills/telegram-bridge/SKILL.md

@@ -46,7 +46,9 @@ 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.
+Before compiling assistant-authored controls, inspect already-loaded capability guidance for an advertised maintained Generative App or view/controller adapter. When that owner-provided view exists and the current intent concerns repeated interaction, load and follow the bundled `generative-apps` Skill and prefer binding or invoking the existing app over synthesizing one-shot prompt buttons. This is a routing breadcrumb, not permission for the bridge to discover capability-specific apps, own their state, or hard-code their identities.
+
+Otherwise, 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.
 
@@ -60,7 +62,7 @@ Button forms:
 <!-- telegram_button [{⬆️ Up|/}[{⬅️|page-1}{➡️|page-3}]{📁 etc|/etc}] -->
 ```
 
-- `telegram_button` accepts one JSON object, a JSON matrix, Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. CML uses `{value}` or `{label|prompt}`, trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
+- `telegram_button` accepts one JSON object, an adaptive JSON/CML matrix, positional Compact Matrix Literal (CML), or double-quoted attributes; `telegram_buttons` is an exact plural alias. One matrix or row may mix named JSON objects with positional cells, and commas are optional only between completed elements while JSON object internals remain strict. CML uses `{value}`, `{label|prompt}`, or `{label|prompt|selected_style}`; the optional third atom requires an explicit prompt and accepts only `primary`, `success`, or `danger`. It trims atom boundaries, preserves other printable text literally, and decodes only `\|`, `\}`, and `\\`. Prefer CML for model-authored controls whenever it can express the required surface; use expanded JSON only for multiline prompts, non-positional metadata, or a concrete parse/render failure fallback, never merely from implementation habit. Deterministic Generative App scripts may use ordinary JSON because their output does not spend model tokens. In a matrix, each top-level cell becomes a full-width row and each nested row groups one or more buttons horizontally without a parser-level width cap. Prefer one matrix comment for multiple buttons, normally keep generated rows at five columns or fewer, and use six through eight only for short position-bearing labels. Keep the complete action in one top-level comment and encode multiline content with JSON `\n`.
 - Use `label` plus a self-contained `prompt`, or non-empty `value` when both are identical.
 - Optional `selected_style` is `primary` (default), `success`, or `danger`; style never suppresses prompt admission.
 - If button comments form the whole reply, the bridge supplies the standard choice heading.
@@ -102,6 +104,10 @@ Threaded Mode operates in private chats when Telegram exposes thread support for
 
 Cross-Thread delivery must preserve the concrete target and current registration authority. Use ordinary reply delivery for the source turn and `telegram_message(thread=...)` only for an explicitly requested different live Thread.
 
+## Generative Apps
+
+Load and follow the bundled `generative-apps` Skill when work designs, authors, reviews, installs, replaces, invokes, or diagnoses a Generative App. Generative Apps compile stable repeated interaction into generated button views that may mix bound methods executed before Pi queue admission with ordinary model prompts; this bridge Skill continues to own Telegram transport, target authority, delivery, general button syntax, and turn behavior rather than duplicating the application workflow.
+
 ## Configurable Handlers And Extensions
 
 Prefer no-code command-template configuration in `telegram.json` before adding a companion extension: