sw-ads-agent/docs/architecture.md

Architecture

Component map

flowchart TB
  subgraph Browser
    C[assistant-ui Composer]
    T[Thread + Tool UI]
    E[Event Timeline]
    S[HarnessClientStore]
    C --> S
    S --> T
    S --> E
  end
  subgraph Server
    F[Fastify protocol layer]
    R[SessionRegistry]
    ES[EventStore]
    AB[ApprovalBroker]
    AS[AttachmentStore]
    MS[ModelConnectionStore]
    P[Pi AgentSession]
    L[DefaultResourceLoader]
    W[SafeWorkspace]
  end
  S -->|JSON / multipart| F
  F -->|SSE| S
  F --> R
  F --> AS
  F --> MS
  R --> P
  R --> ES
  P --> L
  P --> AB
  P --> W

apps/server 只做请求校验、错误映射、SSE framing 与对象组合。packages/harness 拥有 Agent 生命周期和所有核心状态接口。packages/shared 不依赖 Node，定义前后端唯一协议。apps/web 不拥有另一套 Agent 状态机，只用 sequence reducer 投影 EventStore。

Session creation and run

1. Web 创建 Harness Session；服务器建立独立 cwd、事件序列、附件和凭证命名空间。
2. 服务启动时严格加载并缓存 .env 默认模型；新 Session 优先使用该配置。没有环境配置时，Web 可把 localStorage 中通过 strict Zod 校验的非敏感模型元数据恢复到该 Session。API Key 不参与浏览器持久化，来自环境变量或服务器 AES-256-GCM 凭证库。
3. 首次 Run 使用精确模型创建独立 Pi AgentSession、SessionManager.inMemory(cwd) 与安全 extension。
4. message 立即得到 202；后台调用 prompt，Pi 事件由单一 adapter 映射并写 EventStore。
5. SSE 将历史和实时事件交给 HarnessClientStore；assistant-ui External Store Runtime 只负责呈现。

Storage replacement seams

EventStore、ApprovalBroker、AttachmentStore、ModelConnectionStore、SessionRegistry 都有接口。内存/本地临时文件实现可分别替换为 Redis streams、Postgres、对象存储、KMS 与分布式 worker，而不改变 Web 协议。

Failure and shutdown

Run timeout 和用户 cancel 使用不同 reason；Approval wait 监听同一 AbortSignal。删除先 abort，再 cancel pending approval，关闭订阅与 SSE，调用 Pi dispose()，清凭证/附件，最后在 canonical sessions root 校验后删除 cwd。单个 SSE 断开不取消 Run。