agent-loft 0.0.0-stage → 0.2.8

package/src/core/interactions.ts

@@ -0,0 +1,273 @@
+// 交互中枢：agent 发起的每一次审批 / 提问，都在这里变成一条「待处理」和一个 Promise。
+//
+// 和旧桥接器的区别在于它不认识任何渠道：飞书、Web 都只是订阅者。同一条请求可以
+// 同时显示在飞书卡片和 Web 页面上，哪边先处理算哪边，其余订阅者收到 settled 事件
+// 后把自己那份改成「已处理」。
+//
+// 继承下来的几条硬规矩：
+//   - 超时一律按「没放行」收束，绝不能是放行；
+//   - 选项用「设成」语义而不是「切换」，渠道重投回调时结果不变；
+//   - 丢弃 / 中断会话时必须取消它挂着的所有请求，否则阻塞的那一轮永远走不完。
+import crypto from "node:crypto";
+import { EventEmitter } from "node:events";
+import type { InteractionOutcome, InteractionSpec, QuestionSpec, Settlement } from "./types.js";
+
+export type Interaction = {
+  id: string;
+  convKey: string;
+  spec: InteractionSpec;
+  createdAt: number;
+  expiresAt: number;
+  /** 仅提问：与 questions 等长，每问已选中的选项下标 */
+  selections: number[][];
+  /** 仅提问：自由作答，按问题下标存 */
+  freeText: Record<number, string>;
+  settled?: { settlement: Settlement; by: string; at: number };
+  /** 发起它的会话进程编号：只有这个进程还活着时，普通消息才能拿来作答 */
+  owner?: number;
+};
+
+type Entry = Interaction & {
+  resolve: (outcome: InteractionOutcome) => void;
+  timer: NodeJS.Timeout;
+};
+
+export type InteractionEvents = {
+  created: [Interaction];
+  updated: [Interaction];
+  settled: [Interaction];
+};
+
+class InteractionCenter extends EventEmitter<InteractionEvents> {
+  private pending = new Map<string, Entry>();
+  /** 已收束的留一小段时间，供渠道回调时给出准确的「已由 xx 处理」提示 */
+  private recent = new Map<string, Interaction>();
+
+  create(convKey: string, spec: InteractionSpec, timeoutMs: number, owner?: number): Promise<InteractionOutcome> {
+    const id = `req_${crypto.randomBytes(4).toString("hex")}`;
+    let resolve!: (outcome: InteractionOutcome) => void;
+    const promise = new Promise<InteractionOutcome>((r) => {
+      resolve = r;
+    });
+    const timer = setTimeout(() => this.settle(id, "timeout", "无人响应"), timeoutMs);
+    timer.unref?.();
+    const now = Date.now();
+    const entry: Entry = {
+      id,
+      convKey,
+      spec,
+      createdAt: now,
+      expiresAt: now + timeoutMs,
+      selections: spec.kind === "question" ? spec.questions.map(() => []) : [],
+      freeText: {},
+      ...(owner !== undefined ? { owner } : {}),
+      resolve,
+      timer,
+    };
+    this.pending.set(id, entry);
+    this.emit("created", publicView(entry));
+    return promise;
+  }
+
+  get(id: string): Interaction | undefined {
+    const entry = this.pending.get(id);
+    return entry ? publicView(entry) : this.recent.get(id);
+  }
+
+  isPending(id: string): boolean {
+    return this.pending.has(id);
+  }
+
+  /** 某会话当前挂着的全部请求（Web 端打开会话时要补画出来）。 */
+  listPending(convKey?: string): Interaction[] {
+    return [...this.pending.values()]
+      .filter((e) => !convKey || e.convKey === convKey)
+      .map(publicView);
+  }
+
+  /** 审批决定。返回 undefined 表示请求已不在（超时、已处理、或进程重启过）。 */
+  decide(id: string, decision: Settlement, by: string): Interaction | undefined {
+    const entry = this.pending.get(id);
+    if (!entry || entry.spec.kind !== "approval") return undefined;
+    // 卡上没有这个按钮（比如批准计划）就不认：不能靠手打 /approve 绕过去
+    if (decision === "allow-session" && !entry.spec.allowSession) return undefined;
+    const settled = this.settle(id, decision, by);
+    if (decision === "allow-session") {
+      // 并行的工具调用会同时挂着好几张卡：同一个会话进程里能一并放行的，一起放掉
+      for (const other of [...this.pending.values()]) {
+        if (other.convKey !== entry.convKey || other.owner !== entry.owner) continue;
+        if (other.spec.kind !== "approval" || !other.spec.allowSession) continue;
+        this.settle(other.id, "allow-session", `${by}（随「本会话全部允许」）`);
+      }
+    }
+    return settled;
+  }
+
+  /** 把某个选项设成选中 / 未选中。全单选且都答完时自动收束。 */
+  select(
+    id: string,
+    questionIndex: number,
+    optionIndex: number,
+    selected: boolean,
+    by: string,
+  ): { interaction: Interaction; submitted: boolean } | undefined {
+    const entry = this.pending.get(id);
+    if (!entry || entry.spec.kind !== "question") return undefined;
+    const spec = entry.spec.questions[questionIndex];
+    const picked = entry.selections[questionIndex];
+    if (!spec || !picked || !spec.options[optionIndex]) return undefined;
+
+    if (spec.multiSelect) {
+      const at = picked.indexOf(optionIndex);
+      if (selected && at < 0) picked.push(optionIndex);
+      if (!selected && at >= 0) picked.splice(at, 1);
+    } else {
+      entry.selections[questionIndex] = selected ? [optionIndex] : [];
+      delete entry.freeText[questionIndex];
+    }
+
+    const allSingle = entry.spec.questions.every((q) => !q.multiSelect);
+    if (allSingle && unansweredCount(entry) === 0) {
+      return { interaction: this.settle(id, "answered", by)!, submitted: true };
+    }
+    this.emit("updated", publicView(entry));
+    return { interaction: publicView(entry), submitted: false };
+  }
+
+  /** 点「提交」。还有没答的问题时返回 { missing }。 */
+  submit(id: string, by: string): Interaction | { missing: number } | undefined {
+    const entry = this.pending.get(id);
+    if (!entry || entry.spec.kind !== "question") return undefined;
+    const missing = unansweredCount(entry);
+    if (missing > 0) return { missing };
+    return this.settle(id, "answered", by);
+  }
+
+  skip(id: string, by: string): Interaction | undefined {
+    const entry = this.pending.get(id);
+    if (!entry || entry.spec.kind !== "question") return undefined;
+    entry.selections = entry.selections.map(() => []);
+    entry.freeText = {};
+    return this.settle(id, "skipped", by);
+  }
+
+  /**
+   * 用一条普通消息回答提问 —— 等价于官方 UI 里的「Other」自由输入。
+   * 写进第一个还没作答的问题；返回 true 表示这条消息已被消费，不该再送进会话。
+   */
+  answerWithText(id: string, text: string, by: string): boolean {
+    const entry = this.pending.get(id);
+    if (!entry || entry.spec.kind !== "question") return false;
+    const index = entry.selections.findIndex((picked, i) => picked.length === 0 && !entry.freeText[i]);
+    if (index < 0) {
+      // 都答过了（多选还没点提交）：这条消息不是作答，交给会话照常处理
+      return false;
+    }
+    entry.freeText[index] = text;
+    // 还有没答的问题：留着让人继续答（下一条消息或点按钮），不能提前交卷
+    if (unansweredCount(entry) > 0) {
+      this.emit("updated", publicView(entry));
+      return true;
+    }
+    this.settle(id, "answered", by);
+    return true;
+  }
+
+  /** 这条会话里挂着的提问（正常同时只会有一个）。 */
+  findQuestion(convKey: string): Interaction | undefined {
+    let oldest: Entry | undefined;
+    for (const entry of this.pending.values()) {
+      if (entry.spec.kind !== "question" || entry.convKey !== convKey) continue;
+      if (!oldest || entry.createdAt < oldest.createdAt) oldest = entry;
+    }
+    return oldest ? publicView(oldest) : undefined;
+  }
+
+  /** 取消某会话上所有挂着的请求。中断、切目录、开新会话时必须调用。 */
+  cancelAll(convKey: string, note: string): Interaction[] {
+    const out: Interaction[] = [];
+    for (const entry of [...this.pending.values()]) {
+      if (entry.convKey !== convKey) continue;
+      const settled = this.settle(entry.id, "cancelled", note);
+      if (settled) out.push(settled);
+    }
+    return out;
+  }
+
+  private settle(id: string, settlement: Settlement, by: string): Interaction | undefined {
+    const entry = this.pending.get(id);
+    if (!entry) return undefined;
+    clearTimeout(entry.timer);
+    this.pending.delete(id);
+    entry.settled = { settlement, by, at: Date.now() };
+    const view = publicView(entry);
+    this.recent.set(id, view);
+    if (this.recent.size > 200) this.recent.delete(this.recent.keys().next().value!);
+    entry.resolve({ settlement, answers: answersOf(entry) });
+    this.emit("settled", view);
+    return view;
+  }
+}
+
+function publicView(entry: Entry | Interaction): Interaction {
+  const { id, convKey, spec, createdAt, expiresAt, selections, freeText, settled, owner } = entry;
+  return {
+    id,
+    convKey,
+    spec,
+    createdAt,
+    expiresAt,
+    selections: selections.map((s) => [...s]),
+    freeText: { ...freeText },
+    ...(settled ? { settled } : {}),
+    ...(owner !== undefined ? { owner } : {}),
+  };
+}
+
+export function unansweredCount(entry: Interaction): number {
+  return entry.selections.filter((picked, i) => picked.length === 0 && !entry.freeText[i]).length;
+}
+
+/** 问题 id → 答案。没作答的问题不出现在表里 —— 不替人编答案。 */
+export function answersOf(entry: Interaction): Record<string, string[]> {
+  const answers: Record<string, string[]> = {};
+  if (entry.spec.kind !== "question") return answers;
+  if (entry.settled && entry.settled.settlement !== "answered") return answers;
+  entry.spec.questions.forEach((spec: QuestionSpec, i) => {
+    const free = entry.freeText[i];
+    if (free) {
+      answers[spec.id] = [free];
+      return;
+    }
+    const labels = (entry.selections[i] ?? [])
+      .map((o) => spec.options[o]?.label)
+      .filter((l): l is string => !!l);
+    if (labels.length > 0) answers[spec.id] = labels;
+  });
+  return answers;
+}
+
+/** 给人看的：问题原文 → 答案文字。 */
+export function answerTextOf(entry: Interaction): Record<string, string> {
+  const shown: Record<string, string> = {};
+  if (entry.spec.kind !== "question") return shown;
+  const answers = answersOf(entry);
+  for (const spec of entry.spec.questions) {
+    const picked = answers[spec.id];
+    if (picked) shown[spec.question] = picked.join(", ");
+  }
+  return shown;
+}
+
+export const SETTLEMENT_LABEL: Record<Settlement, string> = {
+  "allow-once": "已允许（本次）",
+  "allow-always": "已允许",
+  "allow-session": "已允许（本会话全部放行）",
+  deny: "已拒绝",
+  timeout: "已超时，按拒绝处理",
+  cancelled: "已取消",
+  answered: "已回答",
+  skipped: "已跳过",
+};
+
+export const interactions = new InteractionCenter();

package/src/core/pairing.ts

@@ -0,0 +1,156 @@
+// 配对：陌生人给机器人发消息时拿到一个短码，消息本身不被处理；
+// 在 Web 设置页或终端批准之后他才能用。替代手工抄 open_id。
+//
+// 按渠道实例分开记（channelId = 飞书机器人 id / 以后的 Telegram 机器人 id）：
+// 在 A 机器人上被批准，不等于能用 B 机器人。
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { EventEmitter } from "node:events";
+import { dataDir, readJson, writeJsonAtomic } from "../home.js";
+
+/** 去掉 0/O/1/I，避免念错抄错 */
+const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+const CODE_LENGTH = 8;
+const CODE_TTL_MS = 60 * 60 * 1000;
+/** 同时最多挂 3 个待批请求，防止陌生人刷屏 */
+const MAX_PENDING = 3;
+
+export type PairRequest = {
+  code: string;
+  userId: string;
+  chatId: string;
+  name?: string;
+  createdAt: number;
+};
+
+type ChannelPairs = { pending: PairRequest[]; approved: string[] };
+type Store = Record<string, ChannelPairs>;
+
+const storePath = path.join(dataDir, "pairing.json");
+export const pairingEvents = new EventEmitter<{ approved: [string, PairRequest]; requested: [string, PairRequest] }>();
+
+function read(): Store {
+  return readJson<Store>(storePath, {});
+}
+
+function channel(store: Store, channelId: string, now = Date.now()): ChannelPairs {
+  const entry = (store[channelId] ??= { pending: [], approved: [] });
+  entry.pending = entry.pending.filter((p) => now - p.createdAt < CODE_TTL_MS);
+  return entry;
+}
+
+function newCode(): string {
+  return Array.from(crypto.randomBytes(CODE_LENGTH), (b) => CODE_ALPHABET[b % CODE_ALPHABET.length]).join("");
+}
+
+export function isPaired(channelId: string, userId: string | undefined): boolean {
+  if (!userId) return false;
+  return (read()[channelId]?.approved ?? []).includes(userId.trim().toLowerCase());
+}
+
+export type PairOutcome =
+  | { kind: "already_pending"; request: PairRequest }
+  | { kind: "created"; request: PairRequest }
+  | { kind: "rejected_full" };
+
+export function requestPairing(channelId: string, params: { userId: string; chatId: string; name?: string }): PairOutcome {
+  const store = read();
+  const ch = channel(store, channelId);
+  const userId = params.userId.trim().toLowerCase();
+  const existing = ch.pending.find((p) => p.userId === userId);
+  if (existing) return { kind: "already_pending", request: existing };
+  if (ch.pending.length >= MAX_PENDING) return { kind: "rejected_full" };
+  const request: PairRequest = {
+    code: newCode(),
+    userId,
+    chatId: params.chatId,
+    ...(params.name ? { name: params.name } : {}),
+    createdAt: Date.now(),
+  };
+  ch.pending.push(request);
+  writeJsonAtomic(storePath, store);
+  pairingEvents.emit("requested", channelId, request);
+  return { kind: "created", request };
+}
+
+/** 所有渠道的待批请求 */
+export function listPending(): { channelId: string; request: PairRequest }[] {
+  const store = read();
+  return Object.keys(store).flatMap((id) => channel(store, id).pending.map((request) => ({ channelId: id, request })));
+}
+
+export function listApproved(channelId?: string): { channelId: string; userId: string }[] {
+  const store = read();
+  return Object.entries(store)
+    .filter(([id]) => !channelId || id === channelId)
+    .flatMap(([id, ch]) => ch.approved.map((userId) => ({ channelId: id, userId })));
+}
+
+/** 按配对码批准。码在所有渠道里找，找到哪个算哪个。 */
+export function approve(code: string): { ok: true; channelId: string; request: PairRequest } | { ok: false } {
+  const store = read();
+  const normalized = code.trim().toUpperCase();
+  for (const channelId of Object.keys(store)) {
+    const ch = channel(store, channelId);
+    const index = ch.pending.findIndex((p) => p.code === normalized);
+    if (index === -1) continue;
+    const [request] = ch.pending.splice(index, 1);
+    if (!request) continue;
+    if (!ch.approved.includes(request.userId)) ch.approved.push(request.userId);
+    writeJsonAtomic(storePath, store);
+    pairingEvents.emit("approved", channelId, request);
+    return { ok: true, channelId, request };
+  }
+  return { ok: false };
+}
+
+export function revoke(channelId: string, userId: string): boolean {
+  const store = read();
+  const ch = channel(store, channelId);
+  const normalized = userId.trim().toLowerCase();
+  const before = ch.approved.length;
+  ch.approved = ch.approved.filter((id) => id !== normalized);
+  writeJsonAtomic(storePath, store);
+  return ch.approved.length !== before;
+}
+
+/**
+ * 终端里另一个进程批准的，本进程靠监听文件得知。
+ * 回调收到的是「新出现的已批准用户」。
+ */
+export function watchPairing(onApproved: (channelId: string, userId: string, chatId?: string) => void): void {
+  let known = new Set(listApproved().map((a) => `${a.channelId}|${a.userId}`));
+  // 批准时 pending 里的那条已经被删了，chatId 得提前记下来
+  const chats = new Map<string, string>();
+  for (const { channelId, request } of listPending()) chats.set(`${channelId}|${request.userId}`, request.chatId);
+  pairingEvents.on("requested", (channelId, request) => chats.set(`${channelId}|${request.userId}`, request.chatId));
+  pairingEvents.on("approved", (channelId, request) => {
+    known.add(`${channelId}|${request.userId}`);
+    onApproved(channelId, request.userId, request.chatId);
+  });
+  try {
+    fs.mkdirSync(dataDir, { recursive: true });
+    if (!fs.existsSync(storePath)) writeJsonAtomic(storePath, {});
+    fs.watch(dataDir, { persistent: false }, (_event, file) => {
+      if (file !== "pairing.json") return;
+      const current = listApproved();
+      for (const a of current) {
+        const id = `${a.channelId}|${a.userId}`;
+        if (!known.has(id)) onApproved(a.channelId, a.userId, chats.get(id));
+      }
+      known = new Set(current.map((a) => `${a.channelId}|${a.userId}`));
+    });
+  } catch {
+    // 监听不了就只认本进程里的批准
+  }
+}
+
+/** 直接加入已批准名单（迁移旧数据用）。 */
+export function addApproved(channelId: string, userId: string): void {
+  const store = read();
+  const ch = channel(store, channelId);
+  const normalized = userId.trim().toLowerCase();
+  if (!ch.approved.includes(normalized)) ch.approved.push(normalized);
+  writeJsonAtomic(storePath, store);
+}

package/src/core/store.ts

@@ -0,0 +1,178 @@
+// 会话（conversation）的持久化。
+//
+// 一个 conversation 是「一个聊天上下文」：飞书的一个私聊 / 群 / 话题，或者 Web 上
+// 的一条对话。它记着当前用哪个 agent、在哪个目录，以及**每个 agent 各自**的会话 id
+// 和模型 —— 在同一个群里从 Claude 切到 Codex 再切回来，Claude 那条会话还在。
+import path from "node:path";
+import { dataDir, readJson, writeJsonAtomic } from "../home.js";
+import { config } from "./config.js";
+
+export type AgentBinding = {
+  /** agent 侧的会话 id（Claude 的 sessionId / Codex 的 threadId） */
+  sessionId?: string;
+  /** 用户显式选的模型，开新会话清掉 */
+  model?: string;
+  effort?: string;
+  /**
+   * 待分叉：/fork 之后、新会话真正建立之前，记着要从哪个会话分叉。
+   * 必须落盘：期间切了 agent、或者 agent-loft 重启了，下一条消息仍要分叉，而不是续写原会话。
+   * 拿到不同于它的新会话 id 后清掉。
+   */
+  forkFrom?: string;
+};
+
+export type Conversation = {
+  key: string;
+  /** 渠道类型：feishu / web / telegram… */
+  channel: string;
+  /** 渠道实例：飞书是机器人 id，Web 固定 web */
+  channelId: string;
+  title?: string;
+  agent: string;
+  cwd: string;
+  /** cwd 是否用户显式指定。没指定过的跟随 workspaceRoot 变化 */
+  cwdExplicit?: boolean;
+  perAgent: Record<string, AgentBinding>;
+  /** 最后一次有人说话的时间，用于闲置过期 */
+  activeAt: number;
+  createdAt: number;
+  /** Web 列表里隐藏（Web 上删除的会话只是隐藏，agent 侧的历史还在） */
+  hidden?: boolean;
+  /** /autoedit：这条对话里 agent 在工作目录内改文件不再询问（跨 /new 保留，属于对话不属于某个会话） */
+  autoEdit?: boolean;
+  /** 从哪条对话分叉出来的（对话 key），列表里据此显示关联 */
+  forkOf?: string;
+};
+
+type StoreShape = Record<string, Conversation>;
+
+const storePath = path.join(dataDir, "conversations.json");
+let cache: StoreShape | null = null;
+let persistTimer: NodeJS.Timeout | null = null;
+
+function load(): StoreShape {
+  cache ??= readJson<StoreShape>(storePath, {});
+  return cache;
+}
+
+/** 合并写盘：一轮对话里会频繁 touch，没必要每次都落盘。 */
+function persist(immediate = false): void {
+  if (immediate) {
+    if (persistTimer) clearTimeout(persistTimer);
+    persistTimer = null;
+    writeJsonAtomic(storePath, cache ?? {});
+    return;
+  }
+  persistTimer ??= setTimeout(() => {
+    persistTimer = null;
+    writeJsonAtomic(storePath, cache ?? {});
+  }, 500);
+}
+
+export function flushStore(): void {
+  if (persistTimer) persist(true);
+}
+
+function insideRoot(dir: string): boolean {
+  const root = config().workspaceRoot;
+  const rel = path.relative(root, dir);
+  return dir === root || (rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+/** 目录跟随配置：没显式指定过的跟着 workspaceRoot 走，显式指定的只在越界时回退。 */
+function reconcileCwd(conv: Conversation): Conversation {
+  const root = config().workspaceRoot;
+  const needsReset = conv.cwdExplicit ? !insideRoot(conv.cwd) : conv.cwd !== root;
+  if (!needsReset) return conv;
+  console.warn(`[store] 会话 ${conv.key} 的工作目录由 ${conv.cwd} 重置为 ${root}`);
+  conv.cwd = root;
+  conv.cwdExplicit = false;
+  // 目录变了，旧会话的上下文已经没意义
+  for (const binding of Object.values(conv.perAgent)) {
+    delete binding.sessionId;
+    delete binding.forkFrom;
+  }
+  persist();
+  return conv;
+}
+
+export function getConversation(key: string): Conversation | undefined {
+  const conv = load()[key];
+  return conv ? reconcileCwd(conv) : undefined;
+}
+
+export function ensureConversation(params: {
+  key: string;
+  channel: string;
+  channelId: string;
+  agent: string;
+  title?: string;
+}): Conversation {
+  const existing = getConversation(params.key);
+  if (existing) return existing;
+  const now = Date.now();
+  const conv: Conversation = {
+    key: params.key,
+    channel: params.channel,
+    channelId: params.channelId,
+    agent: params.agent,
+    cwd: config().workspaceRoot,
+    perAgent: {},
+    activeAt: now,
+    createdAt: now,
+    ...(params.title ? { title: params.title } : {}),
+  };
+  load()[params.key] = conv;
+  persist(true);
+  return conv;
+}
+
+export function updateConversation(key: string, patch: Partial<Conversation>): Conversation {
+  const conv = getConversation(key);
+  if (!conv) throw new Error(`会话不存在：${key}`);
+  Object.assign(conv, patch);
+  persist();
+  return conv;
+}
+
+export function agentBinding(conv: Conversation, agent = conv.agent): AgentBinding {
+  return (conv.perAgent[agent] ??= {});
+}
+
+export function updateAgentBinding(key: string, agent: string, patch: Partial<AgentBinding>): void {
+  const conv = getConversation(key);
+  if (!conv) return;
+  const binding = agentBinding(conv, agent);
+  for (const [k, v] of Object.entries(patch)) {
+    if (v === undefined) delete (binding as Record<string, unknown>)[k];
+    else (binding as Record<string, unknown>)[k] = v;
+  }
+  persist();
+}
+
+export function touchConversation(key: string): void {
+  const conv = getConversation(key);
+  if (!conv) return;
+  conv.activeAt = Date.now();
+  persist();
+}
+
+export function isExpired(conv: Conversation, now = Date.now()): boolean {
+  const ttl = config().sessionTtlMs;
+  return ttl > 0 && now - conv.activeAt > ttl;
+}
+
+export function listConversations(): Conversation[] {
+  return Object.values(load()).map(reconcileCwd);
+}
+
+export function deleteConversation(key: string): void {
+  delete load()[key];
+  persist(true);
+}
+
+/** 迁移旧数据用：整条写入。 */
+export function putConversation(conv: Conversation): void {
+  load()[conv.key] = conv;
+  persist(true);
+}