Skip to content

docs(architecture): audit Model access group against implementation #4794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ggbdpq wants to merge 3 commits into
base: main
Choose a base branch
from
+38 −2
Open

docs(architecture): audit Model access group against implementation #4794

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
039e93e
docs(architecture): audit Model access group against implementation
ggbdpq Sep 4, 2026
9ffe10a
Merge branch 'main' into docs/audit-model-access
ggbdpq Sep 5, 2026
5399a7a
docs: correct the startup-path exclusion and mark the transport probl…
ggbdpq Sep 5, 2026
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
18 changes: 18 additions & 0 deletions docs/architecture/openai-responses-incremental-transport.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: architecture.openai-responses-incremental-transport
title: "OpenAI Responses incremental transport"
language: en
source_language: en
implementation_status: current

@hqhq1025 hqhq1025 Sep 5, 2026

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.

[P2] Reconcile current status with the implemented transport

The new implementation_status: current and last_verified metadata make the unchanged present-tense statement at line 36 inaccurate: the exact-head implementation already plans a turn continuation in packages/runtime/src/model-adapter.ts:281-301, slices to the suffix in openai-responses-continuation.ts:67-82, and sends that delta when the WebSocket request properties match in openai-responses-websocket.ts:280-313. Please mark the problem statement as the pre-optimization state (as the other audited document does) or rewrite it in historical tense before declaring the document current.

document_status: current
translation_status: source-only
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand All @@ -21,6 +33,12 @@

## 1. Problem and invariant

> **Status (verified 2026-09-04):** this optimization is implemented — the adapter plans a turn
> continuation and sends the suffix delta over a matching Responses WebSocket
> (`packages/runtime/src/model-adapter.ts`, `openai-responses-continuation.ts`,
> `openai-responses-websocket.ts`). The Problem below is kept as the record of the
> pre-optimization state.

Long tool loops currently rebuild and upload the complete provider history on every step. The
durable Runtime event ledger remains the source of truth, but the OpenAI Responses transport may
reuse a turn-scoped WebSocket and send only the suffix after the previous response.
Expand Down
22 changes: 20 additions & 2 deletions docs/model-metadata-firstscreen-optimization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,15 @@
---
doc_id: model-metadata-firstscreen-optimization
title: "perf(desktop): remove models.dev metadata from the renderer startup path"
language: en
source_language: en
implementation_status: current
document_status: current
translation_status: synced
last_verified: 2026-09-04
owners:
- maka-backend
---
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
Expand All @@ -24,6 +36,10 @@

## Problem

> **Status (verified 2026-09-04):** this optimization is implemented — every one of the five startup
> import paths listed below is cut in the current source. The Problem is kept as the 2026-08-04
> record of the pre-optimization state.

Most users configure only a few providers, but Maka currently loads metadata for every provider and hundreds of models on startup. This data should remain behind the main-process authority boundary, with the renderer receiving only the lightweight projection needed for the current UI.

The Desktop AppShell startup path statically loads `packages/core/src/model-metadata.generated.ts`. The file is generated during installation or build from the committed models.dev snapshot; the 2026-08-04 measurement below was about 520 KB / 13,988 lines and contained full metadata for roughly 44 providers and hundreds of models.
Expand Down Expand Up @@ -75,7 +91,7 @@ Full metadata remains available to the main process and lazy-loaded SettingsModa
Acceptance criteria:

- The startup entry and all of its static transitive dependencies exclude `model-metadata.generated.ts`, `model-metadata.ts`, `provider-registry.ts`, `model-catalog.ts`, and `model-thinking.ts`.
- The startup path no longer statically depends on the renderer's `model-catalog-choices.ts` or `chat-model-selection.ts`.
- The startup path no longer statically depends on the renderer's `model-catalog-choices.ts`; `shell-chat-model-selection.ts` deliberately remains on the static path as the lightweight selector behind `useShellChatModel` — this optimization removes the heavy metadata modules, not that selector.
- Searching startup chunks for `claude-opus|gpt-5\.|gemini-2\.` returns zero; full metadata exists only on lazy Settings paths.
- Model choices, headings, provider logos, and active/new-chat thinking levels remain correct.
- OnboardingHero still shows the four recommended providers with their names, descriptions, and logos.
Expand All @@ -97,6 +113,8 @@ Acceptance criteria:

## 问题

> **状态（2026-09-04 核验）：** 该优化已落地——下面列出的五条首屏依赖链在当前源码中均已切断。Problem 一节保留的是 2026-08-04 优化前状态的记录。

大多数用户只配置少数几个 provider，但 Maka 当前会在启动时加载全部 provider 和数百个模型的元数据。完整目录应留在 main process 的权威边界内，renderer 只接收当前界面所需的轻量投影。

桌面端 AppShell 的首屏静态依赖会加载 `packages/core/src/model-metadata.generated.ts`。该文件在安装或构建时由 committed models.dev snapshot 生成；下面记录的 2026-08-04 实测约为 520 KB、13,988 行，包含约 44 个 provider 和数百个模型的完整元数据。
Expand Down Expand Up @@ -148,7 +166,7 @@ Session health notice 在 event 触发的异步刷新完成前继续使用上一
验收标准：

- 首屏入口及其所有静态传递依赖不包含 `model-metadata.generated.ts`、`model-metadata.ts`、`provider-registry.ts`、`model-catalog.ts` 或 `model-thinking.ts`。
- 首屏不再静态依赖 renderer 的 `model-catalog-choices.ts` 和 `chat-model-selection.ts`。
- 首屏不再静态依赖 renderer 的 `model-catalog-choices.ts`；`shell-chat-model-selection.ts` 作为 `useShellChatModel` 背后的轻量选择器有意保留在静态路径上——本优化移除的是重量级元数据模块，不含这个选择器。
- 构建产物的首屏 chunk 中检索 `claude-opus|gpt-5\.|gemini-2\.` 为 0；完整元数据只存在于设置页懒加载路径。
- model picker 的模型、heading、provider logo，以及 active/new-chat thinking level 选项保持正确。
- OnboardingHero 正常显示 4 个推荐 provider 的名称、描述和 logo。
Expand Down