@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,28 @@
+/**
+ * @qjp88995/agent-runtime：agent 运行时。
+ *
+ * 不依赖 Redis、数据库或任何框架：外部件一律经端口（`ports/`），每个端口都有进程内实现
+ * （`in-process/`），零配置单进程能跑；多实例换适配包。宿主的 agent 字段经
+ * `AgentExtensions`（module augmentation）带进工具与钩子。
+ */
+export {
+  type AgentExtensions,
+  type Initiator,
+  NO_INITIATOR,
+} from './agent-extensions.js';
+export * from './builtins/index.js';
+export * from './context/index.js';
+export {
+  registerRepeatCallHook,
+  REPEAT_CALL_HOOK_META,
+  RepeatCallHook,
+} from './extensions/repeat-call.hook.js';
+export * from './hooks/index.js';
+export * from './images/index.js';
+export * from './in-process/index.js';
+export * from './loop/index.js';
+export * from './ports/index.js';
+export * from './schema/index.js';
+export * from './subagent/index.js';
+export * from './tools/index.js';
+export * from './turn/index.js';

package/src/loop/active-tick.registry.ts

@@ -0,0 +1,49 @@
+import type { StreamBus } from '../ports/stream-bus.js';
+
+/**
+ * 「本进程此刻有哪些 tick 在跑」的登记簿：sessionId → 该 tick 的 streamId。
+ *
+ * **进程内的**（跟 stream 本身一样）——写方是 `LoopDriver` 的 tick，读方是
+ * `LoopDriver.stopSession`（会话级中断要解析出目标 stream）与停机收尾。跨实例
+ * 仍是 best-effort：tick 可能跑在任何实例上，这里查不到不代表没在跑
+ * （`OrphanRunSweeper` 兜的正是这一类）。
+ */
+export class ActiveTickRegistry {
+  private readonly bySession = new Map<string, string>();
+
+  constructor(private readonly bus: StreamBus) {}
+
+  /** tick 开跑：登记它的 stream。 */
+  open(sessionId: string, streamId: string): void {
+    this.bySession.set(sessionId, streamId);
+  }
+
+  /**
+   * tick 收尾：**只在登记的仍是自己那条 stream 时**才摘（同一会话的下一个 tick
+   * 可能已经登记进来，摘掉别人的会让「停止」按钮对着空气按）。
+   */
+  close(sessionId: string, streamId: string): void {
+    if (this.bySession.get(sessionId) === streamId) {
+      this.bySession.delete(sessionId);
+    }
+  }
+
+  /**
+   * 该会话此刻的活跃 stream，没有则 null。**登记在册还不够**——总线上那条流
+   * 可能已经关了（tick 正走 finally），故再问一次 `isActive`。
+   */
+  streamOf(sessionId: string): string | null {
+    const id = this.bySession.get(sessionId);
+    return id && this.bus.isActive(id) ? id : null;
+  }
+
+  /** 停机收尾用：本进程登记在册的全部 stream（不过滤，见 `streamOf`）。 */
+  streamIds(): string[] {
+    return [...this.bySession.values()];
+  }
+
+  /** 停机收尾的等待判据：还有几个 tick 没摘牌。 */
+  get size(): number {
+    return this.bySession.size;
+  }
+}

package/src/loop/index.ts

@@ -0,0 +1,25 @@
+export { ActiveTickRegistry } from './active-tick.registry.js';
+export {
+  LOCK_RENEW_INTERVAL_MS,
+  LoopDriver,
+  type LoopDriverDeps,
+  type LoopHost,
+  SHUTDOWN_DRAIN_MS,
+  type TickRunArgs,
+  type TickTurn,
+} from './loop-driver.js';
+export {
+  INTERRUPTED_PLACEHOLDER,
+  MessageHub,
+  type PostInput,
+  TurnRecorder,
+  type TurnTerminal,
+} from './message-hub.js';
+export {
+  INTERRUPTED_ERROR,
+  ORPHAN_MIN_AGE_MS,
+  OrphanRunSweeper,
+  type OrphanRunSweeperDeps,
+  SWEEP_INTERVAL_MS,
+} from './orphan-run.sweeper.js';
+export { createRootTurnHost, type RootTurnHostOptions } from './root-host.js';

package/src/loop/loop-driver.ts

@@ -0,0 +1,275 @@
+import type { SessionLock, WakeChannel } from '../ports/coordination.js';
+import { type Logger, silentLogger } from '../ports/logger.js';
+import type { StreamBus } from '../ports/stream-bus.js';
+import type { AgentRuntime } from '../turn/agent-runtime.js';
+import type { RunTurnArgs } from '../turn/turn-run.js';
+import { ActiveTickRegistry } from './active-tick.registry.js';
+import type { MessageHub, PostInput, TurnRecorder } from './message-hub.js';
+
+/** 锁 TTL 60s（`LOCK_TTL_MS`），20s 续租留足冗余。 */
+export const LOCK_RENEW_INTERVAL_MS = 20_000;
+
+/**
+ * 停机时留给在跑的 tick 自行收尾的预算。`docker stop` 默认 SIGTERM 之后 10s
+ * 才 SIGKILL，取 7s 留出余量给宿主其余的关闭钩子。
+ *
+ * 超时**不是**故障：`OrphanRunSweeper` 仍然兜底，只是用户要多等一会儿。故这里
+ * 宁可早点放手，也不能赌满 10s——被 SIGKILL 打断的话，连锁的主动释放都没做成。
+ */
+export const SHUTDOWN_DRAIN_MS = 7_000;
+const SHUTDOWN_POLL_MS = 50;
+
+/** 一轮开张时 driver 交给宿主的东西。 */
+export interface TickTurn {
+  sessionId: string;
+  /** = streamId = 本轮 assistant 行主键（`MessageHub.openTurn` 铸的）。 */
+  runId: string;
+  streamId: string;
+  /** 本轮的落库口，交给 `createRootTurnHost`（或宿主自己的 `TurnHost`）。 */
+  recorder: TurnRecorder;
+}
+
+/** 宿主为一轮要组装的 `runTurn` 入参——除了 driver 自己递的那三样。 */
+export type TickRunArgs = Omit<RunTurnArgs, 'nextSeq' | 'sink' | 'abortSignal'>;
+
+/**
+ * loop 向宿主要的东西：一轮跑什么。会话 / agent / 模型怎么解析、system prompt 拼
+ * 什么、工具摘哪些——全是宿主的事（agent-base 里是形式层 + `prepareTurn`）。
+ *
+ * 拆成两段是因为**两段失败的处置不同**：
+ * - `setupTick` 在流打开之前（取会话行、解析 agent 与模型）。抛错 = 这一轮压根
+ *   跑不起来，driver 落一条可见的 setup-error 占位（不补的话消息已进 inbox、界面
+ *   上却什么都不会发生），再把错误抛给 `onWake` 的调用方。
+ * - `buildTurn` 在流打开之后、拿着本轮的 recorder 组装 `runTurn` 的入参（宿主
+ *   通常在这里 `createRootTurnHost`）。抛错 = 这一 tick 崩了，流照常关闭。
+ */
+export interface LoopHost<TSetup> {
+  setupTick(sessionId: string): Promise<TSetup>;
+  buildTurn(setup: TSetup, turn: TickTurn): Promise<TickRunArgs>;
+  /**
+   * setup 失败时那条占位的正文。缺省 `本轮无法启动：<message>`。宿主可在这里
+   * 净化报错（如去掉第三方服务名）、补一句排查提示。
+   */
+  describeSetupError?(error: unknown): string;
+  /**
+   * tick 收尾（锁已释放）之后、re-wake 之前调，对每个会话无条件调。子 Agent 的
+   * 里程碑回投（`finalizeIfIdle`）挂在这里。
+   *
+   * **必须排在 re-wake 之前**：finalizer 判「子空闲了没」的唯一依据就是 inbox
+   * 空不空，而 re-wake 广播出去之后，某个实例随时会抢到刚释放的锁、起一个新 tick
+   * 把消息 drain 走——那时 finalizer 会把一个正在跑的子判成空闲。放在前面则不存在
+   * 这个窗口：此刻锁虽已释放，但还没有任何人被叫醒。
+   */
+  afterTick?(sessionId: string): Promise<void>;
+}
+
+export interface LoopDriverDeps<TSetup> {
+  lock: SessionLock;
+  wake: WakeChannel;
+  bus: StreamBus;
+  hub: MessageHub;
+  runtime: AgentRuntime;
+  host: LoopHost<TSetup>;
+  logger?: Logger;
+  /** 缺省 `LOCK_RENEW_INTERVAL_MS`；单测可调小。 */
+  renewIntervalMs?: number;
+}
+
+/**
+ * inbox 驱动的 agent loop 调度器。`wake` 经 `WakeChannel` 广播（多实例时跨实例）；
+ * 每个实例的订阅者收到即 `onWake` —— 试抢会话锁，只有抢到的那个实例跑一个 tick
+ * （一次 `runTurn` 自驱 loop，drain-first）。tick 收尾释放锁后再查一次 inbox：
+ * 若期间又有新消息进来（插话 / 子 Agent 回投），重新 wake，闭合「刚 drain 完又来
+ * 一条、锁还没放」的丢唤醒窗口。
+ *
+ * 流的生命周期（open / close）完全落在 tick 内，与任何 HTTP 连接解耦。
+ */
+export class LoopDriver<TSetup = unknown> {
+  readonly active: ActiveTickRegistry;
+  private readonly logger: Logger;
+  private unsubscribe?: () => void;
+
+  constructor(private readonly deps: LoopDriverDeps<TSetup>) {
+    this.active = new ActiveTickRegistry(deps.bus);
+    this.logger = deps.logger ?? silentLogger('');
+  }
+
+  /** 订阅唤醒。返回退订函数（`shutdown` 也会退订）。 */
+  start(): () => void {
+    this.unsubscribe ??= this.deps.wake.onWake(sessionId => {
+      void this.onWake(sessionId).catch(err =>
+        this.logger.error(`onWake(${sessionId}) failed: ${String(err)}`)
+      );
+    });
+    return () => this.stopListening();
+  }
+
+  private stopListening(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+  }
+
+  /**
+   * 投递一条消息并唤醒（**post-first**：先写 inbox 再 wake）。宿主的准入检查
+   * （会话能不能发言等）在调它之前自己做。
+   */
+  async post(input: PostInput): Promise<{ messageId: string }> {
+    const out = await this.deps.hub.post(input);
+    await this.deps.wake.wake(input.sessionId);
+    return out;
+  }
+
+  /** 该会话此刻在本进程跑着的流，没有则 null。 */
+  activeStreamOf(sessionId: string): string | null {
+    return this.active.streamOf(sessionId);
+  }
+
+  /**
+   * 会话级中断：解析该会话当前活跃 tick 的流 → abort。跨实例 best-effort（tick 跑在
+   * 别的实例上时这里查不到）。返回是否真的中断了一条流。宿主挂着的同步等待（提问
+   * 面板等）自己作废。
+   */
+  stopSession(sessionId: string): boolean {
+    const streamId = this.active.streamOf(sessionId);
+    if (!streamId) return false;
+    this.deps.bus.abort(streamId);
+    return true;
+  }
+
+  /**
+   * 停机前把本进程正在跑的 tick 全部 abort 掉，并**等它们收完尾**。
+   *
+   * 不做的话，那些轮次的终态就随进程一起没了：跑次停在 running、消息没盖终态。
+   * sweeper 能修，但代价是至少一个锁 TTL（进程被杀时锁不会主动释放）。主动重启
+   * 占了重启的绝大多数，这条路让它们几乎瞬时收尾，sweeper 退回去只兜底真正的崩溃。
+   *
+   * **走的是内核既有的 abort 路径**：`bus.abort` → `runTurn` 照常以 aborted 收尾 →
+   * `host.persist` 盖终态、发 `run-finish`，等价于用户点了停止。
+   *
+   * **必须等**：abort 只是置了标记，立刻返回就等于没做。等到登记簿清空为准，超时
+   * 则放手交给 sweeper。返回是否在预算内清空。
+   */
+  async shutdown(budgetMs: number = SHUTDOWN_DRAIN_MS): Promise<boolean> {
+    this.stopListening();
+    const streams = this.active.streamIds();
+    if (streams.length === 0) return true;
+    this.logger.warn(
+      `shutdown: aborting ${streams.length} in-flight tick(s) so they land a terminal state`
+    );
+    for (const streamId of streams) this.deps.bus.abort(streamId);
+    const deadline = Date.now() + budgetMs;
+    while (this.active.size > 0) {
+      if (Date.now() >= deadline) {
+        this.logger.warn(
+          `shutdown: ${this.active.size} tick(s) still running after ${budgetMs}ms; OrphanRunSweeper will finish them`
+        );
+        return false;
+      }
+      await new Promise(resolve => setTimeout(resolve, SHUTDOWN_POLL_MS));
+    }
+    return true;
+  }
+
+  async onWake(sessionId: string): Promise<void> {
+    const { lock, hub, wake } = this.deps;
+    const token = await lock.acquire(sessionId);
+    if (!token) return; // 已有 loop 在跑，它会 re-drain
+    const renew = setInterval(
+      () => void lock.renew(sessionId, token).catch(() => undefined),
+      this.deps.renewIntervalMs ?? LOCK_RENEW_INTERVAL_MS
+    );
+    try {
+      // 抢到锁之后再确认一次真有货。每一个投递方都是 post-first，另外两个唤醒源
+      // （下面的 re-wake、启动时的 `wakePendingInboxes`）本就以 `hasPending` 为
+      // 条件——所以「持锁而 inbox 空」只有一个成因：这批货在 wake 与抢锁之间没了
+      // （被上一个 tick 领走或被用户撤回）。空跑一趟会开流、开跑次、发 run-start /
+      // run-finish，前端建一个空气泡再收起来。
+      //
+      // **不能直接 return**：跳过的只是 tick，下面的 release 与重新自查必须照走，
+      // 否则一次 wake 落在「查完到释放锁」之间就丢了。
+      if (await hub.hasPending(sessionId)) {
+        await this.runTick(sessionId);
+      }
+    } finally {
+      clearInterval(renew);
+      await lock.release(sessionId, token);
+    }
+    // 必须排在 re-wake 之前，判据见 `LoopHost.afterTick`。
+    await this.deps.host.afterTick?.(sessionId);
+    // 关丢唤醒：释放后再查一次，非空则重新广播（锁此刻空闲，可被重新抢到）。
+    if (await hub.hasPending(sessionId)) {
+      await wake.wake(sessionId);
+    } else {
+      // idle 广播：tick 跑完且 inbox 已空。尽力而为——发不出去只记日志，消费方
+      // 各自有兜底。
+      await wake
+        .idle(sessionId)
+        .catch(err =>
+          this.logger.warn(`publish idle(${sessionId}) failed: ${String(err)}`)
+        );
+    }
+  }
+
+  private async runTick(sessionId: string): Promise<void> {
+    const { bus, hub, host, runtime } = this.deps;
+    const setup = await this.resolveSetup(sessionId);
+
+    // 三位一体的 id 由消息中心铸，**别在这里各生成各的**。recorder 的生命周期
+    // 正好是这个 tick。
+    const recorder = hub.openTurn(sessionId);
+    const { runId, streamId } = recorder;
+    const { nextSeq } = bus.open(streamId);
+    this.active.open(sessionId, streamId);
+    try {
+      // **不给兜底信号**——`open` 之后 `signalOf` 必然有值，拿不到是接线坏了；拿
+      // 一个永不 abort 的空信号顶上去，会把「停止按钮按了没反应」变成一个不报错的
+      // 静默症状。
+      const abortSignal = bus.signalOf(streamId);
+      if (!abortSignal) {
+        throw new Error(`stream ${streamId} opened without an abort signal`);
+      }
+      const args = await host.buildTurn(setup, {
+        sessionId,
+        runId,
+        streamId,
+        recorder,
+      });
+      await runtime.runTurn({
+        ...args,
+        nextSeq,
+        // 事件的去向：本轮的 recorder（消息中心）。内核只认识一个同步投递口。
+        sink: e => recorder.emit(e),
+        abortSignal,
+      });
+    } catch (err) {
+      this.logger.error(`tick ${streamId} crashed: ${String(err)}`);
+    } finally {
+      bus.close(streamId);
+      this.active.close(sessionId, streamId);
+    }
+  }
+
+  /**
+   * setup 阶段：任一步都可能抛（agent 已停用、模型已删除……）。流此时还没开，唯一
+   * 能让用户看到「发生了什么」的办法是补一条可见占位。落占位失败只记日志（不能
+   * 反过来吞掉 / 替换原始 setup 错误），随后原样重新抛出，交由 `onWake` 的 finally
+   * 照常 release 锁。
+   */
+  private async resolveSetup(sessionId: string): Promise<TSetup> {
+    try {
+      return await this.deps.host.setupTick(sessionId);
+    } catch (err) {
+      const text =
+        this.deps.host.describeSetupError?.(err) ??
+        `本轮无法启动：${err instanceof Error ? err.message : String(err)}`;
+      try {
+        await this.deps.hub.appendSetupError(sessionId, text);
+      } catch (persistErr) {
+        this.logger.error(
+          `appendSetupError(${sessionId}) failed: ${String(persistErr)}`
+        );
+      }
+      throw err;
+    }
+  }
+}