@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-telegram/docs/command-templates.md

@@ -0,0 +1,365 @@
+# Command Template Standard
+
+Command templates are the portable integration format for deterministic local automation.
+
+**Meta-contract:** transportable (bit-for-bit identical across projects), high-density (zero fluff), constant (evolve by crystallizing, not speculating), optimal minimum (add only when it hurts).
+
+**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, optional timeout, delay-before-start, bounded retry, failure propagation, recover cleanup, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
+
+---
+
+Extensions may choose their own config files, selectors, placeholder sources, and examples, but should preserve this core contract.
+
+Layer boundary: command templates own only the synchronous execution graph. Recipe imports, import-reference expressions, recipe lookup, `async: true`, run ids, state dirs, FIFO controls, and outbox events are host/recipe/async-run configuration layers, not portable command-template syntax.
+
+## Shape
+
+A command template is either a command-line string or an ordered array of command-template leaves:
+
+```json
+{
+  "template": "/path/to/stt --file {file} --lang {lang=ru}"
+}
+```
+
+When the surrounding schema already implies a command template, the compact string form is equivalent:
+
+```json
+"/path/to/stt --file {file} --lang {lang=ru}"
+```
+
+There is no portable `command` field. The command is derived from `template`: after splitting, the first word is the executable and the remaining words are argv args. Templates do not infer flags: `{file}` is one positional arg; `--file {file}` is a flag arg plus its value.
+
+Common object fields:
+
+- `label`: Optional human label for diagnostics and parallel branch reports.
+- `parallel`: Optional boolean execution flag for array templates. Default is sequential execution; `true` runs children concurrently when the host execution layer supports branch fanout.
+- `when`: Optional boolean or condition string. Falsy values skip the node. String forms may reference a flag name, `!flag`, or a placeholder expression such as `{flag?yes:}`.
+- `args`: Optional placeholder declarations. Untyped names remain valid; compact typed forms such as `file:path`, `timeout:int`, `speed:number`, `dry_run:bool`, `prompts:array`, and `mode:enum(check,fix)` are valid when the host supports typed tool schemas. Defaults belong in `defaults` or inline placeholder defaults; hosts may normalize interactive shorthand such as `timeout:int=60000` before persistence.
+- `defaults`: Placeholder default values by name.
+- `timeout`: Optional execution timeout in milliseconds, as a number or placeholder-resolved string. Omit it, or set `0`, to leave the command unbounded. Set an explicit positive timeout when a tool must fail closed instead of waiting indefinitely.
+- `delay`: Optional wait in milliseconds before starting this node, as a number or placeholder-resolved string. Default is no delay.
+- `output`: Optional result selector. Default is `"stdout"`; runtime values such as `"ogg"` are valid.
+- `retry`: Optional max attempts including the first, as a number or placeholder-resolved string. Default is `1`.
+- `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
+- `recover`: Optional command template run between failed retry attempts. Recovery output is ignored; recovery failure stops retries.
+- `template`: Required command string or ordered composition array.
+
+For object form, write `template` last. Read the node flags first, then the executable content. Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
+
+## Execution
+
+A runtime must:
+
+1. Split the template into shell-like words with simple single quotes, double quotes, and backslash escapes
+2. Substitute placeholders inside each split word
+3. Execute command + args directly, without shell evaluation
+4. Treat exit code `0` as success and non-zero as failure
+5. Use stdout as the default result channel and stderr only for diagnostics
+
+Implementations may expand `~` in command position and may resolve relative command paths against the caller cwd.
+
+## Placeholders
+
+Supported forms:
+
+| Form | Meaning |
+| --- | --- |
+| `{name}` | Required value from runtime values or `defaults` |
+| `{name=default}` | Inline default when no value is provided |
+| `{items[index]}` | Array item selected by literal or repeat index |
+| `{value??fallback}` | Fallback when the value is absent or falsy |
+| `{flag?yes:no}` | Conditional text selected by flag truthiness |
+
+Resolution order is runtime values → `defaults` → inline default → error. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
+
+```json
+{
+  "template": "/path/to/tts --text {text} --lang {lang=ru} --rate {rate=+30%}"
+}
+```
+
+With runtime values `{ "text": "hello" }`, argv is:
+
+```text
+["--text", "hello", "--lang", "ru", "--rate", "+30%"]
+```
+
+Use `defaults` for visible configuration data; use inline defaults for compact local literals. Prefer flag-style examples such as `/path/to/tool --file {file} --lang {lang=ru}` for readability, but positional forms such as `/path/to/tool {file} {lang=ru}` are valid when the invoked script defines that CLI contract.
+
+Typed declarations annotate the public tool interface, not the shell command. They may live in `args` or inline placeholders such as `{timeout:int=60000}` and `{mode:enum(check,fix)=check}`. Use metadata-first authoring (`args` plus `defaults`) when long templates should stay visually short; use inline-first authoring when one self-contained `template` property is clearer. They do not sandbox or reinterpret the executable; they only let the host generate narrower input schemas and normalize runtime values before placeholder substitution. Untyped `args` and untyped placeholders continue to work unchanged.
+
+## Quoting
+
+Placeholder values are not shell-escaped because no shell is used. A value containing spaces remains one argv item when it replaces one split word:
+
+```text
+template="echo {text}"
+text="hello world"
+args=["hello world"]
+```
+
+A placeholder may also be embedded inside one word:
+
+```text
+template="/path/to/tool --file={file}"
+file="/tmp/a b.ogg"
+args=["--file=/tmp/a b.ogg"]
+```
+
+Use quotes only for literal template words that should contain spaces before placeholder substitution:
+
+```text
+template="echo 'literal words' {text}"
+```
+
+## Composition
+
+`template: [...]` means sequential composition by default; each leaf is a command template executed with one shared runtime value map:
+
+```json
+{
+  "template": [
+    "/path/to/tts --text {text} --lang {lang=ru} --out {mp3}",
+    "ffmpeg -y -i {mp3} -c:a libopus {ogg}"
+  ],
+  "output": "ogg"
+}
+```
+
+Composition rules:
+
+- Execute leaves in order by default
+- Execute child templates concurrently when `parallel` is `true`
+- Parallel composition uses soft-quorum semantics by default: failed children are reported as degraded branches unless failure propagation escalates
+- Non-critical failures are recorded and execution continues, while `failure: "branch"` stops the current branch and `failure: "root"` aborts the root composition
+- Treat the whole composition as one handler for selector matching and fallback
+- Top-level `args` and `defaults` apply to every leaf unless the leaf defines private values
+- Leaf `args` replace inherited `args`; leaf `defaults` merge over inherited defaults; `timeout` and `output` are not inherited into leaves
+- Timeout is disabled by default; configure a positive `timeout` for bounded commands that should fail closed
+- Each sequence leaf receives the previous leaf's stdout on stdin by default, while the final leaf stdout remains the default composition result
+- Each parallel child receives the same stdin, and child stdout values are joined in stable array order before flowing to the next sequence leaf
+- Parallel branch joins include branch label and status, and tool details include branch metadata plus coverage summary
+- Each leaf still applies its own inline defaults
+
+```json
+{
+  "template": [
+    "/path/to/tts --text {text} --lang {lang} --out {mp3}",
+    {
+      "defaults": { "codec": "libopus" },
+      "template": "ffmpeg -y -i {mp3} -c:a {codec} {ogg}"
+    }
+  ],
+  "args": ["text", "lang", "mp3", "ogg"],
+  "defaults": { "lang": "en" },
+  "output": "ogg"
+}
+```
+
+`output` selects the primary result channel. Omitted `output` means `"stdout"`, and explicitly writing `"output": "stdout"` is valid standard syntax. Artifact-producing handlers may instead name a runtime value or placeholder path, e.g. `"ogg"` or `"{ogg}"`.
+
+### Repeat
+
+`repeat` expands one command-template node N times before execution. It works with both sequence and parallel nodes and is useful when many branches differ only by a number.
+
+```json
+{
+  "parallel": true,
+  "repeat": 8,
+  "template": "render page{_(index+1)}.html --prev page{_(prev+1)}.html --next page{_(next+1)}.html --zero page{_index}.html"
+}
+```
+
+Reserved repeat placeholders are injected into each repeated node:
+
+- `{index}`: current zero-based index, `0..repeat-1`
+- `{prev}` / `{next}`: wrapped zero-based neighbors
+- `{repeat}`: total repeat count
+
+Human 1-based numbering is intentionally expressed as limited arithmetic: `{index+1}`, `{prev+1}`, `{next+1}`.
+
+Leading underscores on repeat placeholders request zero padding. One underscore means width 2, two underscores mean width 3, and so on:
+
+```text
+{_index}      → 00, 01, ...
+{_(index+1)}  → 01, 02, ...
+{__(index+1)} → 001, 002, ...
+{_(prev+1)}   → wrapped previous page number, padded to width 2
+{_(next+1)}   → wrapped next page number, padded to width 2
+```
+
+Repeat expressions support only integers, `index`, `prev`, `next`, `repeat`, parentheses, and `+`, `-`, `*`, `/`, `%`. They are not JavaScript and cannot call functions or access properties.
+
+Repeat placeholders are local generated values. Call-time args should not use these reserved names to override the repeat index.
+
+Parallel nodes use the same object shape. Flags come first and `template` stays last:
+
+```json
+{
+  "template": [
+    "prepare {out_dir}",
+    {
+      "parallel": true,
+      "template": [
+        {
+          "label": "gpt-5.5",
+          "timeout": 300000,
+          "template": "review-gpt {scope}"
+        },
+        {
+          "label": "deepseek-pro",
+          "timeout": 300000,
+          "template": "review-deepseek {scope}"
+        },
+        {
+          "label": "kimi",
+          "timeout": 300000,
+          "template": "review-kimi {scope}"
+        }
+      ]
+    },
+    "merge {out_dir}"
+  ]
+}
+```
+
+A degraded parallel join is still usable when at least one branch succeeds:
+
+```text
+--- branch: gpt-5.5 status: done ---
+review text
+--- branch: deepseek-pro status: failed ---
+exit: 1
+stderr: provider balance exhausted
+```
+
+Use `template: [...]` for ordered composition. Older local `pipe` aliases are not part of the 0.13.0 command-template standard.
+
+## Fail-Open Default Policy
+
+By default, composition continues on failure: the failed step is logged and the next step executes. This is analogous to `make -k` — the user sees all failures at once and decides what to fix.
+
+## Failure Propagation
+
+By default, failed steps use `failure: "continue"`: record the failure, clear stdout for that step, and continue the current sequence. This preserves the fail-open profile.
+
+Use `failure` when a node should stop more aggressively:
+
+- `"continue"`: record the failure and continue the current sequence.
+- `"branch"`: stop the current sequence/subtree and return a failed branch to the nearest parent. In a parallel node, sibling branches keep running and the join becomes degraded. At the root, branch failure is still a tool failure.
+- `"root"`: abort the outermost composition.
+
+```json
+{
+  "parallel": true,
+  "template": [
+    {
+      "label": "agent-a",
+      "failure": "branch",
+      "template": [
+        "agent-a-work {scope}",
+        "agent-a-validate {scope}",
+        "agent-a-push {scope}"
+      ]
+    },
+    {
+      "label": "agent-b",
+      "failure": "branch",
+      "template": [
+        "agent-b-work {scope}",
+        "agent-b-validate {scope}",
+        "agent-b-push {scope}"
+      ]
+    }
+  ]
+}
+```
+
+If `agent-a-validate` fails, `agent-a-push` is skipped, `agent-b` can still finish, and the parallel join reports degraded branch coverage.
+
+Use `failure: "root"` to abort the root composition. Older local `critical: true` shapes are not part of the 0.13.0 command-template standard.
+
+## Retry
+
+Set `retry: N` to attempt execution up to `N` times including the first. The first successful attempt stops the retry loop.
+
+On leaf commands, retry repeats that command. On sequence or parallel nodes, retry repeats the whole node. A retried group only retries when the group returns a failure, so validator checkpoints normally pair group retry with `failure: "branch"` or `failure: "root"`.
+
+```json
+{
+  "failure": "branch",
+  "retry": 3,
+  "template": ["implement {scope}", "npm test", "git diff --check"]
+}
+```
+
+Here the whole group runs again when a validator fails. Without `failure: "branch"`, the failed validator would be logged and the group would continue by default.
+
+## Recover
+
+Set `recover` on a retried node to run cleanup after a failed attempt and before the next attempt. `recover` is another command template: it can be a string command, sequence, or mode tree. Its output is ignored and the next retry receives the original stdin.
+
+```json
+{
+  "failure": "branch",
+  "retry": 3,
+  "recover": "git -C {work_dir} reset --hard HEAD",
+  "template": ["pi -p --tools read,edit,bash {scope_file}", "npm test"]
+}
+```
+
+`recover` is not a fallback success path. It is cleanup between attempts. Practical uses include resetting a worktree, removing temp files, clearing generated output, releasing a local lock, or stopping a helper process before trying the node again. If recovery fails, retries stop and the recovery failure is returned. Recovery uses fail-closed semantics by default; set an explicit `failure` inside a recover template only when a softer cleanup failure is intentional.
+
+## Delay
+
+Set `delay` to wait before starting a node. The value is milliseconds. Delay is not inherited into child nodes, just like `timeout`.
+
+```json
+{
+  "template": [
+    "prepare {scope}",
+    { "delay": 1000, "template": "review {scope}" }
+  ]
+}
+```
+
+On a sequence node, `delay` waits before the sequence begins. On a parallel node, `delay` waits before launching its children. On a branch, `delay` waits before that branch starts, without blocking sibling branches.
+
+Use `delay` only for explicit backoff, rate pacing, or staged launch. Do not use it as a scheduler.
+
+## Progressive Disclosure
+
+The standard uses a single `template` field that grows with the user's needs:
+
+```text
+string           → leaf command
+string[]         → sequential composition
+{ template }     → leaf command object
+{ parallel, template } → parallel subtree
+{ parallel, when, args, defaults, delay, retry, failure, recover, output, template } → full node
+```
+
+Start with a string. Add composition when needed. Add `parallel: true` when independent work can run concurrently. Add `when` for conditional nodes. Add delay when launch pacing matters. Add retry when flaky. Add `failure` when propagation scope matters. Add `recover` when a retried node needs cleanup before another attempt. Same contract, growing capability, no dead weight.
+
+`parallel: true` is the synchronous fanout shape. Saved JSON recipes and detached lifecycle concerns such as logs, cancellation, and durable state belong to host-specific recipe/async-run standards, not to command templates.
+
+## Trust Boundary
+
+Command templates avoid shell interpolation by splitting the template into argv first and substituting placeholders per arg. A placeholder value containing spaces remains one argv value, not a shell fragment.
+
+This is not a sandbox. The executable still runs with the same user permissions as the host agent. Shells, interpreter eval modes, destructive filesystem commands, and local scripts remain trusted code. Examples that deserve extra operator attention:
+
+- `bash`, `sh`, `zsh`, or `fish`, especially with `-c`.
+- `node -e`, `python -c`, `ruby -e`, `perl -e`, or similar eval modes.
+- `rm`, `mv`, `cp`, or `rsync` over broad paths or placeholder-derived paths.
+
+Hosts may surface lightweight warnings for these obvious high-risk shapes. Warnings should inform review without blocking existing tools, because many trusted local wrappers intentionally use shells or filesystem mutation.
+
+## Tool Boundary
+
+Agent tools are a separate abstraction. A tool name is not a portable command template because the pi extension API exposes tool registration metadata, not a public extension-to-extension `executeTool(name, args)` contract. Until such an API exists, extensions should use command templates for deterministic local automation.
+
+## Compatibility
+
+Consumers should share this contract, not private registry fields or implementation details from any specific extension.

package/node_modules/@llblab/pi-telegram/docs/compact-matrix-literal.md

@@ -0,0 +1,176 @@
+# Adaptive Button Literal
+
+> Status: Portable CML v3 standard implemented by the unreleased `pi-telegram` control-surface parser.
+
+Adaptive Button Literal is one bounded-depth matrix grammar over a shared button AST. It accepts strict JSON button objects, positional Compact Matrix Literal (CML) cells, or both in the same matrix and row. Commas between completed matrix or row elements are optional, so producers can progressively compress representation without changing runtime meaning.
+
+```text
+full named JSON → comma-optional adjacency → mixed named/positional cells → compact CML
+```
+
+The compact form is not JSON: `{label|prompt|variant}` assigns meaning by position. The formats share semantics and topology, not syntax.
+
+## Goals
+
+- Preserve one ordered button matrix across multiple representation densities.
+- Let producers compress individual cells without converting the whole surface.
+- Preserve valid strict JSON behavior unchanged.
+- Admit deterministic linear-time parsing without evaluation or partial recovery.
+- Keep rendering, callback ownership, and application state outside the notation.
+
+## Data Model
+
+Every accepted payload normalizes to a non-empty ordered list of non-empty rows:
+
+```text
+Cell = { label?: string, prompt?: string, value?: string, selected_style?: string }
+Rows = Cell[][]
+```
+
+A top-level cell becomes a singleton row. A nested row preserves horizontal grouping.
+
+These representations are semantically equivalent:
+
+```text
+[[{"label":"Pause","prompt":"music::pause"},{"value":"Next"}],{"value":"Status"}]
+[[{"label":"Pause","prompt":"music::pause"}{"value":"Next"}]{"value":"Status"}]
+[[{"label":"Pause","prompt":"music::pause"},{Next}],{Status}]
+[[{Pause|music::pause}{Next}]{Status}]
+```
+
+Named JSON objects and positional cells may coexist within the same horizontal row:
+
+```text
+[[{"label":"Open","prompt":"/tmp"}{Back|/}]]
+```
+
+## Positional Cells
+
+A one-atom cell copies its value into label and prompt through the existing button contract:
+
+```text
+{Next}
+```
+
+A two-atom cell separates label and prompt:
+
+```text
+{Pause|music::pause}
+```
+
+A three-atom cell adds the selected style:
+
+```text
+{Stop|music::stop|danger}
+```
+
+The style atom is accepted only as `primary`, `success`, or `danger`.
+
+## Adaptive Grammar
+
+The structural grammar is:
+
+```text
+payload         := json-object | matrix | positional-cell
+matrix          := "[" ws element (boundary element)* ws "]"
+element         := cell | row
+row             := "[" ws cell (boundary cell)* ws "]"
+cell            := json-object | positional-cell
+boundary        := ws [","] ws
+positional-cell := "{" atom "}"
+                 | "{" atom "|" atom "}"
+                 | "{" atom "|" atom "|" atom "}"
+atom            := atom-unit+
+atom-unit       := ordinary | "\|" | "\}" | "\\"
+ws              := *(SP | HTAB | CR | LF)
+```
+
+`boundary` occurs only after one complete element and before another. It may contain one comma or no comma. Element delimiters make empty adjacency unambiguous. Leading, repeated, and trailing commas are invalid.
+
+A `json-object` is one complete strict JSON object. Its property commas, strings, escaping, nested values, and other internals remain ordinary strict JSON; comma optionality applies only between matrix or row elements.
+
+Rows cannot contain rows. The grammar never recurses beyond one row inside the top-level matrix.
+
+## Atoms, Whitespace, And Escapes
+
+Leading and trailing whitespace in positional atoms is trimmed. Internal ordinary spaces are preserved. CR, LF, HTAB, C0 controls, DEL, and C1 controls remaining inside an atom after trimming are invalid.
+
+Only three positional-cell escapes exist:
+
+```text
+\|  → literal |
+\}  → literal }
+\\  → literal \
+```
+
+Every other printable character is literal inside a positional cell, including commas, colons, quotes, square brackets, emoji, and ordinary spaces. A comma inside `{label|prompt}` is data; a comma after the closing `}` is an optional element separator.
+
+## Deterministic Parsing
+
+A conforming parser:
+
+1. Attempts strict JSON first for sources beginning with `{` or `[`. Successful JSON is validated only against the existing button matrix schema and never reinterpreted.
+2. If strict JSON parsing fails, parses the original source with the adaptive grammar.
+3. Tries one complete strict JSON object at each cell boundary before positional interpretation.
+4. Accepts at most one optional comma between completed matrix or row elements.
+5. Rejects leading, repeated, trailing, or property-level omitted commas.
+6. Rejects empty atoms, matrices, rows, and nesting deeper than one row.
+7. Decodes only `\|`, `\}`, and `\\` in positional cells.
+8. Consumes exactly one complete payload and rejects trailing content.
+9. Returns no partial rows or cells after any failure.
+10. Runs in linear time over a host-bounded payload with fixed grammar depth.
+
+Malformed JSON-looking input receives no generic recovery. It is accepted only if it independently forms a complete valid adaptive literal.
+
+## Telegram Profile
+
+For `telegram_button` and the exact `telegram_buttons` alias:
+
+- JSON `value` keeps its existing label/prompt fallback semantics.
+- Positional `{value}` is equivalent to JSON `{"value":"value"}`.
+- Positional `{label|prompt}` is equivalent to JSON `{"label":"label","prompt":"prompt"}`.
+- Positional `{label|prompt|selected_style}` is equivalent to the corresponding three-field JSON object.
+- Top-level cells become full-width rows.
+- Nested rows become horizontal keyboard rows.
+- Invalid payloads are stripped with their recognized action comment and register no callbacks.
+
+Example:
+
+```html
+<!-- telegram_button [{⬆️ Up|/},[{⬅️|page-1}{➡️|page-3}],{"label":"📁 etc","prompt":"/etc"}] -->
+```
+
+The enclosing HTML-comment transport owns its own delimiter boundary. Content containing the comment terminator must use another supported representation.
+
+## Width Policy
+
+The grammar imposes no visual row-width maximum. Renderer and interaction policy own width. The bundled Generated Control Surface Skill defaults to at most five short position-bearing controls per row, permits six to eight only when labels remain compact, and treats eight as the phone-width UX maximum.
+
+## Conformance
+
+Accepted classes include:
+
+- Strict JSON objects and matrices.
+- Positional singleton, two-atom, and styled cells.
+- Matrices and rows with commas, without commas, or a mixture of boundaries.
+- Named JSON and positional cells mixed in one matrix or row.
+- Literal commas inside positional atoms and strict JSON strings.
+- Unicode, defined escapes, structural whitespace, and rows at supported renderer widths.
+- Semantic equivalence across every progressive-compression step.
+
+Rejected classes include:
+
+- Empty payloads, matrices, rows, labels, prompts, or style atoms.
+- Leading, repeated, or trailing element commas.
+- Missing commas between properties inside a JSON object.
+- Deeper row nesting.
+- Missing, crossed, or mismatched delimiters.
+- A third positional separator, unknown style, unknown escape, or trailing backslash.
+- Internal control characters and trailing garbage.
+- Valid JSON that fails the existing JSON action schema.
+
+Every rejected case proves zero callback registration.
+
+## Versioning
+
+This document defines CML v3. V3 extends the v2 positional grammar with strict JSON object cells, mixed representation, and optional element-boundary commas. It does not make JSON object internals permissive and does not add deeper structures. Future versions must preserve strict-JSON-first routing, bounded depth, atomic rejection, and an explicit discriminator for any new meaning at a security or ownership boundary.