@llblab/pi-telegram 0.5.2 → 0.6.0

package/lib/{handlers.ts → attachment-handlers.ts}

@@ -3,19 +3,31 @@
  * Owns MIME/type matching, command-template execution, fallback handling, and prompt injection before prompt enqueueing
  */
 
-import { homedir } from "node:os";
-import { basename, isAbsolute, resolve } from "node:path";
+import { basename } from "node:path";
+
+import {
+  buildCommandTemplateInvocation,
+  expandCommandTemplateConfigs,
+  normalizeCommandTemplateConfig,
+  type CommandTemplateConfig,
+  type CommandTemplateObjectConfig,
+} from "./command-templates.ts";
 
 const DEFAULT_ATTACHMENT_HANDLER_TIMEOUT_MS = 120_000;
 
+type TelegramAttachmentCommandTemplateConfig =
+  | string
+  | CommandTemplateObjectConfig;
+
 export interface TelegramAttachmentHandlerConfig {
   match?: string | string[];
   mime?: string | string[];
   type?: string | string[];
-  template?: string;
-  args?: string | string[];
+  template?: string | TelegramAttachmentCommandTemplateConfig[];
+  pipe?: TelegramAttachmentCommandTemplateConfig[];
+  args?: string[];
   defaults?: Record<string, unknown>;
-  timeoutMs?: number;
+  timeout?: number;
 }
 
 export interface TelegramAttachmentHandlerFile {
@@ -45,6 +57,7 @@ export interface TelegramAttachmentHandlerExecOptions {
   cwd?: string;
   timeout?: number;
   signal?: AbortSignal;
+  stdin?: string;
 }
 
 export interface TelegramAttachmentHandlerExecResult {
@@ -163,151 +176,96 @@ function hasAttachmentFilePlaceholder(value: string): boolean {
   return /\{file\}/.test(value);
 }
 
-function normalizeTelegramAttachmentHandlerArgs(
-  value: string | string[] | undefined,
-): string[] {
-  if (Array.isArray(value)) return value.map(String).map((item) => item.trim());
-  if (typeof value !== "string") return [];
-  return value.split(",").map((item) => item.trim());
-}
-
-function getTelegramAttachmentHandlerArgDefaults(
-  handler: TelegramAttachmentHandlerConfig,
-): Record<string, string> {
-  const defaults: Record<string, string> = {};
-  for (const item of normalizeTelegramAttachmentHandlerArgs(handler.args)) {
-    if (!item) continue;
-    const [name, ...defaultParts] = item.split("=");
-    if (!name || defaultParts.length === 0) continue;
-    defaults[name.trim()] = defaultParts.join("=").trim();
-  }
-  for (const [key, value] of Object.entries(handler.defaults ?? {})) {
-    defaults[key] = value === undefined || value === null ? "" : String(value);
-  }
-  return defaults;
-}
-
 function getTelegramAttachmentHandlerTemplateValues(
-  handler: TelegramAttachmentHandlerConfig,
   file: TelegramAttachmentHandlerFile,
 ): Record<string, string> {
   return {
-    ...getTelegramAttachmentHandlerArgDefaults(handler),
     file: file.path,
     mime: file.mimeType ?? "",
     type: file.kind ?? "",
   };
 }
 
-function substituteTelegramAttachmentHandlerTemplateToken(
-  token: string,
-  values: Record<string, string>,
-): string {
-  return token.replace(/\{([A-Za-z_][A-Za-z0-9_-]*)\}/g, (_match, name) => {
-    if (Object.hasOwn(values, name)) return values[name] ?? "";
-    throw new Error(`Missing attachment handler template value: ${name}`);
-  });
-}
-
-export function splitTelegramAttachmentHandlerTemplate(input: string): string[] {
-  const words: string[] = [];
-  let current = "";
-  let quote: "'" | '"' | undefined;
-  let escaped = false;
-  let active = false;
-  for (const char of input) {
-    if (escaped) {
-      current += char;
-      escaped = false;
-      active = true;
-      continue;
-    }
-    if (char === "\\" && quote !== "'") {
-      escaped = true;
-      active = true;
-      continue;
-    }
-    if (quote) {
-      if (char === quote) quote = undefined;
-      else current += char;
-      active = true;
-      continue;
-    }
-    if (char === "'" || char === '"') {
-      quote = char;
-      active = true;
-      continue;
-    }
-    if (/\s/.test(char)) {
-      if (active) words.push(current);
-      if (active) current = "";
-      active = false;
-      continue;
-    }
-    current += char;
-    active = true;
-  }
-  if (escaped) current += "\\";
-  if (active || current) words.push(current);
-  return words;
-}
-
-function expandExecutablePath(command: string, cwd: string): string {
-  if (command === "~") return homedir();
-  if (command.startsWith("~/")) return resolve(homedir(), command.slice(2));
-  if (command.includes("/") && !isAbsolute(command)) {
-    return resolve(cwd, command);
-  }
-  return command;
-}
-
 function buildTelegramAttachmentTemplateInvocation(
-  template: string,
-  handler: TelegramAttachmentHandlerConfig,
+  handler: CommandTemplateConfig,
   file: TelegramAttachmentHandlerFile,
   cwd: string,
+  appendFileIfMissing = true,
 ): AttachmentHandlerInvocation {
-  const parts = splitTelegramAttachmentHandlerTemplate(template);
-  const commandPart = parts[0];
-  if (!commandPart) throw new Error("Attachment handler template is empty");
-  const values = getTelegramAttachmentHandlerTemplateValues(handler, file);
-  const hadFilePlaceholder = parts.some(hasAttachmentFilePlaceholder);
-  const command = expandExecutablePath(
-    substituteTelegramAttachmentHandlerTemplateToken(commandPart, values),
-    cwd,
-  );
-  const args = parts
-    .slice(1)
-    .map((part) =>
-      substituteTelegramAttachmentHandlerTemplateToken(part, values),
-    );
-  if (!hadFilePlaceholder) args.push(file.path);
-  return { command, args };
+  const values = getTelegramAttachmentHandlerTemplateValues(file);
+  const templateConfig = normalizeCommandTemplateConfig(handler);
+  const hadFilePlaceholder =
+    typeof templateConfig.template === "string"
+      ? hasAttachmentFilePlaceholder(templateConfig.template)
+      : false;
+  const invocation = buildCommandTemplateInvocation(handler, values, cwd, {
+    emptyMessage: "Attachment handler template is empty",
+    missingLabel: "attachment handler template",
+  });
+  if (appendFileIfMissing && !hadFilePlaceholder)
+    invocation.args.push(file.path);
+  return invocation;
 }
 
 export function buildTelegramAttachmentHandlerInvocation(
-  handler: TelegramAttachmentHandlerConfig,
+  handler: CommandTemplateConfig,
   file: TelegramAttachmentHandlerFile,
   cwd: string,
+  appendFileIfMissing = true,
 ): AttachmentHandlerInvocation {
-  const { template } = handler;
+  const { template } = normalizeCommandTemplateConfig(handler);
   if (!template) throw new Error("Attachment handler template is required");
-  return buildTelegramAttachmentTemplateInvocation(template, handler, file, cwd);
+  return buildTelegramAttachmentTemplateInvocation(
+    handler,
+    file,
+    cwd,
+    appendFileIfMissing,
+  );
+}
+
+function getTelegramAttachmentHandlerConfiguredTimeout(
+  handler: TelegramAttachmentCommandTemplateConfig,
+): number | undefined {
+  const timeout = typeof handler === "string" ? undefined : handler.timeout;
+  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
+    ? timeout
+    : undefined;
 }
 
 function getTelegramAttachmentHandlerTimeout(
+  handler: TelegramAttachmentCommandTemplateConfig,
+): number {
+  return (
+    getTelegramAttachmentHandlerConfiguredTimeout(handler) ??
+    DEFAULT_ATTACHMENT_HANDLER_TIMEOUT_MS
+  );
+}
+
+function getRemainingTelegramAttachmentTimeout(
+  timeout: number,
+  startedAt: number,
+): number {
+  return Math.max(1, timeout - (Date.now() - startedAt));
+}
+
+function getTelegramAttachmentCompositionStepTimeout(
   handler: TelegramAttachmentHandlerConfig,
+  step: TelegramAttachmentCommandTemplateConfig,
+  startedAt: number,
 ): number {
-  return typeof handler.timeoutMs === "number" &&
-    Number.isFinite(handler.timeoutMs) &&
-    handler.timeoutMs > 0
-    ? handler.timeoutMs
-    : DEFAULT_ATTACHMENT_HANDLER_TIMEOUT_MS;
+  const remaining = getRemainingTelegramAttachmentTimeout(
+    getTelegramAttachmentHandlerTimeout(handler),
+    startedAt,
+  );
+  const stepTimeout = getTelegramAttachmentHandlerConfiguredTimeout(step);
+  return stepTimeout === undefined ? remaining : Math.min(stepTimeout, remaining);
 }
 
 function getTelegramAttachmentHandlerKind(
   handler: TelegramAttachmentHandlerConfig,
 ): string {
+  if (Array.isArray(handler.template) || handler.pipe?.length)
+    return "composition";
   if (handler.template) return "template";
   return "unknown";
 }
@@ -323,24 +281,78 @@ function formatTelegramAttachmentHandlerFailure(
   return parts.join("\n\n");
 }
 
-async function executeTelegramAttachmentHandler(
-  handler: TelegramAttachmentHandlerConfig,
+async function executeTelegramAttachmentHandlerInvocation(
+  handler: TelegramAttachmentCommandTemplateConfig,
   file: TelegramAttachmentHandlerFile,
   cwd: string,
   deps: Pick<TelegramAttachmentHandlerRuntimeDeps<unknown>, "execCommand">,
+  appendFileIfMissing = true,
+  timeout = getTelegramAttachmentHandlerTimeout(handler),
+  stdin?: string,
 ): Promise<string> {
   const invocation = buildTelegramAttachmentHandlerInvocation(
     handler,
     file,
     cwd,
+    appendFileIfMissing,
   );
   const result = await deps.execCommand(invocation.command, invocation.args, {
     cwd,
-    timeout: getTelegramAttachmentHandlerTimeout(handler),
+    timeout,
+    ...(stdin !== undefined ? { stdin } : {}),
   });
   if (result.code !== 0)
     throw new Error(formatTelegramAttachmentHandlerFailure(result));
-  return result.stdout.trim();
+  return result.stdout;
+}
+
+function getTelegramAttachmentHandlerCompositionSteps(
+  handler: TelegramAttachmentHandlerConfig,
+): TelegramAttachmentCommandTemplateConfig[] {
+  if (Array.isArray(handler.template)) {
+    return expandCommandTemplateConfigs(
+      handler,
+    ) as TelegramAttachmentCommandTemplateConfig[];
+  }
+  if (handler.pipe?.length) {
+    return expandCommandTemplateConfigs({
+      ...handler,
+      template: handler.pipe,
+    }) as TelegramAttachmentCommandTemplateConfig[];
+  }
+  return [];
+}
+
+async function executeTelegramAttachmentHandler(
+  handler: TelegramAttachmentHandlerConfig,
+  file: TelegramAttachmentHandlerFile,
+  cwd: string,
+  deps: Pick<TelegramAttachmentHandlerRuntimeDeps<unknown>, "execCommand">,
+): Promise<string> {
+  const steps = getTelegramAttachmentHandlerCompositionSteps(handler);
+  if (steps.length === 0) {
+    const output = await executeTelegramAttachmentHandlerInvocation(
+      handler,
+      file,
+      cwd,
+      deps,
+    );
+    return output.trim();
+  }
+  const startedAt = Date.now();
+  let output = "";
+  for (const [index, step] of steps.entries()) {
+    output = await executeTelegramAttachmentHandlerInvocation(
+      step,
+      file,
+      cwd,
+      deps,
+      false,
+      getTelegramAttachmentCompositionStepTimeout(handler, step, startedAt),
+      index === 0 ? undefined : output,
+    );
+  }
+  return output.trim();
 }
 
 export async function processTelegramAttachmentHandlers<

package/lib/command-templates.ts

@@ -0,0 +1,292 @@
+/**
+ * Command-template standard helpers
+ * Owns shell-free command-template splitting, placeholder defaults, composition expansion, executable path expansion, and direct execution
+ */
+
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+
+export interface CommandTemplateObjectConfig {
+  template?: CommandTemplateValue;
+  args?: string[];
+  defaults?: Record<string, unknown>;
+  timeout?: number;
+  output?: string;
+}
+
+export type CommandTemplateValue = string | CommandTemplateConfig[];
+
+export type CommandTemplateConfig = string | CommandTemplateObjectConfig;
+
+export interface CommandTemplateLeafConfig extends CommandTemplateObjectConfig {
+  template: string;
+}
+
+export interface CommandTemplateInvocation {
+  command: string;
+  args: string[];
+}
+
+export interface CommandTemplateExecOptions {
+  cwd?: string;
+  timeout?: number;
+  signal?: AbortSignal;
+  stdin?: string;
+}
+
+export interface CommandTemplateExecResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  killed: boolean;
+}
+
+export type CommandTemplateExecCommand = (
+  command: string,
+  args: string[],
+  options?: CommandTemplateExecOptions,
+) => Promise<CommandTemplateExecResult>;
+
+function normalizeCommandTemplateArgs(value: string[] | undefined): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.map(String).map((item) => item.trim());
+}
+
+export function normalizeCommandTemplateConfig(
+  config: CommandTemplateConfig,
+): CommandTemplateObjectConfig {
+  return typeof config === "string" ? { 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);
+  }
+  return normalized;
+}
+
+export function expandCommandTemplateConfigs(
+  config: CommandTemplateConfig,
+  inherited: Pick<CommandTemplateObjectConfig, "args" | "defaults"> = {},
+): CommandTemplateLeafConfig[] {
+  const normalizedConfig = normalizeCommandTemplateConfig(config);
+  const inheritedDefaults = normalizeCommandTemplateDefaults(
+    inherited.defaults,
+  );
+  const ownDefaults = normalizeCommandTemplateDefaults(
+    normalizedConfig.defaults,
+  );
+  const context = {
+    ...(inherited.args !== undefined ? { args: inherited.args } : {}),
+    ...(inheritedDefaults ? { defaults: inheritedDefaults } : {}),
+    ...(normalizedConfig.args !== undefined
+      ? { args: normalizedConfig.args }
+      : {}),
+    ...(ownDefaults
+      ? { defaults: { ...(inheritedDefaults ?? {}), ...ownDefaults } }
+      : {}),
+  };
+  if (Array.isArray(normalizedConfig.template)) {
+    return normalizedConfig.template.flatMap((step) =>
+      expandCommandTemplateConfigs(step, context),
+    );
+  }
+  if (typeof normalizedConfig.template !== "string") return [];
+  return [
+    { ...normalizedConfig, ...context, template: normalizedConfig.template },
+  ];
+}
+
+export function getCommandTemplateDefaults(
+  config: CommandTemplateConfig | undefined,
+): Record<string, string> {
+  const normalizedConfig = config
+    ? normalizeCommandTemplateConfig(config)
+    : undefined;
+  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();
+  }
+  for (const [key, value] of Object.entries(normalizedConfig?.defaults ?? {})) {
+    defaults[key] = value === undefined || value === null ? "" : String(value);
+  }
+  return defaults;
+}
+
+export function splitCommandTemplate(input: string): string[] {
+  const words: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  let escaped = false;
+  let active = false;
+  for (const char of input) {
+    if (escaped) {
+      current += char;
+      escaped = false;
+      active = true;
+      continue;
+    }
+    if (char === "\\" && quote !== "'") {
+      escaped = true;
+      active = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) quote = undefined;
+      else current += char;
+      active = true;
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      active = true;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (active) words.push(current);
+      if (active) current = "";
+      active = false;
+      continue;
+    }
+    current += char;
+    active = true;
+  }
+  if (escaped) current += "\\";
+  if (active || current) words.push(current);
+  return words;
+}
+
+export function expandCommandTemplateExecutable(
+  command: string,
+  cwd: string,
+): string {
+  if (command === "~") return homedir();
+  if (command.startsWith("~/")) return resolve(homedir(), command.slice(2));
+  if (command.includes("/") && !isAbsolute(command))
+    return resolve(cwd, command);
+  return command;
+}
+
+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}`);
+    },
+  );
+}
+
+export function execCommandTemplate(
+  command: string,
+  args: string[],
+  options: CommandTemplateExecOptions = {},
+): Promise<CommandTemplateExecResult> {
+  return new Promise((resolve) => {
+    const proc = spawn(command, args, {
+      cwd: options.cwd,
+      shell: false,
+      stdio: [options.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    let settled = false;
+    let timeoutId: NodeJS.Timeout | undefined;
+    const killProcess = (): void => {
+      if (killed) return;
+      killed = true;
+      proc.kill("SIGTERM");
+      setTimeout(() => {
+        if (!proc.killed) proc.kill("SIGKILL");
+      }, 5000);
+    };
+    const settle = (code: number): void => {
+      if (settled) return;
+      settled = true;
+      if (timeoutId) clearTimeout(timeoutId);
+      if (options.signal)
+        options.signal.removeEventListener("abort", killProcess);
+      resolve({ stdout, stderr, code, killed });
+    };
+    if (options.signal) {
+      if (options.signal.aborted) killProcess();
+      else
+        options.signal.addEventListener("abort", killProcess, { once: true });
+    }
+    if (options.timeout && options.timeout > 0)
+      timeoutId = setTimeout(killProcess, options.timeout);
+    proc.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.stdin?.on("error", () => {});
+    if (options.stdin !== undefined) proc.stdin?.end(options.stdin);
+    proc.on("error", (error) => {
+      stderr += error instanceof Error ? error.message : String(error);
+      settle(1);
+    });
+    proc.on("close", (code) => {
+      settle(code ?? (killed ? 1 : 0));
+    });
+  });
+}
+
+export function buildCommandTemplateInvocation(
+  config: CommandTemplateConfig,
+  values: Record<string, string>,
+  cwd: string,
+  options: { emptyMessage?: string; missingLabel?: string } = {},
+): CommandTemplateInvocation {
+  const normalizedConfig = normalizeCommandTemplateConfig(config);
+  if (Array.isArray(normalizedConfig.template)) {
+    throw new Error(
+      options.emptyMessage ??
+        "Command template sequence cannot be executed as one command",
+    );
+  }
+  if (!normalizedConfig.template)
+    throw new Error(options.emptyMessage ?? "Command template is required");
+  const parts = splitCommandTemplate(normalizedConfig.template);
+  const commandPart = parts[0];
+  if (!commandPart)
+    throw new Error(options.emptyMessage ?? "Command template is empty");
+  const resolvedValues = {
+    ...getCommandTemplateDefaults(normalizedConfig),
+    ...values,
+  };
+  const command = expandCommandTemplateExecutable(
+    substituteCommandTemplateToken(
+      commandPart,
+      resolvedValues,
+      options.missingLabel,
+    ),
+    cwd,
+  );
+  const args = parts
+    .slice(1)
+    .map((part) =>
+      substituteCommandTemplateToken(
+        part,
+        resolvedValues,
+        options.missingLabel,
+      ),
+    );
+  return { command, args };
+}

package/lib/config.ts

@@ -7,7 +7,8 @@ import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
-import type { TelegramAttachmentHandlerConfig } from "./handlers.ts";
+import type { TelegramAttachmentHandlerConfig } from "./attachment-handlers.ts";
+import type { CommandTemplateObjectConfig } from "./command-templates.ts";
 
 function getAgentDir(): string {
   return process.env.PI_CODING_AGENT_DIR
@@ -19,6 +20,17 @@ function getConfigPath(): string {
   return join(getAgentDir(), "telegram.json");
 }
 
+export type TelegramOutboundCommandTemplateConfig =
+  | string
+  | CommandTemplateObjectConfig;
+export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
+  type?: string;
+  match?: string | string[];
+  pipe?: TelegramOutboundCommandTemplateConfig[];
+  output?: string;
+  timeout?: number;
+}
+
 export interface TelegramConfig {
   botToken?: string;
   botUsername?: string;
@@ -26,6 +38,7 @@ export interface TelegramConfig {
   allowedUserId?: number;
   lastUpdateId?: number;
   attachmentHandlers?: TelegramAttachmentHandlerConfig[];
+  outboundHandlers?: TelegramOutboundHandlerConfig[];
 }
 
 export interface TelegramConfigStore {
@@ -36,6 +49,7 @@ export interface TelegramConfigStore {
   hasBotToken: () => boolean;
   getAllowedUserId: () => number | undefined;
   getAttachmentHandlers: () => TelegramAttachmentHandlerConfig[] | undefined;
+  getOutboundHandlers: () => TelegramOutboundHandlerConfig[] | undefined;
   setAllowedUserId: (userId: number) => void;
   load: () => Promise<void>;
   persist: (config?: TelegramConfig) => Promise<void>;
@@ -89,6 +103,7 @@ export function createTelegramConfigStore(
     hasBotToken: () => !!config.botToken,
     getAllowedUserId: () => config.allowedUserId,
     getAttachmentHandlers: () => config.attachmentHandlers,
+    getOutboundHandlers: () => config.outboundHandlers,
     setAllowedUserId: (userId) => {
       config.allowedUserId = userId;
     },