glab-agent 0.1.0

package/src/local-agent/health-server.ts

@@ -0,0 +1,56 @@
+import { createServer, type Server } from "node:http";
+
+export interface HealthStatus {
+  agent: string;
+  status: "idle" | "busy" | "offline";
+  pid: number;
+  uptime: number;       // seconds since start
+  cycleCount: number;
+  activeIssue?: number; // issueIid if busy
+  lastError?: string;
+}
+
+export interface HealthServerOptions {
+  port: number;
+  agent: string;
+  getStatus: () => HealthStatus;
+}
+
+export function startHealthServer(options: HealthServerOptions): { server: Server; close: () => void } {
+  const { port, getStatus } = options;
+
+  const server = createServer((req, res) => {
+    if (req.method === "GET" && req.url === "/health") {
+      const status = getStatus();
+      const body = JSON.stringify(status);
+      res.writeHead(200, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      });
+      res.end(body);
+    } else {
+      const body = JSON.stringify({ error: "not found" });
+      res.writeHead(404, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      });
+      res.end(body);
+    }
+  });
+
+  server.on("error", (err: NodeJS.ErrnoException) => {
+    if (err.code === "EADDRINUSE") {
+      console.warn(`[health-server] Port ${port} already in use, health endpoint not available`);
+    } else {
+      console.warn(`[health-server] Error: ${err.message}`);
+    }
+  });
+
+  server.listen(port, "0.0.0.0");
+
+  function close(): void {
+    server.close();
+  }
+
+  return { server, close };
+}

package/src/local-agent/heartbeat.ts

@@ -0,0 +1,33 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+export interface HeartbeatData {
+  timestamp: string;
+  cycleCount: number;
+  lastError?: string;
+}
+
+export async function writeHeartbeat(heartbeatPath: string, data: HeartbeatData): Promise<void> {
+  try {
+    await mkdir(path.dirname(heartbeatPath), { recursive: true });
+    await writeFile(heartbeatPath, JSON.stringify(data), "utf8");
+  } catch {
+    // Heartbeat write failure must never affect main workflow
+  }
+}
+
+export async function readHeartbeat(heartbeatPath: string): Promise<HeartbeatData | undefined> {
+  try {
+    const content = await readFile(heartbeatPath, "utf8");
+    return JSON.parse(content) as HeartbeatData;
+  } catch {
+    return undefined;
+  }
+}
+
+export function isHeartbeatStale(heartbeat: HeartbeatData, pollIntervalSeconds: number, maxMissedCycles = 3): boolean {
+  const heartbeatTime = new Date(heartbeat.timestamp).getTime();
+  const now = Date.now();
+  const thresholdMs = pollIntervalSeconds * maxMissedCycles * 1000;
+  return (now - heartbeatTime) > thresholdMs;
+}

package/src/local-agent/log-rotate.ts

@@ -0,0 +1,56 @@
+import { stat, rename, unlink } from "node:fs/promises";
+
+export interface LogRotateOptions {
+  maxBytes: number; // default 10 * 1024 * 1024 (10MB)
+  maxFiles: number; // default 5
+}
+
+const DEFAULT_OPTIONS: LogRotateOptions = {
+  maxBytes: 10 * 1024 * 1024,
+  maxFiles: 5,
+};
+
+/**
+ * Check if a log file needs rotation and perform it if needed.
+ * Rotation scheme: file → file.1 → file.2 → ... → file.N (oldest deleted)
+ *
+ * @returns true if rotation was performed
+ */
+export async function rotateIfNeeded(
+  filePath: string,
+  options?: Partial<LogRotateOptions>
+): Promise<boolean> {
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+
+  try {
+    const stats = await stat(filePath);
+    if (stats.size < opts.maxBytes) return false;
+  } catch {
+    return false; // File doesn't exist
+  }
+
+  // Delete oldest rotated file
+  try {
+    await unlink(`${filePath}.${opts.maxFiles}`);
+  } catch {
+    /* doesn't exist */
+  }
+
+  // Shift existing rotated files: .4 → .5, .3 → .4, etc.
+  for (let i = opts.maxFiles - 1; i >= 1; i--) {
+    try {
+      await rename(`${filePath}.${i}`, `${filePath}.${i + 1}`);
+    } catch {
+      /* doesn't exist */
+    }
+  }
+
+  // Rotate current file to .1
+  try {
+    await rename(filePath, `${filePath}.1`);
+  } catch {
+    /* race condition, ignore */
+  }
+
+  return true;
+}

package/src/local-agent/logger.ts

@@ -0,0 +1,92 @@
+export interface Logger {
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+
+export type LogFormat = "text" | "json";
+
+export interface LogEntry {
+  timestamp: string;
+  level: "info" | "warn" | "error";
+  agent?: string;
+  module: string;
+  message: string;
+  context?: Record<string, unknown>;
+}
+
+function timestamp(): string {
+  return new Date().toLocaleString("zh-CN", {
+    timeZone: "Asia/Shanghai",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+}
+
+export function formatLogEntry(entry: LogEntry, format: LogFormat): string {
+  if (format === "json") {
+    return JSON.stringify(entry);
+  }
+  // text format: [timestamp] [agent] [module] message
+  const prefix = entry.agent ? `[${entry.agent}] [${entry.module}]` : `[${entry.module}]`;
+  const contextStr = entry.context ? ` ${JSON.stringify(entry.context)}` : "";
+  return `[${entry.timestamp}] ${prefix} ${entry.message}${contextStr}`;
+}
+
+/**
+ * Creates a tagged logger.
+ *
+ * Output format (text):
+ *   [2026/04/06 14:33:25] [claude-coder] [watcher] message
+ *   [2026/04/06 14:33:25] [claude-coder] [runner]  message
+ *
+ * Output format (json):
+ *   {"timestamp":"...","level":"info","agent":"claude-coder","module":"watcher","message":"..."}
+ *
+ * @param module  Short name for the calling module (e.g. "watcher", "runner", "worktree")
+ * @param agent   Optional agent name included after the timestamp for multi-agent disambiguation
+ * @param format  Output format: "text" (default, human-readable) or "json" (JSON Lines / NDJSON)
+ */
+export function createLogger(module: string, agent?: string, format: LogFormat = "text"): Logger {
+  const makeEntry = (level: "info" | "warn" | "error", args: unknown[]): LogEntry => {
+    // If last arg is a plain object, treat as context
+    let context: Record<string, unknown> | undefined;
+    let messageArgs = args;
+    if (
+      args.length > 0 &&
+      typeof args[args.length - 1] === "object" &&
+      args[args.length - 1] !== null &&
+      !Array.isArray(args[args.length - 1])
+    ) {
+      context = args[args.length - 1] as Record<string, unknown>;
+      messageArgs = args.slice(0, -1);
+    }
+    return {
+      timestamp: timestamp(),
+      level,
+      agent,
+      module,
+      message: messageArgs.map(String).join(" "),
+      context
+    };
+  };
+
+  return {
+    info: (...args: unknown[]) => {
+      const entry = makeEntry("info", args);
+      console.info(formatLogEntry(entry, format));
+    },
+    warn: (...args: unknown[]) => {
+      const entry = makeEntry("warn", args);
+      console.warn(formatLogEntry(entry, format));
+    },
+    error: (...args: unknown[]) => {
+      const entry = makeEntry("error", args);
+      console.error(formatLogEntry(entry, format));
+    }
+  };
+}

package/src/local-agent/metrics.ts

@@ -0,0 +1,51 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import path from "node:path";
+
+export interface MetricEvent {
+  timestamp: string;
+  agent: string;
+  provider: string;
+  event: "run_start" | "run_complete" | "run_failed" | "run_timeout" | "cycle_error";
+  issueIid?: number;
+  issueTitle?: string;
+  durationMs?: number;
+  branch?: string;
+  mrUrl?: string;
+  error?: string;
+}
+
+export async function appendMetric(metricsDir: string, agentName: string, event: MetricEvent): Promise<void> {
+  try {
+    await mkdir(metricsDir, { recursive: true });
+    const filePath = path.join(metricsDir, `${agentName}.jsonl`);
+    await appendFile(filePath, JSON.stringify(event) + "\n", "utf8");
+  } catch {
+    // Metrics write failure must never affect main workflow
+  }
+}
+
+export async function readMetrics(metricsDir: string, agentName: string): Promise<MetricEvent[]> {
+  const filePath = path.join(metricsDir, `${agentName}.jsonl`);
+  const events: MetricEvent[] = [];
+  try {
+    const rl = createInterface({ input: createReadStream(filePath, "utf8"), crlfDelay: Infinity });
+    for await (const line of rl) {
+      if (line.trim()) {
+        try {
+          events.push(JSON.parse(line) as MetricEvent);
+        } catch {
+          // Skip malformed lines
+        }
+      }
+    }
+  } catch {
+    // File not found or read error
+  }
+  return events;
+}
+
+export function metricsPath(repoPath: string): string {
+  return path.join(repoPath, ".glab-agent", "metrics");
+}

package/src/local-agent/mr-actions.ts

@@ -0,0 +1,121 @@
+import type { GitlabClient, GitlabTodoItem } from "./gitlab-glab-client.js";
+import type { Logger } from "./logger.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type MrIntent = "rebase" | "contextual";
+
+export type MrActionResult =
+  | { action: "rebase"; success: boolean; message: string }
+  | { action: "contextual"; message: string };
+
+export interface ReplyContext {
+  targetType: "MergeRequest" | "Issue";
+  targetIid: number;
+  targetTitle: string;
+  targetDescription?: string;
+  mentionBody: string;
+  recentNotes: string[];
+  gitlabHost: string;
+  projectId: number;
+}
+
+export interface MrActionDependencies {
+  gitlabClient: Pick<GitlabClient, "addMergeRequestNote" | "markTodoDone" | "getMergeRequestNotes">;
+  rebaseBranch: (branch: string) => Promise<void>;
+  generateReply: (context: ReplyContext) => Promise<string>;
+  projectId: number;
+  gitlabHost: string;
+  logger?: Logger;
+}
+
+// ---------------------------------------------------------------------------
+// Intent parsing
+// ---------------------------------------------------------------------------
+
+export function parseMrIntent(body: string | undefined): MrIntent {
+  if (!body) return "contextual";
+  if (/\brebase\b/i.test(body)) return "rebase";
+  return "contextual";
+}
+
+// ---------------------------------------------------------------------------
+// MR todo filtering
+// ---------------------------------------------------------------------------
+
+export function filterMrTodos(
+  todos: GitlabTodoItem[],
+  processedTodoIds: Set<number>,
+  acceptedActions: Set<string>
+): GitlabTodoItem[] {
+  return todos.filter(
+    (todo) =>
+      todo.targetType === "MergeRequest" &&
+      todo.state === "pending" &&
+      acceptedActions.has(todo.actionName) &&
+      !processedTodoIds.has(todo.id)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Handle a single MR todo
+// ---------------------------------------------------------------------------
+
+export async function handleMrTodo(
+  todo: GitlabTodoItem,
+  deps: MrActionDependencies
+): Promise<MrActionResult> {
+  const logger = deps.logger ?? console;
+  const mrIid = todo.targetIid ?? 0;
+  const intent = parseMrIntent(todo.body);
+
+  if (intent === "rebase" && todo.sourceBranch) {
+    try {
+      await deps.rebaseBranch(todo.sourceBranch);
+      const note = `已完成 rebase（分支 \`${todo.sourceBranch}\`）。`;
+      await deps.gitlabClient.addMergeRequestNote(deps.projectId, mrIid, note);
+      logger.info(`MR !${mrIid}: rebase succeeded for branch ${todo.sourceBranch}`);
+      return { action: "rebase", success: true, message: note };
+    } catch (error) {
+      const reason = String(error).slice(0, 300);
+      const note = `rebase 失败：${reason}`;
+      try {
+        await deps.gitlabClient.addMergeRequestNote(deps.projectId, mrIid, note);
+      } catch { /* silent */ }
+      logger.warn(`MR !${mrIid}: rebase failed: ${reason}`);
+      return { action: "rebase", success: false, message: note };
+    }
+  }
+
+  // Contextual reply — collect context and delegate to AI
+  try {
+    const notes = await deps.gitlabClient.getMergeRequestNotes(deps.projectId, mrIid);
+    const recentNotes = notes
+      .filter((n) => !n.system)
+      .slice(-10)
+      .map((n) => n.body);
+
+    const reply = await deps.generateReply({
+      targetType: "MergeRequest",
+      targetIid: mrIid,
+      targetTitle: `MR !${mrIid}`,
+      mentionBody: todo.body ?? "",
+      recentNotes,
+      gitlabHost: deps.gitlabHost,
+      projectId: deps.projectId
+    });
+
+    await deps.gitlabClient.addMergeRequestNote(deps.projectId, mrIid, reply);
+    logger.info(`MR !${mrIid}: posted contextual reply`);
+    return { action: "contextual", message: reply };
+  } catch (error) {
+    const fallback = "收到！但处理你的请求时遇到了问题，请稍后重试或在 Issue 中 @我。";
+    try {
+      await deps.gitlabClient.addMergeRequestNote(deps.projectId, mrIid, fallback);
+    } catch { /* silent */ }
+    logger.warn(`MR !${mrIid}: contextual reply failed: ${String(error).slice(0, 300)}`);
+    return { action: "contextual", message: fallback };
+  }
+}

package/src/local-agent/notifier.ts

@@ -0,0 +1,190 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export interface NotifyOptions {
+  title: string;
+  subtitle?: string;
+  message: string;
+  url?: string; // URL to open when notification is clicked
+  sound?: boolean; // default true
+}
+
+// Cache the terminal-notifier availability check
+let terminalNotifierAvailable: boolean | undefined;
+
+async function hasTerminalNotifier(): Promise<boolean> {
+  if (terminalNotifierAvailable !== undefined) return terminalNotifierAvailable;
+  try {
+    await execFileAsync("which", ["terminal-notifier"]);
+    terminalNotifierAvailable = true;
+  } catch {
+    terminalNotifierAvailable = false;
+  }
+  return terminalNotifierAvailable;
+}
+
+/** Reset cached availability — for testing only */
+export function _resetTerminalNotifierCache(): void {
+  terminalNotifierAvailable = undefined;
+}
+
+export async function sendNotification(options: NotifyOptions): Promise<void> {
+  const { title, subtitle, message, url, sound = true } = options;
+
+  try {
+    if (process.platform !== "darwin") return; // macOS only
+
+    if (await hasTerminalNotifier()) {
+      const args = ["-title", title, "-message", message];
+      if (subtitle) args.push("-subtitle", subtitle);
+      if (url) args.push("-open", url);
+      if (sound) args.push("-sound", "default");
+      args.push("-group", "glab-agent"); // prevent notification stacking
+      await execFileAsync("terminal-notifier", args);
+    } else {
+      // Fallback to osascript
+      const escape = (s: string) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      let script = `display notification "${escape(message)}" with title "${escape(title)}"`;
+      if (subtitle) script += ` subtitle "${escape(subtitle)}"`;
+      if (sound) script += ` sound name "default"`;
+      await execFileAsync("osascript", ["-e", script]);
+    }
+  } catch {
+    // Notification failures must never affect the main workflow
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Webhook notification
+// ──────────────────────────────────────────────────────────────────────────────
+
+export interface WebhookPayload {
+  title: string;
+  message: string;
+  url?: string;
+}
+
+function isFeishuUrl(url: string): boolean {
+  return url.includes("feishu.cn") || url.includes("larksuite.com");
+}
+
+function isSlackUrl(url: string): boolean {
+  return url.includes("hooks.slack.com");
+}
+
+function buildWebhookBody(url: string, payload: WebhookPayload): unknown {
+  const text = payload.url
+    ? `${payload.title}\n${payload.message}\n${payload.url}`
+    : `${payload.title}\n${payload.message}`;
+
+  if (isFeishuUrl(url)) {
+    return {
+      msg_type: "text",
+      content: { text }
+    };
+  }
+
+  if (isSlackUrl(url)) {
+    return { text };
+  }
+
+  // Generic webhook — send a structured JSON body
+  return {
+    title: payload.title,
+    message: payload.message,
+    url: payload.url
+  };
+}
+
+export async function sendWebhook(
+  webhookUrl: string,
+  payload: WebhookPayload
+): Promise<void> {
+  try {
+    const body = buildWebhookBody(webhookUrl, payload);
+    const response = await fetch(webhookUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000)
+    });
+    if (!response.ok) {
+      // Read body to prevent connection leak, but ignore content
+      await response.text().catch(() => {});
+    }
+  } catch {
+    // Webhook failures must never affect the main workflow
+  }
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Pre-defined notification templates
+// ──────────────────────────────────────────────────────────────────────────────
+
+export function notifyAccepted(
+  agentName: string,
+  issueIid: number,
+  issueTitle: string,
+  webhookUrl?: string
+): Promise<void> {
+  const title = `\u{1F916} ${agentName} 已接单`;
+  const message = `#${issueIid} ${issueTitle}`;
+  const promises: Promise<void>[] = [
+    sendNotification({
+      title: `\u{1F916} ${agentName}`,
+      subtitle: "\u5DF2\u63A5\u5355",
+      message,
+    })
+  ];
+  if (webhookUrl) {
+    promises.push(sendWebhook(webhookUrl, { title, message }));
+  }
+  return Promise.all(promises).then(() => {});
+}
+
+export function notifyCompleted(
+  agentName: string,
+  issueIid: number,
+  issueTitle: string,
+  mrUrl?: string,
+  webhookUrl?: string
+): Promise<void> {
+  const title = `\u2705 ${agentName} 已完成`;
+  const message = `#${issueIid} ${issueTitle}`;
+  const promises: Promise<void>[] = [
+    sendNotification({
+      title: `\u2705 ${agentName}`,
+      subtitle: "\u5DF2\u5B8C\u6210",
+      message,
+      url: mrUrl,
+    })
+  ];
+  if (webhookUrl) {
+    promises.push(sendWebhook(webhookUrl, { title, message, url: mrUrl }));
+  }
+  return Promise.all(promises).then(() => {});
+}
+
+export function notifyFailed(
+  agentName: string,
+  issueIid: number,
+  issueTitle: string,
+  summary: string,
+  webhookUrl?: string
+): Promise<void> {
+  const title = `\u274C ${agentName} 执行失败`;
+  const message = `#${issueIid} ${issueTitle}\n${summary.slice(0, 100)}`;
+  const promises: Promise<void>[] = [
+    sendNotification({
+      title: `\u274C ${agentName}`,
+      subtitle: "\u6267\u884C\u5931\u8D25",
+      message,
+    })
+  ];
+  if (webhookUrl) {
+    promises.push(sendWebhook(webhookUrl, { title, message }));
+  }
+  return Promise.all(promises).then(() => {});
+}