@llblab/pi-telegram 0.12.0 → 0.13.0

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,

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";

package/lib/inbound.ts

@@ -11,6 +11,7 @@ import {
   buildCommandTemplateInvocation,
   expandCommandTemplateConfigs,
   normalizeCommandTemplateConfig,
+  substituteCommandTemplateToken,
   type CommandTemplateConfig,
   type CommandTemplateObjectConfig,
 } from "./command-templates.ts";
@@ -28,10 +29,9 @@ export interface TelegramInboundHandlerConfig {
   mime?: string | string[];
   type?: string | string[];
   template?: string | TelegramInboundCommandTemplateConfig[];
-  pipe?: TelegramInboundCommandTemplateConfig[];
   args?: string[];
   defaults?: Record<string, unknown>;
-  timeout?: number;
+  timeout?: number | string;
 }
 
 export interface TelegramInboundHandlerFile {
@@ -62,6 +62,7 @@ export interface TelegramInboundHandlerExecOptions {
   timeout?: number;
   signal?: AbortSignal;
   stdin?: string;
+  retry?: number;
 }
 
 export interface TelegramInboundHandlerExecResult {
@@ -322,13 +323,28 @@ export function buildTelegramInboundHandlerInvocation(
   );
 }
 
+function resolveTelegramInboundNumericControlField(
+  value: number | string | undefined,
+  values: Record<string, unknown>,
+  label: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const resolved =
+    typeof value === "string"
+      ? substituteCommandTemplateToken(value, values, label)
+      : value;
+  if (resolved === "") return undefined;
+  const numeric = Number(resolved);
+  if (!Number.isFinite(numeric) || numeric < 0)
+    throw new Error(`Command template ${label} must be a non-negative number.`);
+  return numeric;
+}
+
 function getTelegramInboundHandlerConfiguredTimeout(
   handler: TelegramInboundCommandTemplateConfig,
 ): number | undefined {
   const timeout = typeof handler === "string" ? undefined : handler.timeout;
-  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
-    ? timeout
-    : undefined;
+  return resolveTelegramInboundNumericControlField(timeout, {}, "timeout");
 }
 
 function getTelegramInboundHandlerTimeout(
@@ -374,8 +390,7 @@ function getTelegramInboundCompositionStepTimeout(
 function getTelegramInboundHandlerKind(
   handler: TelegramInboundHandlerConfig,
 ): string {
-  if (Array.isArray(handler.template) || handler.pipe?.length)
-    return "composition";
+  if (Array.isArray(handler.template)) return "composition";
   if (handler.template) return "template";
   return "unknown";
 }
@@ -410,7 +425,7 @@ async function executeTelegramInboundHandlerInvocation(
     cwd,
     timeout,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: handler.retry }
+      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
       : {}),
     ...(stdin !== undefined ? { stdin } : {}),
   });
@@ -427,12 +442,6 @@ function getTelegramInboundHandlerCompositionSteps(
       handler,
     ) as TelegramInboundCommandTemplateConfig[];
   }
-  if (handler.pipe?.length) {
-    return expandCommandTemplateConfigs({
-      ...handler,
-      template: handler.pipe,
-    }) as TelegramInboundCommandTemplateConfig[];
-  }
   return [];
 }
 
@@ -490,7 +499,7 @@ async function executeTelegramTextHandlerInvocation(
     timeout,
     stdin: text,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: handler.retry }
+      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
       : {}),
   });
   if (result.code !== 0)
@@ -524,7 +533,7 @@ async function executeTelegramTextHandler(
           : getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
       );
     } catch (error) {
-      if (typeof step === "object" && step.critical) throw error;
+      if (typeof step === "object" && step.failure === "root") throw error;
       output = "";
     }
     if (index > 0 && !output) output = text;
@@ -682,7 +691,7 @@ async function executeTelegramInboundHandler(
         index === 0 ? undefined : output,
       );
     } catch (error) {
-      if (typeof step === "object" && step.critical) throw error;
+      if (typeof step === "object" && step.failure === "root") throw error;
       output = "";
     }
   }