@llblab/pi-telegram 0.11.1 → 0.12.0

package/lib/bindings.ts

@@ -0,0 +1,301 @@
+/**
+ * Telegram bridge binding composition
+ * Zones: telegram, pi agent, orchestration
+ * 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";
+import * as Keyboard from "./keyboard.ts";
+import * as Lifecycle from "./lifecycle.ts";
+import * as Locks from "./locks.ts";
+import * as Model from "./model.ts";
+import * as OutboundAttachments from "./outbound-attachments.ts";
+import * as OutboundHandlers from "./outbound.ts";
+import * as Pi from "./pi.ts";
+import * as Preview from "./preview.ts";
+import * as Prompts from "./prompts.ts";
+import * as Queue from "./queue.ts";
+import * as Replies from "./replies.ts";
+import * as Runtime from "./runtime.ts";
+import * as Setup from "./setup.ts";
+import * as Status from "./status.ts";
+
+type ActivePiModel = NonNullable<Pi.ExtensionContext["model"]>;
+
+type TelegramRuntimeEventRecorder = (
+  category: string,
+  error: unknown,
+  details?: Record<string, unknown>,
+) => void;
+
+type TelegramBridgeStatusUpdater =
+  Status.TelegramStatusRuntime<Pi.ExtensionContext>["updateStatus"];
+
+interface TelegramCommandsAndToolsBindingDeps {
+  pi: Pi.ExtensionAPI;
+  configStore: Config.TelegramConfigStore;
+  setup: Setup.TelegramSetupGuard;
+  activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
+  lockedPollingRuntime: Locks.TelegramLockedPollingRuntime<Pi.ExtensionContext>;
+  getStatusLines: () => string[];
+  updateStatus: TelegramBridgeStatusUpdater;
+  recordRuntimeEvent: TelegramRuntimeEventRecorder;
+}
+
+export function registerTelegramCommandsAndTools({
+  pi,
+  configStore,
+  setup,
+  activeTurnRuntime,
+  lockedPollingRuntime,
+  getStatusLines,
+  updateStatus,
+  recordRuntimeEvent,
+}: TelegramCommandsAndToolsBindingDeps): void {
+  OutboundAttachments.registerTelegramOutboundAttachmentTool(pi, {
+    getActiveTurn: activeTurnRuntime.get,
+    recordRuntimeEvent,
+  });
+
+  Commands.registerTelegramBridgeCommands(pi, {
+    promptForConfig: Setup.createTelegramSetupPromptRuntime({
+      getConfig: configStore.get,
+      setConfig: configStore.set,
+      setupGuard: setup,
+      getMe: Api.fetchTelegramBotIdentity,
+      persistConfig: configStore.persist,
+      startPolling: lockedPollingRuntime.start,
+      updateStatus,
+      recordRuntimeEvent,
+    }),
+    getStatusLines,
+    reloadConfig: configStore.load,
+    hasBotToken: configStore.hasBotToken,
+    startPolling: lockedPollingRuntime.start,
+    stopPolling: lockedPollingRuntime.stop,
+    updateStatus,
+  });
+}
+
+interface TelegramLifecycleBindingDeps {
+  pi: Pi.ExtensionAPI;
+  sessionLifecycleRuntime: Pick<
+    Lifecycle.TelegramLifecycleRegistrationDeps,
+    "onSessionStart" | "onSessionShutdown" | "onModelSelect"
+  >;
+  queueSessionLifecycle: Pick<
+    Lifecycle.TelegramLifecycleRegistrationDeps,
+    "onSessionShutdown"
+  >;
+  configStore: Pick<Config.TelegramConfigStore, "getOutboundHandlers">;
+  abort: Runtime.TelegramRuntimeAbortPort;
+  typing: Runtime.TelegramRuntimeTypingPort;
+  lifecycle: Runtime.TelegramRuntimeLifecyclePort;
+  activeTurnRuntime: Queue.TelegramActiveTurnStore<Queue.PendingTelegramTurn>;
+  telegramQueueStore: Queue.TelegramQueueStore<Pi.ExtensionContext>;
+  modelSwitchController: Model.TelegramModelSwitchController<
+    Pi.ExtensionContext,
+    Model.ScopedTelegramModel<ActivePiModel>
+  >;
+  previewRuntime: Preview.TelegramAssistantPreviewRuntime<
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >;
+  promptDispatchRuntime: Runtime.TelegramPromptDispatchRuntime<Pi.ExtensionContext>;
+  deferredQueueDispatchRuntime: Queue.TelegramDeferredQueueDispatchRuntime<Pi.ExtensionContext>;
+  lockOwnershipGuard: Pick<
+    Locks.TelegramLockOwnershipGuard<Pi.ExtensionContext>,
+    "ownsContext"
+  >;
+  buttonActionStore: OutboundHandlers.TelegramButtonActionStore;
+  callMultipart: OutboundHandlers.TelegramVoiceReplySenderDeps["sendMultipart"];
+  sendChatAction: NonNullable<
+    OutboundHandlers.TelegramVoiceReplySenderDeps["sendChatAction"]
+  >;
+  sendRecordVoiceAction: NonNullable<
+    OutboundHandlers.TelegramVoiceReplySenderDeps["sendRecordVoiceAction"]
+  >;
+  sendMarkdownReply: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["sendMarkdownReply"];
+  sendTextReply: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["sendTextReply"] &
+    NonNullable<OutboundHandlers.TelegramVoiceReplySenderDeps["sendTextReply"]>;
+  dispatchNextQueuedTelegramTurn: (ctx: Pi.ExtensionContext) => void;
+  answerGuestQuery: NonNullable<
+    Queue.TelegramAgentEndHookRuntimeDeps<
+      Queue.PendingTelegramTurn,
+      Pi.ExtensionContext,
+      Pi.AgentEndEvent["messages"][number],
+      Keyboard.TelegramInlineKeyboardMarkup
+    >["answerGuestQuery"]
+  >;
+  sendGuestReply: NonNullable<
+    Queue.TelegramAgentEndHookRuntimeDeps<
+      Queue.PendingTelegramTurn,
+      Pi.ExtensionContext,
+      Pi.AgentEndEvent["messages"][number],
+      Keyboard.TelegramInlineKeyboardMarkup
+    >["sendGuestReply"]
+  >;
+  finalizeMarkdownPreview: Queue.TelegramAgentEndHookRuntimeDeps<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    Pi.AgentEndEvent["messages"][number],
+    Keyboard.TelegramInlineKeyboardMarkup
+  >["finalizeMarkdownPreview"];
+  proactivePushChatIdGetter: () => number | undefined;
+  isProactivePushEnabled: () => boolean;
+  updateStatus: TelegramBridgeStatusUpdater;
+  recordRuntimeEvent: TelegramRuntimeEventRecorder;
+}
+
+export function registerTelegramLifecycleRuntimeHooks({
+  pi,
+  sessionLifecycleRuntime,
+  queueSessionLifecycle,
+  configStore,
+  abort,
+  typing,
+  lifecycle,
+  activeTurnRuntime,
+  telegramQueueStore,
+  modelSwitchController,
+  previewRuntime,
+  promptDispatchRuntime,
+  deferredQueueDispatchRuntime,
+  lockOwnershipGuard,
+  buttonActionStore,
+  callMultipart,
+  sendChatAction,
+  sendRecordVoiceAction,
+  sendMarkdownReply,
+  sendTextReply,
+  dispatchNextQueuedTelegramTurn,
+  answerGuestQuery,
+  sendGuestReply,
+  finalizeMarkdownPreview,
+  proactivePushChatIdGetter,
+  isProactivePushEnabled,
+  updateStatus,
+  recordRuntimeEvent,
+}: TelegramLifecycleBindingDeps): void {
+  const agentEndResetter = Runtime.createTelegramAgentEndResetter({
+    abort,
+    typing,
+    clearActiveTurn: activeTurnRuntime.clear,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    clearPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+  });
+  const queuedAttachmentSender =
+    OutboundAttachments.createTelegramQueuedOutboundAttachmentSender({
+      sendMultipart: callMultipart,
+      sendTextReply,
+      recordRuntimeEvent,
+    });
+  const outboundReplyPlanner =
+    OutboundHandlers.createTelegramOutboundReplyPlanner(buttonActionStore);
+  const outboundReplyArtifactSender =
+    OutboundHandlers.createTelegramOutboundReplyArtifactSender({
+      execCommand: CommandTemplates.execCommandTemplate,
+      sendMultipart: callMultipart,
+      sendTextReply,
+      sendChatAction,
+      sendRecordVoiceAction,
+      getHandlers: configStore.getOutboundHandlers,
+      recordRuntimeEvent,
+    });
+  const agentLifecycleHooks = Queue.createTelegramAgentLifecycleHooks<
+    Queue.PendingTelegramTurn,
+    Pi.ExtensionContext,
+    unknown,
+    Keyboard.TelegramInlineKeyboardMarkup
+  >({
+    setAbortHandler: Runtime.createTelegramContextAbortHandlerSetter(abort),
+    getQueuedItems: telegramQueueStore.getQueuedItems,
+    hasPendingDispatch: lifecycle.hasDispatchPending,
+    hasActiveTurn: activeTurnRuntime.has,
+    resetToolExecutions: lifecycle.resetActiveToolExecutions,
+    resetPendingModelSwitch: modelSwitchController.clearPendingSwitch,
+    setQueuedItems: telegramQueueStore.setQueuedItems,
+    clearDispatchPending: lifecycle.clearDispatchPending,
+    setActiveTurn: activeTurnRuntime.set,
+    createPreviewState: previewRuntime.resetState,
+    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    updateStatus,
+    getActiveTurn: activeTurnRuntime.get,
+    extractAssistant: Replies.extractLatestAssistantMessageText,
+    getPreserveQueuedTurnsAsHistory:
+      lifecycle.shouldPreserveQueuedTurnsAsHistory,
+    resetRuntimeState: agentEndResetter,
+    dispatchNextQueuedTelegramTurn,
+    requestDeferredDispatchNextQueuedTelegramTurn:
+      deferredQueueDispatchRuntime.request,
+    clearPreview: previewRuntime.clear,
+    setPreviewPendingText: previewRuntime.setPendingText,
+    finalizeMarkdownPreview,
+    sendMarkdownReply,
+    sendTextReply,
+    sendQueuedAttachments: queuedAttachmentSender,
+    answerGuestQuery,
+    sendGuestReply,
+    planOutboundReply: outboundReplyPlanner,
+    sendOutboundReplyArtifacts: outboundReplyArtifactSender,
+    isCurrentOwner: lockOwnershipGuard.ownsContext,
+    getDefaultChatId: proactivePushChatIdGetter,
+    isProactivePushEnabled,
+    recordRuntimeEvent,
+    getActiveToolExecutions: lifecycle.getActiveToolExecutions,
+    setActiveToolExecutions: lifecycle.setActiveToolExecutions,
+    triggerPendingModelSwitchAbort: modelSwitchController.triggerPendingAbort,
+  });
+
+  Lifecycle.setResetTransportReplyDedup(Replies.resetTransportReplyDedup);
+  const agentStartWithDedupReset = Lifecycle.createAgentStartDedupHook(
+    agentLifecycleHooks.onAgentStart,
+  );
+  const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
+    setCompactionInProgress: lifecycle.setCompactionInProgress,
+    updateStatus,
+    startTypingLoop: promptDispatchRuntime.startTypingLoop,
+    stopTypingLoop: typing.stop,
+    requestDeferredDispatchNextQueuedTelegramTurn:
+      deferredQueueDispatchRuntime.request,
+    dispatchNextQueuedTelegramTurn,
+    recordRuntimeEvent,
+  });
+  const messageActivityTypingHooks =
+    Lifecycle.createTelegramMessageActivityTypingHooks({
+      hasActiveTurn: activeTurnRuntime.has,
+      startTypingLoop: promptDispatchRuntime.startTypingLoop,
+      onMessageStart: previewRuntime.onMessageStart,
+      onMessageUpdate: previewRuntime.onMessageUpdate,
+    });
+  Lifecycle.registerTelegramLifecycleHooks(pi, {
+    ...sessionLifecycleRuntime,
+    ...agentLifecycleHooks,
+    async onSessionShutdown(event, ctx) {
+      compactionObserver.onSessionShutdown();
+      await queueSessionLifecycle.onSessionShutdown(event, ctx);
+    },
+    onSessionBeforeCompact: compactionObserver.onSessionBeforeCompact,
+    onSessionCompact: compactionObserver.onSessionCompact,
+    onAgentStart: agentStartWithDedupReset,
+    onBeforeAgentStart: Prompts.createTelegramProactiveBeforeAgentStartHook({
+      isProactivePushEnabled,
+      isCurrentOwner: lockOwnershipGuard.ownsContext,
+    }),
+    ...messageActivityTypingHooks,
+  });
+}

package/lib/command-templates.ts

@@ -8,9 +8,8 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 
-export const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
-
 export type CommandTemplateMode = "sequence" | "parallel";
+export type CommandTemplateFailureScope = "continue" | "branch" | "root";
 
 export interface CommandTemplateObjectConfig {
   label?: string;
@@ -23,7 +22,9 @@ export interface CommandTemplateObjectConfig {
   output?: string;
   retry?: number;
   critical?: boolean;
-  repeat?: number;
+  failure?: CommandTemplateFailureScope;
+  recover?: CommandTemplateValue;
+  repeat?: number | string;
 }
 
 export type CommandTemplateValue = string | CommandTemplateConfig[] | CommandTemplateObjectConfig;
@@ -72,23 +73,92 @@ export function normalizeCommandTemplateConfig(
   return typeof config === "string" ? { template: config } : config;
 }
 
+function normalizeRecoverConfig(
+  config: CommandTemplateValue | undefined,
+): CommandTemplateConfig | undefined {
+  if (config === undefined) return undefined;
+  return Array.isArray(config) ? { template: config } : config;
+}
+
 function normalizeCommandTemplateDefaults(
   defaults: Record<string, unknown> | undefined,
 ): Record<string, unknown> | undefined {
   if (!defaults) return undefined;
   const normalized: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(defaults)) {
-    normalized[key] =
-      value === undefined || value === null ? "" : String(value);
+    normalized[key] = Array.isArray(value)
+      ? value
+      : value === undefined || value === null ? "" : String(value);
   }
   return normalized;
 }
 
-function normalizeRepeat(value: number | undefined): number | undefined {
+export function resolveCommandTemplateRepeat(
+  value: number | string | undefined,
+  values: Record<string, unknown> = {},
+): 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;
+  if (typeof value === "number") {
+    if (!Number.isInteger(value) || value < 1)
+      throw new Error("Command template repeat must be a positive integer.");
+    return value;
+  }
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  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}.");
+}
+
+function getExecutableName(command: string | undefined): string {
+  if (!command) return "";
+  return command.split(/[\\/]/).pop()?.toLowerCase() ?? "";
+}
+
+function hasAnyFlag(args: string[], flags: string[]): boolean {
+  return args.some((arg) => flags.includes(arg));
+}
+
+function hasRiskyPathArg(args: string[]): boolean {
+  return args.some((arg) =>
+    arg === "/" ||
+    arg === "~" ||
+    arg === "./" ||
+    arg === "../" ||
+    arg.includes("{") ||
+    arg.startsWith("~/") ||
+    arg.startsWith("/"),
+  );
+}
+
+function getLeafCommandTemplateWarnings(
+  config: CommandTemplateLeafConfig,
+): string[] {
+  const parts = splitCommandTemplate(config.template);
+  const command = getExecutableName(parts[0]);
+  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.`);
+  }
+  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 (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.`);
+  }
+  return warnings;
 }
 
 function pad(value: number, width: number): string {
@@ -124,7 +194,7 @@ function expandRepeatConfig(
   config: CommandTemplateObjectConfig,
   context: Pick<CommandTemplateObjectConfig, "args" | "defaults">,
 ): CommandTemplateObjectConfig[] | undefined {
-  const repeat = normalizeRepeat(config.repeat);
+  const repeat = resolveCommandTemplateRepeat(config.repeat, context.defaults ?? {});
   if (repeat === undefined) return undefined;
   return Array.from({ length: repeat }, (_unused, index0) => {
     const { repeat: _repeat, ...rest } = config;
@@ -164,12 +234,19 @@ export function expandCommandTemplateConfigs(
   if (repeated) {
     return repeated.flatMap((step) => expandCommandTemplateConfigs(step, context));
   }
+  const recoverConfig = normalizeRecoverConfig(normalizedConfig.recover);
+  const recoverSteps = recoverConfig
+    ? expandCommandTemplateConfigs(recoverConfig, context)
+    : [];
   if (Array.isArray(normalizedConfig.template)) {
-    return normalizedConfig.template.flatMap((step) =>
-      expandCommandTemplateConfigs(step, context),
-    );
+    return [
+      ...normalizedConfig.template.flatMap((step) =>
+        expandCommandTemplateConfigs(step, context),
+      ),
+      ...recoverSteps,
+    ];
   }
-  if (typeof normalizedConfig.template !== "string") return [];
+  if (typeof normalizedConfig.template !== "string") return recoverSteps;
   return [
     {
       ...normalizedConfig,
@@ -178,9 +255,37 @@ export function expandCommandTemplateConfigs(
       retry: normalizedConfig.retry,
       critical: normalizedConfig.critical,
     },
+    ...recoverSteps,
   ];
 }
 
+export function getCommandTemplateWarnings(
+  config: CommandTemplateConfig,
+): string[] {
+  return [
+    ...new Set(
+      expandCommandTemplateConfigs(config)
+        .flatMap((leaf) => getLeafCommandTemplateWarnings(leaf)),
+    ),
+  ];
+}
+
+function parseCommandTemplateArgToken(value: string): { name: string; defaultValue?: string } {
+  const separatorIndex = value.indexOf("=");
+  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() }),
+  };
+}
+
+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] } : {}) };
+}
+
 export function getCommandTemplateDefaults(
   config: CommandTemplateConfig | undefined,
 ): Record<string, string> {
@@ -190,9 +295,9 @@ export function getCommandTemplateDefaults(
   const defaults: Record<string, string> = {};
   for (const item of normalizeCommandTemplateArgs(normalizedConfig?.args)) {
     if (!item) continue;
-    const [name, ...defaultParts] = item.split("=");
-    if (!name || defaultParts.length === 0) continue;
-    defaults[name.trim()] = defaultParts.join("=").trim();
+    const parsed = parseCommandTemplateArgToken(item);
+    if (!parsed.name || parsed.defaultValue === undefined) continue;
+    defaults[parsed.name] = parsed.defaultValue;
   }
   for (const [key, value] of Object.entries(normalizedConfig?.defaults ?? {})) {
     defaults[key] = value === undefined || value === null ? "" : String(value);
@@ -256,7 +361,7 @@ export function expandCommandTemplateExecutable(
 
 function evaluateCommandTemplateExpression(
   expression: string,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
 ): number {
   let index = 0;
   const source = expression.replace(/\s+/g, "");
@@ -283,7 +388,7 @@ function evaluateCommandTemplateExpression(
     if (nameMatch) {
       index += nameMatch[0].length;
       const value = values[nameMatch[0]];
-      if (value === undefined || !/^-?\d+$/.test(value))
+      if (value === undefined || !/^-?\d+$/.test(String(value)))
         throw new Error(`Invalid command template expression variable: ${nameMatch[0]}`);
       return Number(value);
     }
@@ -313,7 +418,7 @@ function evaluateCommandTemplateExpression(
 
 function substituteCommandTemplateExpression(
   content: string,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
 ): string | undefined {
   const padded = content.match(/^(_{1,6})\((.+)\)$/);
   if (padded) {
@@ -323,22 +428,50 @@ function substituteCommandTemplateExpression(
   return String(evaluateCommandTemplateExpression(content, values));
 }
 
+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 (indexed) {
+    const source = values[indexed[1]];
+    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) {
+      throw new Error(`Missing ${missingLabel} value: ${content}`);
+    }
+    return String(source[index] ?? "");
+  }
+  const simple = parseCommandTemplatePlaceholderContent(content);
+  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);
+      }
+      return Array.isArray(raw) ? JSON.stringify(raw) : String(raw);
+    }
+    if (simple.inlineDefault !== undefined) return simple.inlineDefault;
+  }
+  const expression = substituteCommandTemplateExpression(content, values);
+  if (expression !== undefined) return expression;
+  return undefined;
+}
+
 export function substituteCommandTemplateToken(
   token: string,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
   missingLabel = "command template",
+  depth = 0,
 ): string {
   return token.replace(
     /\{([^{}]+)\}/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;
+      const resolved = resolveCommandTemplateValue(content, values, missingLabel, depth);
+      if (resolved !== undefined) return resolved;
       throw new Error(`Missing ${missingLabel} value: ${content}`);
     },
   );
@@ -405,8 +538,6 @@ function execCommandTemplateOnce(
     }
     if (options.timeout !== undefined && options.timeout > 0)
       timeoutId = setTimeout(killProcess, options.timeout);
-    else if (options.timeout === undefined)
-      timeoutId = setTimeout(killProcess, DEFAULT_COMMAND_TIMEOUT_MS);
     proc.stdout?.on("data", (data) => {
       stdout += data.toString();
     });
@@ -427,7 +558,7 @@ function execCommandTemplateOnce(
 
 export function buildCommandTemplateInvocation(
   config: CommandTemplateConfig,
-  values: Record<string, string>,
+  values: Record<string, unknown>,
   cwd: string,
   options: { emptyMessage?: string; missingLabel?: string } = {},
 ): CommandTemplateInvocation {