Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

17.0 KB
Raw Blame
/**
 * 自动任务(scheduler)终态通知的抑制标记。
 *
 * 两组标记语义刻意分开:
 *   - silenced:静默运行的成功 run —— 完全不发通知、不亮角标。来源有两条:
 *     `Schedule.silentWhenIdle` 预设(run 开始、session-bound 时就静默),以及 agent
 *     在自己 turn 内调 `schedule_silence_current_run`(引擎 `silenceRun`)。两条都走
 *     `silenced` 事件,但**建立标记的时机相对 turn 完全不同**(一条在 turn 之前、
 *     一条在 turn 中间),任何依赖「事件序」的判断都会在其中一条上翻车。
 *   - schedulerOwned:普通自动任务 —— scheduler notifier 已按 `schedule.notify`
 *     发过这次终态通知,renderer 不能再发第二条。成功完成不再从 running→done
 *     点 `done` attention(绿点改认 schedule 未读 + `completed && !silenced`
 *     乐观未读);失败仍立即点 `error` 红点。
 *
 * **标记的生命周期跟随 run,不是「被第一次 done 消费掉」**:一个 run 内 session
 * 的 running→done 会翻转多次(后台 subagent 完成后 SDK 自动续 turn、silent-stop
 * 守卫 1.5s 后自动续跑、队列自动衔接),标记必须活过每一次中间 done,否则最终那
 * 次真 done 会当成普通完成,把 macOS toast / 飞书 / 手机推送全发一遍。
 *
 * 清除只有三条路径:scheduler 的 completed / failed / notified 事件、run 已终态后该
 * session 又起新 turn、以及对账权威 run 状态(`reconcileRunMarkers`,治事件丢失)。前两条
 * 与第三条统一走 `MARKER_TERMINAL_LINGER_MS` 的退场窗口。main 侧灵动岛
 * (`main/agent-island/service.ts` 的 `isCompletionEventSilenced`)是同一套语义,
 * 两边不要再分叉。
 */

const silencedRunSessionIds = new Map<string, string>();
const silencedSessionRunIds = new Map<string, string>();
const silencedRunHadAttention = new Map<string, boolean>();
const schedulerOwnedRunSessionIds = new Map<string, string>();
const schedulerOwnedSessionRunIds = new Map<string, string>();
const schedulerOwnedClearTimers = new Map<string, ReturnType<typeof setTimeout>>();
const runAttentionBaselines = new Map<
  string,
  { sessionId: string; hadSessionAttention: boolean }
>();
const clearTimers = new Map<string, ReturnType<typeof setTimeout>>();

/**
 * 事件丢失的自愈**不用定时器**。历史上试过三种「猜 run 还在不在飞行」的判据,
 * 每一种都被证明会误判,不要再往回走:
 *
 *   1. 事件先后顺序(建标记时武装、新 turn 起时撤销):agent 在自己 turn 内调
 *      `schedule_silence_current_run` 时,标记建立时该 turn 已经 running,此后再没
 *      有信号能撤销;反过来只在新 turn 起时撤销,消费方随后卸载就永远没有兜底。
 *   2. renderer 的 running 快照:`makerChatStore` 的折算**刻意**把 `remote_agent`、
 *      `local_bash`、未知 task_type 排除在 `WAKE_AGENT_TASK_TYPES` 之外,device-link
 *      远程会话整体豁免 —— run 仍在飞行而快照为 false 是设计内行为。
 *   3. 固定时长上限:runner 的 `BG_TASK_IDLE_FALLBACK_MS` 是**事件静默**超时,每个
 *      事件都会重新武装,不是最大 run 时长。持续产出事件的后台任务可以合法飞行
 *      任意长,任何固定窗口都必然误清。
 *
 * 现在改为向权威来源对账:scheduler 落库的 run 状态(见
 * `reconcileRunMarkers`)。不猜,只问。
 */

export function rememberScheduleRunSessionAttentionBaseline(
  runId: string,
  sessionId: string,
  hadSessionAttention: boolean,
): void {
  if (!runId || !sessionId) return;
  runAttentionBaselines.set(runId, { sessionId, hadSessionAttention });
}

export function getScheduleRunSessionAttentionBaseline(
  runId: string,
): { sessionId: string; hadSessionAttention: boolean } | undefined {
  return runAttentionBaselines.get(runId);
}

export function markNextSessionDoneSilenced(
  runId: string,
  sessionId: string,
  hadSessionAttention = false,
): void {
  if (!runId || !sessionId) return;
  const previousRunId = silencedSessionRunIds.get(sessionId);
  if (previousRunId) {
    silencedRunSessionIds.delete(previousRunId);
    silencedRunHadAttention.delete(previousRunId);
    // 被顶替的 run 不会再有人调 clearSilencedRun(它已不在 silencedRunSessionIds
    // 里,scheduleClearSilencedRun 会直接 return),baseline 必须在这里一起清,
    // 否则 runAttentionBaselines 会随 session 复用无界增长。
    runAttentionBaselines.delete(previousRunId);
  }
  clearPendingTimer(previousRunId);
  clearPendingTimer(runId);
  silencedRunSessionIds.set(runId, sessionId);
  silencedSessionRunIds.set(sessionId, runId);
  silencedRunHadAttention.set(runId, hadSessionAttention);
}

/** 纯查询:同一个 run 内每次 done 转换都要得到 true(见文件头注释)。 */
export function isSessionDoneSilenced(sessionId: string): boolean {
  return silencedSessionRunIds.has(sessionId);
}

export function markNextSessionTerminalNotificationOwnedByScheduler(
  runId: string,
  sessionId: string,
): void {
  if (!runId || !sessionId) return;
  const previousRunId = schedulerOwnedSessionRunIds.get(sessionId);
  if (previousRunId) schedulerOwnedRunSessionIds.delete(previousRunId);
  clearSchedulerOwnedTimer(previousRunId);
  clearSchedulerOwnedTimer(runId);
  schedulerOwnedRunSessionIds.set(runId, sessionId);
  schedulerOwnedSessionRunIds.set(sessionId, runId);
}

/** 与 `isSessionDoneSilenced` 同款语义:纯查询,run 内多次 done 都命中。 */
export function isSessionTerminalNotificationOwnedByScheduler(
  sessionId: string,
): boolean {
  return schedulerOwnedSessionRunIds.has(sessionId);
}

/** 对账用的 run 存活态:只关心「还在飞行」与「不再飞行」。 */
export type RunLivenessStatus = 'running' | 'terminal';

/**
 * 标记从「run 已终态」到真正删除之间的退场窗口。
 *
 * 这段延迟是留给 renderer 的 done transition 的:scheduler 的终态事件可能早于 React
 * 处理该 session 的 running→done,立刻删标记会让那次 transition 看不到标记、于是发出
 * 不该发的(或重复的)通知。事件路径与对账路径都必须走这段 linger —— 对账遇到的恰恰是
 * 「终态事件丢了、从未排过 linger」的标记,直接清就会踩到同一个坑。
 *
 * 于是全模块只有一个统一语义:**linger 定时器存在 = run 已终态、标记进入退场倒计时**,
 * 不论这个判定来自事件还是来自对账。`clearCompleted*ForNewActivity` 正是拿它当终态判据。
 */
export const MARKER_TERMINAL_LINGER_MS = 2000;

/** 是否还有任何标记等待对账。消费方据此决定要不要继续重试拉取快照。 */
export function hasAnyRunMarker(): boolean {
  return silencedRunSessionIds.size > 0 || schedulerOwnedRunSessionIds.size > 0;
}

export interface ReconcileRunMarkersResult {
  /**
   * 本轮出现了「DB 说还在跑、引擎的 in-flight 快照里却没有」的持标记 run,说明这两份读
   * 拿到的不是同一时刻的状态。
   *
   * 它们由同一次 IPC 取回,但中间隔着 DB 查询的 `await`:run 恰好在那个窗口内结束时,
   * SQLite 返回的行还是 `running`,而 controller 已被注销 —— 于是本轮只能保守保持标记
   * (它也可能真的还在跑,无法区分)。问题在于:**如果该 run 的终态事件正是丢掉的那个,
   * 就再没有任何信号来清这个标记**,自愈保证被打破。
   *
   * 所以消费方拿到 true 时必须安排一次快速重新对账 —— 下一轮 DB 已落到终态,不一致自然
   * 消解。这是 review 指出的竞态的收口方式(race-safe 快照需要在 main 侧忙等重采样,
   * 代价更大;这里用一次重查换同样的正确性)。
   */
  needsRecheck: boolean;
}

/**
 * 用 scheduler 落库的**权威** run 状态对账标记 —— 事件丢失(广播断链、事件早于消费方
 * 挂载等)的唯一自愈路径。不猜时间、也不看 renderer 的 running 快照,那几种判据都会
 * 误判,见上方「事件丢失的自愈不用定时器」注释。
 *
 * **两份数据缺一不可**,且**引擎的 in-flight 快照优先级更高**:
 *   - `inflightRunIds` 有 → 保持。仍在飞行,飞多久都不清。「行不在库里」并不等于
 *     「跑完了」——agent 在任务 run 内调 `schedule_delete` 删自己的 schedule 时,引擎用
 *     `exemptRunId` 豁免 caller run 不 abort,它的行随 schedule 级联删除后仍继续跑到底。
 *     引擎内存态是这件事唯一的权威来源。
 *   - `dbRunStatus` 是 `terminal` → 排 linger 退场。它的 completed / failed 事件没送到。
 *   - 两份都没有 → 同样排 linger 退场。该 run 已经不存在了:删除 schedule 会级联删掉
 *     它的 `schedule_runs` 行,deferred run 也会被显式删除,这两种情况永远等不到一个终态
 *     状态。这里不可能是「标记建好但 run 还没落库」的极早期 —— 引擎先 `updateRun` 写
 *     sessionId、再 emit `session-bound` / `silenced`,而权威快照包含所有 running run,
 *     所以标记存在就意味着该 run 当时已进入快照范围。异步拉取的过期结果由调用方的
 *     seq 守卫挡掉,不会走到这里。
 *
 * **空的 dbRunStatus 不是异常,一样要对账**:权威查询在库里没有匹配行时合法返回空数组
 * (删掉了最后一个 schedule、或唯一的 run 被 defer 后删除),而查询失败是 reject、走调用方
 * 的 catch 与重试,根本不会以空映射的形式到这里。
 *
 * 清除统一走 `MARKER_TERMINAL_LINGER_MS` 的 linger,不立即删 —— 对账面对的正是「终态
 * 事件丢了、从未排过 linger」的标记,而 DB 可能已报终态、React 却还没处理该 session 的
 * running→done。已排 linger 的标记跳过,避免重置它的倒计时。
 *
 * 返回 `needsRecheck`:见 `ReconcileRunMarkersResult`。
 */
export function reconcileRunMarkers(
  dbRunStatus: ReadonlyMap<string, RunLivenessStatus>,
  inflightRunIds: ReadonlySet<string>,
): ReconcileRunMarkersResult {
  let needsRecheck = false;
  const resolve = (runId: string): 'running' | 'terminal' | 'inconsistent' => {
    if (inflightRunIds.has(runId)) return 'running';
    // DB 说还在跑、引擎却说没在跑 —— 两份读之间那个 await 窗口里 run 刚好结束了。
    if (dbRunStatus.get(runId) === 'running') return 'inconsistent';
    return 'terminal';
  };
  for (const runId of [...silencedRunSessionIds.keys()]) {
    if (clearTimers.has(runId)) continue;
    const state = resolve(runId);
    if (state === 'inconsistent') needsRecheck = true;
    if (state !== 'terminal') continue;
    scheduleClearSilencedRun(runId, MARKER_TERMINAL_LINGER_MS);
  }
  for (const runId of [...schedulerOwnedRunSessionIds.keys()]) {
    if (schedulerOwnedClearTimers.has(runId)) continue;
    const state = resolve(runId);
    if (state === 'inconsistent') needsRecheck = true;
    if (state !== 'terminal') continue;
    scheduleClearSchedulerOwnedRun(runId, MARKER_TERMINAL_LINGER_MS);
  }
  return { needsRecheck };
}

/** 与 IPC 快照里的 `inflightPolicies` 同形,避免本 store 去依赖 maker-scheduler。 */
export interface InflightRunPolicySnapshot {
  runId: string;
  sessionId?: string;
  silenced: boolean;
}

/**
 * 用引擎的 in-flight 策略快照重建从未建成(或已被误清)的标记。
 *
 * hook 晚挂、事件早于订阅时,reconcile 只能清已有标记、不能凭空恢复。本函数补那条腿:
 *   - 已绑定 session 的 in-flight run 一律重建 schedulerOwned;
 *   - `silenced` 才重建静默;非静默则丢掉该 run 上过期的 silenced(可能错过了 notified);
 *   - in-flight 要取消误排的 linger(只清 timer,不删标记)—— `markNext*` 会顺带清 timer。
 */
export function restoreInflightRunMarkers(
  policies: ReadonlyArray<InflightRunPolicySnapshot>,
  hadAttention: (sessionId: string) => boolean,
): void {
  for (const policy of policies) {
    if (!policy.runId || !policy.sessionId) continue;
    markNextSessionTerminalNotificationOwnedByScheduler(policy.runId, policy.sessionId);
    if (policy.silenced) {
      markNextSessionDoneSilenced(policy.runId, policy.sessionId, hadAttention(policy.sessionId));
    } else if (silencedRunSessionIds.has(policy.runId)) {
      clearSilencedRun(policy.runId);
    }
  }
}

export interface RecentlyReadSilentRunSnapshot {
  runId: string;
  sessionId?: string;
  status: string;
  readAt?: number;
}

/**
 * 刚静默成功落库的 run(`success` + `readAt`)若还在 linger 窗口内,补回标记并排 linger。
 * 已有 timer 不重置。启发式:用户在 2s 内点已读也可能被当成静默,可接受。
 */
export function restoreRecentlyReadSilentMarkers(
  runs: ReadonlyArray<RecentlyReadSilentRunSnapshot>,
  now: number,
  hadAttention: (sessionId: string) => boolean,
  inflightRunIds: ReadonlySet<string> = new Set(),
): void {
  for (const run of runs) {
    if (inflightRunIds.has(run.runId)) continue;
    if (run.status !== 'success' || !run.sessionId || run.readAt == null) continue;
    if (now - run.readAt >= MARKER_TERMINAL_LINGER_MS) continue;
    if (!silencedRunSessionIds.has(run.runId)) {
      markNextSessionDoneSilenced(run.runId, run.sessionId, hadAttention(run.sessionId));
    }
    if (!schedulerOwnedRunSessionIds.has(run.runId)) {
      markNextSessionTerminalNotificationOwnedByScheduler(run.runId, run.sessionId);
    }
    scheduleClearSilencedRun(run.runId, MARKER_TERMINAL_LINGER_MS);
    scheduleClearSchedulerOwnedRun(run.runId, MARKER_TERMINAL_LINGER_MS);
  }
}

export function scheduleClearSchedulerOwnedRun(runId: string, delayMs: number): void {
  if (!schedulerOwnedRunSessionIds.has(runId)) return;
  if (schedulerOwnedClearTimers.has(runId)) return;
  const timer = setTimeout(() => {
    schedulerOwnedClearTimers.delete(runId);
    clearSchedulerOwnedRun(runId);
  }, delayMs);
  schedulerOwnedClearTimers.set(runId, timer);
}

export function clearSchedulerOwnedRun(runId: string): string | undefined {
  clearSchedulerOwnedTimer(runId);
  const sessionId = schedulerOwnedRunSessionIds.get(runId);
  if (!sessionId) return undefined;
  schedulerOwnedRunSessionIds.delete(runId);
  if (schedulerOwnedSessionRunIds.get(sessionId) === runId) {
    schedulerOwnedSessionRunIds.delete(sessionId);
  }
  return sessionId;
}

/**
 * run 已终态(completed/failed 排了 linger)后该 session 又起新 turn:那是用户手动
 * 对话或下一个 run,立刻交回普通通知路径。run 还在跑时不清 —— 判据是
 * `schedulerOwnedClearTimers` 有没有 linger 定时器,而不是任何时间或 running 推断。
 */
export function clearCompletedSchedulerOwnedRunForNewActivity(sessionId: string): void {
  const runId = schedulerOwnedSessionRunIds.get(sessionId);
  if (!runId || !schedulerOwnedClearTimers.has(runId)) return;
  clearSchedulerOwnedRun(runId);
}

export function scheduleClearSilencedRun(runId: string, delayMs: number): void {
  if (!silencedRunSessionIds.has(runId)) return;
  if (clearTimers.has(runId)) return;
  const timer = setTimeout(() => {
    clearTimers.delete(runId);
    clearSilencedRun(runId);
  }, delayMs);
  clearTimers.set(runId, timer);
}

/** 与 `clearCompletedSchedulerOwnedRunForNewActivity` 对称。 */
export function clearCompletedSilencedRunForNewActivity(sessionId: string): void {
  const runId = silencedSessionRunIds.get(sessionId);
  if (!runId || !clearTimers.has(runId)) return;
  clearSilencedRun(runId);
}

export function clearSilencedRun(runId: string): string | undefined {
  clearPendingTimer(runId);
  const sessionId = silencedRunSessionIds.get(runId);
  if (!sessionId) {
    runAttentionBaselines.delete(runId);
    return undefined;
  }
  silencedRunSessionIds.delete(runId);
  silencedRunHadAttention.delete(runId);
  runAttentionBaselines.delete(runId);
  if (silencedSessionRunIds.get(sessionId) === runId) {
    silencedSessionRunIds.delete(sessionId);
  }
  return sessionId;
}

export function getSilencedRunSessionId(runId: string): string | undefined {
  return silencedRunSessionIds.get(runId);
}

export function getSilencedRunSessionIdForAttentionFallback(runId: string): string | undefined {
  if (silencedRunHadAttention.get(runId) !== false) return undefined;
  return silencedRunSessionIds.get(runId);
}

export function resetSilencedSessionDoneStoreForTests(): void {
  for (const timer of clearTimers.values()) clearTimeout(timer);
  clearTimers.clear();
  silencedRunSessionIds.clear();
  silencedSessionRunIds.clear();
  silencedRunHadAttention.clear();
  runAttentionBaselines.clear();
  for (const timer of schedulerOwnedClearTimers.values()) clearTimeout(timer);
  schedulerOwnedClearTimers.clear();
  schedulerOwnedRunSessionIds.clear();
  schedulerOwnedSessionRunIds.clear();
}

function clearPendingTimer(runId: string | undefined): void {
  if (!runId) return;
  const timer = clearTimers.get(runId);
  if (!timer) return;
  clearTimeout(timer);
  clearTimers.delete(runId);
}

function clearSchedulerOwnedTimer(runId: string | undefined): void {
  if (!runId) return;
  const timer = schedulerOwnedClearTimers.get(runId);
  if (!timer) return;
  clearTimeout(timer);
  schedulerOwnedClearTimers.delete(runId);
}