@llblab/pi-telegram 0.12.0 → 0.13.1

package/docs/voice.md

@@ -1,6 +1,6 @@
 # Voice Integration
 
-Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. In `0.11.0`, this is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot polling loop.
+Voice messages flow through an **inbound transcription → outbound voice reply** pipeline. This document describes the bridge's role in that pipeline; provider-specific mechanics (TTS/STT backends, voice IDs, languages) are owned by voice provider extensions. This is a first-class extension surface: one companion extension can provide STT fallbacks for inbound voice/audio files and TTS fallbacks for outbound Telegram voice replies without owning a second bot polling loop.
 
 ## Overview
 
@@ -67,12 +67,12 @@ The reply policy itself remains a built-in pi-telegram setting (`voice.replyMode
 
 ## Outbound Voice Synthesis Provider Registration
 
-Voice synthesis provider extensions (such as `pi-xai-voice`) register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
+Voice synthesis provider extensions register themselves through `registerTelegramVoiceSynthesisProvider()`. The bridge only provides the registration seam and the actual delivery to Telegram. **The provider is fully responsible for**:
 
 - Text optimisation / speech-style rewriting
 - Adding speech tags (when desired)
 - Running TTS + ffmpeg conversion to OGG/Opus
-- Deciding whether to return `transcriptText` at all (based on the user's "Send Transcript" toggle)
+- Deciding whether to return `transcriptText` at all based on the bridge-owned `voice.sendTranscript` preference when the provider has access to the current Telegram config
 - `transcriptText` (when returned) is attached by the bridge as the voice message **caption** only. Separate transcript messages are no longer sent.
 
 The bridge shows a `record_voice` action while delivering and sends the final audio with Telegram `sendVoice`. When a provider returns `transcriptText`, the bridge attaches it as the voice caption.
@@ -86,7 +86,7 @@ The provider receives the raw agent text plus optional `{ lang?, rate? }`.
 It must return one of:
 
 - `string` — path to a ready `.ogg` or `.opus` file
-- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. A provider UI can expose a "Send Transcript" toggle by returning `transcriptText` only when that toggle is enabled.
+- `{ audioPath: string, transcriptText?: string }` — `audioPath` must be OGG/Opus. When `transcriptText` is present it is attached as the voice message **caption**. Providers should treat pi-telegram's `voice.sendTranscript` as the bridge-owned transcript preference instead of inventing a second reply-policy UI.
 - `undefined` — skip this text block
 
 **Important:** Providers are fully responsible for producing a clean, TTS-optimised native voice file. The bridge may also run configured outbound voice command templates for users who prefer process-boundary handlers instead of provider extensions.
@@ -124,20 +124,25 @@ Priority for outbound voice delivery is: configured `outboundHandlers` with `typ
 When the user's "Send Transcript" toggle is ON, return the clean spoken text as `transcriptText`. The bridge attaches it as the caption on the voice message. When the toggle is OFF, return only the audio path (no `transcriptText`).
 
 ```typescript
-import { registerTelegramVoiceSynthesisProvider } from "@llblab/pi-telegram/voice";
+import {
+  getTelegramVoiceSendTranscript,
+  registerTelegramVoiceSynthesisProvider,
+} from "@llblab/pi-telegram/voice";
 
 registerTelegramVoiceSynthesisProvider(
   async (text, options) => {
     const rewritten = rewriteWithSpeechTags(text);
     const audioPath = await myTTS(rewritten, { language: options?.lang });
-    const sendTranscript = getUserSendTranscriptPreference(); // from your UI + telegram.json
+    const sendTranscript = getTelegramVoiceSendTranscript(
+      getCurrentTelegramConfigView(),
+    );
     return sendTranscript ? { audioPath, transcriptText: text } : { audioPath };
   },
   { id: "my-voice-provider/tts" },
 );
 ```
 
-The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
+`getCurrentTelegramConfigView()` represents whatever current `TelegramConfig` view your extension already owns or receives; pi-telegram does not require providers to read config directly. The bridge never sends a separate transcript message. Caption-only is the "ON" behavior.
 
 ### Surfacing provider diagnostics
 
@@ -146,7 +151,7 @@ Voice provider extensions can record runtime events that appear in `/telegram-st
 ```typescript
 import { recordTelegramRuntimeEvent } from "@llblab/pi-telegram/outbound";
 
-recordTelegramRuntimeEvent("xai-voice", new Error("TTS failed"), {
+recordTelegramRuntimeEvent("voice-provider", new Error("TTS failed"), {
   phase: "tts",
   text: text.slice(0, 50),
 });

package/index.ts

@@ -4,7 +4,6 @@
  * Keeps the runtime wiring in one place while delegating reusable domain logic to /lib modules
  */
 
-import * as Api from "./lib/api.ts";
 import * as Bindings from "./lib/bindings.ts";
 import * as CommandTemplates from "./lib/command-templates.ts";
 import * as Commands from "./lib/commands.ts";
@@ -28,6 +27,7 @@ import * as Routing from "./lib/routing.ts";
 import * as Runtime from "./lib/runtime.ts";
 import * as Sections from "./lib/sections.ts";
 import * as Status from "./lib/status.ts";
+import * as TelegramApi from "./lib/telegram-api.ts";
 import * as TextGroups from "./lib/text-groups.ts";
 import * as TimeInjection from "./lib/time-injection.ts";
 import * as Updates from "./lib/updates.ts";
@@ -82,11 +82,11 @@ export default function (pi: Pi.ExtensionAPI) {
   const hasPendingMessages = Pi.hasExtensionContextPendingMessages;
   const compact = Pi.compactExtensionContext;
   const mediaGroupRuntime = Media.createTelegramMediaGroupController<
-    Api.TelegramMessage,
+    TelegramApi.TelegramMessage,
     Pi.ExtensionContext
   >();
   const textGroupRuntime = TextGroups.createTelegramTextGroupController<
-    Api.TelegramMessage,
+    TelegramApi.TelegramMessage,
     Pi.ExtensionContext
   >();
   const telegramQueueStore =
@@ -153,7 +153,7 @@ export default function (pi: Pi.ExtensionAPI) {
     answerGuestQuery,
     deleteMessage: deleteTelegramMessage,
     prepareTempDir,
-  } = Api.createDefaultTelegramBridgeApiRuntime({
+  } = TelegramApi.createDefaultTelegramBridgeApiRuntime({
     getBotToken: configStore.getBotToken,
     recordRuntimeEvent,
   });

package/lib/bindings.ts

@@ -4,7 +4,6 @@
  * Owns pi-facing tool, command, and lifecycle hook registration for the entrypoint
  */
 
-import * as Api from "./api.ts";
 import * as CommandTemplates from "./command-templates.ts";
 import * as Commands from "./commands.ts";
 import * as Config from "./config.ts";
@@ -22,6 +21,7 @@ import * as Replies from "./replies.ts";
 import * as Runtime from "./runtime.ts";
 import * as Setup from "./setup.ts";
 import * as Status from "./status.ts";
+import * as TelegramApi from "./telegram-api.ts";
 
 type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
 
@@ -59,13 +59,12 @@ export function registerTelegramCommandsAndTools({
     getActiveTurn: activeTurnRuntime.get,
     recordRuntimeEvent,
   });
-
   Commands.registerTelegramBridgeCommands(pi, {
     promptForConfig: Setup.createTelegramSetupPromptRuntime({
       getConfig: configStore.get,
       setConfig: configStore.set,
       setupGuard: setup,
-      getMe: Api.fetchTelegramBotIdentity,
+      getMe: TelegramApi.fetchTelegramBotIdentity,
       persistConfig: configStore.persist,
       startPolling: lockedPollingRuntime.start,
       updateStatus,
@@ -260,7 +259,6 @@ export function registerTelegramLifecycleRuntimeHooks({
     setActiveToolExecutions: lifecycle.setActiveToolExecutions,
     triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
   });
-
   Lifecycle.setResetTransportReplyDedup(Replies.resetTransportReplyDedup);
   const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
     agentLifecycleHooks.onAgentStart,
@@ -281,6 +279,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       startTypingLoop: promptDispatchRuntime.startTypingLoop,
       onMessageStart: previewRuntime.onMessageStart,
       onMessageUpdate: previewRuntime.onMessageUpdate,
+      recordRuntimeEvent,
     });
   Lifecycle.registerTelegramLifecycleHooks(pi, {
     ...sessionLifecycleRuntime,

package/lib/command-templates.ts

@@ -8,26 +8,28 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 
-export type CommandTemplateMode = "sequence" | "parallel";
 export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
 export interface CommandTemplateObjectConfig {
   label?: string;
-  mode?: CommandTemplateMode;
+  parallel?: boolean;
+  when?: boolean | string;
   template?: CommandTemplateValue;
   args?: string[];
   defaults?: Record<string, unknown>;
-  timeout?: number;
-  delay?: number;
+  timeout?: number | string;
+  delay?: number | string;
   output?: string;
-  retry?: number;
-  critical?: boolean;
+  retry?: number | string;
   failure?: CommandTemplateFailureScope;
   recover?: CommandTemplateValue;
   repeat?: number | string;
 }
 
-export type CommandTemplateValue = string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
+export type CommandTemplateValue =
+  | string
+  | CommandTemplateConfig[]
+  | CommandTemplateObjectConfig;
 
 export type CommandTemplateConfig = string | CommandTemplateObjectConfig;
 
@@ -88,11 +90,34 @@ function normalizeCommandTemplateDefaults(
   for (const [key, value] of Object.entries(defaults)) {
     normalized[key] = Array.isArray(value)
       ? value
-      : value === undefined || value === null ? "" : String(value);
+      : value === undefined || value === null
+        ? ""
+        : String(value);
   }
   return normalized;
 }
 
+export function resolveInheritedDefaultReferences(
+  ownDefaults: Record<string, unknown> | undefined,
+  inheritedDefaults: Record<string, unknown> | undefined,
+  runtimeValues: Record<string, unknown> = {},
+): Record<string, unknown> | undefined {
+  if (!ownDefaults || !inheritedDefaults) return ownDefaults;
+  const resolved = { ...ownDefaults };
+  for (const [key, value] of Object.entries(ownDefaults)) {
+    if (typeof value !== "string") continue;
+    const exact = /^\{([A-Za-z_][A-Za-z0-9_-]*)\}$/.exec(value);
+    if (
+      !exact ||
+      Object.hasOwn(runtimeValues, exact[1]) ||
+      !Object.hasOwn(inheritedDefaults, exact[1])
+    )
+      continue;
+    resolved[key] = inheritedDefaults[exact[1]];
+  }
+  return resolved;
+}
+
 export function resolveCommandTemplateRepeat(
   value: number | string | undefined,
   values: Record<string, unknown> = {},
@@ -105,13 +130,17 @@ export function resolveCommandTemplateRepeat(
   }
   const trimmed = value.trim();
   if (/^\d+$/.test(trimmed)) return Number(trimmed);
-  const lengthMatch = trimmed.match(/^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/);
+  const lengthMatch = trimmed.match(
+    /^\{?([A-Za-z_][A-Za-z0-9_-]*)\.length\}?$/,
+  );
   if (lengthMatch) {
     const source = values[lengthMatch[1]];
     if (Array.isArray(source)) return source.length;
     if (source === undefined) return undefined;
   }
-  throw new Error("Command template repeat must be a positive integer or {array.length}.");
+  throw new Error(
+    "Command template repeat must be a positive integer or {array.length}.",
+  );
 }
 
 function getExecutableName(command: string | undefined): string {
@@ -124,14 +153,15 @@ function hasAnyFlag(args: string[], flags: string[]): boolean {
 }
 
 function hasRiskyPathArg(args: string[]): boolean {
-  return args.some((arg) =>
-    arg === "/" ||
-    arg === "~" ||
-    arg === "./" ||
-    arg === "../" ||
-    arg.includes("{") ||
-    arg.startsWith("~/") ||
-    arg.startsWith("/"),
+  return args.some(
+    (arg) =>
+      arg === "/" ||
+      arg === "~" ||
+      arg === "./" ||
+      arg === "../" ||
+      arg.includes("{") ||
+      arg.startsWith("~/") ||
+      arg.startsWith("/"),
   );
 }
 
@@ -143,20 +173,42 @@ function getLeafCommandTemplateWarnings(
   const args = parts.slice(1);
   const warnings: string[] = [];
   if (["bash", "sh", "zsh", "fish"].includes(command)) {
-    const mode = hasAnyFlag(args, ["-c"]) ? "shell command strings" : "shell scripts";
-    warnings.push(`${config.label ?? command}: invokes ${command}; ${mode} are trusted executable content and are not sandboxed by command-template argv splitting.`);
+    const shellContent = hasAnyFlag(args, ["-c"])
+      ? "shell command strings"
+      : "shell scripts";
+    warnings.push(
+      `${config.label ?? command}: invokes ${command}; ${shellContent} are trusted executable content and are not sandboxed by command-template argv splitting.`,
+    );
   }
-  if (["node", "deno", "bun"].includes(command) && hasAnyFlag(args, ["-e", "--eval"])) {
-    warnings.push(`${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`);
+  if (
+    ["node", "deno", "bun"].includes(command) &&
+    hasAnyFlag(args, ["-e", "--eval"])
+  ) {
+    warnings.push(
+      `${config.label ?? command}: invokes ${command} eval mode; code strings are trusted executable content and are not sandboxed.`,
+    );
   }
-  if (["python", "python3", "perl", "ruby"].includes(command) && hasAnyFlag(args, ["-c", "-e"])) {
-    warnings.push(`${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`);
+  if (
+    ["python", "python3", "perl", "ruby"].includes(command) &&
+    hasAnyFlag(args, ["-c", "-e"])
+  ) {
+    warnings.push(
+      `${config.label ?? command}: invokes ${command} code-eval mode; code strings are trusted executable content and are not sandboxed.`,
+    );
   }
-  if (command === "rm" && (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) || hasRiskyPathArg(args))) {
-    warnings.push(`${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`);
+  if (
+    command === "rm" &&
+    (args.some((arg) => /^-[^-]*r/.test(arg) || /^-[^-]*f/.test(arg)) ||
+      hasRiskyPathArg(args))
+  ) {
+    warnings.push(
+      `${config.label ?? command}: removes filesystem paths; verify placeholders and paths before running trusted destructive commands.`,
+    );
   }
   if (["mv", "cp", "rsync"].includes(command) && hasRiskyPathArg(args)) {
-    warnings.push(`${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`);
+    warnings.push(
+      `${config.label ?? command}: mutates broad filesystem paths; verify placeholders and paths before running trusted commands.`,
+    );
   }
   return warnings;
 }
@@ -184,7 +236,10 @@ export function getCommandTemplateRepeatDefaults(
   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);
+      values[`${"_".repeat(underscores)}${name}`] = pad(
+        numeric,
+        underscores + 1,
+      );
     }
   }
   return values;
@@ -194,7 +249,10 @@ function expandRepeatConfig(
   config: CommandTemplateObjectConfig,
   context: Pick<CommandTemplateObjectConfig, "args" | "defaults">,
 ): CommandTemplateObjectConfig[] | undefined {
-  const repeat = resolveCommandTemplateRepeat(config.repeat, context.defaults ?? {});
+  const repeat = resolveCommandTemplateRepeat(
+    config.repeat,
+    context.defaults ?? {},
+  );
   if (repeat === undefined) return undefined;
   return Array.from({ length: repeat }, (_unused, index0) => {
     const { repeat: _repeat, ...rest } = config;
@@ -217,8 +275,9 @@ export function expandCommandTemplateConfigs(
   const inheritedDefaults = normalizeCommandTemplateDefaults(
     inherited.defaults,
   );
-  const ownDefaults = normalizeCommandTemplateDefaults(
-    normalizedConfig.defaults,
+  const ownDefaults = resolveInheritedDefaultReferences(
+    normalizeCommandTemplateDefaults(normalizedConfig.defaults),
+    inheritedDefaults,
   );
   const context = {
     ...(inherited.args !== undefined ? { args: inherited.args } : {}),
@@ -232,7 +291,9 @@ export function expandCommandTemplateConfigs(
   };
   const repeated = expandRepeatConfig(normalizedConfig, context);
   if (repeated) {
-    return repeated.flatMap((step) => expandCommandTemplateConfigs(step, context));
+    return repeated.flatMap((step) =>
+      expandCommandTemplateConfigs(step, context),
+    );
   }
   const recoverConfig = normalizeRecoverConfig(normalizedConfig.recover);
   const recoverSteps = recoverConfig
@@ -253,7 +314,6 @@ export function expandCommandTemplateConfigs(
       ...context,
       template: normalizedConfig.template,
       retry: normalizedConfig.retry,
-      critical: normalizedConfig.critical,
     },
     ...recoverSteps,
   ];
@@ -264,26 +324,40 @@ export function getCommandTemplateWarnings(
 ): string[] {
   return [
     ...new Set(
-      expandCommandTemplateConfigs(config)
-        .flatMap((leaf) => getLeafCommandTemplateWarnings(leaf)),
+      expandCommandTemplateConfigs(config).flatMap((leaf) =>
+        getLeafCommandTemplateWarnings(leaf),
+      ),
     ),
   ];
 }
 
-function parseCommandTemplateArgToken(value: string): { name: string; defaultValue?: string } {
+function parseCommandTemplateArgToken(value: string): {
+  name: string;
+  defaultValue?: string;
+} {
   const separatorIndex = value.indexOf("=");
-  const rawName = separatorIndex === -1 ? value : value.slice(0, separatorIndex);
+  const rawName =
+    separatorIndex === -1 ? value : value.slice(0, separatorIndex);
   const colonIndex = rawName.indexOf(":");
   return {
     name: (colonIndex === -1 ? rawName : rawName.slice(0, colonIndex)).trim(),
-    ...(separatorIndex === -1 ? {} : { defaultValue: value.slice(separatorIndex + 1).trim() }),
+    ...(separatorIndex === -1
+      ? {}
+      : { defaultValue: value.slice(separatorIndex + 1).trim() }),
   };
 }
 
-function parseCommandTemplatePlaceholderContent(content: string): { name: string; inlineDefault?: string } | undefined {
-  const match = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)(?::(?:string|path|int|number|bool|array|enum\([^)]*\)))?(?:=([^}]*))?$/);
+function parseCommandTemplatePlaceholderContent(
+  content: string,
+): { name: string; inlineDefault?: string } | undefined {
+  const match = content.match(
+    /^([A-Za-z_][A-Za-z0-9_-]*)(?::(?:string|path|int|number|bool|array|enum\([^)]*\)))?(?:=([^}]*))?$/,
+  );
   if (!match) return undefined;
-  return { name: match[1], ...(match[2] !== undefined ? { inlineDefault: match[2] } : {}) };
+  return {
+    name: match[1],
+    ...(match[2] !== undefined ? { inlineDefault: match[2] } : {}),
+  };
 }
 
 export function getCommandTemplateDefaults(
@@ -376,7 +450,8 @@ function evaluateCommandTemplateExpression(
   function parsePrimary(): number {
     if (consume("(")) {
       const value = parseExpression();
-      if (!consume(")")) throw new Error(`Invalid command template expression: ${expression}`);
+      if (!consume(")"))
+        throw new Error(`Invalid command template expression: ${expression}`);
       return value;
     }
     const numberMatch = source.slice(index).match(/^\d+/);
@@ -389,7 +464,9 @@ function evaluateCommandTemplateExpression(
       index += nameMatch[0].length;
       const value = values[nameMatch[0]];
       if (value === undefined || !/^-?\d+$/.test(String(value)))
-        throw new Error(`Invalid command template expression variable: ${nameMatch[0]}`);
+        throw new Error(
+          `Invalid command template expression variable: ${nameMatch[0]}`,
+        );
       return Number(value);
     }
     throw new Error(`Invalid command template expression: ${expression}`);
@@ -412,7 +489,8 @@ function evaluateCommandTemplateExpression(
     }
   }
   const value = parseExpression();
-  if (index !== source.length) throw new Error(`Invalid command template expression: ${expression}`);
+  if (index !== source.length)
+    throw new Error(`Invalid command template expression: ${expression}`);
   return value;
 }
 
@@ -422,25 +500,125 @@ function substituteCommandTemplateExpression(
 ): string | undefined {
   const padded = content.match(/^(_{1,6})\((.+)\)$/);
   if (padded) {
-    return pad(evaluateCommandTemplateExpression(padded[2], values), padded[1].length + 1);
+    return pad(
+      evaluateCommandTemplateExpression(padded[2], values),
+      padded[1].length + 1,
+    );
   }
   if (!/[()+\-*\/%]/.test(content)) return undefined;
   return String(evaluateCommandTemplateExpression(content, values));
 }
 
+function shouldResolveEmbeddedCommandTemplateToken(
+  token: string,
+  values: Record<string, unknown>,
+): boolean {
+  const matches = [...token.matchAll(/\{([^{}]+)\}/g)];
+  if (matches.length === 0) return false;
+  return matches.every((match) => {
+    const content = match[1];
+    if (resolveCommandTemplateNullish(content, values) !== undefined)
+      return true;
+    if (resolveCommandTemplateTernary(content, values) !== undefined)
+      return true;
+    const indexed = content.match(
+      /^([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]$/,
+    );
+    if (indexed) return Object.hasOwn(values, indexed[1]);
+    const simple = parseCommandTemplatePlaceholderContent(content);
+    if (simple)
+      return (
+        Object.hasOwn(values, simple.name) || simple.inlineDefault !== undefined
+      );
+    try {
+      return substituteCommandTemplateExpression(content, values) !== undefined;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function isFalsyCommandTemplateValue(value: unknown): boolean {
+  if (value === undefined || value === null || value === false) return true;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === "" || normalized === "0" || normalized === "false" || normalized === "no";
+}
+
+function resolveCommandTemplateCondition(
+  condition: string,
+  values: Record<string, unknown>,
+): unknown {
+  const trimmed = condition.trim();
+  const negated = trimmed.startsWith("!");
+  const name = negated ? trimmed.slice(1).trim() : trimmed;
+  const value = /^[A-Za-z_][A-Za-z0-9_-]*$/.test(name)
+    ? values[name]
+    : undefined;
+  return negated ? isFalsyCommandTemplateValue(value) : value;
+}
+
+export function shouldRunCommandTemplateNode(
+  value: boolean | string | undefined,
+  values: Record<string, unknown>,
+): boolean {
+  if (value === undefined) return true;
+  if (typeof value === "boolean") return value;
+  const trimmed = value.trim();
+  if (!trimmed) return false;
+  const exact = /^\{([^{}]+)\}$/.exec(trimmed);
+  const resolved = exact
+    ? resolveCommandTemplateValue(exact[1], values, "command template when")
+    : resolveCommandTemplateCondition(trimmed, values);
+  return !isFalsyCommandTemplateValue(resolved);
+}
+
+function resolveCommandTemplateNullish(
+  content: string,
+  values: Record<string, unknown>,
+): string | undefined {
+  const coalescing = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\?\?(.*)$/);
+  if (!coalescing) return undefined;
+  const value = values[coalescing[1]];
+  return isFalsyCommandTemplateValue(value) ? coalescing[2] : String(value);
+}
+
+function resolveCommandTemplateTernary(
+  content: string,
+  values: Record<string, unknown>,
+): string | undefined {
+  const ternary = content.match(/^([^?:]+)\?([^:]*):(.*)$/);
+  if (!ternary) return undefined;
+  const condition = resolveCommandTemplateCondition(ternary[1], values);
+  return isFalsyCommandTemplateValue(condition) ? ternary[3] : ternary[2];
+}
+
 function resolveCommandTemplateValue(
   content: string,
   values: Record<string, unknown>,
   missingLabel: string,
   depth = 0,
 ): string | undefined {
-  if (depth > 5) throw new Error(`Command template value recursion exceeded: ${content}`);
-  const indexed = content.match(/^([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]$/);
+  if (depth > 5)
+    throw new Error(`Command template value recursion exceeded: ${content}`);
+  const nullish = resolveCommandTemplateNullish(content, values);
+  if (nullish !== undefined) return nullish;
+  const ternary = resolveCommandTemplateTernary(content, values);
+  if (ternary !== undefined) return ternary;
+  const indexed = content.match(
+    /^([A-Za-z_][A-Za-z0-9_-]*)\[([A-Za-z_][A-Za-z0-9_-]*|\d+)\]$/,
+  );
   if (indexed) {
     const source = values[indexed[1]];
-    const indexValue = /^\d+$/.test(indexed[2]) ? indexed[2] : values[indexed[2]];
+    const indexValue = /^\d+$/.test(indexed[2])
+      ? indexed[2]
+      : values[indexed[2]];
     const index = Number(indexValue);
-    if (!Array.isArray(source) || !Number.isInteger(index) || index < 0 || index >= source.length) {
+    if (
+      !Array.isArray(source) ||
+      !Number.isInteger(index) ||
+      index < 0 ||
+      index >= source.length
+    ) {
       throw new Error(`Missing ${missingLabel} value: ${content}`);
     }
     return String(source[index] ?? "");
@@ -449,8 +627,16 @@ function resolveCommandTemplateValue(
   if (simple) {
     if (Object.hasOwn(values, simple.name)) {
       const raw = values[simple.name] ?? "";
-      if (typeof raw === "string" && /^\{[^{}]+\}$/.test(raw)) {
-        return substituteCommandTemplateToken(raw, values, missingLabel, depth + 1);
+      if (
+        typeof raw === "string" &&
+        shouldResolveEmbeddedCommandTemplateToken(raw, values)
+      ) {
+        return substituteCommandTemplateToken(
+          raw,
+          values,
+          missingLabel,
+          depth + 1,
+        );
       }
       return Array.isArray(raw) ? JSON.stringify(raw) : String(raw);
     }
@@ -467,14 +653,16 @@ export function substituteCommandTemplateToken(
   missingLabel = "command template",
   depth = 0,
 ): string {
-  return token.replace(
-    /\{([^{}]+)\}/g,
-    (_match, content: string) => {
-      const resolved = resolveCommandTemplateValue(content, values, missingLabel, depth);
-      if (resolved !== undefined) return resolved;
-      throw new Error(`Missing ${missingLabel} value: ${content}`);
-    },
-  );
+  return token.replace(/\{([^{}]+)\}/g, (_match, content: string) => {
+    const resolved = resolveCommandTemplateValue(
+      content,
+      values,
+      missingLabel,
+      depth,
+    );
+    if (resolved !== undefined) return resolved;
+    throw new Error(`Missing ${missingLabel} value: ${content}`);
+  });
 }
 
 export async function execCommandTemplate(
@@ -601,6 +789,7 @@ export function buildCommandTemplateInvocation(
         resolvedValues,
         options.missingLabel,
       ),
-    );
+    )
+    .filter((part) => part !== "");
   return { command, args };
 }

package/lib/config.ts

@@ -30,9 +30,8 @@ export type TelegramOutboundCommandTemplateConfig =
 export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
   type?: string;
   match?: string | string[];
-  pipe?: TelegramOutboundCommandTemplateConfig[];
   output?: string;
-  timeout?: number;
+  timeout?: number | string;
 }
 
 export type TelegramTimeMode = "hidden" | "always" | "interval";