kiro-telegram-bot 1.5.1

package/src/acp/types.ts

@@ -0,0 +1,136 @@
+/**
+ * Agent Client Protocol (ACP) type definitions for the Kiro CLI agent.
+ * Wire format: newline-delimited JSON-RPC 2.0 over stdio.
+ * @see https://agentclientprotocol.com  @see https://kiro.dev/docs/cli/acp/
+ */
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: number | string;
+  method: string;
+  params?: unknown;
+}
+
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: number | string;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+
+export type JsonRpcMessage = JsonRpcResponse & JsonRpcNotification & { method?: string };
+
+/** A content block in a prompt or message. */
+export interface ContentBlock {
+  type: "text" | "image" | "resource";
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  [k: string]: unknown;
+}
+
+export interface InitializeResult {
+  protocolVersion: number;
+  agentCapabilities?: {
+    loadSession?: boolean;
+    promptCapabilities?: { image?: boolean };
+  };
+  agentInfo?: { name?: string; version?: string };
+}
+
+export interface NewSessionResult {
+  sessionId: string;
+}
+
+export interface PromptResult {
+  stopReason?: string; // e.g. "end_turn", "cancelled", "max_tokens"
+}
+
+/** session/update notification payload. */
+export interface SessionUpdate {
+  sessionUpdate:
+    | "agent_message_chunk"
+    | "agent_thought_chunk"
+    | "tool_call"
+    | "tool_call_update"
+    | "plan"
+    | "user_message_chunk"
+    | string;
+  content?: ContentBlock;
+  // tool_call / tool_call_update fields
+  toolCallId?: string;
+  title?: string;
+  kind?: string; // "read" | "edit" | "execute" | "search" | ...
+  status?: "pending" | "in_progress" | "completed" | "failed" | string;
+  rawInput?: Record<string, unknown>;
+  content_blocks?: ToolCallContent[];
+  // ACP also nests content for tool calls as `content`
+  [k: string]: unknown;
+}
+
+/** A piece of tool-call content (text, diff, etc.). */
+export interface ToolCallContent {
+  type: "content" | "diff" | string;
+  path?: string;
+  oldText?: string | null;
+  newText?: string;
+  content?: ContentBlock;
+  [k: string]: unknown;
+}
+
+export interface SessionNotificationParams {
+  sessionId: string;
+  update: SessionUpdate;
+}
+
+/** Permission request from the agent (server -> client). */
+export interface RequestPermissionParams {
+  sessionId: string;
+  toolCall?: { toolCallId?: string; title?: string; kind?: string; rawInput?: Record<string, unknown> };
+  options: Array<{ optionId: string; name: string; kind?: string }>;
+}
+
+export type PermissionOutcome =
+  | { outcome: { outcome: "selected"; optionId: string } }
+  | { outcome: { outcome: "cancelled" } };
+
+/**
+ * One subagent ("crew" member) as reported by Kiro's
+ * `_kiro.dev/subagent/list_update` notification. The list is process-global
+ * (it is not scoped to a parent session id on the wire).
+ */
+export interface SubagentInfo {
+  /** The subagent's own session id (distinct from the parent session). */
+  sessionId: string;
+  sessionName?: string;
+  agentName?: string;
+  role?: string;
+  initialQuery?: string;
+  status?: { type?: string; message?: string };
+  group?: string;
+  dependsOn?: string[];
+  hasLoop?: boolean;
+  loopIteration?: number;
+  loopMaxIterations?: number;
+  createdAtMs?: number;
+}
+
+/** A not-yet-started pipeline stage reported alongside the subagent list. */
+export interface PendingStage {
+  name?: string;
+  role?: string;
+  agentName?: string;
+  dependsOn?: string[];
+  [k: string]: unknown;
+}
+
+export interface SubagentListUpdate {
+  subagents?: SubagentInfo[];
+  pendingStages?: PendingStage[];
+}

package/src/agents/catalog.ts

@@ -0,0 +1,44 @@
+/**
+ * Discover Kiro custom agents from disk: the global ~/.kiro/agents and the
+ * selected project's .kiro/agents directory.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("agents");
+
+export interface AgentInfo {
+  name: string;
+  description?: string;
+  scope: "project" | "global";
+}
+
+export function listAgents(projectPath?: string): AgentInfo[] {
+  const found = new Map<string, AgentInfo>();
+  if (projectPath) scan(join(projectPath, ".kiro", "agents"), "project", found);
+  scan(join(homedir(), ".kiro", "agents"), "global", found);
+  return [...found.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function scan(dir: string, scope: "project" | "global", out: Map<string, AgentInfo>): void {
+  let files: string[];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".json"));
+  } catch {
+    return;
+  }
+  for (const file of files) {
+    const name = basename(file, ".json");
+    if (out.has(name)) continue;
+    let description: string | undefined;
+    try {
+      const json = JSON.parse(readFileSync(join(dir, file), "utf-8")) as { description?: string };
+      description = json.description;
+    } catch (e) {
+      log.debug(`skip ${file}:`, (e as Error).message);
+    }
+    out.set(name, { name, description, scope });
+  }
+}

package/src/app/json-store.ts

@@ -0,0 +1,54 @@
+/**
+ * Minimal atomic JSON persistence. Reads on construction, writes atomically
+ * (temp file + rename) on save. No external dependencies.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("json-store");
+
+export class JsonStore<T> {
+  private data: T;
+
+  constructor(
+    private readonly path: string,
+    private readonly fallback: T,
+  ) {
+    this.data = this.read();
+  }
+
+  get(): T {
+    return this.data;
+  }
+
+  set(data: T): void {
+    this.data = data;
+    this.save();
+  }
+
+  /** Mutate via a callback, then persist. */
+  update(fn: (data: T) => void): void {
+    fn(this.data);
+    this.save();
+  }
+
+  private read(): T {
+    try {
+      return JSON.parse(readFileSync(this.path, "utf-8")) as T;
+    } catch {
+      return structuredClone(this.fallback);
+    }
+  }
+
+  private save(): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true });
+      const tmp = `${this.path}.tmp`;
+      writeFileSync(tmp, JSON.stringify(this.data, null, 2), "utf-8");
+      renameSync(tmp, this.path);
+    } catch (e) {
+      log.error(`failed to save ${this.path}:`, (e as Error).message);
+    }
+  }
+}

package/src/app/reasoning.ts

@@ -0,0 +1,30 @@
+/**
+ * Reasoning effort — a per-chat preference that steers how much deliberation
+ * the agent applies. Implemented as a concise directive prepended to prompts so
+ * it works regardless of backend-specific knobs.
+ */
+import type { ReasoningEffort } from "./types.js";
+
+const DIRECTIVE: Record<ReasoningEffort, string> = {
+  minimal: "Answer directly and briefly with minimal deliberation.",
+  low: "Keep reasoning light; prefer a quick, concise solution.",
+  medium: "", // default behaviour — no directive
+  high: "Think carefully and thoroughly before answering; verify your work.",
+  max: "Use maximum rigor: explore edge cases, double-check assumptions, and verify the result before finishing.",
+};
+
+const LABEL: Record<ReasoningEffort, string> = {
+  minimal: "Minimal",
+  low: "Low",
+  medium: "Medium",
+  high: "High",
+  max: "Max",
+};
+
+export function reasoningDirective(effort: ReasoningEffort): string {
+  return DIRECTIVE[effort] ?? "";
+}
+
+export function reasoningLabel(effort: ReasoningEffort): string {
+  return LABEL[effort] ?? effort;
+}

package/src/app/settings-store.ts

@@ -0,0 +1,31 @@
+/**
+ * Per-chat settings persistence (project, agent, model, reasoning, pinned
+ * status message id). Backed by a single JSON file so state survives restarts.
+ */
+import { join } from "node:path";
+import { JsonStore } from "./json-store.js";
+import { type ChatSettings, defaultSettings } from "./types.js";
+
+type SettingsMap = Record<string, ChatSettings>;
+
+export class SettingsStore {
+  private readonly store: JsonStore<SettingsMap>;
+
+  constructor(dataDir: string) {
+    this.store = new JsonStore<SettingsMap>(join(dataDir, "settings.json"), {});
+  }
+
+  get(chatId: number): ChatSettings {
+    const existing = this.store.get()[String(chatId)];
+    return existing ?? defaultSettings();
+  }
+
+  update(chatId: number, patch: Partial<ChatSettings>): ChatSettings {
+    const key = String(chatId);
+    const next = { ...this.get(chatId), ...patch };
+    this.store.update((m) => {
+      m[key] = next;
+    });
+    return next;
+  }
+}

package/src/app/stt.ts

@@ -0,0 +1,53 @@
+/**
+ * Speech-to-text via any OpenAI/Whisper-compatible endpoint.
+ *
+ * Language handling: when STT_LANGUAGE is unset, Whisper auto-detects the
+ * spoken language (covers English, Russian, Romanian/Moldovan, and ~100 more),
+ * so multilingual voice notes work out of the box.
+ */
+import { createLogger } from "../logger.js";
+
+const log = createLogger("stt");
+
+export interface SttConfig {
+  apiUrl?: string;
+  apiKey?: string;
+  model: string;
+  language?: string;
+}
+
+export class SttService {
+  constructor(private readonly cfg: SttConfig) {}
+
+  get enabled(): boolean {
+    return Boolean(this.cfg.apiUrl);
+  }
+
+  /** Transcribe audio bytes; returns the recognized text (may be empty). */
+  async transcribe(bytes: Buffer, mimeType: string, filename: string): Promise<string> {
+    if (!this.cfg.apiUrl) throw new Error("STT is not configured (set STT_API_URL).");
+    const url = endpoint(this.cfg.apiUrl);
+
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(bytes)], { type: mimeType }), filename);
+    form.append("model", this.cfg.model);
+    if (this.cfg.language) form.append("language", this.cfg.language);
+
+    const headers: Record<string, string> = {};
+    if (this.cfg.apiKey) headers.Authorization = `Bearer ${this.cfg.apiKey}`;
+
+    const res = await fetch(url, { method: "POST", headers, body: form });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      throw new Error(`STT HTTP ${res.status}: ${detail.slice(0, 200)}`);
+    }
+    const data = (await res.json()) as { text?: string };
+    log.debug("transcribed", (data.text ?? "").length, "chars");
+    return (data.text ?? "").trim();
+  }
+}
+
+function endpoint(base: string): string {
+  const b = base.replace(/\/$/, "");
+  return b.endsWith("/audio/transcriptions") ? b : `${b}/audio/transcriptions`;
+}

package/src/app/types.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared application types: per-chat settings, reasoning levels, and the
+ * prompt input model (text plus optional images) used across the bot.
+ */
+
+export const REASONING_LEVELS = ["minimal", "low", "medium", "high", "max"] as const;
+export type ReasoningEffort = (typeof REASONING_LEVELS)[number];
+
+export interface ChatSettings {
+  projectPath?: string;
+  projectName?: string;
+  sessionId?: string;
+  agent?: string;
+  model?: string;
+  reasoning: ReasoningEffort;
+  /** Telegram message id of the pinned status panel, if any. */
+  statusMessageId?: number;
+  /** Sessions this chat controls (for multi-session switching). */
+  controlledSessions?: ControlledSession[];
+  /** Which controlled session is currently in the foreground. */
+  foregroundSessionId?: string;
+}
+
+export interface ControlledSession {
+  sessionId?: string;
+  projectPath: string;
+  projectName?: string;
+}
+
+export function defaultSettings(): ChatSettings {
+  return { reasoning: "medium" };
+}
+
+/** A decoded image to attach to a prompt as an ACP image content block. */
+export interface PromptImage {
+  data: string; // base64-encoded bytes
+  mimeType: string;
+}
+
+/** A unit of work submitted to the agent: text plus optional images. */
+export interface PromptInput {
+  text: string;
+  images: PromptImage[];
+}
+
+export function textPrompt(text: string): PromptInput {
+  return { text, images: [] };
+}

package/src/app/usage.ts

@@ -0,0 +1,32 @@
+/**
+ * Account info via `kiro-cli whoami`. (Kiro's full billing/quota panel isn't
+ * available headlessly over ACP, so /usage shows account + live context usage.)
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const run = promisify(execFile);
+
+export interface AccountInfo {
+  accountType?: string;
+  email?: string;
+  region?: string;
+  startUrl?: string;
+}
+
+export class UsageService {
+  constructor(private readonly kiroCliPath: string) {}
+
+  async account(): Promise<AccountInfo | undefined> {
+    try {
+      const { stdout } = await run(this.kiroCliPath, ["whoami", "--format", "json"], {
+        timeout: 10_000,
+        encoding: "utf-8",
+      });
+      const match = stdout.match(/\{[\s\S]*?\}/);
+      return match ? (JSON.parse(match[0]) as AccountInfo) : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/src/bot/auth.ts

@@ -0,0 +1,27 @@
+/**
+ * Authorization middleware: restricts the bot to ALLOWED_USERS when configured.
+ */
+import type { Context, NextFunction } from "grammy";
+import type { AppConfig } from "../config.js";
+import { createLogger } from "../logger.js";
+
+const log = createLogger("auth");
+
+export function createAuthMiddleware(cfg: AppConfig) {
+  const allowAll = cfg.allowedUsers.size === 0;
+  if (allowAll) {
+    log.warn("ALLOWED_USERS is empty — the bot will respond to ANY Telegram user.");
+  }
+
+  return async (ctx: Context, next: NextFunction): Promise<void> => {
+    const userId = ctx.from?.id ? String(ctx.from.id) : undefined;
+    if (allowAll || (userId && cfg.allowedUsers.has(userId))) {
+      await next();
+      return;
+    }
+    log.warn(`blocked unauthorized user ${userId ?? "unknown"}`);
+    if (ctx.chat) {
+      await ctx.reply("\u26D4 Not authorized. Ask the bot owner to add your Telegram ID.");
+    }
+  };
+}

package/src/bot/bot.ts

@@ -0,0 +1,154 @@
+/**
+ * Assemble the grammY bot: dependencies, middleware, handlers, persistent menu,
+ * status panel, and the task scheduler. Handler registration order matters:
+ *   auth -> menu buttons -> wizard input -> commands -> photos -> text prompt.
+ */
+import { Bot } from "grammy";
+import type { AcpClient } from "../acp/client.js";
+import { SettingsStore } from "../app/settings-store.js";
+import { SttService } from "../app/stt.js";
+import { UsageService } from "../app/usage.js";
+import type { AppConfig } from "../config.js";
+import { createLogger } from "../logger.js";
+import { ProjectManager } from "../projects/manager.js";
+import { SessionStore } from "../sessions/store.js";
+import { TaskRunner } from "../tasks/runner.js";
+import { Scheduler } from "../tasks/scheduler.js";
+import { TaskStore } from "../tasks/store.js";
+import { createAuthMiddleware } from "./auth.js";
+import { COMMANDS } from "./commands.js";
+import { type BotDeps, MenuCache } from "./deps.js";
+import { registerControl } from "./handlers/control.js";
+import { registerHistory } from "./handlers/history.js";
+import { registerKill } from "./handlers/kill.js";
+import { registerMcp } from "./handlers/mcp.js";
+import { registerMenu } from "./handlers/menu.js";
+import { registerMessages } from "./handlers/message.js";
+import { registerPhotos } from "./handlers/photo.js";
+import { registerProjects } from "./handlers/projects.js";
+import { registerRunning, switchAndShow } from "./handlers/running.js";
+import { registerSessions } from "./handlers/sessions.js";
+import { registerSystem } from "./handlers/system.js";
+import { registerTasks, registerWizardInput } from "./handlers/tasks.js";
+import { registerUsage } from "./handlers/usage.js";
+import { registerVoice } from "./handlers/voice.js";
+import { StatusPanel } from "./menu/status-panel.js";
+import { PermissionService } from "./permission-service.js";
+import { RuntimeRegistry } from "./registry.js";
+import { TaskWizard } from "./wizard/task-wizard.js";
+
+const log = createLogger("bot");
+
+/** Telegram methods that support disable_notification (silenced in quiet mode). */
+const SILENCEABLE = new Set([
+  "sendMessage",
+  "sendPhoto",
+  "sendDocument",
+  "sendAudio",
+  "sendVoice",
+  "sendVideo",
+  "sendAnimation",
+  "sendMediaGroup",
+  "copyMessage",
+  "forwardMessage",
+]);
+
+export interface BotBundle {
+  bot: Bot;
+  registry: RuntimeRegistry;
+  scheduler: Scheduler;
+}
+
+export async function createBot(cfg: AppConfig, acp: AcpClient): Promise<BotBundle> {
+  const bot = new Bot(cfg.token);
+
+  // Quiet mode (default): silence every outgoing message unless the caller
+  // explicitly set disable_notification:false (turn completion, permission
+  // prompts, task results). Edits never notify, so they're unaffected.
+  if (cfg.quietNotifications) {
+    bot.api.config.use(async (prev, method, payload, signal) => {
+      if (SILENCEABLE.has(method)) {
+        const p = payload as { disable_notification?: boolean };
+        if (p.disable_notification === undefined) p.disable_notification = true;
+      }
+      return prev(method, payload, signal);
+    });
+  }
+
+  const settings = new SettingsStore(cfg.dataDir);
+  const store = new SessionStore(cfg.sessionsDir);
+  const registry = new RuntimeRegistry(bot.api, acp, cfg, settings, store);
+  const tasks = new TaskStore(cfg.dataDir);
+  const taskRunner = new TaskRunner(bot.api, acp);
+  const wizard = new TaskWizard(tasks);
+  const statusPanel = new StatusPanel(bot.api, settings, registry);
+  registry.setRefresher((chatId) => void statusPanel.refresh(chatId));
+
+  const deps: BotDeps = {
+    api: bot.api,
+    cfg,
+    acp,
+    registry,
+    store,
+    projects: new ProjectManager(cfg.projectRoots),
+    menuCache: new MenuCache(),
+    settings,
+    statusPanel,
+    tasks,
+    taskRunner,
+    wizard,
+    stt: new SttService({
+      apiUrl: cfg.sttApiUrl,
+      apiKey: cfg.sttApiKey,
+      model: cfg.sttModel,
+      language: cfg.sttLanguage,
+    }),
+    usage: new UsageService(cfg.kiroCliPath),
+  };
+
+  // Inline approvals: when NOT in trust-all mode, Kiro asks before risky tools.
+  const permissions = new PermissionService(bot.api, registry);
+  acp.permissionHandler = (p) => permissions.handle(p);
+
+  bot.use(createAuthMiddleware(cfg));
+
+  bot.callbackQuery(/^perm:(\d+):(\d+)$/, async (ctx) => {
+    const label = permissions.resolveChoice(ctx.match![1]!, Number(ctx.match![2]));
+    await ctx.answerCallbackQuery({ text: label ?? "Expired" });
+    await ctx.editMessageText(label ? `\u{1F510} ${label}` : "\u{1F510} (expired)").catch(() => {});
+  });
+
+  bot.callbackQuery(/^permsw:(\d+)$/, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    const sid = permissions.sessionFor(ctx.match![1]!);
+    if (sid) await switchAndShow(ctx, deps, sid);
+  });
+
+  registerMenu(bot, deps); // persistent-keyboard buttons (hears)
+  registerWizardInput(bot, deps); // wizard text input (before commands)
+  registerControl(bot, deps);
+  registerProjects(bot, deps);
+  registerSessions(bot, deps);
+  registerRunning(bot, deps);
+  registerHistory(bot, deps);
+  registerSystem(bot, deps);
+  registerUsage(bot, deps);
+  registerKill(bot, deps);
+  registerMcp(bot, deps);
+  registerTasks(bot, deps);
+  registerPhotos(bot, deps); // photos & image documents
+  registerVoice(bot, deps); // voice / audio -> transcription -> prompt
+  registerMessages(bot, deps); // catch-all text prompt — keep last
+
+  bot.catch((err) => {
+    log.error("unhandled bot error:", err.error instanceof Error ? err.error.message : err.error);
+  });
+
+  try {
+    await bot.api.setMyCommands(COMMANDS);
+  } catch (e) {
+    log.warn("setMyCommands failed:", (e as Error).message);
+  }
+
+  return { bot, registry, scheduler: new Scheduler(tasks, taskRunner) };
+}