内部模块: Session (会话管理)

// src/session/index.ts
export const Info = z.object({
  id: Identifier.schema("session"),
  projectID: z.string(),
  directory: z.string(),
  parentID: Identifier.schema("session").optional(),  // 子会话支持
  
  // 会话摘要统计
  summary: z.object({
    additions: z.number(),
    deletions: z.number(),
    files: z.number(),
    diffs: Snapshot.FileDiff.array().optional(),
  }).optional(),
  
  // 分享信息
  share: z.object({
    url: z.string(),
  }).optional(),
  
  title: z.string(),
  version: z.string(),
  
  // 时间戳
  time: z.object({
    created: z.number(),
    updated: z.number(),
    compacting: z.number().optional(),
    archived: z.number().optional(),
  }),
  
  // 权限规则集
  permission: PermissionNext.Ruleset.optional(),
  
  // 撤销信息
  revert: z.object({
    messageID: z.string(),
    partID: z.string().optional(),
    snapshot: z.string().optional(),
    diff: z.string().optional(),
  }).optional(),
})

// src/session/message-v2.ts
export type Part = 
  | TextPart          // 文本内容
  | FilePart          // 文件引用
  | ToolPart          // 工具调用
  | ReasoningPart     // 推理过程 (Claude 3.5 Thinking)
  | AgentPart         // Agent 切换
  | SubtaskPart       // 子任务
  | ErrorPart         // 错误信息

// src/session/prompt.ts
export const prompt = fn(PromptInput, async (input) => {
  // 1. 创建或获取 Assistant Message
  const assistantMessage = await iife(async () => {
    if (input.messageID) {
      return MessageV2.get({ id: input.messageID, sessionID: input.sessionID })
    }
    // 创建新的 Assistant Message
    return MessageV2.create({
      sessionID: input.sessionID,
      role: "assistant",
      parts: input.parts,
    })
  })
 
  // 2. 准备工具和上下文
  const tools = await prepareTools(input)
  const messages = await buildContext(input)
  
  // 3. 创建 Processor
  const processor = SessionProcessor.create({
    assistantMessage,
    sessionID: input.sessionID,
    model: selectedModel,
    abort: abortController.signal,
  })
 
  // 4. **开始循环**
  const result = await processor.process({
    messages,
    tools,
    model: selectedModel,
    system: systemPrompt,
    // ...
  })
 
  return assistantMessage
})

// src/session/processor.ts
export function create(input: {
  assistantMessage: MessageV2.Assistant
  sessionID: string
  model: Provider.Model
  abort: AbortSignal
}) {
  return {
    async process(streamInput: LLM.StreamInput) {
      while (true) {  // ← 无限循环！
        try {
          // 1. 调用 LLM 获取流式响应
          const stream = await LLM.stream(streamInput)
          
          for await (const value of stream.fullStream) {
            switch (value.type) {
              case "text-delta":
                // 增量更新文本 Part
                await updateTextPart(value.text)
                break
                
              case "tool-call-delta":
                // 工具调用参数增量更新
                await updateToolPart(value)
                break
                
              case "tool-call":
                // 工具调用完成，执行工具
                const result = await executeTool(value)
                
                // 将工具结果添加到消息历史
                streamInput.messages.push({
                  role: "tool",
                  content: result,
                })
                break
                
              case "finish":
                // LLM 决定停止
                if (value.finishReason === "stop") {
                  return "stop"  // ← 退出循环
                }
                break
            }
          }
          
          // 2. 如果有工具调用，继续下一轮循环
          // LLM 会看到工具结果，继续思考
          
        } catch (error) {
          // 错误处理和重试逻辑
          await SessionRetry.handle(error)
        }
      }
    }
  }
}

// src/session/prompt.ts
async function buildContext(input: PromptInput) {
  // 1. 获取所有消息（包含压缩后的）
  const messages = await MessageV2.filterCompacted(
    MessageV2.stream(input.sessionID)
  )
  
  // 2. 转换为 LLM 格式
  const llmMessages = MessageV2.toModelMessage(messages)
  
  // 3. 添加 System Prompt
  const systemPrompt = await SystemPrompt.build({
    agent: selectedAgent,
    model: selectedModel,
  })
  
  return { messages: llmMessages, system: systemPrompt }
}

// src/session/processor.ts
export function create(input) {
  const toolcalls: Record<string, MessageV2.ToolPart> = {}
  let snapshot: string | undefined
  let blocked = false
  let attempt = 0
  let needsCompaction = false
 
  return {
    // 核心处理函数
    async process(streamInput: LLM.StreamInput) {
      // 处理流式事件...
    },
    
    // 从 tool call ID 获取 Part
    partFromToolCall(toolCallID: string) {
      return toolcalls[toolCallID]
    },
    
    // 获取当前消息
    get message() {
      return input.assistantMessage
    }
  }
}

// src/session/processor.ts (简化版)
for await (const value of stream.fullStream) {
  switch (value.type) {
    case "tool-call-start":
      // 创建 ToolPart
      const part: MessageV2.ToolPart = {
        id: Identifier.ascending("part"),
        type: "tool",
        tool: value.toolName,
        args: {},
        state: { status: "pending" },
      }
      toolcalls[value.toolCallId] = part
      break
 
    case "tool-call-delta":
      // 增量更新参数
      const part = toolcalls[value.toolCallId]
      part.args = mergeJson(part.args, value.argsTextDelta)
      await Session.updatePart({ part, delta: value.argsTextDelta })
      break
 
    case "tool-call":
      // 执行工具
      const part = toolcalls[value.toolCallId]
      part.state.status = "executing"
      await Session.updatePart(part)
      
      try {
        // 工具执行（带权限检查）
        const result = await tools[value.toolName].execute(
          value.args,
          toolContext
        )
        
        part.state = {
          status: "completed",
          output: result,
        }
      } catch (error) {
        part.state = {
          status: "failed",
          error: error.message,
        }
      }
      
      await Session.updatePart(part)
      break
  }
}

// src/session/compaction.ts
export const PRUNE_MINIMUM = 20_000   // 最少保留 20K tokens
export const PRUNE_PROTECT = 40_000   // 保护最近 40K tokens
 
export async function prune(input: { sessionID: string }) {
  const msgs = await Session.messages({ sessionID: input.sessionID })
  let total = 0
  let pruned = 0
  
  // 从后往前遍历消息
  for (let msgIndex = msgs.length - 1; msgIndex >= 0; msgIndex--) {
    const msg = msgs[msgIndex]
    
    for (const part of msg.parts) {
      if (part.type === "tool" && part.state.status === "completed") {
        const estimate = Token.estimate(part.state.output)
        total += estimate
        
        // 超过保护阈值的工具调用输出可以删除
        if (total > PRUNE_PROTECT) {
          pruned += estimate
          await compactPart(part)  // 清空输出，保留元数据
        }
      }
    }
  }
}

// src/session/compaction.ts (简化逻辑)
export async function compact(input: { sessionID: string }) {
  // 1. 检查是否需要压缩
  const isOverflow = await SessionCompaction.isOverflow({
    tokens: latestMessage.tokens,
    model: selectedModel,
  })
  
  if (!isOverflow) return
  
  // 2. 先尝试修剪
  await prune({ sessionID: input.sessionID })
  
  // 3. 如果还不够，生成摘要
  const summary = await SessionSummary.generate({
    sessionID: input.sessionID,
    upToMessageID: lastUserMessage.id,
  })
  
  // 4. 用摘要替换原始消息
  await Message.markAsSummarized(messagesBeforeLastUser)
  await Message.createSummaryMessage(summary)
}

// src/session/compaction.ts
export async function isOverflow(input: {
  tokens: { input: number; output: number; cache: { read: number } }
  model: Provider.Model
}) {
  const context = input.model.limit.context  // 200K for Claude Sonnet 4
  const count = input.tokens.input + input.tokens.cache.read + input.tokens.output
  
  // 预留输出空间
  const output = Math.min(input.model.limit.output, 32_000)
  const usable = context - output
  
  return count > usable  // 超过可用空间？
}

// src/session/summary.ts
export namespace SessionSummary {
  export async function generate(input: {
    sessionID: string
    upToMessageID: string
  }) {
    const messages = await getMessagesUpTo(input.upToMessageID)
    
    // 使用特殊的 "summary" Agent
    const result = await LLM.generate({
      agent: "summary",  // 专门的摘要 Agent
      messages: messages,
      prompt: "总结以上对话的关键信息和决策...",
    })
    
    return result.summary
  }
}

// src/session/retry.ts
export namespace SessionRetry {
  const MAX_RETRIES = 3
  
  export async function handle(error: Error, attempt: number) {
    // 可重试的错误类型
    if (error.code === "rate_limit_exceeded" || 
        error.code === "server_error") {
      
      if (attempt < MAX_RETRIES) {
        const delay = Math.pow(2, attempt) * 1000  // 指数退避
        await sleep(delay)
        return "retry"
      }
    }
    
    throw error  // 不可重试或超过次数
  }
}

// src/session/revert.ts
export namespace SessionRevert {
  export async function create(input: {
    sessionID: string
    messageID: string
    partID?: string
  }) {
    // 1. 创建 Git 快照
    const snapshot = await Snapshot.create()
    
    // 2. 记录撤销点
    await Session.update({
      id: input.sessionID,
      revert: {
        messageID: input.messageID,
        partID: input.partID,
        snapshot: snapshot.id,
      }
    })
  }
  
  export async function apply(input: { sessionID: string }) {
    const session = await Session.get(input.sessionID)
    if (!session.revert) throw new Error("No revert point")
    
    // 1. 恢复 Git 快照
    await Snapshot.restore(session.revert.snapshot)
    
    // 2. 删除撤销点之后的消息
    await Message.deleteAfter(session.revert.messageID)
    
    // 3. 清除撤销点
    await Session.update({
      id: input.sessionID,
      revert: undefined,
    })
  }
}

// src/session/todo.ts
export namespace SessionTodo {
  export const Item = z.object({
    id: z.string(),
    content: z.string(),
    status: z.enum(["pending", "in_progress", "completed", "cancelled"]),
    priority: z.enum(["high", "medium", "low"]),
  })
  
  export async function update(input: {
    sessionID: string
    todos: Item[]
  }) {
    // 存储在 Session Storage 中
    await Storage.set(`todo/${input.sessionID}`, input.todos)
    
    // 发布事件通知 UI
    await Bus.publish(Event.Updated, {
      sessionID: input.sessionID,
      todos: input.todos,
    })
  }
}

// src/session/system.ts
export namespace SystemPrompt {
  export async function build(input: {
    agent: Agent.Info
    model: Provider.Model
  }) {
    let template = ""
    
    // 1. 根据 Provider 选择模板
    if (input.model.providerID === "anthropic") {
      if (input.model.modelID.includes("sonnet-4")) {
        template = ANTHROPIC_20250930
      } else {
        template = ANTHROPIC
      }
    } else if (input.model.providerID === "google") {
      template = GEMINI
    }
    
    // 2. 根据 Agent 选择
    if (input.agent.name === "plan") {
      template += PLAN
    }
    
    // 3. 添加 Agent 的自定义 Prompt
    if (input.agent.prompt) {
      template += "\n\n" + input.agent.prompt
    }
    
    return template
  }
}

// 1. 创建会话
const session = await Session.create({
  directory: "/path/to/project",
  title: "Implement user authentication",
})
 
// 2. 发送用户消息
await SessionPrompt.prompt({
  sessionID: session.id,
  parts: [
    {
      type: "text",
      text: "帮我实现用户登录功能，使用 JWT",
    }
  ],
})
 
// 3. Agent 会自动开始工作
// - 读取现有代码
// - 生成新文件
// - 运行测试
// - 返回结果

// 订阅会话事件
Bus.subscribe(Session.Event.Updated, async (event) => {
  console.log("Session updated:", event.properties.info.id)
  console.log("Title:", event.properties.info.title)
})
 
// 订阅消息更新
Bus.subscribe(MessageV2.Event.Updated, async (event) => {
  const message = event.properties.info
  console.log("New message:", message.role, message.parts.length)
})
 
// 订阅 Part 更新（实时流式）
Bus.subscribe(MessageV2.Event.PartUpdated, async (event) => {
  const part = event.properties.part
  if (part.type === "text") {
    console.log("Text delta:", event.properties.delta)
  }
})

// 检查是否需要压缩
const lastMessage = await MessageV2.latest({ sessionID })
const needsCompaction = await SessionCompaction.isOverflow({
  tokens: lastMessage.tokens,
  model: selectedModel,
})
 
if (needsCompaction) {
  // 先修剪
  await SessionCompaction.prune({ sessionID })
  
  // 如果还不够，生成摘要
  const stillOverflow = await SessionCompaction.isOverflow(...)
  if (stillOverflow) {
    await SessionCompaction.compact({ sessionID })
  }
}

// 在配置中定义
const customAgent: Agent.Info = {
  name: "code-reviewer",
  description: "专门进行代码审查",
  mode: "primary",
  temperature: 0.3,
  prompt: `
你是一个资深的代码审查专家。
你的任务是：
1. 检查代码质量
2. 发现潜在 bug
3. 提出改进建议
  `,
  permission: {
    "*": "allow",
    "edit": "deny",  // 只读，不能修改代码
    "write": "deny",
    "bash": "deny",
  }
}
 
// 使用自定义 Agent
await SessionPrompt.prompt({
  sessionID,
  agent: "code-reviewer",
  parts: [{ type: "text", text: "审查 src/auth.ts" }],
})

// 不检查 token 使用量就发送大量消息
for (const file of 100files) {
  await SessionPrompt.prompt({
    sessionID,
    parts: [{ type: "file", path: file }],
  })
}

// 监控 token 使用量
const session = await Session.get(sessionID)
const lastMessage = await MessageV2.latest({ sessionID })
 
if (lastMessage.tokens.input > 150_000) {
  // 触发压缩
  await SessionCompaction.compact({ sessionID })
}

// 同步等待结果
const result = await SessionPrompt.prompt({ ... })
// 这会阻塞，直到 Agent 完成所有工作

// 使用事件监听
const promise = SessionPrompt.prompt({ ... })
 
Bus.subscribe(SessionStatus.Event.Updated, (event) => {
  if (event.properties.status.type === "idle") {
    console.log("Agent 完成工作")
  }
})
 
await promise

// 主会话
const mainSession = await Session.create({ ... })
 
// 创建子会话处理子任务
const childSession = await Session.create({
  parentID: mainSession.id,
  directory: mainSession.directory,
  title: "Subtask: Generate tests",
})
 
// 子会话完成后，结果会汇总到主会话

// 在重要操作前创建撤销点
await SessionRevert.create({
  sessionID,
  messageID: lastSafeMessage.id,
})
 
// 执行高风险操作
await dangerousOperation()
 
// 如果出错，可以回滚
if (failed) {
  await SessionRevert.apply({ sessionID })
}