脊柱：从 kick 出发

97export class ReactLoopAgent implements Agent {
98  readonly inbox: ReactLoopInbox
99  private phase: Phase
112  private requestSurfaceGeneration: number
117  private readonly systemPrompt: SystemPromptProjection   // 0.1.5 新增system prompt 投影器
119  private readonly frozenMessages = new WeakSet<Message>()
121  constructor(
122    private loopCtx: Context,
123    public readonly id: SessionId,
124    public readonly options: AgentOptions,
125    public readonly session: Session,
126  ) {
127    this.requestSurfaceGeneration = session.surface.contentGeneration0.1.6：contentGeneration
128    this.dispatch = agentEvents(loopCtx, this)
129    this.scope = createScope(loopCtx, this)
130    this.ctx = this.scope.ctx   // 0.1.5：不再 extend({ agent: this })
131    this.inbox = new ReactLoopInbox(this.ctx.sessionProjections, session, this.dispatch)
133    const lastTurn = this.loopCtx.sessionProjections.stateOf(session, 'turnBoundary')?.lastTurn ?? 0
134    this.phase = { kind: 'idle', lastTurn }
135    this.runtimeContext = new RuntimeContextProjection(this.ctx, session)
136    this.systemPrompt = new SystemPromptProjection(session)
137  }

41type Phase =
42  | { kind: 'idle'; lastTurn: number }
43  | {
44    kind: 'maintenance'
45    abort: AbortController
46    lastTurn: number
47    wakeRequested: boolean
48  }
49  | { kind: 'running'; abort: AbortController; turn: number; step: number; wakeRequested: boolean }
139  get status(): AgentStatus {
140    return this.phase.kind === 'idle' || this.phase.kind === 'maintenance' ? 'idle' : 'running'
141  }
144  private setPhase(next: Phase): void {
145    const previousStatus = this.status
146    this.phase = next
147    const status = this.status
148    if (status !== previousStatus) {
149      this.dispatch.emit('agent/status', { status })
150    }
151  }

251  private async kick(): Promise<void> {
252    try {
253      while (await this.turn()) {}
254    } catch (_error) {
255      // Reported failures and cancellation are contained at the driver boundary.
256    } finally {
258      if (this.phase.kind === 'running') {
259        const { turn, wakeRequested } = this.phase
260        this.setPhase({ kind: 'idle', lastTurn: turn })
261        if (wakeRequested && this.inbox.hasPending) this.wakeDriver()
262      }
263    }
264  }

295  private async turn(): Promise<boolean> {
296    if (this.phase.kind !== 'running') {
297      this.throwError(new Error(`agent "${this.id}": turn without driver reservation`))
298    }
299    const phase = this.phase
300    const { signal } = phase.abort
301    signal.throwIfAborted()
302    const turn = phase.turn + 1
303    try {
304      this.session.append('turn/start', { turn })
305    } catch (error: unknown) {
306      this.throwError(error)
307    }
308    phase.turn = turn
309    let turnEnds: TurnEndReason | null = null
310    let target: InboxTarget = 'next-turn'
311    try {
312      while (true) {
313        signal.throwIfAborted()
314        const step = phase.step + 1
315        const decision = await this.preStep(target, { turn, step })
316        if (decision.kind === 'reject') {
317          turnEnds = { kind: 'blocked' }
318          return false
319        }
320        if (turnEnds && decision.messages.length === 0) break0.1.5：终局已定且无新输入 → 收
323        if (phase.step === 0 && decision.messages.length === 0) {
324          turnEnds = { kind: 'completed' }
325          return false
326        }
327        signal.throwIfAborted()
328        this.session.append('step/start', { turn, step })
329        phase.step = step
330        try {
333          const stepEnd = await this.step(decision)
336          if (turnEnds === null || turnEnds.kind !== 'max-tokens') turnEnds = stepEnd
337        } finally {
338          this.session.append('step/end', { turn, step })
339        }
340        signal.throwIfAborted()
341        if (turnEnds && this.inbox.nextStep.length === 0) {
342          await this.dispatch.serial('agent/turn-stopping', { turn, signal })
343          signal.throwIfAborted()
344        }
345        if (turnEnds && this.inbox.nextStep.length === 0) break
346        target = 'next-step'
347      }
348    } catch (error: unknown) {
350      const cause = abortedCancelCause(signal)   // 0.1.7 新增：归一化取消原因见下方
351      if (cause !== undefined) {
352        turnEnds = { kind: 'aborted', reason: cause }
353        throw error
354      }
357      turnEnds = {
358        kind: 'error',
359        error: error instanceof LlmError
360          ? error.failure
361          : { message: errorChain(error), code: 'UNKNOWN' },
362      }
363      this.throwError(error)
364    } finally {
365      try {
367        this.session.append('turn/end', { turn, reason: turnEnds! })
368      } catch (error: unknown) {
369        this.throwError(error)
370      }
371    }
372    if (!this.inbox.hasPending) return false
373    phase.abort = new AbortController()
375    phase.wakeRequested = false
376    phase.step = 0
377    return true
378  }

213  private wakeDriver(wakeAfterAbort = false): void {
214    if (this.phase.kind !== 'idle') {
218      const reason = abortedCancelCause(this.phase.abort.signal)   // 0.1.7 改以前是 as AgentCancelCause 断言
219      if (reason?.kind !== 'disposed' && (this.phase.kind === 'maintenance' || wakeAfterAbort)) {
220        this.phase.wakeRequested = true
221      }
222      return
223    }
224    const driver = Promise.withResolvers<void>()
225    this.activityDone = driver.promise
226    this.setPhase({
227      kind: 'running',
228      abort: new AbortController(),
229      turn: this.phase.lastTurn,
230      step: 0,
231      wakeRequested: false,
232    })
233    this.loopCtx.agents.withInitiator(this, () => this.kick())
234      .then(driver.resolve, driver.reject)

79function abortedCancelCause(signal: AbortSignal): AgentCancelCause | undefined {
80  if (!signal.aborted) return undefined   // 返回值即「是否已取消」一条语句同时表达两件事
81  // `cancel()` is the only aborter of the signals this loop owns.
82  const cause = signal.reason as AgentCancelCause
83  switch (cause.kind) {
84    case 'user':
85    case 'parent':
86    case 'disposed':
87      return { kind: cause.kind }   // 重建干净对象，丢掉附加的 stack关键
88    case 'hook':
89      return { kind: 'hook', reason: cause.reason }
90    /* v8 ignore next -- cancel accepts the closed AgentCancelCause union */
91    default:
92      return assertNever(cause)
93  }
94}