@chenacc/agentbridge 0.0.0-stage → 0.1.1

package/src/event-store.js

@@ -0,0 +1,330 @@
+import { appendFile, mkdir, open, readFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+
+// The log is append-only and grows without bound, so startup reads a bounded
+// tail. It is still compacted while scanning, because applying the window to raw
+// log lines would let an on-disk delta flood truncate the conversation again.
+const MAX_INIT_BYTES = 16 * 1024 * 1024;
+
+function deltaKey(event) {
+  return `${event.sessionId ?? ""}\u0000${event.turnId ?? ""}`;
+}
+
+// Streaming deltas are progress, not history. Keeping every token in the
+// replay window is what previously pushed real conversation out of it: a single
+// long turn could emit thousands of message.delta events, so a phone that
+// reconnected only ever received the token tail of the newest turn instead of
+// the messages. `retain` therefore keeps at most one delta per turn, merging
+// later chunks into it so a reconnecting client still receives the whole
+// in-progress text.
+function retain(events, deltaByTurn, event) {
+  if (event.kind !== "message.delta") {
+    events.push(event);
+    return;
+  }
+  const key = deltaKey(event);
+  const previous = deltaByTurn.get(key);
+  if (previous) {
+    const index = events.indexOf(previous);
+    if (index >= 0) events.splice(index, 1);
+    const payload = event.payload ?? {};
+    event.payload = {
+      ...payload,
+      text: `${previous.payload?.text ?? ""}${payload.text ?? ""}`,
+      offset: previous.payload?.offset ?? 0,
+    };
+  }
+  events.push(event);
+  deltaByTurn.set(key, event);
+}
+
+export class EventStore {
+  #events = [];
+  #seq = 0;
+  #writes = Promise.resolve();
+  #emitter = new EventEmitter();
+  #appendFile;
+  #deltaByTurn = new Map();
+  // Set once the in-memory window has dropped anything. Until then the window
+  // still holds every event, so a per-session history read never needs the log.
+  #evicted = false;
+
+  constructor({ filePath, maxMemory = 5000, appendFileImpl = appendFile }) {
+    this.filePath = filePath;
+    this.maxMemory = maxMemory;
+    this.#appendFile = appendFileImpl;
+  }
+
+  async init() {
+    await mkdir(path.dirname(this.filePath), { recursive: true });
+    let content;
+    try {
+      content = await this.#readLog();
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      return;
+    }
+    this.#events = [];
+    this.#deltaByTurn = new Map();
+    let lastSeq = 0;
+    for (const line of content.split(/\r?\n/)) {
+      if (!line) continue;
+      let event;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        // A process that was killed mid-append leaves one torn line at the tail.
+        // Refusing to start over that would make the log itself the reason the
+        // bridge cannot come back — every read path below already skips unparsable
+        // lines, and the event they describe was never acknowledged anyway.
+        continue;
+      }
+      if (Number.isSafeInteger(event.seq)) lastSeq = Math.max(lastSeq, event.seq);
+      retain(this.#events, this.#deltaByTurn, event);
+      while (this.#events.length > this.maxMemory) this.#evictOldest();
+    }
+    this.#seq = lastSeq;
+  }
+
+  async #readLog(maxBytes = MAX_INIT_BYTES) {
+    const handle = await open(this.filePath, "r");
+    try {
+      const { size } = await handle.stat();
+      if (size <= maxBytes) return await readFile(this.filePath, "utf8");
+      const start = size - maxBytes;
+      const buffer = Buffer.alloc(maxBytes);
+      await handle.read(buffer, 0, maxBytes, start);
+      const text = buffer.toString("utf8");
+      // The first line of a mid-file slice is almost certainly partial.
+      const firstBreak = text.indexOf("\n");
+      return firstBreak === -1 ? "" : text.slice(firstBreak + 1);
+    } finally {
+      await handle.close();
+    }
+  }
+
+  get lastSeq() {
+    return this.#seq;
+  }
+
+  #evictOldest() {
+    const dropped = this.#events.shift();
+    if (!dropped) return;
+    this.#evicted = true;
+    if (dropped.kind === "message.delta") {
+      const key = deltaKey(dropped);
+      if (this.#deltaByTurn.get(key) === dropped) this.#deltaByTurn.delete(key);
+    }
+  }
+
+  async append(kind, payload, context = {}) {
+    const event = {
+      v: 1,
+      eventId: randomUUID(),
+      seq: ++this.#seq,
+      time: new Date().toISOString(),
+      machineId: context.machineId ?? "local",
+      sessionId: context.sessionId ?? null,
+      turnId: context.turnId ?? null,
+      kind,
+      actor: context.actor ?? { type: "bridge" },
+      payload,
+    };
+
+    // Persist the chunk exactly as it arrived. Merging happens on the in-memory
+    // copy only; writing the merged text would store a growing prefix per line
+    // and make the log grow quadratically.
+    const persisted = { ...event };
+    retain(this.#events, this.#deltaByTurn, event);
+    while (this.#events.length > this.maxMemory) this.#evictOldest();
+    // A transient disk error must not permanently reject the serialized queue.
+    // Recover the chain before scheduling the next append, while preserving order.
+    const write = this.#writes
+      .catch(() => undefined)
+      .then(() => this.#appendFile(this.filePath, `${JSON.stringify(persisted)}\n`, "utf8"));
+    this.#writes = write;
+    try {
+      await write;
+    } catch (cause) {
+      this.#events = this.#events.filter((item) => item.eventId !== event.eventId);
+      const error = new Error("AgentBridge event log is temporarily unavailable; please retry");
+      error.statusCode = 503;
+      error.cause = cause;
+      throw error;
+    }
+    this.#emitter.emit("event", event);
+    return event;
+  }
+
+  listAfter(seq = 0, { sessionId } = {}) {
+    return this.#events.filter((event) => event.seq > seq && (!sessionId || event.sessionId === sessionId));
+  }
+
+  /**
+   * History for one session, independent of what else shares the window.
+   *
+   * The replay window is global, so a busy session can evict a quiet one and a
+   * phone that switches to it would render an empty transcript. Once anything
+   * has been evicted the log tail is read back for that one session, which makes
+   * switching always land on real history instead of on a hole.
+   *
+   * `beforeSeq` pages backwards: the page holds the newest events strictly older
+   * than that cursor, so "加载更早" walks one window at a time instead of asking
+   * for everything at once.
+   */
+  async readSessionHistory(sessionId, { limit = 300, beforeSeq = null } = {}) {
+    const wanted = Number.isSafeInteger(limit) && limit > 0 ? Math.min(limit, 1_000) : 300;
+    const cursor = Number.isSafeInteger(beforeSeq) && beforeSeq > 0 ? beforeSeq : null;
+    const withinCursor = (event) => cursor === null || event.seq < cursor;
+    const inMemory = this.listAfter(0, { sessionId }).filter(withinCursor);
+    let events = inMemory;
+    let fromLog = false;
+    if (this.#evicted) {
+      const persisted = await this.#readSessionFromLog(sessionId);
+      if (persisted.length) {
+        fromLog = true;
+        const bySeq = new Map();
+        for (const event of persisted) {
+          if (withinCursor(event)) bySeq.set(event.seq, event);
+        }
+        for (const event of inMemory) bySeq.set(event.seq, event);
+        events = [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+      }
+    }
+    const hasMore = events.length > wanted;
+    const page = hasMore ? events.slice(-wanted) : events;
+    return {
+      events: page,
+      truncated: hasMore,
+      hasMore,
+      oldestSeq: page.length ? page[0].seq : null,
+      lastSeq: page.length ? page.at(-1).seq : 0,
+      fromLog,
+    };
+  }
+
+  async #readSessionFromLog(sessionId) {
+    let content;
+    try {
+      content = await this.#readLog();
+    } catch (error) {
+      if (error.code === "ENOENT") return [];
+      throw error;
+    }
+    const events = [];
+    const deltaByTurn = new Map();
+    for (const line of content.split(/\r?\n/)) {
+      if (!line) continue;
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      if (event.sessionId !== sessionId || !Number.isSafeInteger(event.seq)) continue;
+      // Same coalescing as the live window: history is read for display, and a
+      // raw delta flood would push the conversation out of it again.
+      retain(events, deltaByTurn, event);
+    }
+    return events;
+  }
+
+  /**
+   * Case-insensitive search across conversation text.
+   *
+   * Long-running agents produce conversations you cannot re-read from the top, so
+   * "which conversation did I agree to that in" has to be answerable. Only message
+   * text is searched (what a person remembers), the newest hits win, and every
+   * result carries the session and sequence so the phone can jump straight there.
+   */
+  async search(query, { limit = 30, perSession = 5, maxLogBytes = 24 * 1024 * 1024 } = {}) {
+    const needle = String(query ?? "").trim().toLowerCase();
+    const wanted = Math.min(Math.max(Number(limit) || 30, 1), 100);
+    const hits = [];
+    if (needle.length < 2) return { hits, scanned: 0, truncated: false };
+
+    const consider = (event, source) => {
+      if (!event || !Number.isSafeInteger(event.seq)) return;
+      const payload = event.payload ?? {};
+      let text = "";
+      let role = "agent";
+      if (event.kind === "message.completed") {
+        text = String(payload.text ?? "");
+        role = payload.role === "user" ? "user" : "assistant";
+      } else if (event.kind === "tool.started" || event.kind === "tool.completed") {
+        text = [payload.command, payload.type].filter(Boolean).join(" ");
+        role = "tool";
+      } else {
+        return;
+      }
+      if (!text) return;
+      const at = text.toLowerCase().indexOf(needle);
+      if (at < 0) return;
+      const padded = text.slice(Math.max(0, at - 40), Math.min(text.length, at + needle.length + 60)).replace(/\s+/g, " ").trim();
+      hits.push({
+        sessionId: event.sessionId ?? null,
+        seq: event.seq,
+        at: event.time ?? event.at ?? null,
+        kind: event.kind,
+        role,
+        snippet: padded,
+        source,
+      });
+    };
+
+    // Newest first, so a cap keeps the most relevant recent matches.
+    const memory = this.listAfter(0);
+    let scanned = 0;
+    for (let index = memory.length - 1; index >= 0 && hits.length < wanted * 3; index -= 1) {
+      scanned += 1;
+      consider(memory[index], "memory");
+    }
+
+    let truncated = false;
+    if (this.#evicted) {
+      let content = null;
+      try {
+        content = await this.#readLog(maxLogBytes);
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+      if (content === null) truncated = true;
+      if (content) {
+        const lines = content.split(/\r?\n/);
+        for (let index = lines.length - 1; index >= 0 && hits.length < wanted * 3; index -= 1) {
+          const line = lines[index];
+          if (!line) continue;
+          let event;
+          try { event = JSON.parse(line); } catch { continue; }
+          scanned += 1;
+          consider(event, "log");
+        }
+      }
+    }
+
+    // De-duplicate the same event seen in both places, then keep the newest.
+    const seen = new Set();
+    const unique = [];
+    for (const hit of hits) {
+      const key = `${hit.sessionId}:${hit.seq}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      unique.push(hit);
+    }
+    unique.sort((a, b) => (b.seq ?? 0) - (a.seq ?? 0));
+
+    const perSessionCount = new Map();
+    const balanced = [];
+    for (const hit of unique) {
+      const count = perSessionCount.get(hit.sessionId) ?? 0;
+      if (count >= perSession) continue;
+      perSessionCount.set(hit.sessionId, count + 1);
+      balanced.push(hit);
+      if (balanced.length >= wanted) break;
+    }
+    return { hits: balanced, scanned, truncated };
+  }
+
+  subscribe(listener) {
+    this.#emitter.on("event", listener);
+    return () => this.#emitter.off("event", listener);
+  }
+}

package/src/notifier.js

@@ -0,0 +1,266 @@
+/**
+ * Outbound notifications for the moments a phone user cannot afford to miss.
+ *
+ * The whole product promise is "let the agent run while you are away", but nothing
+ * can be away-proof if the only signal is a page that has to be open. This module
+ * pushes the three moments that actually block progress — a pending approval, a
+ * pending question, and a finished or failed turn — to a channel the user already
+ * watches (a WeCom bot, Telegram, ServerChan, or any endpoint that accepts JSON).
+ *
+ * Design rules, learned the hard way elsewhere in this codebase:
+ * - Never throw: a dead webhook must not fail the turn it is describing.
+ * - Never block: the caller fires and forgets; `send` resolves to a result object.
+ * - Never storm: transcripts emit many events, so identical (session, kind) pairs
+ *   are rate limited, and only the five meaningful kinds are forwarded at all.
+ * - Never leak the access key unless the operator explicitly opts in.
+ */
+
+const FORMATS = new Set(["json", "wecom", "telegram", "serverchan", "pushplus"]);
+
+const DEFAULT_TITLES = {
+  "approval.requested": "需要批准",
+  "input.requested": "等你回答",
+  "turn.completed": "回合结束",
+  "turn.failed": "回合失败",
+  "session.failed": "会话失败",
+  "notify.test": "通知测试",
+};
+
+function clip(value, limit) {
+  const text = typeof value === "string" ? value : value === undefined || value === null ? "" : String(value);
+  return text.length > limit ? `${text.slice(0, limit)}…` : text;
+}
+
+/** Build the human-readable body of a notification, in the app's own voice. */
+export function describeNotification(kind, payload = {}, context = {}) {
+  const sessionLabel = clip(context.sessionTitle || "未命名会话", 60);
+  const adapter = clip(context.adapterLabel ?? context.adapterId ?? "", 40);
+  const where = [sessionLabel, adapter].filter(Boolean).join(" · ");
+  switch (kind) {
+    case "approval.requested": {
+      const method = clip(payload.request?.toolName ?? payload.method ?? "工具", 60);
+      return {
+        title: `⚠️ 需要批准：${method}`,
+        text: [`${where}`, `Agent 想执行 ${method}，等你确认。`, clip(payload.request?.reason ?? "", 200)].filter(Boolean).join("\n"),
+      };
+    }
+    case "input.requested": {
+      const first = payload.questions?.[0];
+      const question = clip(first?.question ?? first?.header ?? "一个问题", 200);
+      const more = (payload.questions?.length ?? 1) > 1 ? `（共 ${payload.questions.length} 个问题）` : "";
+      return { title: `❓ 等你回答${more}`, text: [`${where}`, question].filter(Boolean).join("\n") };
+    }
+    case "turn.completed": {
+      const last = clip(context.lastAssistantText ?? "", 160);
+      return { title: `✅ 回合结束：${sessionLabel}`, text: [where, last].filter(Boolean).join("\n") };
+    }
+    case "turn.failed": {
+      return { title: `❌ 回合失败：${sessionLabel}`, text: [where, clip(payload.error ?? "未知错误", 300)].filter(Boolean).join("\n") };
+    }
+    case "session.failed": {
+      return { title: `❌ 会话失败：${sessionLabel}`, text: [where, clip(payload.error ?? "未知错误", 300)].filter(Boolean).join("\n") };
+    }
+    case "notify.test": {
+      return { title: "🔔 AgentBridge 通知测试", text: [`${where}`, "如果你看到这条消息，通知链路是通的。"].filter(Boolean).join("\n") };
+    }
+    default:
+      return { title: DEFAULT_TITLES[kind] ?? "AgentBridge", text: where };
+  }
+}
+
+/** Shape the request for one provider. Kept separate so it can be unit tested. */
+export function buildWebhookRequest({ format, webhookUrl, chatId, token, channel, title, text, payload }) {
+  if (format === "wecom") {
+    return { url: webhookUrl, body: { msgtype: "text", text: { content: `${title}\n${text}` } } };
+  }
+  if (format === "serverchan") {
+    return { url: webhookUrl, body: { title, desp: text.replace(/\n/g, "\n\n") } };
+  }
+  if (format === "pushplus") {
+    // PushPlus takes `token` in the body (or in the URL as /send/{token}), plus a
+    // title and content; `txt` keeps the newlines a chat message needs.
+    const tokenInUrl = /[?&]token=|\/send\/[^/?]+/.test(webhookUrl);
+    return {
+      url: webhookUrl,
+      body: {
+        ...(!tokenInUrl && token ? { token } : {}),
+        title,
+        content: `${title}\n${text}`,
+        template: "txt",
+        // PushPlus delivers through a chosen channel; `clawbot` is the 微信ClawBot one.
+        ...(channel ? { channel } : {}),
+      },
+    };
+  }
+  if (format === "telegram") {
+    return {
+      url: webhookUrl,
+      body: {
+        ...(chatId ? { chat_id: chatId } : {}),
+        text: `${title}\n${text}`,
+        disable_web_page_preview: true,
+      },
+    };
+  }
+  // Generic JSON: a superset that custom receivers, Discord and Slack-style
+  // endpoints can all read (`text` is the common denominator).
+  return { url: webhookUrl, body: { ...payload, title, text: `${title}\n${text}` } };
+}
+
+/**
+ * Providers answer HTTP 200 and put the real result in the body.
+ *
+ * This is the difference between "the test button said sent" and a message that
+ * actually arrived: WeCom returns `errcode`, PushPlus returns `code`, ServerChan
+ * returns `code`/`data.errno`, Telegram returns `ok`. The generic `json` format is
+ * left alone because a custom endpoint's body is its own business.
+ */
+export function providerProblem(format, body) {
+  if (!body || typeof body !== "object") return null;
+  const describe = (code, message) => `provider-${code}${message ? `:${String(message).slice(0, 120)}` : ""}`;
+  if (format === "wecom" && Number(body.errcode) > 0) return describe(body.errcode, body.errmsg);
+  if (format === "pushplus") {
+    const code = Number(body.code);
+    if (Number.isFinite(code) && code !== 200) return describe(code, body.msg ?? body.message);
+    return null;
+  }
+  if (format === "serverchan") {
+    if (Number(body.code) > 0) return describe(body.code, body.message);
+    if (body.data && Number(body.data.errno) > 0) return describe(body.data.errno, body.data.errmsg);
+    return null;
+  }
+  if (format === "telegram" && body.ok === false) return describe(body.error_code ?? "error", body.description);
+  return null;
+}
+
+export class Notifier {
+  #fmt = "json";
+  #webhookUrl = null;
+  #chatId = null;
+  #token = null;
+  #channel = null;
+  #muted = false;
+  #linkUrl = null;
+  #fetch = null;
+  #now = () => Date.now();
+  #logger = console;
+  #timeoutMs = 5_000;
+  #minIntervalMs = 15_000;
+  #lastSent = new Map();
+
+  constructor(options = {}) {
+    const format = String(options.format ?? "json").toLowerCase();
+    this.#fmt = FORMATS.has(format) ? format : "json";
+    this.#webhookUrl = typeof options.webhookUrl === "string" && options.webhookUrl.trim() ? options.webhookUrl.trim() : null;
+    this.#chatId = options.chatId ? String(options.chatId) : null;
+    this.#token = options.token ? String(options.token) : null;
+    this.#channel = options.channel ? String(options.channel) : null;
+    this.#muted = options.muted === true;
+    this.#linkUrl = typeof options.linkUrl === "string" && options.linkUrl.trim() ? options.linkUrl.trim() : null;
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    if (typeof options.now === "function") this.#now = options.now;
+    if (options.logger) this.#logger = options.logger;
+    if (Number.isFinite(options.timeoutMs)) this.#timeoutMs = options.timeoutMs;
+    if (Number.isFinite(options.minIntervalMs)) this.#minIntervalMs = options.minIntervalMs;
+  }
+
+  get enabled() {
+    return Boolean(this.#webhookUrl);
+  }
+
+  get format() {
+    return this.#fmt;
+  }
+
+  /** The provider-specific delivery channel, when one is configured. */
+  get channel() {
+    return this.#channel;
+  }
+
+  /**
+   * Muted means configured-but-silent: the phone can stop the buzzing without
+   * throwing away the webhook, the token or the channel.
+   */
+  get muted() {
+    return this.#muted;
+  }
+
+  setMuted(value) {
+    this.#muted = value === true;
+    return this.#muted;
+  }
+
+  /**
+   * Send one notification. Always resolves: `{ sent, reason }` describes what
+   * happened, and a failure is logged instead of thrown.
+   */
+  async send(kind, payload, context = {}) {
+    if (!this.enabled) return { sent: false, reason: "disabled" };
+    if (this.#muted) return { sent: false, reason: "muted" };
+    if (kind !== "notify.test") {
+      const key = `${context.sessionId ?? "-"}:${kind}`;
+      const last = this.#lastSent.get(key);
+      // The first signal for a pair always goes out; only repeats are damped.
+      if (last !== undefined && this.#now() - last < this.#minIntervalMs) {
+        return { sent: false, reason: "rate-limited" };
+      }
+      this.#lastSent.set(key, this.#now());
+      if (this.#lastSent.size > 500) this.#lastSent.delete(this.#lastSent.keys().next().value);
+    }
+
+    const { title, text } = describeNotification(kind, payload, context);
+    const body = {
+      kind,
+      machine: clip(context.machineName ?? "", 60),
+      sessionId: context.sessionId ?? null,
+      sessionTitle: clip(context.sessionTitle ?? "", 100),
+      adapter: context.adapterId ?? null,
+      at: new Date(this.#now()).toISOString(),
+      ...(this.#linkUrl ? { url: this.#linkUrl } : {}),
+    };
+    const request = buildWebhookRequest({
+      format: this.#fmt,
+      webhookUrl: this.#webhookUrl,
+      chatId: this.#chatId,
+      token: this.#token,
+      channel: this.#channel,
+      title,
+      text,
+      payload: body,
+    });
+
+    try {
+      const response = await this.#fetch(request.url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(request.body),
+        signal: AbortSignal.timeout(this.#timeoutMs),
+      });
+      if (!response?.ok) {
+        this.#logger.warn?.(`AgentBridge notification rejected (${response?.status ?? "no response"})`);
+        return { sent: false, reason: `http-${response?.status ?? "error"}` };
+      }
+      // A 200 with an error code in the body is the normal failure mode of these
+      // providers, and reporting it as "sent" would make the test button lie.
+      let providerBody = null;
+      try {
+        if (typeof response.text === "function") {
+          const raw = await response.text();
+          if (raw) providerBody = JSON.parse(raw);
+        }
+      } catch {
+        providerBody = null;
+      }
+      const problem = providerProblem(this.#fmt, providerBody);
+      if (problem) {
+        this.#logger.warn?.(`AgentBridge notification rejected by the provider (${problem})`);
+        return { sent: false, reason: problem };
+      }
+      return { sent: true };
+    } catch (error) {
+      // A notification is best-effort by definition: never let it break a turn.
+      this.#logger.warn?.(`AgentBridge notification failed: ${error instanceof Error ? error.message : String(error)}`);
+      return { sent: false, reason: "error" };
+    }
+  }
+}