Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@ flowchart LR
Routes --> SessionOwners["explicit session owners<br/>search / translation / export / usage / catalog"]
Routes --> Services["SessionService / ChatService"]
Services --> Coordinators["Lifecycle / Turn / Assignment / Projection"]
Compat["AgentSessionPresenter<br/>compatibility forwarding"] --> Coordinators
Coordinators --> Manager["AgentManager<br/>descriptor.kind router"]
Manager --> DeepBackend["typed DeepChat backend"]
Manager --> AcpBackend["direct ACP backend"]
Expand All @@ -38,9 +37,8 @@ flowchart LR
选择才进入 `AcpProvider` adapter。
- 四个 `sessionApplication` coordinator 拥有 core session lifecycle、turn、assignment 和 projection;
Session/Chat routes、Remote 和 Cron 通过 consumer-owned narrow ports 使用同一组实例。
- `AgentSessionPresenter` 仅保留 compatibility forwarding,把兼容调用转发到同一组 coordinator;不再拥有
core session policy/state,也不再拥有 history、translation、export、usage、RTK、catalog 或 startup
migration behavior。
- `AgentSessionPresenter` 与 `IAgentSessionPresenter` 已退休;main routes、Remote、Cron、Tool、MCP 与
Floating 直接依赖 consumer-owned coordinator ports。
- history、translation、export、usage、RTK、catalog 和 startup migrations 由 typed routes/lifecycle
hooks 直接组合各自 owner。
- `AgentRuntimePresenter` 仍初始化 `DeepChatAgentRuntime`,并保留 DeepChat state/delegate、message、Tape、
Expand All @@ -61,7 +59,6 @@ flowchart LR
| DeepChat Memory adapter | `src/main/agent/deepchat/memory/` | sole runtime coordinator、prompt contributor、background ingestion observer |
| ACP runtime | `src/main/agent/acp/` | catalog、launch、client/process/session/protocol、direct instance/runtime |
| session application | `src/main/presenter/sessionApplication/` | Lifecycle、Turn、AgentAssignment、Projection coordinators 与窄 dependency ports |
| `AgentSessionPresenter` | `src/main/presenter/agentSessionPresenter/` | core session public compatibility forwarding;不拥有 application behavior |
| session boundary owners | `src/main/routes/sessions/`, `src/main/presenter/exporter/agentSessionExporter.ts`, `src/main/presenter/usageStatsService.ts` | history、translation、current export、usage dashboard/backfill |
| startup maintenance | `src/main/presenter/startupMigrations/` | default legacy import and stateless session-data migrations |
| shared session policies | `src/main/agent/shared/` | available-agent catalog and assistant-model selection |
Expand Down
16 changes: 7 additions & 9 deletions docs/FLOWS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,13 +36,11 @@ sequenceDiagram
- `src/main/agent/manager/deepChatAgentBackend.ts`
- `src/main/agent/manager/directAcpAgentBackend.ts`
- `src/main/presenter/sessionApplication/`
- `src/main/presenter/agentSessionPresenter/index.ts`

`SessionService` / `ChatService` 直接使用 consumer-owned coordinator ports。`AgentSessionPresenter` 只为
兼容调用转发 core session methods;history、translation、export、usage、RTK、catalog 与 startup
maintenance 直接进入各自 owner,不经过该 presenter。agent kind resolution 和 executable backend
selection 只发生在 `AgentManager`。`new_sessions.session_kind` 仍表示 `regular | subagent`,不决定
DeepChat/ACP backend。
`SessionService` / `ChatService` 直接使用 consumer-owned coordinator ports;原 aggregate session
presenter 已退休。history、translation、export、usage、RTK、catalog 与 startup maintenance 直接进入
各自 owner。agent kind resolution 和 executable backend selection 只发生在 `AgentManager`。
`new_sessions.session_kind` 仍表示 `regular | subagent`,不决定 DeepChat/ACP backend。

## 2. DeepChat 消息处理主循环

Expand Down Expand Up @@ -147,14 +145,14 @@ sequenceDiagram
- `deepchat_assistant_blocks` 存 assistant block 增量。
- `deepchat_search_documents` / `_fts` 存历史搜索索引。

`sessions.searchHistory` 不经过 `AgentSessionPresenter`;typed route 直接调用
`sessions.searchHistory` typed route 直接调用
`src/main/routes/sessions/sessionHistorySearch.ts`,由该 owner 保持 FTS、LIKE 与 legacy SQL fallback。

## 5. ACP direct backend 与 provider compatibility

```mermaid
flowchart TD
CompatFacade["AgentSessionPresenter<br/>compatibility forwarding"] --> App["Session application coordinator"]
Entry["Routes / Remote / Cron"] --> App["Session application coordinators"]
App --> Manager["AgentManager"]
Manager --> Kind{"descriptor.kind"}
Kind -->|acp| Direct["DirectAcpSessionBackend"]
Expand Down Expand Up @@ -200,7 +198,7 @@ Spotlight 默认由 `CommandOrControl+P` 打开,混排 recent sessions、agent

## 7. Startup Maintenance

五个 lifecycle startup hooks 只负责调度,不经 `AgentSessionPresenter`:legacy import 调用
五个 lifecycle startup hooks 只负责调度:legacy import 调用
`LegacyChatImportService`,usage backfill 调用 `UsageStatsService`,两类 session-data cleanup 调用 stateless
startup migration functions,RTK health 调用 RTK runtime service。task id、priority、resource 与持久状态 key
保持稳定。
Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ shared contracts 进入;少数仍需要 raw IPC 的能力只能封装在明确
| --- | --- |
| [ARCHITECTURE.md](./ARCHITECTURE.md) | 当前主架构、能力 owner、typed boundary 规则 |
| [FLOWS.md](./FLOWS.md) | 当前消息、工具、ACP、导入、定时任务、远程控制流程 |
| [architecture/agent-system.md](./architecture/agent-system.md) | `agentSessionPresenter` / `agentRuntimePresenter` 细节 |
| [architecture/agent-system.md](./architecture/agent-system.md) | session application coordinators / `agentRuntimePresenter` 细节 |
| [architecture/tool-system.md](./architecture/tool-system.md) | `ToolPresenter`、agent tools、ACP helper 分层 |
| [architecture/session-management.md](./architecture/session-management.md) | 新会话管理、分页恢复、legacy 数据平面边界 |
| [architecture/event-system.md](./architecture/event-system.md) | EventBus 与 typed events 的当前分工 |
Expand Down
68 changes: 68 additions & 0 deletions docs/architecture/agent-runtime-presenter-thinning/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# Agent Runtime Presenter Thinning — Spec

> Status: implemented
> Baseline: `dev@868241322`, 2026-07-14

## Problem

The layered runtime migration moved session-owned mutable state into
`DeepChatAgentInstance` and split direct ACP from the DeepChat backend, but
`src/main/presenter/agentRuntimePresenter/index.ts` is still an implementation owner rather than a
thin presenter boundary:

- 8,167 lines;
- 211 class methods;
- 29 class fields;
- prompt assembly, generation-setting normalization, permission review, tool-result adaptation,
interaction projection, compaction projection, and turn orchestration remain in one file.

The latest reliability work increased the file by 557 net lines. The backend split was real, but it
did not finish the presenter split.

## Goal

Reduce `AgentRuntimePresenter` to the remaining turn/session façade and wiring by moving cohesive,
independently testable policies to their existing owners or focused modules. This goal must remove
responsibilities from the class, not move the entire class behind a new name.

## Acceptance Criteria

- `agentRuntimePresenter/index.ts` is at most 3,200 lines.
- The class has at most 130 methods.
Comment on lines +30 to +31

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Outcome contradicts this spec's own acceptance criteria.

Acceptance criteria require ≤3,200 lines / ≤130 methods (Lines 30-31), but the Outcome reports 4,905 lines / 135 methods (Lines 59-60) while also claiming the guard already "rejects growth beyond 3,200 lines" (Line 64). A 4,905-line file cannot coexist with an already-enforced 3,200-line guard. Per the follow-up spec, the 3,200 ceiling appears to actually be adopted by the later deepchat-runtime-lifecycle-owners work, not this one — Line 64 seems to prematurely claim that outcome here.

Also applies to: 59-64

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/architecture/agent-runtime-presenter-thinning/spec.md` around lines 30 -
31, Reconcile the acceptance criteria and Outcome in the architecture spec:
remove the claim that the 3,200-line guard is already enforced and update the
reported results so they do not contradict the ≤3,200-line/≤130-method criteria.
Keep adoption of that ceiling attributed to the later
deepchat-runtime-lifecycle-owners work, unless this spec explicitly documents
the criteria as unmet.

- Public presenter and session-application contracts remain unchanged.
- Extracted modules do not receive the presenter instance or a generic service locator.
- Generation settings, auto-approve review, system prompt/resources, and tool-result normalization
have focused tests that do not construct the full presenter graph.
- Existing provider round, Tape, compaction, pending input, permission, tool, Memory, and terminal
ordering remains unchanged.
- A repository check prevents the presenter from silently growing past the accepted ceiling.

## Constraints

- No new runtime dependency.
- No IPC, event payload, database schema, renderer, or user-facing behavior change.
- Preserve cancellation and stale-instance checks at their current boundaries.
- Keep `DeepChatAgentInstance` as the owner of per-session mutable runtime state.
- Keep `ToolPresenter`, `SkillPresenter`, `McpPresenter`, Memory, message, and Tape ownership intact.

## Non-goals

- Rewriting the provider/tool loop.
- Moving the 8,000-line implementation unchanged into a `TurnRunner` class.
- Introducing a DI container, plugin lifecycle, base presenter, mixin, or inheritance hierarchy.
- Forcing `index.ts` below 1,000 lines in one high-risk change. The remaining turn runner can be
extracted separately once these collaborators are stable.
- Fixing unrelated behavior found during extraction.

## Outcome

- The initial policy-extraction checkpoint reduced `agentRuntimePresenter/index.ts` from 8,167 to
4,905 lines and `AgentRuntimePresenter` from 211 to 135 methods. That checkpoint did not yet meet
the final 3,200-line / 130-method criteria.
- Generation policy, prompt/resource assembly, permission review, tool normalization, interaction
projection, session settings, tool resolution, deferred execution, ACP compatibility, compaction
projection, and provider permission settlement now have focused owners with explicit dependencies.
- Follow-up [runtime lifecycle ownership](../deepchat-runtime-lifecycle-owners/spec.md) moved the
initial/resume turn, provider/tool loop, and paused-interaction control flows behind three explicit
owners, reduced the presenter boundary to 2,604 lines / 122 methods, and adopted the 3,200-line
architecture guard, completing the acceptance criteria.
5 changes: 5 additions & 0 deletions docs/architecture/agent-system-layered-runtime/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,11 @@ assignment 与 projection 已由四个 composition-owned session application coo
与 hooks 直接使用分离的 coordinator ports;history、translation、export、usage、RTK 与 catalog owner
继续独立。startup hooks 直接调用 migration/maintenance owner。`AgentRuntimePresenter` 保留 DeepChat
state/delegate 与 adapter wiring,不再构成 generic agent runtime。
后续的 [Agent Runtime Presenter Thinning](../agent-runtime-presenter-thinning/spec.md) 又把 generation、
prompt/resource、permission review、tool adaptation、interaction projection、session settings、ACP
compatibility 与 compaction/provider-permission coordination 移到 focused owner;presenter boundary
经 [runtime lifecycle ownership](../deepchat-runtime-lifecycle-owners/spec.md) 继续拆分后现为 2,604 行 /
122 methods,并由 3,200 行 architecture guard 约束。
current docs、architecture guards 与 baseline generator
已在 `ASLR-091` 收敛;`ASLR-092` 已完成 canonical baseline write、全量
main/renderer/Memory/native/build/E2E gates 与最终契约 diff。
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@
> 仍可按兼容合同选择 ACP。下文 stage/type 伪代码表达生命周期合同;当前 concrete API 以实施进度和
> `src/main/agent/deepchat/loop/` 为准。

> Current ownership: `TurnCoordinator` owns initial/resume preparation,
> `DeepChatLoopRunner` owns provider-attempt execution and context-pressure recovery, and
> `DeepChatLoopEngine` remains the inner provider-round/tool-batch decision engine. The presenter is
> the composition root and compatibility façade; session/run state remains in
> `DeepChatAgentInstance`/`LoopRun`.
>
> Implementation progress: ASLR-050 introduced the per-turn `LoopRun` and narrow provider, tool,
> Tape, output, and context port contracts. That slice left the legacy `processStream` control flow
> unchanged while moving provider-round state, provider-attempt sequencing, and recovery flags into
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@
> notification observer 已由 ASLR-057 隔离;ASLR-070..073 已接入 direct ACP permission continuation。
> 两者共享 decision UI,不共享 continuation 实现;下文类型是合同伪代码。

> Current ownership: `InteractionCoordinator.respond()` performs ordered DeepChat interaction
> settlement and calls the single `TurnCoordinator.resume()` boundary only after the final pending
> interaction. `DeepChatAgentInstance` remains the batch/interaction state owner.

## 1. 模块目的

本模块把“等待用户决定”建模为明确 gate/interaction,而不是散落 callback。DeepChat tool permission、
Expand Down
73 changes: 73 additions & 0 deletions docs/architecture/deepchat-runtime-lifecycle-owners/spec.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# DeepChat Runtime Lifecycle Owners — Spec

> Status: implemented
> Baseline: `codex/agent-runtime-presenter-thinning@4c5c20b0c`, 2026-07-14

## Problem

`AgentRuntimePresenter` is still 4,874 lines because it owns four long-lived control flows:

- initial turn setup in `processMessage`;
- resumed turn setup in `resumeAssistantMessage`;
- provider/tool loop execution in `runStreamForMessage`;
- paused interaction settlement in `respondToolInteraction`.

These are not four independent state owners. Initial and resumed setup are two entries into one turn
lifecycle, while loop execution and interaction settlement have separate invariants. Keeping all four
flows in the presenter hides those three ownership boundaries.

## Goal

Move the lifecycle implementations behind three explicit owners that do not retain session or run
state:

- `TurnCoordinator.start()` and `TurnCoordinator.resume()` own pre-stream turn preparation and
terminal settlement;
- `DeepChatLoopRunner.run()` owns provider/tool round execution and context-pressure recovery;
- `InteractionCoordinator.respond()` owns paused interaction reconciliation and resume decisions.

`AgentRuntimePresenter` remains the public façade and composition root.

## Acceptance Criteria

- The presenter keeps its existing public API and thin compatibility wrappers used by current tests.
- No extracted owner receives an `AgentRuntimePresenter` instance or a general-purpose service
locator.
- Owner ports are explicit, owner-specific, and contain no mutable runtime state.
- Per-session and per-run mutable state remains in `DeepChatAgentInstance` and `LoopRun`.
- Initial/resume ordering, cancellation, stale-instance checks, persistence, hooks, Tape, Memory,
permissions, queue draining, and terminal outcomes remain unchanged.
- `agentRuntimePresenter/index.ts` is at most 3,200 lines.
- Total production TypeScript across the presenter and the three new owner files grows by no more
than 700 lines over the 4,874-line baseline. The allowed delta is the explicit owner-port
contracts and composition wiring, not duplicated control flow.
- The architecture guard adopts the new presenter ceiling.

## Constraints

- No new runtime dependency, database schema, IPC contract, event payload, or user-visible change.
- No new shared mutable maps, generic dependency container, inheritance hierarchy, or framework.
- Preserve the existing private wrapper names where tests intentionally replace the loop or resume
boundary.
- Prefer existing stores, coordinators, and loop primitives over new abstractions.

## Non-goals

- Rewriting the provider/tool algorithm.
- Merging initial and resumed context construction.
- Moving session state out of `DeepChatAgentInstance`.
- Splitting every helper into its own class or forcing the presenter below 1,000 lines.
- Syncing a GitHub issue.

## Outcome

- `agentRuntimePresenter/index.ts`: 4,874 → 2,604 lines; class methods: 136 → 122.
- `TurnCoordinator` owns `start()`/`resume()` in 1,226 lines.
- `DeepChatLoopRunner` owns `run()`, context-pressure recovery, Tape manifests, request traces, and
rate-limit projection in 967 lines.
- `InteractionCoordinator` owns `respond()` and deferred permission/question/skill-draft settlement
in 728 lines.
- The four-file production total is 5,525 lines, a 651-line increase for explicit port contracts and
composition wiring, within the 700-line ceiling.
- The presenter guard is 3,200 lines. Focused runtime validation passes 605 tests with 19 skipped;
format, i18n, lint, architecture guards, and node/web type checks pass.
30 changes: 0 additions & 30 deletions docs/architecture/multi-agent-isolation/plan.md

This file was deleted.

14 changes: 0 additions & 14 deletions docs/architecture/multi-agent-isolation/tasks.md

This file was deleted.

Loading
Loading