RunState：跨进程审批的序列化

Agent 后端（Go 服务）           浏览器前端
    │                              │
    ├─ Run 到 delete_user，暂停     │
    ├─ RunState → JSON             │
    ├─ 通过 WebSocket 发 JSON ───► │
    │                              ├─ 弹窗"要删用户 123，同意？"
    │                              ├─ 用户点"同意"
    │   ◄──── WS 发回 {approve: true}
    ├─ 重建 RunState               │
    ├─ ResumeRun                   │

type RunState struct {
    CurrentAgent        *Agent           // 指针！
    GeneratedItems      []RunItem        // 接口，背后是各种具体类型
    Interruptions       []*ToolApprovalItem  // 又是指针
    Approvals           *ApprovalStore   // 带 mutex 的对象
    // ...
}

// agents/run_state.go:125
type serialRunState struct {
    SchemaVersion    string                            `json:"schema_version"`
    CurrentAgent     string                            `json:"current_agent"`     // 名字，不是指针
    CurrentTurn      int                               `json:"current_turn"`
    OriginalInput    []json.RawMessage                 `json:"original_input"`    // 原始 JSON
    GeneratedItems   []serialItem                      `json:"generated_items"`   // 拍平的 item
    ModelResponses   []serialResponse                  `json:"model_responses"`
    InterruptedResponse *serialResponse                `json:"interrupted_response"`
    Interruptions    []serialInterruption              `json:"interruptions"`
    Approvals        map[string]serialApproval         `json:"approvals_by_call_id"`
    ApprovalsByTool  map[string]serialApproval         `json:"approvals_by_tool"`
    Usage            *Usage                            `json:"usage"`
}

type serialItem struct {
    Type  string          `json:"type"`   // "message" / "tool_call" / ...
    Agent string          `json:"agent"`  // 哪个 agent 产的（名字）
    Input json.RawMessage `json:"input"`  // 原始的 Responses API input item JSON
}

// agents/run_state.go:237
func RunStateFromJSON(data []byte, registry map[string]*Agent) (*RunState, error) {
    var in serialRunState
    json.Unmarshal(data, &in)

    lookup := func(name string) *Agent { return registry[name] }

    st := &RunState{
        CurrentAgent: lookup(in.CurrentAgent),  // 按名字找回指针
        // ...
    }
    if st.CurrentAgent == nil {
        return nil, fmt.Errorf("unknown agent %q; add it to the registry", in.CurrentAgent)
    }
}

registry := map[string]*agents.Agent{
    "main_agent":    mainAgent,
    "billing_agent": billingAgent,
    "support_agent": supportAgent,
}

state, _ := agents.RunStateFromJSON(jsonBytes, registry)
agents.ResumeRun(ctx, state, opts)

// agents/run_items.go:150（简化）
type rawInputRunItem struct {
    item  TResponseInputItem  // 直接持有的 input item
    agent *Agent
}

func (r *rawInputRunItem) ToInputItem() TResponseInputItem {
    return r.item  // 直接返回持有的 input item
}

Approvals       map[string]serialApproval `json:"approvals_by_call_id"`  // 按调用 ID
ApprovalsByTool map[string]serialApproval `json:"approvals_by_tool"`     // 按工具名

s.Approvals.mu.Lock()
for k, d := range s.Approvals.byCallID {
    out.Approvals[k] = serialApproval{...}
}
s.Approvals.mu.Unlock()

SchemaVersion string `json:"schema_version"`
const RunStateSchemaVersion = "1.0"

if in.SchemaVersion != RunStateSchemaVersion {
    return nil, fmt.Errorf("unsupported schema version %q (want %q)", ...)
}

// === 后端进程 ===

// 1. 第一次 Run，遇到审批中断
result, _ := agents.Run(ctx, agent, "删用户 123", opts)
if result.State != nil {
    // 2. 序列化 RunState
    stateJSON, _ := json.Marshal(result.State)

    // 3. 存到数据库（或发给前端）
    db.Save("run_state", runID, stateJSON)
    ws.Send(frontend, map[string]any{
        "type": "approval_needed",
        "interruptions": result.State.Interruptions,
    })
}

// === 前端进程（浏览器）===

// 4. 收到审批请求，弹窗，用户点"同意"
// 5. 发回决策
ws.Send(backend, map[string]any{
    "type": "approve",
    "call_id": "call_abc",
})

// === 后端进程（恢复）===

// 6. 读回 RunState JSON
stateJSON, _ := db.Load("run_state", runID)

// 7. 反序列化（需要 registry）
registry := map[string]*agents.Agent{"main": agent}
state, _ := agents.RunStateFromJSON(stateJSON, registry)

// 8. 记录审批决策
state.Approve(findInterruption(state, "call_abc"), false)

// 9. Resume
result, _ = agents.ResumeRun(ctx, state, opts)
// 继续执行，完成