kiro-telegram-bot 1.5.1

package/src/render/diff.ts

@@ -0,0 +1,48 @@
+/**
+ * Render a unified diff for a file edit as RAW markdown (a ```diff fenced
+ * block). Escaping/splitting is handled downstream by the markdown converter.
+ */
+import { structuredPatch } from "diff";
+
+export interface DiffInput {
+  path: string;
+  oldText: string | null | undefined;
+  newText: string | null | undefined;
+  maxLines: number;
+}
+
+export interface DiffResult {
+  block: string; // raw ```diff fenced markdown, or ""
+  added: number;
+  removed: number;
+}
+
+export function renderUnifiedDiff(input: DiffInput): DiffResult {
+  const oldText = input.oldText ?? "";
+  const newText = input.newText ?? "";
+  if (oldText === newText) return { block: "", added: 0, removed: 0 };
+
+  const patch = structuredPatch(input.path, input.path, oldText, newText, "", "", { context: 2 });
+  const lines: string[] = [];
+  let added = 0;
+  let removed = 0;
+
+  for (const hunk of patch.hunks) {
+    lines.push(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`);
+    for (const l of hunk.lines) {
+      if (l.startsWith("\\")) continue; // drop ""
+      if (l.startsWith("+")) added++;
+      else if (l.startsWith("-")) removed++;
+      lines.push(l);
+    }
+  }
+  if (lines.length === 0) return { block: "", added, removed };
+
+  let shown = lines;
+  let note = "";
+  if (lines.length > input.maxLines) {
+    shown = lines.slice(0, input.maxLines);
+    note = `\n… +${lines.length - input.maxLines} more lines`;
+  }
+  return { block: "```diff\n" + shown.join("\n") + note + "\n```", added, removed };
+}

package/src/render/escape.ts

@@ -0,0 +1,22 @@
+/**
+ * Telegram MarkdownV2 escaping helpers.
+ * @see https://core.telegram.org/bots/api#markdownv2-style
+ */
+
+// Characters that must be escaped in normal MarkdownV2 text.
+const SPECIAL = /[_*\[\]()~`>#+\-=|{}.!\\]/g;
+
+/** Escape text that appears in normal (non-entity) MarkdownV2 context. */
+export function escapeMdV2(text: string): string {
+  return text.replace(SPECIAL, (c) => `\\${c}`);
+}
+
+/** Escape the body of an inline code span or code block (only ` and \). */
+export function escapeCode(text: string): string {
+  return text.replace(/([`\\])/g, "\\$1");
+}
+
+/** Escape a URL used inside a MarkdownV2 link target. */
+export function escapeUrl(url: string): string {
+  return url.replace(/([)\\])/g, "\\$1");
+}

package/src/render/markdown.ts

@@ -0,0 +1,126 @@
+/**
+ * Convert standard Markdown (as produced by the agent) into Telegram
+ * MarkdownV2, with correct escaping and graceful handling of code blocks,
+ * headings, lists, quotes, links and inline styles.
+ */
+import { escapeCode, escapeMdV2, escapeUrl } from "./escape.js";
+
+const FENCE = /```([^\n`]*)\n([\s\S]*?)```/g;
+
+/** Main entry: returns a MarkdownV2-safe string. */
+export function toTelegramMarkdown(src: string): string {
+  let out = "";
+  let last = 0;
+  let m: RegExpExecArray | null;
+  FENCE.lastIndex = 0;
+
+  while ((m = FENCE.exec(src)) !== null) {
+    out += renderTextBlock(src.slice(last, m.index));
+    const lang = (m[1] ?? "").trim();
+    const code = (m[2] ?? "").replace(/\n$/, "");
+    out += "```" + lang + "\n" + escapeCode(code) + "\n```\n";
+    last = FENCE.lastIndex;
+  }
+  out += renderTextBlock(src.slice(last));
+
+  return out.replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function renderTextBlock(text: string): string {
+  if (!text) return "";
+  return text
+    .split("\n")
+    .map((line) => renderLine(line))
+    .join("\n");
+}
+
+function renderLine(line: string): string {
+  // Heading -> bold
+  const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+  if (heading) return "*" + renderInline((heading[2] ?? "").replace(/#+\s*$/, "").trim()) + "*";
+
+  // Horizontal rule
+  if (/^\s*([-*_])\1{2,}\s*$/.test(line)) return "\u2014\u2014\u2014\u2014\u2014\u2014\u2014\u2014";
+
+  // Blockquote (keep '>' literal so Telegram renders the quote)
+  const quote = /^>\s?(.*)$/.exec(line);
+  if (quote) return ">" + renderInline(quote[1] ?? "");
+
+  // Unordered list
+  const ul = /^(\s*)[-*+]\s+(.*)$/.exec(line);
+  if (ul) return (ul[1] ?? "") + "\u2022 " + renderInline(ul[2] ?? "");
+
+  // Ordered list
+  const ol = /^(\s*)(\d+)[.)]\s+(.*)$/.exec(line);
+  if (ol) return (ol[1] ?? "") + (ol[2] ?? "") + "\\. " + renderInline(ol[3] ?? "");
+
+  return renderInline(line);
+}
+
+/** Render inline markdown spans into MarkdownV2. */
+function renderInline(text: string): string {
+  let out = "";
+  let i = 0;
+  const n = text.length;
+
+  while (i < n) {
+    const c = text[i]!;
+    const next = text[i + 1];
+
+    // Inline code
+    if (c === "`") {
+      const end = text.indexOf("`", i + 1);
+      if (end !== -1) {
+        out += "`" + escapeCode(text.slice(i + 1, end)) + "`";
+        i = end + 1;
+        continue;
+      }
+    }
+
+    // Bold ** ** or __ __
+    if ((c === "*" && next === "*") || (c === "_" && next === "_")) {
+      const marker = c + c;
+      const end = text.indexOf(marker, i + 2);
+      if (end !== -1 && end > i + 2) {
+        out += "*" + renderInline(text.slice(i + 2, end)) + "*";
+        i = end + 2;
+        continue;
+      }
+    }
+
+    // Strikethrough ~~ ~~
+    if (c === "~" && next === "~") {
+      const end = text.indexOf("~~", i + 2);
+      if (end !== -1 && end > i + 2) {
+        out += "~" + renderInline(text.slice(i + 2, end)) + "~";
+        i = end + 2;
+        continue;
+      }
+    }
+
+    // Italic * * (single)
+    if (c === "*") {
+      const end = text.indexOf("*", i + 1);
+      if (end !== -1 && end > i + 1) {
+        out += "_" + renderInline(text.slice(i + 1, end)) + "_";
+        i = end + 1;
+        continue;
+      }
+    }
+
+    // Link [text](url)
+    if (c === "[") {
+      const link = /^\[([^\]]*)\]\(([^)\s]+)\)/.exec(text.slice(i));
+      if (link) {
+        out += "[" + renderInline(link[1] ?? "") + "](" + escapeUrl(link[2] ?? "") + ")";
+        i += link[0].length;
+        continue;
+      }
+    }
+
+    out += escapeMdV2(c);
+    i += 1;
+  }
+
+  return out;
+}

package/src/render/subagent.ts

@@ -0,0 +1,75 @@
+/**
+ * Render subagent ("crew") activity into short, readable status lines so the
+ * user can see what's happening while the main agent waits on its subagents.
+ */
+import type { PendingStage, SubagentInfo } from "../acp/types.js";
+
+const STATUS_ICON: Record<string, string> = {
+  working: "\u{1F3C3}", // 🏃 running
+  running: "\u{1F3C3}",
+  pending: "\u23F3",
+  queued: "\u23F3",
+  completed: "\u2705",
+  done: "\u2705",
+  terminated: "\u2705",
+  failed: "\u274C",
+  error: "\u274C",
+  cancelled: "\u23F9",
+};
+
+function trunc(s: string, n: number): string {
+  return s.length > n ? s.slice(0, n - 1) + "\u2026" : s;
+}
+
+/** Normalize a subagent's status type to a short, stable key. */
+export function statusKey(s: SubagentInfo): string {
+  return (s.status?.type || "working").toLowerCase();
+}
+
+/** A one-line label for a subagent (no leading icon). */
+export function subagentLabel(s: SubagentInfo): string {
+  const name = s.sessionName || s.agentName || s.sessionId.slice(0, 8);
+  const role = s.role || s.agentName;
+  return role && role !== name ? `${name} (${role})` : name;
+}
+
+/**
+ * A markdown block announcing a subagent's status transition, or "" to skip.
+ * `kind`: "start" the first time it appears, otherwise from its status.
+ */
+export function renderSubagentTransition(s: SubagentInfo, kind: "start" | "status"): string {
+  const key = statusKey(s);
+  const label = subagentLabel(s);
+  if (kind === "start") {
+    const q = s.initialQuery ? `\n    \u2197 ${trunc(s.initialQuery.trim(), 140)}` : "";
+    return `\u{1F916} Subagent **${label}** started${q}`;
+  }
+  const icon = STATUS_ICON[key] ?? "\u{1F916}";
+  const verb =
+    key === "terminated" || key === "completed" || key === "done"
+      ? "finished"
+      : key === "failed" || key === "error"
+        ? "failed"
+        : key;
+  const msg = s.status?.message && !/^running$/i.test(s.status.message) ? ` \u2014 ${trunc(s.status.message, 80)}` : "";
+  return `${icon} Subagent **${label}** ${verb}${msg}`;
+}
+
+/** A compact summary for the status panel, e.g. "🤖 2 running · 1 pending". */
+export function subagentSummary(subagents: SubagentInfo[], pending: PendingStage[]): string | undefined {
+  const running = subagents.filter((s) => {
+    const k = statusKey(s);
+    return k === "working" || k === "running" || k === "pending" || k === "queued";
+  }).length;
+  const pend = pending.length;
+  if (running === 0 && pend === 0) return undefined;
+  const parts: string[] = [];
+  if (running > 0) parts.push(`${running} running`);
+  if (pend > 0) parts.push(`${pend} pending`);
+  return `\u{1F916} ${parts.join(" \u00B7 ")}`;
+}
+
+/** True when a status type means the subagent is still active. */
+export function isActiveStatus(key: string): boolean {
+  return key === "working" || key === "running" || key === "pending" || key === "queued";
+}

package/src/render/tool-call.ts

@@ -0,0 +1,102 @@
+/**
+ * Format ACP tool-call updates into clear, RAW markdown blocks so they read
+ * distinctly from the agent's prose and thinking. Commands appear in a `bash`
+ * block, file edits as a `diff` block.
+ */
+import type { SessionUpdate, ToolCallContent } from "../acp/types.js";
+import { renderUnifiedDiff } from "./diff.js";
+
+const KIND_ICON: Record<string, string> = {
+  read: "\u{1F4D6}",
+  edit: "\u270F\uFE0F",
+  execute: "\u{1F4BB}",
+  search: "\u{1F50E}",
+  delete: "\u{1F5D1}\uFE0F",
+  move: "\u{1F4E6}",
+  fetch: "\u{1F310}",
+  think: "\u{1F4AD}",
+  other: "\u{1F527}",
+};
+
+const STATUS_ICON: Record<string, string> = {
+  pending: "",
+  in_progress: "\u23F3",
+  completed: "\u2705",
+  failed: "\u274C",
+};
+
+export interface ToolFormatOptions {
+  showDiffs: boolean;
+  diffMaxLines: number;
+}
+
+/** Returns a RAW markdown block describing the tool call, or "" to skip. */
+export function formatToolCall(u: SessionUpdate, opts: ToolFormatOptions): string {
+  const kind = (u.kind || "other").toLowerCase();
+  const icon = KIND_ICON[kind] ?? KIND_ICON.other;
+  const status = u.status ? (STATUS_ICON[u.status] ?? "") : "";
+  const raw = (u.rawInput || {}) as Record<string, unknown>;
+  const title = u.title || titleFromRaw(kind, raw);
+
+  let out = `${icon} **${title}**${status ? ` ${status}` : ""}`;
+
+  if (kind === "execute") {
+    const cmd = strOf(raw.command ?? raw.cmd);
+    if (cmd) out += "\n```bash\n" + cmd + "\n```";
+  }
+
+  if (kind === "edit" && opts.showDiffs) {
+    const diff = buildEditDiff(u, raw, opts.diffMaxLines);
+    if (diff && diff.block) {
+      const stat = `${diff.added > 0 ? "+" + diff.added : ""}${diff.removed > 0 ? " -" + diff.removed : ""}`.trim();
+      out += `${stat ? `  (${stat})` : ""}\n${diff.block}`;
+    }
+  }
+
+  return out;
+}
+
+function buildEditDiff(u: SessionUpdate, raw: Record<string, unknown>, maxLines: number) {
+  const blocks = collectContent(u);
+  const diffBlock = blocks.find((b) => b.type === "diff");
+  if (diffBlock) {
+    return renderUnifiedDiff({
+      path: strOf(diffBlock.path) || strOf(raw.path) || "file",
+      oldText: typeof diffBlock.oldText === "string" ? diffBlock.oldText : "",
+      newText: typeof diffBlock.newText === "string" ? diffBlock.newText : "",
+      maxLines,
+    });
+  }
+  const oldStr = strOf(raw.old_str ?? raw.oldStr);
+  const newStr = strOf(raw.new_str ?? raw.newStr);
+  if (oldStr || newStr) {
+    return renderUnifiedDiff({ path: strOf(raw.path) || "file", oldText: oldStr, newText: newStr, maxLines });
+  }
+  const content = strOf(raw.file_text ?? raw.content ?? raw.text);
+  if (content) {
+    return renderUnifiedDiff({ path: strOf(raw.path) || "file", oldText: "", newText: content, maxLines });
+  }
+  return undefined;
+}
+
+function titleFromRaw(kind: string, raw: Record<string, unknown>): string {
+  const path = strOf(raw.path ?? raw.file_path ?? raw.filename);
+  if (path) return `${capitalize(kind)} ${path}`;
+  return capitalize(kind);
+}
+
+function collectContent(u: SessionUpdate): ToolCallContent[] {
+  const out: ToolCallContent[] = [];
+  if (Array.isArray(u.content_blocks)) out.push(...u.content_blocks);
+  const content = (u as unknown as { content?: unknown }).content;
+  if (Array.isArray(content)) out.push(...(content as ToolCallContent[]));
+  return out;
+}
+
+function strOf(v: unknown): string {
+  return typeof v === "string" ? v : "";
+}
+
+function capitalize(s: string): string {
+  return s.length ? s[0]!.toUpperCase() + s.slice(1) : s;
+}

package/src/service/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Selects the right service controller for the current platform.
+ */
+import { detectPlatform } from "./platform.js";
+import { linuxController } from "./linux.js";
+import { macosController } from "./macos.js";
+import type { ServiceController } from "./types.js";
+import { windowsController } from "./windows.js";
+
+export { buildLaunchSpec } from "./platform.js";
+export type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+export function getController(): ServiceController {
+  switch (detectPlatform()) {
+    case "windows":
+      return windowsController;
+    case "linux":
+      return linuxController;
+    case "macos":
+      return macosController;
+    default:
+      throw new Error(`Unsupported platform: ${process.platform}`);
+  }
+}

package/src/service/linux.ts

@@ -0,0 +1,83 @@
+/**
+ * Linux service controller — installs a systemd *user* service so no sudo is
+ * required. `loginctl enable-linger` is attempted so the bot runs at boot even
+ * before you log in.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, userInfo } from "node:os";
+import { join } from "node:path";
+import { runSafe } from "./platform.js";
+import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+const UNIT = "kiro-telegram-bot.service";
+
+function unitPath(): string {
+  return join(homedir(), ".config", "systemd", "user", UNIT);
+}
+
+export const linuxController: ServiceController = {
+  platform: "linux",
+
+  async install(spec) {
+    mkdirSync(join(homedir(), ".config", "systemd", "user"), { recursive: true });
+    mkdirSync(spec.logsDir, { recursive: true });
+    writeFileSync(unitPath(), unitFile(spec), "utf-8");
+
+    runSafe("systemctl", ["--user", "daemon-reload"]);
+    const en = runSafe("systemctl", ["--user", "enable", "--now", UNIT]);
+    if (!en.ok) return fail(`systemctl enable failed: ${en.out}`);
+    const linger = runSafe("loginctl", ["enable-linger", userInfo().username]);
+    const note = linger.ok ? " Boot-without-login enabled (linger)." : " (run `loginctl enable-linger` for boot-without-login)";
+    return ok(`Installed and started systemd user service "${UNIT}".${note}`);
+  },
+
+  async uninstall() {
+    runSafe("systemctl", ["--user", "disable", "--now", UNIT]);
+    rmSync(unitPath(), { force: true });
+    runSafe("systemctl", ["--user", "daemon-reload"]);
+    return ok(`Removed systemd user service "${UNIT}".`);
+  },
+
+  async start() {
+    const r = runSafe("systemctl", ["--user", "start", UNIT]);
+    return r.ok ? ok("Started.") : fail(r.out);
+  },
+
+  async stop() {
+    const r = runSafe("systemctl", ["--user", "stop", UNIT]);
+    return r.ok ? ok("Stopped.") : fail(r.out);
+  },
+
+  async status() {
+    const r = runSafe("systemctl", ["--user", "status", UNIT, "--no-pager"]);
+    return ok(r.out.trim() || "No status.");
+  },
+};
+
+function unitFile(spec: LaunchSpec): string {
+  const exec = `${spec.nodePath} ${spec.args.join(" ")}`;
+  return [
+    "[Unit]",
+    `Description=${spec.displayName}`,
+    "After=network-online.target",
+    "Wants=network-online.target",
+    "",
+    "[Service]",
+    "Type=simple",
+    `WorkingDirectory=${spec.cwd}`,
+    `ExecStart=${exec}`,
+    "Restart=always",
+    "RestartSec=5",
+    "",
+    "[Install]",
+    "WantedBy=default.target",
+    "",
+  ].join("\n");
+}
+
+function ok(message: string): ServiceResult {
+  return { ok: true, message };
+}
+function fail(message: string): ServiceResult {
+  return { ok: false, message };
+}

package/src/service/macos.ts

@@ -0,0 +1,91 @@
+/**
+ * macOS service controller — installs a launchd LaunchAgent that runs at login
+ * and is kept alive automatically.
+ */
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runSafe } from "./platform.js";
+import type { LaunchSpec, ServiceController, ServiceResult } from "./types.js";
+
+const LABEL = "com.kiro.telegrambot";
+
+function plistPath(): string {
+  return join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
+}
+
+export const macosController: ServiceController = {
+  platform: "macos",
+
+  async install(spec) {
+    mkdirSync(join(homedir(), "Library", "LaunchAgents"), { recursive: true });
+    mkdirSync(spec.logsDir, { recursive: true });
+    const path = plistPath();
+    runSafe("launchctl", ["unload", "-w", path]); // ignore if not loaded
+    writeFileSync(path, plist(spec), "utf-8");
+    const r = runSafe("launchctl", ["load", "-w", path]);
+    return r.ok ? ok(`Installed and loaded LaunchAgent "${LABEL}".`) : fail(r.out);
+  },
+
+  async uninstall() {
+    runSafe("launchctl", ["unload", "-w", plistPath()]);
+    rmSync(plistPath(), { force: true });
+    return ok(`Removed LaunchAgent "${LABEL}".`);
+  },
+
+  async start() {
+    const r = runSafe("launchctl", ["start", LABEL]);
+    return r.ok ? ok("Started.") : fail(r.out);
+  },
+
+  async stop() {
+    const r = runSafe("launchctl", ["stop", LABEL]);
+    return r.ok ? ok("Stopped.") : fail(r.out);
+  },
+
+  async status() {
+    const r = runSafe("launchctl", ["list"]);
+    const line = r.out.split("\n").find((l) => l.includes(LABEL));
+    return ok(line ? `Loaded: ${line.trim()}` : "Not loaded.");
+  },
+};
+
+function plist(spec: LaunchSpec): string {
+  const args = [spec.nodePath, ...spec.args].map((a) => `    <string>${esc(a)}</string>`).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<plist version="1.0">',
+    "<dict>",
+    "  <key>Label</key>",
+    `  <string>${LABEL}</string>`,
+    "  <key>ProgramArguments</key>",
+    "  <array>",
+    args,
+    "  </array>",
+    "  <key>WorkingDirectory</key>",
+    `  <string>${esc(spec.cwd)}</string>`,
+    "  <key>RunAtLoad</key>",
+    "  <true/>",
+    "  <key>KeepAlive</key>",
+    "  <true/>",
+    "  <key>StandardOutPath</key>",
+    `  <string>${esc(spec.logFile)}</string>`,
+    "  <key>StandardErrorPath</key>",
+    `  <string>${esc(spec.logFile)}</string>`,
+    "</dict>",
+    "</plist>",
+    "",
+  ].join("\n");
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function ok(message: string): ServiceResult {
+  return { ok: true, message };
+}
+function fail(message: string): ServiceResult {
+  return { ok: false, message };
+}

package/src/service/platform.ts

@@ -0,0 +1,59 @@
+/**
+ * Platform detection, launch-spec construction, and a small command runner
+ * shared by the per-OS service controllers.
+ */
+import { execFileSync } from "node:child_process";
+import { join } from "node:path";
+import { PROJECT_ROOT, INSTANCE_DIR } from "../config.js";
+
+export type Platform = "windows" | "linux" | "macos" | "unknown";
+
+export function detectPlatform(): Platform {
+  switch (process.platform) {
+    case "win32":
+      return "windows";
+    case "linux":
+      return "linux";
+    case "darwin":
+      return "macos";
+    default:
+      return "unknown";
+  }
+}
+
+import type { LaunchSpec } from "./types.js";
+
+/** Build the launch spec that runs the bot via the current node + tsx loader. */
+export function buildLaunchSpec(): LaunchSpec {
+  const logsDir = join(INSTANCE_DIR, "logs");
+  const args = ["--import", "tsx", join(PROJECT_ROOT, "src", "index.ts")];
+  // Run the code from the package dir (cwd below) so `tsx` resolves, but tell
+  // the bot where its .env/logs/data live. Only appended for a global install
+  // (instance dir differs) so in-place checkouts keep identical launch args.
+  if (INSTANCE_DIR !== PROJECT_ROOT) args.push("--instance", INSTANCE_DIR);
+  return {
+    id: "kiro-telegram-bot",
+    displayName: "Kiro Telegram Bot",
+    nodePath: process.execPath,
+    args,
+    cwd: PROJECT_ROOT,
+    logsDir,
+    logFile: join(logsDir, "kiro-telegram-bot.log"),
+  };
+}
+
+/** Run a command, returning combined output. Throws on non-zero exit. */
+export function run(cmd: string, args: string[]): string {
+  return execFileSync(cmd, args, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"] });
+}
+
+/** Run a command, swallowing errors and returning { ok, out }. */
+export function runSafe(cmd: string, args: string[]): { ok: boolean; out: string } {
+  try {
+    return { ok: true, out: run(cmd, args) };
+  } catch (e) {
+    const err = e as { stdout?: Buffer | string; stderr?: Buffer | string; message?: string };
+    const out = String(err.stdout ?? "") + String(err.stderr ?? "") || err.message || "failed";
+    return { ok: false, out };
+  }
+}

package/src/service/types.ts

@@ -0,0 +1,34 @@
+/**
+ * Cross-platform service (daemon) abstraction.
+ */
+
+export interface LaunchSpec {
+  /** Internal service id, e.g. "kiro-telegram-bot". */
+  id: string;
+  /** Human-readable name. */
+  displayName: string;
+  /** Absolute path to the node binary that should run the bot. */
+  nodePath: string;
+  /** Arguments after the node binary (tsx loader + entry file). */
+  args: string[];
+  /** Working directory (the installed bot folder). */
+  cwd: string;
+  /** Absolute log file path. */
+  logFile: string;
+  /** Log directory. */
+  logsDir: string;
+}
+
+export interface ServiceResult {
+  ok: boolean;
+  message: string;
+}
+
+export interface ServiceController {
+  readonly platform: string;
+  install(spec: LaunchSpec): Promise<ServiceResult>;
+  uninstall(spec: LaunchSpec): Promise<ServiceResult>;
+  start(spec: LaunchSpec): Promise<ServiceResult>;
+  stop(spec: LaunchSpec): Promise<ServiceResult>;
+  status(spec: LaunchSpec): Promise<ServiceResult>;
+}