@llblab/pi-telegram 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.9.4: Temp Dir And Command Template Hotfix
+
+- `[Telegram Temp Dir]` Default Telegram API temp files now respect `PI_CODING_AGENT_DIR`, falling back to `~/.pi/agent` when the env var is unset. Impact: sandboxed or relocated agent dirs no longer force Telegram downloads through the default home-directory path.
+- `[Command Templates]` Synced the local Command Template Standard with `pi-auto-tools@0.5.5`: command-template nodes now document `mode`, `label`, `delay`, `repeat`, parallel fanout semantics, zero-based repeat placeholders, padding, and limited arithmetic expressions such as `{_(index+1)}`. Impact: inbound/outbound Telegram handler docs and helpers share the current portable automation contract.
+- `[Queue Menu]` Empty queue refresh clicks now rotate through compact alternate empty-state headings while preserving the default first-open `⌛ Queue is empty.` state, and the Refresh button now stays directly under Back for both empty and populated queue lists. Impact: manual queue polling feels alive and the primary refresh control stays in a stable location without changing queue semantics.
+- `[Package]` Bumped package metadata to `0.9.4` and kept the lockfile in sync.
+
+## 0.9.3: External Handlers Rename
+
+- `[External Handlers]` Renamed the external update handlers domain to `external-handlers` across source, tests, and docs. Impact: the interop domain now has a cleaner name aligned with inbound/outbound handler naming.
+- `[Breaking]` Removed the old `external-update-handlers` module/doc path and old exported update/interceptor aliases. Impact: layered extensions should import from `@llblab/pi-telegram/lib/external-handlers.ts` and use the `TelegramExternalHandler*` names.
+- `[Package]` Bumped package metadata to `0.9.3` and kept the lockfile in sync.
+
 ## 0.9.2: External Update Interceptors
 
 - `[External Update Interceptors]` Added a versioned `globalThis` registry that lets layered pi extensions observe and optionally consume Telegram updates before pi-telegram's default routing. Impact: approval gates and other same-process extensions can react synchronously to Telegram callbacks without owning a second bot poller.

package/README.md

@@ -224,7 +224,7 @@ List the main risks first.
 <!-- telegram_button: OK -->
 ```
 
-Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Layered extensions that need to react to Telegram updates synchronously inside their own runtime (for example, to resolve a blocking-tool approval Promise the moment a callback arrives) can register a runtime interceptor on the shared update registry; see [External Update Handlers](./docs/external-update-handlers.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
+Button prompts are routed back into the normal Telegram queue as prompt turns. Keep the opening comment unclosed until the body-ending `-->` for body-form buttons. Closed heads must use `prompt="..."` or the colon shorthand to create a button. Unknown inline-button callbacks that do not belong to pi-telegram are forwarded to π as `[callback] <data>` so other extensions can namespace and handle their own Telegram buttons without polling the bot themselves; see the [Callback Namespace Standard](./docs/callback-namespaces.md). Layered extensions that need to react to Telegram updates synchronously inside their own runtime (for example, to resolve a blocking-tool approval Promise the moment a callback arrives) can register a runtime interceptor on the shared update registry; see [External Handlers](./docs/external-handlers.md). Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).
 
 ## Streaming
 

package/docs/README.md

@@ -10,4 +10,4 @@ Living index of project documentation in `/docs`.
 - [outbound-handlers.md](./outbound-handlers.md) — Local `pi-telegram` outbound-handler config, text/voice/button behavior, artifact outputs, and callback routing
 - [locks.md](./locks.md) — Shared `locks.json` standard for singleton extension ownership
 - [callback-namespaces.md](./callback-namespaces.md) — Shared Telegram `callback_data` namespace standard for layered extensions
-- [external-update-handlers.md](./external-update-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection
+- [external-handlers.md](./external-handlers.md) — Runtime interceptor registry that lets layered extensions observe and consume Telegram updates without owning their own polling connection

package/docs/command-templates.md

@@ -4,7 +4,7 @@ Command templates are the portable integration format for deterministic local au
 
 **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 command execution format — shell-free exec, composition/pipes, timeout (30s default), retry, critical-step branching, output artifact selection, handler-level fallback. Single JSON standard; no platform lock-in.
+**Scope:** portable synchronous command execution format — shell-free exec, composition/pipes, timeout (30s default), delay-before-start, retry, critical-step branching, output artifact selection, and handler-level fallback. Single JSON standard; no platform lock-in.
 
 ---
 
@@ -30,17 +30,18 @@ There is no portable `command` field. The command is derived from `template`: af
 
 Common object fields:
 
-| Field      | Meaning                                                                                    |
-| ---------- | ------------------------------------------------------------------------------------------ |
-| `template` | Required command string or ordered composition array                                       |
-| `args`     | Optional placeholder-name declarations only; never stores defaults                         |
-| `defaults` | Placeholder default values by name                                                         |
-| `timeout`  | Optional execution timeout in milliseconds; default `30000` (30s)                          |
-| `output`   | Optional result selector; default `"stdout"`, or a "runtime value", e.g. `"ogg"`           |
-| `retry`    | Optional max attempts (including first); default `1`. Retries immediately on non-zero exit |
-| `critical` | Optional boolean; default `false`. When `true`, failure aborts the entire root composition |
+- `label`: Optional human label for diagnostics and parallel branch reports.
+- `mode`: Optional execution mode for array templates. Default is `"sequence"`; `"parallel"` runs children concurrently.
+- `args`: Optional placeholder-name declarations only. Never stores defaults.
+- `defaults`: Placeholder default values by name.
+- `timeout`: Optional execution timeout in milliseconds. Default is `30000`. Long-running agent calls should set this explicitly.
+- `delay`: Optional wait in milliseconds before starting this node. 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. Default is `1`.
+- `critical`: Optional boolean. When `true`, failure aborts the root composition.
+- `template`: Required command string or ordered composition array.
 
-Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
+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
 
@@ -105,7 +106,7 @@ template="echo 'literal words' {text}"
 
 ## Composition
 
-`template: [...]` means sequential composition; each leaf is a command template executed with one shared runtime value map:
+`template: [...]` means sequential composition by default; each leaf is a command template executed with one shared runtime value map:
 
 ```json
 {
@@ -119,12 +120,17 @@ template="echo 'literal words' {text}"
 
 Composition rules:
 
-- Execute leaves in order; non-critical failures are recorded and execution continues, while `critical: true` failures abort the root composition
+- Execute leaves in order when `mode` is omitted or set to `"sequence"`
+- Execute child templates concurrently when `mode` is set to `"parallel"`
+- Parallel composition uses soft-quorum semantics by default: failed non-critical children are reported but do not abort siblings or the next sequence step
+- Non-critical failures are recorded and execution continues, while `critical: true` failures abort 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
 - Default `30000` (30s) timeout applies automatically; configure `timeout` only for exceptional long-running commands
-- Each leaf receives the previous leaf's stdout on stdin by default, while the final leaf stdout remains the default composition result
+- 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
@@ -132,8 +138,8 @@ Composition rules:
   "template": [
     "/path/to/tts --text {text} --lang {lang} --out {mp3}",
     {
-      "template": "ffmpeg -y -i {mp3} -c:a {codec} {ogg}",
-      "defaults": { "codec": "libopus" }
+      "defaults": { "codec": "libopus" },
+      "template": "ffmpeg -y -i {mp3} -c:a {codec} {ogg}"
     }
   ],
   "args": ["text", "lang", "mp3", "ogg"],
@@ -144,6 +150,81 @@ Composition rules:
 
 `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
+{
+  "mode": "parallel",
+  "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}",
+    {
+      "mode": "parallel",
+      "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
+```
+
 Legacy local schemas may accept `pipe` as an alias, but the portable standard is `template: [...]`.
 
 ## Fail-Open Default Policy
@@ -159,7 +240,7 @@ Set `critical: true` on any leaf to abort the entire root composition on failure
   "template": [
     { "template": "cargo build" },
     { "template": "cargo fmt --check" },
-    { "template": "cargo test", "critical": true }
+    { "critical": true, "template": "cargo test" }
   ]
 }
 ```
@@ -175,14 +256,31 @@ Set `retry: N` on a leaf to attempt execution up to `N` times (including the fir
 ```json
 {
   "template": [
-    { "template": "npm install", "retry": 3 },
-    { "template": "npm test", "critical": true, "retry": 2 }
+    { "retry": 3, "template": "npm install" },
+    { "retry": 2, "critical": true, "template": "npm test" }
   ]
 }
 ```
 
 `npm install` is retried up to 3 times. `npm test` is retried up to 2 times; if all attempts fail, the critical step aborts the pipeline.
 
+## 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:
@@ -190,11 +288,14 @@ The standard uses a single `template` field that grows with the user's needs:
 ```text
 string           → leaf command
 string[]         → sequential composition
-{ template }     → leaf with defaults
-{ template, retry, critical, output } → full leaf
+{ template }     → leaf command object
+{ mode, template } → sequence or parallel subtree
+{ mode, args, defaults, delay, retry, critical, output, template } → full node
 ```
 
-Start with a string. Add composition when needed. Add retry when flaky. Add critical when safety matters. Same contract, growing capability, no dead weight.
+Start with a string. Add composition when needed. Add `mode: "parallel"` when independent work can run concurrently. Add delay when launch pacing matters. Add retry when flaky. Add critical when safety matters. Same contract, growing capability, no dead weight.
+
+`mode: "parallel"` is the synchronous fanout shape. Detached lifecycle, logs, cancellation, and durable state belong to host-specific async job or runtime-envelope standards, not to command templates.
 
 ## Tool Boundary
 

package/docs/{external-update-handlers.md → external-handlers.md}

@@ -1,4 +1,4 @@
-# External Update Handlers
+# External Handlers
 
 `pi-telegram` owns a single `getUpdates` long-poll connection per bot. Other
 pi extensions cannot open a competing poller against the same bot — the
@@ -12,7 +12,7 @@ fires.
 
 It is the runtime counterpart to
 [Callback Namespaces](./callback-namespaces.md): callback namespaces define
-how to share `callback_data` cleanly; external update handlers define how to
+how to share `callback_data` cleanly; external handlers define how to
 observe and optionally short-circuit the dispatch of those updates.
 
 ## When to use it
@@ -63,9 +63,9 @@ Two equivalent paths.
 ### Typed import (recommended when you can depend on `@llblab/pi-telegram`)
 
 ```ts
-import { onTelegramUpdate } from "@llblab/pi-telegram/lib/external-update-handlers.ts";
+import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
 
-const off = onTelegramUpdate(async (update) => {
+const off = onTelegramExternalUpdate(async (update) => {
   const cb = (update as { callback_query?: { id?: string; data?: string } })
     .callback_query;
   if (!cb?.data?.startsWith("myext:")) return "pass";
@@ -83,7 +83,7 @@ When the layered extension prefers no `import` from `@llblab/pi-telegram` (so
 load order between the two extensions does not matter, and either can be
 installed first), it must implement the **full v1 registry contract**, not
 just `version` and `add`. pi-telegram's polling runtime calls `dispatch` on
-whatever object it finds at `globalThis.__piTelegramExternalUpdateRegistry__`,
+whatever object it finds at `globalThis.__piTelegramExternalHandlerRegistry__`,
 so a partial object would silently break the first update.
 
 pi-telegram defensively re-creates the registry if the object on `globalThis`
@@ -100,19 +100,19 @@ type PiTelegramVerdict =
   | Promise<"consume" | "pass" | void>;
 type PiTelegramInterceptor = (update: unknown) => PiTelegramVerdict;
 
-interface PiTelegramExternalUpdateRegistry {
+interface PiTelegramExternalHandlerRegistry {
   readonly version: 1;
   add: (handler: PiTelegramInterceptor) => () => void;
   // Required: pi-telegram's polling loop calls this on every update.
   dispatch: (update: unknown) => Promise<"consume" | "pass">;
 }
 
-const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
+const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
 
-function getOrCreateRegistry(): PiTelegramExternalUpdateRegistry {
+function getOrCreateRegistry(): PiTelegramExternalHandlerRegistry {
   const g = globalThis as Record<string, unknown>;
   const existing = g[REGISTRY_KEY] as
-    | PiTelegramExternalUpdateRegistry
+    | PiTelegramExternalHandlerRegistry
     | undefined;
   if (
     existing &&
@@ -123,7 +123,7 @@ function getOrCreateRegistry(): PiTelegramExternalUpdateRegistry {
     return existing;
   }
   const handlers = new Set<PiTelegramInterceptor>();
-  const registry: PiTelegramExternalUpdateRegistry = {
+  const registry: PiTelegramExternalHandlerRegistry = {
     version: 1,
     add(handler) {
       handlers.add(handler);
@@ -151,7 +151,7 @@ const off = getOrCreateRegistry().add((update) => {
 });
 ```
 
-The registry object on `globalThis.__piTelegramExternalUpdateRegistry__` is
+The registry object on `globalThis.__piTelegramExternalHandlerRegistry__` is
 versioned (`version: 1`) and stable across pi-telegram releases; future
 breaking changes will use a new schema version and a new key.
 

package/index.ts

@@ -8,7 +8,7 @@ import * as Api from "./lib/api.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
 import * as Config from "./lib/config.ts";
-import { createTelegramInterceptedHandleUpdate } from "./lib/external-update-handlers.ts";
+import { createTelegramExternalHandleUpdate } from "./lib/external-handlers.ts";
 import * as InboundHandlers from "./lib/inbound-handlers.ts";
 import * as Keyboard from "./lib/keyboard.ts";
 import * as Lifecycle from "./lib/lifecycle.ts";
@@ -359,7 +359,7 @@ export default function (pi: Pi.ExtensionAPI) {
     deleteWebhook,
     getUpdates,
     persistConfig: configStore.persist,
-    handleUpdate: createTelegramInterceptedHandleUpdate({
+    handleUpdate: createTelegramExternalHandleUpdate({
       defaultHandle: inboundRouteRuntime.handleUpdate,
     }),
     stopTypingLoop: typing.stop,

package/lib/api.ts

@@ -8,7 +8,7 @@ import { randomUUID } from "node:crypto";
 import { createWriteStream, openAsBlob } from "node:fs";
 import { mkdir, readdir, stat, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 
@@ -28,7 +28,12 @@ export function getTelegramInboundFileByteLimitFromEnv(
   return defaultValue;
 }
 
-const TEMP_DIR = join(homedir(), ".pi", "agent", "tmp", "telegram");
+function getTelegramApiTempDir(): string {
+  const agentDir = process.env.PI_CODING_AGENT_DIR
+    ? resolve(process.env.PI_CODING_AGENT_DIR)
+    : join(homedir(), ".pi", "agent");
+  return join(agentDir, "tmp", "telegram");
+}
 const TELEGRAM_TEMP_FILE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 const TELEGRAM_INBOUND_FILE_MAX_BYTES = getTelegramInboundFileByteLimitFromEnv(
   process.env,
@@ -641,7 +646,7 @@ export function createDefaultTelegramBridgeApiRuntime(deps: {
 }): TelegramBridgeApiRuntime {
   return createTelegramBridgeApiRuntime({
     client: createTelegramApiClient(deps.getBotToken),
-    tempDir: TEMP_DIR,
+    tempDir: getTelegramApiTempDir(),
     maxFileSizeBytes: TELEGRAM_INBOUND_FILE_MAX_BYTES,
     tempFileMaxAgeMs: TELEGRAM_TEMP_FILE_MAX_AGE_MS,
     recordRuntimeEvent: deps.recordRuntimeEvent,

package/lib/command-templates.ts

@@ -10,17 +10,23 @@ import { isAbsolute, resolve } from "node:path";
 
 export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
 
+export type CommandTemplateMode = "sequence" | "parallel";
+
 export interface CommandTemplateObjectConfig {
+  label?: string;
+  mode?: CommandTemplateMode;
   template?: CommandTemplateValue;
   args?: string[];
   defaults?: Record<string, unknown>;
   timeout?: number;
+  delay?: number;
   output?: string;
   retry?: number;
   critical?: boolean;
+  repeat?: number;
 }
 
-export type CommandTemplateValue = string | CommandTemplateConfig[];
+export type CommandTemplateValue = string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
 
 export type CommandTemplateConfig = string | CommandTemplateObjectConfig;
 
@@ -78,6 +84,61 @@ function normalizeCommandTemplateDefaults(
   return normalized;
 }
 
+function normalizeRepeat(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isInteger(value) || value < 1)
+    throw new Error("Command template repeat must be a positive integer.");
+  return value;
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, "0");
+}
+
+export function isCommandTemplateRepeatPlaceholder(name: string): boolean {
+  return /^_{0,6}(?:index|prev|next|repeat)$/.test(name);
+}
+
+export function getCommandTemplateRepeatDefaults(
+  index: number,
+  repeat: number,
+): Record<string, string> {
+  const prev = (index - 1 + repeat) % repeat;
+  const next = (index + 1) % repeat;
+  const values: Record<string, string> = {
+    index: String(index),
+    next: String(next),
+    prev: String(prev),
+    repeat: String(repeat),
+  };
+  for (const name of ["index", "prev", "next", "repeat"]) {
+    const numeric = Number(values[name]);
+    for (let underscores = 1; underscores <= 6; underscores += 1) {
+      values[`${"_".repeat(underscores)}${name}`] = pad(numeric, underscores + 1);
+    }
+  }
+  return values;
+}
+
+function expandRepeatConfig(
+  config: CommandTemplateObjectConfig,
+  context: Pick<CommandTemplateObjectConfig, "args" | "defaults">,
+): CommandTemplateObjectConfig[] | undefined {
+  const repeat = normalizeRepeat(config.repeat);
+  if (repeat === undefined) return undefined;
+  return Array.from({ length: repeat }, (_unused, index0) => {
+    const { repeat: _repeat, ...rest } = config;
+    return {
+      ...rest,
+      defaults: {
+        ...(context.defaults ?? {}),
+        ...(rest.defaults ?? {}),
+        ...getCommandTemplateRepeatDefaults(index0, repeat),
+      },
+    };
+  });
+}
+
 export function expandCommandTemplateConfigs(
   config: CommandTemplateConfig,
   inherited: Pick<CommandTemplateObjectConfig, "args" | "defaults"> = {},
@@ -99,6 +160,10 @@ export function expandCommandTemplateConfigs(
       ? { defaults: { ...(inheritedDefaults ?? {}), ...ownDefaults } }
       : {}),
   };
+  const repeated = expandRepeatConfig(normalizedConfig, context);
+  if (repeated) {
+    return repeated.flatMap((step) => expandCommandTemplateConfigs(step, context));
+  }
   if (Array.isArray(normalizedConfig.template)) {
     return normalizedConfig.template.flatMap((step) =>
       expandCommandTemplateConfigs(step, context),
@@ -189,17 +254,92 @@ export function expandCommandTemplateExecutable(
   return command;
 }
 
+function evaluateCommandTemplateExpression(
+  expression: string,
+  values: Record<string, string>,
+): number {
+  let index = 0;
+  const source = expression.replace(/\s+/g, "");
+  function peek(): string | undefined {
+    return source[index];
+  }
+  function consume(char: string): boolean {
+    if (peek() !== char) return false;
+    index += 1;
+    return true;
+  }
+  function parsePrimary(): number {
+    if (consume("(")) {
+      const value = parseExpression();
+      if (!consume(")")) throw new Error(`Invalid command template expression: ${expression}`);
+      return value;
+    }
+    const numberMatch = source.slice(index).match(/^\d+/);
+    if (numberMatch) {
+      index += numberMatch[0].length;
+      return Number(numberMatch[0]);
+    }
+    const nameMatch = source.slice(index).match(/^[A-Za-z_][A-Za-z0-9_-]*/);
+    if (nameMatch) {
+      index += nameMatch[0].length;
+      const value = values[nameMatch[0]];
+      if (value === undefined || !/^-?\d+$/.test(value))
+        throw new Error(`Invalid command template expression variable: ${nameMatch[0]}`);
+      return Number(value);
+    }
+    throw new Error(`Invalid command template expression: ${expression}`);
+  }
+  function parseTerm(): number {
+    let value = parsePrimary();
+    while (true) {
+      if (consume("*")) value *= parsePrimary();
+      else if (consume("/")) value = Math.trunc(value / parsePrimary());
+      else if (consume("%")) value %= parsePrimary();
+      else return value;
+    }
+  }
+  function parseExpression(): number {
+    let value = parseTerm();
+    while (true) {
+      if (consume("+")) value += parseTerm();
+      else if (consume("-")) value -= parseTerm();
+      else return value;
+    }
+  }
+  const value = parseExpression();
+  if (index !== source.length) throw new Error(`Invalid command template expression: ${expression}`);
+  return value;
+}
+
+function substituteCommandTemplateExpression(
+  content: string,
+  values: Record<string, string>,
+): string | undefined {
+  const padded = content.match(/^(_{1,6})\((.+)\)$/);
+  if (padded) {
+    return pad(evaluateCommandTemplateExpression(padded[2], values), padded[1].length + 1);
+  }
+  if (!/[()+\-*\/%]/.test(content)) return undefined;
+  return String(evaluateCommandTemplateExpression(content, values));
+}
+
 export function substituteCommandTemplateToken(
   token: string,
   values: Record<string, string>,
   missingLabel = "command template",
 ): string {
   return token.replace(
-    /\{([A-Za-z_][A-Za-z0-9_-]*)(?:=([^}]*))?\}/g,
-    (_match, name, inlineDefault: string | undefined) => {
-      if (Object.hasOwn(values, name)) return values[name] ?? "";
-      if (inlineDefault !== undefined) return inlineDefault;
-      throw new Error(`Missing ${missingLabel} value: ${name}`);
+    /\{([^{}]+)\}/g,
+    (_match, content: string) => {
+      const simple = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?:=([^}]*))?$/);
+      if (simple) {
+        const [, name, inlineDefault] = simple;
+        if (Object.hasOwn(values, name)) return values[name] ?? "";
+        if (inlineDefault !== undefined) return inlineDefault;
+      }
+      const expression = substituteCommandTemplateExpression(content, values);
+      if (expression !== undefined) return expression;
+      throw new Error(`Missing ${missingLabel} value: ${content}`);
     },
   );
 }
@@ -300,6 +440,12 @@ export function buildCommandTemplateInvocation(
   }
   if (!normalizedConfig.template)
     throw new Error(options.emptyMessage ?? "Command template is required");
+  if (typeof normalizedConfig.template !== "string") {
+    throw new Error(
+      options.emptyMessage ??
+        "Command template object cannot be executed as one command",
+    );
+  }
   const parts = splitCommandTemplate(normalizedConfig.template);
   const commandPart = parts[0];
   if (!commandPart)

package/lib/{external-update-handlers.ts → external-handlers.ts}

@@ -1,5 +1,5 @@
 /**
- * External Telegram update interceptor registry
+ * External Telegram handler registry
  * Zones: telegram transport, layered extension interop
  * Lets other pi extensions hook into the polling loop without owning their own getUpdates connection
  */
@@ -10,16 +10,16 @@
  * - `"consume"` — the interceptor handled this update; pi-telegram skips default routing.
  * - `"pass"` (or `void`/`undefined`) — pi-telegram routes the update normally.
  */
-export type TelegramExternalUpdateVerdict = "consume" | "pass";
+export type TelegramExternalHandlerVerdict = "consume" | "pass";
 
-export type TelegramExternalUpdateInterceptor = (
+export type TelegramExternalHandler = (
   update: unknown,
 ) =>
-  | TelegramExternalUpdateVerdict
+  | TelegramExternalHandlerVerdict
   | void
-  | Promise<TelegramExternalUpdateVerdict | void>;
+  | Promise<TelegramExternalHandlerVerdict | void>;
 
-export interface TelegramExternalUpdateRegistry {
+export interface TelegramExternalHandlerRegistry {
   /** Schema version of this registry shape. */
   readonly version: 1;
   /**
@@ -29,17 +29,17 @@ export interface TelegramExternalUpdateRegistry {
    * before pi-telegram's own routing. The first interceptor that returns
    * `"consume"` wins and stops the chain for that update.
    */
-  add: (handler: TelegramExternalUpdateInterceptor) => () => void;
+  add: (handler: TelegramExternalHandler) => () => void;
   /**
    * Run all registered interceptors against an update.
    *
    * Used by pi-telegram's polling runtime; layered extensions should call
-   * {@link onTelegramUpdate} or `add` instead of dispatching directly.
+   * {@link onTelegramExternalUpdate} or `add` instead of dispatching directly.
    */
-  dispatch: (update: unknown) => Promise<TelegramExternalUpdateVerdict>;
+  dispatch: (update: unknown) => Promise<TelegramExternalHandlerVerdict>;
 }
 
-const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
+const REGISTRY_KEY = "__piTelegramExternalHandlerRegistry__";
 
 /**
  * Validate that a value on `globalThis` matches the full v1 registry contract.
@@ -55,9 +55,9 @@ const REGISTRY_KEY = "__piTelegramExternalUpdateRegistry__";
  */
 function isValidV1Registry(
   candidate: unknown,
-): candidate is TelegramExternalUpdateRegistry {
+): candidate is TelegramExternalHandlerRegistry {
   if (!candidate || typeof candidate !== "object") return false;
-  const r = candidate as Partial<TelegramExternalUpdateRegistry>;
+  const r = candidate as Partial<TelegramExternalHandlerRegistry>;
   return (
     r.version === 1 &&
     typeof r.add === "function" &&
@@ -65,12 +65,12 @@ function isValidV1Registry(
   );
 }
 
-function getOrCreateRegistry(): TelegramExternalUpdateRegistry {
+function getOrCreateRegistry(): TelegramExternalHandlerRegistry {
   const g = globalThis as Record<string, unknown>;
   const existing = g[REGISTRY_KEY];
   if (isValidV1Registry(existing)) return existing;
-  const handlers = new Set<TelegramExternalUpdateInterceptor>();
-  const registry: TelegramExternalUpdateRegistry = {
+  const handlers = new Set<TelegramExternalHandler>();
+  const registry: TelegramExternalHandlerRegistry = {
     version: 1,
     add(handler) {
       handlers.add(handler);
@@ -95,16 +95,18 @@ function getOrCreateRegistry(): TelegramExternalUpdateRegistry {
 /**
  * Called by pi-telegram's own runtime to obtain the registry it dispatches
  * through. Layered extensions should not call this; use
- * {@link onTelegramUpdate} instead.
+ * {@link onTelegramExternalUpdate} instead.
  */
-export function getTelegramExternalUpdateRegistry(): TelegramExternalUpdateRegistry {
+export function getTelegramExternalHandlerRegistry(): TelegramExternalHandlerRegistry {
   return getOrCreateRegistry();
 }
 
-export interface TelegramExternalInterceptorWrapDeps<TUpdate, TContext> {
+export interface TelegramExternalHandlerWrapDeps<TUpdate, TContext> {
   defaultHandle: (update: TUpdate, ctx: TContext) => Promise<void>;
-  registry?: TelegramExternalUpdateRegistry;
+  registry?: TelegramExternalHandlerRegistry;
 }
+export type TelegramExternalInterceptorWrapDeps<TUpdate, TContext> =
+  TelegramExternalHandlerWrapDeps<TUpdate, TContext>;
 
 /**
  * Wrap a default polling `handleUpdate` with the external interceptor registry.
@@ -115,8 +117,8 @@ export interface TelegramExternalInterceptorWrapDeps<TUpdate, TContext> {
  * Composition-root callers (pi-telegram's `index.ts`) should use this builder
  * instead of writing the lifting logic inline.
  */
-export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
-  deps: TelegramExternalInterceptorWrapDeps<TUpdate, TContext>,
+export function createTelegramExternalHandleUpdate<TUpdate, TContext>(
+  deps: TelegramExternalHandlerWrapDeps<TUpdate, TContext>,
 ): (update: TUpdate, ctx: TContext) => Promise<void> {
   const registry = deps.registry ?? getOrCreateRegistry();
   const { defaultHandle } = deps;
@@ -140,9 +142,9 @@ export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
  *
  * @example
  * ```ts
- * import { onTelegramUpdate } from "@llblab/pi-telegram/lib/external-update-handlers.ts";
+ * import { onTelegramExternalUpdate } from "@llblab/pi-telegram/lib/external-handlers.ts";
  *
- * const off = onTelegramUpdate(async (update) => {
+ * const off = onTelegramExternalUpdate(async (update) => {
  *   const cb = (update as { callback_query?: { data?: string } }).callback_query;
  *   if (!cb?.data?.startsWith("myext:")) return "pass";
  *   await handleMyCallback(cb);
@@ -154,12 +156,12 @@ export function createTelegramInterceptedHandleUpdate<TUpdate, TContext>(
  * ```
  *
  * Extensions that prefer zero coupling can also reach the registry directly
- * via `globalThis.__piTelegramExternalUpdateRegistry__` (versioned object,
- * see {@link TelegramExternalUpdateRegistry}). This avoids importing
+ * via `globalThis.__piTelegramExternalHandlerRegistry__` (versioned object,
+ * see {@link TelegramExternalHandlerRegistry}). This avoids importing
  * `@llblab/pi-telegram` and tolerates either install order.
  */
-export function onTelegramUpdate(
-  handler: TelegramExternalUpdateInterceptor,
+export function onTelegramExternalUpdate(
+  handler: TelegramExternalHandler,
 ): () => void {
   return getOrCreateRegistry().add(handler);
 }

package/lib/menu-queue.ts

@@ -13,6 +13,12 @@ import * as Queue from "./queue.ts";
 
 const QUEUE_ITEM_PROMPT_HTML_LIMIT = 3600;
 const QUEUE_ITEM_PROMPT_TRUNCATION_SUFFIX = "\n… [truncated]";
+const EMPTY_QUEUE_REFRESH_TITLES = [
+  "<b>⌛ Queue is still empty.</b>",
+  "<b>🫙 Still nothing in queue.</b>",
+  "<b>🍃 Queue remains empty.</b>",
+  "<b>🕳 Nothing queued yet.</b>",
+] as const;
 type TelegramQueueMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 interface TelegramQueueMenuItem {
   chatId: number;
@@ -55,9 +61,16 @@ function toTelegramQueueMenuItems<Context>(
 }
 function buildTelegramQueueMenuReplyMarkup(
   items: readonly TelegramQueueMenuItem[],
+  emptyRefreshIndex = 0,
 ): TelegramQueueMenuReplyMarkup {
   const backRow = [{ text: "⬆️ Main menu", callback_data: "menu:back" }];
-  const refreshRow = [{ text: "🌀 Refresh", callback_data: "queue:refresh" }];
+  const nextEmptyRefreshIndex =
+    (emptyRefreshIndex + 1) % EMPTY_QUEUE_REFRESH_TITLES.length;
+  const refreshData =
+    items.length === 0
+      ? `queue:refresh:${nextEmptyRefreshIndex}`
+      : "queue:refresh";
+  const refreshRow = [{ text: "🌀 Refresh", callback_data: refreshData }];
   if (items.length === 0) return { inline_keyboard: [backRow, refreshRow] };
   const rows = items.map(function buildTelegramQueueMenuRow(item, index) {
     const prefix = item.isPriority
@@ -73,7 +86,7 @@ function buildTelegramQueueMenuReplyMarkup(
       },
     ];
   });
-  return { inline_keyboard: [backRow, ...rows, refreshRow] };
+  return { inline_keyboard: [backRow, refreshRow, ...rows] };
 }
 function findTelegramQueueItem<Context>(
   items: readonly Queue.TelegramQueueItem<Context>[],
@@ -215,7 +228,7 @@ async function handleTelegramQueueMenuCallback<Context>(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "queue:list" || data === "queue:refresh") {
+  if (data === "queue:list") {
     await updateTelegramQueueMenuList(
       callbackQueryId,
       replyChatId,
@@ -224,6 +237,18 @@ async function handleTelegramQueueMenuCallback<Context>(
     );
     return true;
   }
+  const refreshMatch = data.match(/^queue:refresh(?::(\d+))?$/);
+  if (refreshMatch) {
+    await updateTelegramQueueMenuList(
+      callbackQueryId,
+      replyChatId,
+      replyMessageId,
+      deps,
+      undefined,
+      refreshMatch[1] === undefined ? 0 : Number(refreshMatch[1]),
+    );
+    return true;
+  }
   const pickMatch = data.match(/^queue:pick:(\d+):(\d+)$/);
   if (pickMatch) {
     await handleTelegramQueueMenuPick(
@@ -306,9 +331,13 @@ async function handleTelegramQueueMenuCallback<Context>(
 }
 function getTelegramQueueMenuListText(
   items: readonly TelegramQueueMenuItem[],
+  emptyRefreshIndex?: number,
 ): string {
-  if (items.length === 0) return "<b>⌛ Queue is empty.</b>";
-  return "<b>⏳ Queue:</b>";
+  if (items.length > 0) return "<b>⏳ Queue:</b>";
+  if (emptyRefreshIndex === undefined) return "<b>⌛ Queue is empty.</b>";
+  return EMPTY_QUEUE_REFRESH_TITLES[
+    emptyRefreshIndex % EMPTY_QUEUE_REFRESH_TITLES.length
+  ];
 }
 async function updateTelegramQueueMenuList<Context>(
   callbackQueryId: string,
@@ -316,13 +345,14 @@ async function updateTelegramQueueMenuList<Context>(
   replyMessageId: number,
   deps: TelegramQueueMenuCallbackDeps<Context>,
   notice?: string,
+  emptyRefreshIndex?: number,
 ): Promise<void> {
   const items = deps.getQueuedItems();
   await deps.updateQueueMessage(
     replyChatId,
     replyMessageId,
-    getTelegramQueueMenuListText(items),
-    buildTelegramQueueMenuReplyMarkup(items),
+    getTelegramQueueMenuListText(items, emptyRefreshIndex),
+    buildTelegramQueueMenuReplyMarkup(items, emptyRefreshIndex),
   );
   await deps.answerCallbackQuery(callbackQueryId, notice);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.9.2",
+  "version": "0.9.4",
   "private": false,
   "description": "Better Telegram DM bridge extension for π",
   "type": "module",