第四章：核心与 Agent 循环

// 来自 packages/core/agent/src/types.ts（概念性）
interface Agent {
  /** 唯一标识 */
  readonly id: SessionId
  /** 消息收件箱 */
  readonly inbox: Inbox
  /** 关联的会话 */
  readonly session: Session
  /** Agent 作用域 */
  readonly ctx: Context
  /** 选项 */
  readonly options: AgentOptions
}

// 来自 packages/core/agent/src/index.ts
interface AgentFactory {
  createAgent(options: CreateAgentOptions): AgentHandle
}

interface AgentHandle {
  // 句柄：取消、状态查询等
  // 可以通过 abort controller 取消
}

interface CreateAgentOptions {
  /** 活的 agent/session 身份 */
  readonly sessionId: SessionId
  /** 会话创建元数据 */
  readonly meta?: {
    readonly cwd?: string
    readonly parentSession?: SessionId
    readonly isSeeded?: boolean
    readonly origin?: 'subagent'
    readonly delegationDepth?: number
    readonly agentPreset?: string
  }
  /** fork 继承的前缀长度 */
  readonly inheritedEventCount?: SessionLogOffset
  /** 初始 replay/fork 历史 */
  readonly seed?: readonly SessionEvent[]
}

// 来自 packages/core/agent-loop/src/agent.ts
class ReactLoopAgent implements Agent {
  readonly inbox: Inbox
  private phase: Phase
  readonly scope: Scope
  readonly ctx: Context
  private readonly dispatch: AgentEventDispatch

  constructor(
    private loopCtx: Context,
    public readonly id: SessionId,
    public readonly options: AgentOptions,
    public readonly session: Session,
  ) {
    this.dispatch = agentEvents(loopCtx, this)
    this.inbox = new Inbox(session, {
      inserted: (message) => { this.dispatch.emit('agent/inbox/inserted', { message }) },
      discarded: (message) => { this.dispatch.emit('agent/inbox/discarded', { message }) },
      claimed: (message, turn) => { this.dispatch.emit('agent/inbox/claimed', { message, turn }) },
    })
  }
}

type Phase =
  | { kind: 'idle'; lastTurn: number }
  | { kind: 'maintenance'; abort: AbortController; lastTurn: number; wakeRequested: boolean }
  | { kind: 'running'; abort: AbortController; turn: number; step: number; wakeRequested: boolean }

turn/start
  claim next-step input plus one queued message
  assemble prompt sections + tool schemas
  -> agent/pre-step                   reject | enter(messages, startsRequestSeries?)
     reject, or a first enter rewritten empty -> close the turn with no step
     step/start
     append entered messages as user/message
     derive model history from the log
     agent/request -> llm/stream -> assistant/chunk* -> assistant/message
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
     tools owe another request, or next-step input arrived -> claim -> next step
  -> agent/turn-stopping
turn/end

// 概念性例子
ctx.on('agent/pre-step', (decision, next) => {
  // 1. 可以重写消息
  decision.messages = decision.messages.filter(m => !m.suppressed)
  
  // 2. 可以添加上下文
  decision.messages.push({
    role: 'system',
    content: getCurrentContext()
  })
  
  // 3. 可以设置 startsRequestSeries
  if (isNewSeries) {
    decision.startsRequestSeries = true
  }
  
  // 4. 必须调用 next()
  return next(decision)
})

type AgentCancelCause =
  | { kind: 'user' }          // 用户取消
  | { kind: 'turn-end' }      // Turn 正常结束
  | { kind: 'error' }         // 错误导致取消
  | { kind: 'dispose' }       // Fiber 卸载

// 概念性描述
type RequestErrorAction =
  | { kind: 'retry' }     // 重试请求
  | { kind: 'abort' }     // 中止 turn
  | { kind: 'continue' }  // 跳过，继续下一个 step

// 来自 packages/core/scope
interface Scope {
  // 带范围的注册
}

// 创建带范围的上下文
const agentCtx = ctx.extend({ agent: myAgent })

// 在 Agent 作用域内注册
agentCtx.on('agent/step', (step) => {
  // 这个监听器只在这个 Agent 的上下文中生效
})

interface Agent {
  /** Agent 作用域的上下文 */
  readonly ctx: Context
}

declare module '@deepseek-ai/cordis' {
  interface Context {
    agents: AgentRegistry
    agent?: Agent  // 当前上下文关联的 Agent
  }
}

// 来自 packages/core/agent-loop/src/index.ts
class FactoryOwnership {
  private accepting = true
  private readonly teardown = new AbortController()
  private readonly inactive = Promise.withResolvers<void>()
  
  constructor(private readonly loop: AgentLoop) {}
  
  signal(): void {
    // 通知所有 Agent 关闭
  }
}

interface PromptAssembly {
  // 系统提示段落
  sections: PromptSection[]
  // 工具 schema
  toolSchemas: ToolSchema[]
  // 完整的渲染结果
  // renderPrompt(assembly) → 完整消息列表
}

// 概念性描述
function deriveMessages(log: SessionEventLog): Message[] {
  // 从日志中提取：
  // 1. user/message 事件 → UserMessage
  // 2. assistant/message 事件 → AssistantMessage
  // 3. tool/result 事件 → ToolResultMessage
  // 按 seq 排序，保持时序
}

// 概念性描述
agent.inject({
  type: 'context',
  content: '用户刚才提到了关于部署的问题'
})