diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml index a79104468c..3f4683f480 100644 --- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md -2026-07-14-provider-routed-llm-adapters.md: e1eaf52f21481a7c65e85effb7607b16f9b0ffdd -2026-07-14-provider-routed-llm-adapters.zh.md: 4e620408dabffc8368293635613afb5778b6e822 +2026-07-14-provider-routed-llm-adapters.md: 78c8d6788006c503b532ff2bbddd30342415f0a4 +2026-07-14-provider-routed-llm-adapters.zh.md: 5e73cab5f1f2b1296c9a486d1c833e95bb5674a0 diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md index e1eaf52f21..78c8d67880 100644 --- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md +++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.md @@ -40,9 +40,9 @@ pi-ai's common stream options do not expose stop sequences. `dsh-llm-pi-ai` reje Assistant messages carry the request's `provider` and `model`, plus an optional JSON-serializable adapter replay state. A successful `assistant/message` session event records those fields and `deriveMessages()` returns them with the assistant message. User, system, context, and tool-result messages carry no assistant route fields. The provider/model fields are authoritative loop data; an adapter owns only its opaque replay-state payload. -A terminal successful `finish` chunk may carry replay state, and `BlockAssembler` retains it alongside usage and finish reason. The loop attaches that state to the assembled assistant message's model source without exposing a response-rewrite hook. Error and aborted responses do not produce a normal assistant message and therefore do not enter future model history. +A terminal successful `finish` chunk may carry replay state as a `ReplayEnvelope`: opaque response-level metadata plus optional per-block entries aligned with the emitted block sequence. `BlockAssembler` makes one keep/drop decision for content and metadata — when max-token assembly drops a tool call, the envelope loses the entry at the same position — so the state the loop attaches to the assembled assistant message's model source always describes the stored blocks, per the [max-token replay-state alignment decision](../bug-fix/2026-08-15-max-token-replay-state-alignment.md). The loop exposes no response-rewrite hook. Error and aborted responses do not produce a normal assistant message and therefore do not enter future model history. -The pi-ai replay state is a versioned, minimal projection of its successful `AssistantMessage`: source API/provider/model, response id/model, stop reason, and index-aligned text, thinking, and tool-call signatures. It does not duplicate text or tool arguments already carried by Harness content blocks, and it omits diagnostics, timestamps, usage, and errors. On a later request, `LlmRuntime` gives replay state to the target adapter only when the historical provider and target provider are currently owned by the same adapter instance. That adapter combines the logged Harness content with replay state when it can restore the historical response, and owns any required cross-model or cross-provider conversion. An adapter receiving replay state with an unknown version or mismatched block shape fails explicitly; a different adapter receives only provider-neutral content plus provider/model fields. +The pi-ai replay state fills that envelope with a versioned, minimal projection of its successful `AssistantMessage`: a response half (source API/provider/model, response id/model, stop reason) and per-block text, thinking, and tool-call signatures. It does not duplicate text or tool arguments already carried by Harness content blocks, and it omits diagnostics, timestamps, usage, and errors. On a later request, `LlmRuntime` gives replay state to the target adapter only when the historical provider and target provider are currently owned by the same adapter instance. That adapter combines the logged Harness content with replay state when it can restore the historical response, and owns any required cross-model or cross-provider conversion. Durable content stays authoritative: an adapter receiving replay state it cannot use — an unknown kind or version, malformed metadata, or a block shape that no longer matches the content — degrades that message to provider-neutral conversion with a diagnostic; a different adapter receives only provider-neutral content plus provider/model fields. This state is model-visible replay input and therefore follows the existing [reconstructable-request rule](2026-07-05-reconstructable-requests.md): it is present in both the terminal `finish` chunk and the assembled `assistant/message` model source that drives derivation. Resume and fork preserve it verbatim. Compaction that shadows the assistant message also removes its replay state from the active surface; the summary is ordinary provider-neutral content. diff --git a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md index 4e620408da..5e73cab5f1 100644 --- a/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-14-provider-routed-llm-adapters.zh.md @@ -40,9 +40,9 @@ pi-ai 的通用流选项不支持停止序列。若 Harness `stop` 选项已定 助手消息携带请求的 `provider` 和 `model`，以及可选的 JSON 可序列化适配器回放状态。成功的 `assistant/message` 会话事件记录这些字段，`deriveMessages()` 返回助手消息时也会包含它们。用户、系统、上下文与工具结果消息不携带助手路由字段。提供方/模型字段是 agent loop 的权威数据；适配器仅拥有其不透明回放状态 payload。 -成功的终止 `finish` 分片可以携带回放状态，`BlockAssembler` 会将其与 token 用量和结束原因一起保留。agent loop 会把该状态附加到已组装助手消息的模型来源中，但不公开响应改写钩子。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。 +成功的终止 `finish` 分片可以以 `ReplayEnvelope` 形式携带回放状态：不透明的响应级元数据，加上与发射块序列对齐的可选逐块条目。`BlockAssembler` 对内容与元数据只做一次保留/丢弃决定——max-token 组装丢弃工具调用时，数据同一位置的条目一并丢弃——因此 agent loop 附加到已组装助手消息模型来源中的状态始终描述存储的块，见 [max-token 回放状态对齐决定](../bug-fix/2026-08-15-max-token-replay-state-alignment.md)。agent loop 不公开响应改写钩子。错误或中止响应不会生成正常助手消息，因此不会进入后续模型历史。 -pi-ai 回放状态是其成功 `AssistantMessage` 的带版本最小投影，包含源 API/提供方/模型、响应 ID/模型、停止原因，以及按索引对齐的文本签名、thinking 签名和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmRuntime` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。适配器收到未知版本或块形状不匹配的回放状态时会显式失败；其他适配器只能收到提供方无关的内容以及提供方/模型字段。 +pi-ai 回放状态用其成功 `AssistantMessage` 的带版本最小投影填充该结构：一个响应半区（源 API/提供方/模型、响应 ID/模型、停止原因），以及逐块的文本签名、thinking 签名和工具调用签名。它不会重复 Harness 内容块中已有的文本或工具参数，也不包含诊断信息、时间戳、用量或错误。后续请求中，只有历史提供方和目标提供方当前归同一个适配器实例所有时，`LlmRuntime` 才会把回放状态交给目标适配器。适配器在能够恢复历史响应时，将 Harness 记录的内容与回放状态组合，并负责所需的跨模型或跨提供方转换。持久化内容保持权威：适配器收到无法使用的回放状态——未知 kind 或版本、格式错误的元数据、或与内容不再匹配的块结构——会把该消息降级为提供方无关转换并带出诊断；其他适配器只能收到提供方无关的内容以及提供方/模型字段。 该状态属于模型可见的回放输入，因此遵循现有的[请求可重建规则](2026-07-05-reconstructable-requests.md)：它同时存在于终止 `finish` 分片和驱动派生的已组装 `assistant/message` 模型来源中。恢复和 fork 会原样保留该状态。压缩（compaction）遮蔽助手消息时，也会从活动 surface 中移除其回放状态；摘要属于普通的提供方无关内容。 diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml index f11d779582..674bd5bd51 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md -2026-07-30-config-plane-boundaries.md: 2dfb527749e8dea54e037abc602af1611c3f9794 -2026-07-30-config-plane-boundaries.zh.md: 8b1ec3206237b7c2deafb743b62e697b3c452ffc +2026-07-30-config-plane-boundaries.md: aab0d7a80c2732b33637ec721a9ab7c1b50fce3f +2026-07-30-config-plane-boundaries.zh.md: fb069e6dd9f276c7cc0069695b388ef37a081ab4 diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md index 2dfb527749..aab0d7a80c 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md +++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.md @@ -6,6 +6,8 @@ English | [中文](2026-07-30-config-plane-boundaries.zh.md) > Scope: boundary hardening of the [web configuration plane](2026-07-30-web-config-plane.md) — which namespaces reach the wire, which callers reach them, and how an editor holding a partial, possibly stale view writes without destroying what it cannot see. +> The caller boundary, the redaction, and the revision fencing remain current. Restricting which namespaces reach the wire to the configurable-provider directory is superseded by the [plugin-owned settings surface](2026-08-12-plugin-owned-settings-surface.md), which serves every registered namespace. + ## Problem The plane worked and was reachable by more callers, and with more authority, than its design claimed. diff --git a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md index 8b1ec32062..fb069e6dd9 100644 --- a/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-30-config-plane-boundaries.zh.md @@ -6,6 +6,8 @@ Status: implemented > 范围：对 [Web 配置面](2026-07-30-web-config-plane.md)的边界加固——哪些 namespace 能抵达协议、哪些调用方能抵达它们，以及一个只持有局部且可能陈旧的视图的编辑器该如何写入，才不会毁掉它看不见的东西。 +> 调用方边界、脱敏与 revision 设栅依然有效。把「哪些 namespace 能抵达协议」限制为可配置提供方目录这一条，已被[由插件自己拥有的设置表层](2026-08-12-plugin-owned-settings-surface.md)取代——后者服务每一个已注册的 namespace。 + ## 问题 这个面能用，但能触达它的调用方、以及它们所拥有的权限，都比设计声称的更多。 diff --git a/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.i18n.yaml new file mode 100644 index 0000000000..d77b2c75c7 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.md +2026-08-12-plugin-owned-settings-surface.md: 3137cfe81ef3cb78a940f085c559ab4a7b62cce3 +2026-08-12-plugin-owned-settings-surface.zh.md: 8dd5e5ccebf1cfb80b55a615f6049dd391943bd7 diff --git a/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.md b/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.md new file mode 100644 index 0000000000..3137cfe81e --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.md @@ -0,0 +1,61 @@ +# Agent Note: Plugin-owned settings surface + +Status: implemented + +English | [中文](2026-08-12-plugin-owned-settings-surface.zh.md) + +## Problem + +A plugin that registered a settings namespace could not reach the browser configuration page, and both gates that stopped it lived in this repository. + +`packages/host/apiproxy` held two hardcoded namespace lists. `settings.describe` filtered its answer through them and every write checked them first, so a namespace outside them answered `settings-not-exposed` even when its owner had registered it. Adding a plugin to the configuration page therefore meant editing a package the plugin author does not own. + +The plugin configuration section rendered an unordered list of whatever cards were registered into `settings.plugin.item`. A card carried an opaque `id`, never the namespace it edited, so the section could not tell which served namespaces already had a home. That left every question about "who renders this namespace" unanswerable from the ledger the section could see. + +Together the two meant a user-authored plugin was configurable only by hand-editing `settings.yaml`. The [web plugin configuration note](../feature/2026-08-10-web-plugin-configuration.md) recorded the allowlist as deliberate, and the [config-plane boundaries note](2026-07-30-config-plane-boundaries.md) tied web-configurability to membership in the configurable-provider directory. Both conclusions blocked exactly the plugin authors the general seam was built for. + +## Decision + +**Registering is exposing.** The api-proxy serves every namespace `ctx.settings.describe()` returns and gates no write. `WEB_SETTINGS_NAMESPACES`, `PRODUCT_SETTINGS_NAMESPACES`, the union with `ctx.llm.listConfigurableProviders()`, and the `settings-not-exposed` error code are gone. A name no registration answers — unknown, or malformed and therefore unable to address one — folds into the seam's own `settings-rejected`, so the proxy contributes no boundary and no vocabulary of its own. + +**The settings seam is untouched.** Which client may read a namespace, and which page renders it, are facts about consumers; a Service Definition that carried either would let one Consumer dictate its contract. `SettingsRegisterOptions` gains nothing. + +**`settings.plugin.item` is keyed on the settings namespace.** The slot moved from `list` to `keyed`, the key being the namespace the card edits, following the `tool.call.toolview` precedent where each tool plugin registers its renderer under the tool name. A card declares `key`, not `id`/`order`. The slot is declared by the Plugins section's `configurable` tab, which owns the card list. + +**The tab drives dispatch from the served namespaces.** It reads `settings.describe` once, subscribes to the settings-document invalidation and to connection resets, and dispatches one key per served namespace. What renders is the intersection of two ledgers — namespaces a live Host plugin registered, and cards registered under those keys — computed in the tab's controller from the slot ledger (`ctx.slots.entries`, `ctx.slots.subscribe`) and the wire answer. + +Keying makes absence the signal, and that is what removes the bookkeeping the previous shape needed. A namespace another surface owns (`ui-theme`, `permission`, `llm-*`, `agent-presets`) has no card under its key, so it renders nothing without declaring anything anywhere. A card whose namespace this deployment does not serve is never dispatched, which also fixes the old empty-state defect: the tab counted registered cards, including ones rendering nothing, so a deployment exposing none showed an empty list instead of its empty line. + +**Nothing renders a form it was not given.** The tab supplies no fallback card. A plugin's browser half owns its card completely — chrome, controls, and copy — which is what the slot's `fallback` option would have replaced with a schema-reverse-rendered form. + +## What the allowlist protected + +The gate did keep one thing off the wire, and this note states it plainly because the decision has to survive the accurate version: a registered namespace the list did not name never had its resolved, `base`, or `user` values reach the browser at all. The plugin inventory page is not a substitute — `PluginInventoryEntry` carries `entryId`, `moduleName`, `enabled`, and `fiberPhase`, and its "configuration" row renders an enabled/disabled tag, never a stored value. + +What the gate was not is the boundary its position suggested. Every `settings.*` method sits in `PRIVILEGED_METHODS` (`packages/client/connection`), so a non-loopback or cross-origin request is refused with 403 before reaching this code; `role('secret')` fields are structurally stripped from every layer of every response; and the document the plane edits is the user's own `settings.yaml`, which the same settings page offers to open. The writes it did not block were also the consequential ones: `permission` (which can widen the approval preset) and `agent-presets` (which decides what a session mounts) were both already served. + +So the exposure this change actually adds, in this repository, is one namespace: `agent-default-model`, whose two fields name a provider and a model and which no browser half renders. A future namespace whose values genuinely must not cross the wire is answered per field by `role('secret')` — finer than a namespace switch, and already enforced. + +## Alternatives considered + +**A declaration on `settings.register()`** (`client: { surface: 'plugin-config' | 'custom', title, description }`), which the removed `WEB_SETTINGS_NAMESPACES` comment named as the intended direction. It keeps registration from crossing the transport by default and lets a plugin author self-serve in one line. Rejected because `surface` is browser-page vocabulary and `title`/`description` are presentation: a Service Definition carrying them is a seam shaped by one Consumer. Its fail-closed property is also worth less than it reads — see what the allowlist protected, above. + +**A separate exposure catalog**, a registry of its own that plugins join beside their settings registration, generalizing `ctx.llm.registerConfigurableProviders()`. Rejected because it makes one fact require two registrations that can drift: registering a namespace and forgetting the catalog entry produces a section nothing can edit, with no gate able to see the mistake. + +**A deny-list `Config` field on the api-proxy**, so a deployment could withhold a namespace. Rejected for having no consumer: every currently registered namespace is one a user may edit, and a genuinely sensitive field is answered per-field by `role('secret')`, which is the finer instrument. A namespace-wide switch invented ahead of its first use is the speculative option the package rules forbid. + +**A schema-driven generic card as the slot's `fallback`**, so a plugin with no browser half still got a form from `schema.toJSON()` (schemastery already carries `description`, `role`, `min`/`max`/`step` and serializes them). Rejected because client plugins load at runtime from mounted Loader entries, so a plugin author can ship a real card, and a reverse-rendered form was already judged worse than a hand-written one for the Models page. The `fallback` option remains available without a contract change if that judgment changes. + +**A client-side claim registry**, where each surface owning a namespace declares it so a generic card knows what is already covered. Rejected with the generic card: keyed dispatch already makes an unclaimed key render nothing, so the registry would restate what the slot ledger says. + +**Keeping the list slot and adding a namespace field to its options.** Rejected because the section would still enumerate entries rather than namespaces, keeping the empty-state defect and leaving a card for an uncomposed plugin to suppress itself. + +## Consequences + +A plugin distributed outside this repository is configurable from the settings page with no change here: it registers its namespace on the Host and its card under that key in the browser, and the section pairs the two. Cards now appear in card registration order rather than by hand-assigned `order`. That is stable for the cards this package registers, which install from one generator, and **not** stable across plugins: apply order between packages is unconstrained (`packages/client/AGENTS.md`), so several external cards can still reorder between boots. Ordering them needs an explicit key the section can sort on, which the keyed registration does not carry today. + +Deferred, and larger than this change: the redactor returns a `role('secret')` reachable only through a union, intersection, or transform verbatim (its own `TODO(settings-wire-redaction)`), and `schema.toJSON()` carries a secret's default. That gap predates this change, but serving every registered namespace widens its blast radius from schemas audited in this repository to any third-party schema, so the wire should refuse a namespace it cannot prove it can redact. Also deferred: an assembled-composition test of the headline capability — an overlay-mounted fixture plugin whose Host half registers a namespace and whose `dsh.client` half registers a card, asserted end-to-end. The current coverage proves each half separately; the shipped cards' unchanged output cannot prove the new path. + +The wire read the section adds is one `settings.describe` beside the per-scope reads the cards already make. Its invalidation is imprecise in one direction: the wire announces document commits and connection resets, not registrations, so a namespace registered after the section's read joins on the next commit or reconnect. + +Two frictions remain for an author outside this repository, both recorded in the section's README. The browser half must be a `dsh.client` package built in the client module system's lazy-CJS factory format, and the `clientBundle` preset that emits it lives in `packages/client/tsdown.client.ts` rather than a published package. The bundle-purity gate forbids importing this package's card chrome or staged-form model as values, so such a card reimplements staging and revision fencing. Sharing them would mean either publishing the preset or declaring a child slot inside the card so the section supplies the chrome; neither is built. diff --git a/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.zh.md b/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.zh.md new file mode 100644 index 0000000000..8dd5e5cceb --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.zh.md @@ -0,0 +1,61 @@ +# Agent Note: 由插件自己拥有的设置表层 + +Status: implemented + +[English](2026-08-12-plugin-owned-settings-surface.md) | 中文 + +## Problem + +注册了 settings 命名空间的插件到不了浏览器配置页，而拦住它的两道门都在本仓库里。 + +`packages/host/apiproxy` 持有两份硬编码的命名空间清单。`settings.describe` 用它们过滤答复，每次写入也先对照它们，因此清单之外的命名空间即便其拥有方已注册，也只会得到 `settings-not-exposed`。于是把一个插件加进配置页，意味着要改一个插件作者并不拥有的包。 + +插件配置分区渲染的是注册进 `settings.plugin.item` 的卡片列表，无序。卡片携带的是不透明的 `id`，从不是它所编辑的命名空间，因此分区无从判断哪些被服务的命名空间已经有了归属。凡是"这个命名空间由谁渲染"的问题，都无法从分区看得见的账本里得到答案。 + +两者相加，用户自己写的插件就只能靠手改 `settings.yaml` 来配置。[web 插件配置 note](../feature/2026-08-10-web-plugin-configuration.md) 把白名单记为刻意为之，[配置面边界 note](2026-07-30-config-plane-boundaries.md) 则把「可在 Web 上配置」绑定到可配置提供方目录的成员资格。这两条结论恰恰挡住了那个通用 seam 本来要服务的插件作者。 + +## Decision + +**注册即暴露。** api-proxy 服务 `ctx.settings.describe()` 返回的每一个命名空间，写入不设门禁。`WEB_SETTINGS_NAMESPACES`、`PRODUCT_SETTINGS_NAMESPACES`、与 `ctx.llm.listConfigurableProviders()` 的并集，以及 `settings-not-exposed` 错误码，全部删除。没有任何注册应答的名字——未知的，或格式非法因而根本无法寻址到注册的——都折叠为 seam 自己的 `settings-rejected`，于是代理既不贡献边界，也不贡献自己的词汇。 + +**settings seam 不动。** 哪个客户端可以读某个命名空间、哪个页面渲染它，都是关于 Consumer 的事实；Service Definition 只要携带其中之一，就等于让一个 Consumer 决定它的契约。`SettingsRegisterOptions` 一个字段都没加。 + +**`settings.plugin.item` 以 settings 命名空间为键。** 该 slot 从 `list` 改为 `keyed`，键就是卡片所编辑的命名空间，沿用 `tool.call.toolview` 的先例——每个工具插件把自己的渲染器注册在工具名这个键上。卡片声明 `key`，不再声明 `id`/`order`。该 slot 由「插件」分区的 `configurable` 标签页声明，卡片列表归它所有。 + +**标签页以被服务的命名空间驱动派发。** 它读取一次 `settings.describe`，订阅 settings 文档失效通知与连接重置，并为每个被服务的命名空间派发一个键。渲染出来的是两份账本的交集——存活 Host 插件注册的命名空间，以及注册在这些键上的卡片——由标签页的 controller 从 slot 账本（`ctx.slots.entries`、`ctx.slots.subscribe`）与协议答复算出。 + +以命名空间为键，让「缺席」本身成为信号，而这正是它消掉旧形态所需簿记的原因。归别的界面所有的命名空间（`ui-theme`、`permission`、`llm-*`、`agent-presets`）在其键上没有卡片，于是什么都不渲染，且无需在任何地方声明任何东西。命名空间未被本部署服务的卡片根本不会被派发，这同时修掉了旧的空态缺陷：标签页数的是已注册卡片，其中包含那些什么都不渲染的，因此一个都不暴露的部署看到的是空列表，而不是它那行空态文案。 + +**不渲染任何未被交给它的表单。** 标签页不提供兜底卡片。插件的浏览器半侧完整拥有自己的卡片——外观、控件与文案——而这正是 slot 的 `fallback` 选项会用一份 schema 反向渲染的表单取代掉的东西。 + +## 白名单实际护住了什么 + +这道门确实挡住了一样东西，本 note 如实写出，因为这个决策必须在准确版本下也站得住：不在名单上的已注册命名空间，其 resolved、`base` 与 `user` 值根本不会抵达浏览器。插件清单页不能替代它——`PluginInventoryEntry` 携带的是 `entryId`、`moduleName`、`enabled` 与 `fiberPhase`，它那一行「configuration」渲染的是启用／停用标签，从不是任何已存值。 + +这道门不是的，是它所处位置暗示的那种边界。每个 `settings.*` 方法都在 `PRIVILEGED_METHODS` 里（`packages/client/connection`），非回环或跨源请求在到达这段代码之前就以 403 被拒；`role('secret')` 字段在每种响应的每一层都被结构性剥离；而这个面所编辑的文档，本就是用户自己的 `settings.yaml`，同一个设置页还提供了打开它的入口。它没有挡住的写入，恰恰是有分量的那些：`permission`（能放宽审批预设）与 `agent-presets`（决定一个会话挂载什么）本来就已被服务。 + +因此本次改动在本仓库实际新增的暴露面是一个命名空间：`agent-default-model`——它的两个字段指明一个提供方与一个模型，且没有任何浏览器半侧渲染它。将来若某个命名空间的值确实不该跨越协议，由 `role('secret')` 逐字段作答：比整命名空间开关更精细，而且已经在执行。 + +## Alternatives considered + +**在 `settings.register()` 上加声明**（`client: { surface: 'plugin-config' | 'custom', title, description }`），这也是被删掉的 `WEB_SETTINGS_NAMESPACES` 注释所点名的既定方向。它让注册默认不跨越传输边界，并让插件作者一行代码自助。否决的原因是 `surface` 是浏览器页面的词汇，而 `title`/`description` 属于呈现：Service Definition 一旦携带它们，就成了被单个 Consumer 塑形的 seam。它那条 fail-closed 性质的价值也不如读起来那么高——见上文「白名单实际护住了什么」。 + +**另设一份暴露目录**，插件在注册 settings 之外再加入这份自有注册表，即把 `ctx.llm.registerConfigurableProviders()` 一般化。否决的原因是它把一件事实拆成两处可能脱节的注册：注册了命名空间却忘了目录条目，产出的是一个谁都编辑不了的分节，而没有任何门禁看得见这个错误。 + +**给 api-proxy 加一个 deny-list `Config` 字段**，让部署方能扣下某个命名空间。因为没有消费者而否决：当前每一个已注册的命名空间都是用户可以编辑的，而真正敏感的字段由 `role('secret')` 逐字段作答，那是更精细的工具。在第一个用例出现之前就发明出来的整命名空间开关，正是包规则所禁止的投机选项。 + +**把 schema 驱动的通用卡片作为该 slot 的 `fallback`**，让没有浏览器半侧的插件也能从 `schema.toJSON()` 得到一份表单（schemastery 本就携带 `description`、`role`、`min`/`max`/`step` 并将其序列化）。否决的原因是客户端插件按已挂载的 Loader entries 在运行时加载，插件作者完全可以交付一张真正的卡片；而反向渲染的表单在模型页那次已被判定不如手写。若这个判断日后改变，`fallback` 选项无需改动契约即可启用。 + +**客户端认领注册表**，让每个拥有某命名空间的界面声明它，好让通用卡片知道哪些已经有人管。与通用卡片一并否决：keyed 派发本就让无人认领的键什么都不渲染，这份注册表只会把 slot 账本已经说过的话再说一遍。 + +**保留 list slot，只给它的 options 加一个命名空间字段。** 否决的原因是分区枚举的仍是 entry 而非命名空间，空态缺陷照旧，未组装插件的卡片也仍需自我抑制。 + +## Consequences + +在本仓库之外分发的插件无需改动这里即可从设置页配置：它在 Host 上注册自己的命名空间、在浏览器里把卡片注册在该键上，由分区把两者配对。卡片现在按卡片注册顺序出现，而不再依赖手工指定的 `order`。对本包注册的这几张卡它是稳定的——它们从同一个 generator 安装；对**跨插件**的卡片它并不稳定：包与包之间的 apply 顺序是无约束的（`packages/client/AGENTS.md`），因此多个外部卡片仍可能在不同次启动之间重排。要为它们定序，需要一个 section 可排序的显式键，而 keyed 注册今天并不携带。 + +以下延后，且都大于本次改动：脱敏器对只能经由 union、intersection 或 transform 抵达的 `role('secret')` 原样返回（其自身的 `TODO(settings-wire-redaction)`），而 `schema.toJSON()` 会携带 secret 的默认值。该缺口早于本次改动，但服务每一个已注册命名空间，把它的影响面从本仓库内经审计的 schema 扩大到任意第三方 schema，因此协议应当拒绝服务它无法证明可安全脱敏的命名空间。同样延后的还有：对本次头号能力的组装态测试——用 overlay 挂载一个 fixture 插件（Host 半注册命名空间、`dsh.client` 半注册卡片）并在端到端断言。当前覆盖分别证明了两个半侧；已发卡片输出未变这一点，证明不了新路径。 + +分区新增的协议读取是一次 `settings.describe`，与卡片各自已有的 per-scope 读取并列。它的失效通知在一个方向上不精确：协议通告的是文档提交与连接重置，而非注册行为，因此在分区读取之后才被注册的命名空间，要等下一次提交或重连才会加入。 + +对仓库之外的作者仍留有两处摩擦，均记在该分区的 README 里。浏览器半侧必须是按客户端模块系统的 lazy-CJS factory 格式构建的 `dsh.client` 包，而产出它的 `clientBundle` 预设位于 `packages/client/tsdown.client.ts`，并非已发布的包。bundle 纯净度门禁禁止以值的形式导入本包的卡片外观与暂存表单模型，因此这样的卡片要重新实现暂存与 revision 设栅。要共享它们，要么发布该预设，要么在卡片内部声明一层子 slot 让分区提供外观；两者都尚未构建。 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml index 92dcd28a7e..4c5e88d55e 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md -2026-07-31-composer-text-layers-share-one-scrollport.md: 6097779529f86e6d994296ae396f108c63f01abc -2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 753d67d538d0c17512444639d60b7b5c8ff80e9a +2026-07-31-composer-text-layers-share-one-scrollport.md: d01231f706a7d3850ce1b3770ef351cb7e211384 +2026-07-31-composer-text-layers-share-one-scrollport.zh.md: 3ce8cc05dc57b05bb8c0bd903a0b64b12d4a6963 diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md index 6097779529..d01231f706 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.md @@ -24,6 +24,8 @@ One scrolling box, holding both layers. The browser then applies one offset to both layers, in the same frame, on the same compositor. The caret is bound to its glyphs by construction rather than by upkeep: there is no code to run, no event to wait for, and no state that can be one frame stale. The wheel-chaining handler stays, retargeted from the textarea to the scrollport, and remains the only listener on the box. +Safari's native text control has one engine exception: deleting across a soft-wrap threshold can retain the former line layout after the mirror shrinks. The [Safari soft-wrap recovery](2026-08-13-safari-textarea-soft-wrap-reflow.md) restores the zero-overflow invariant before paint without changing the one-scrollport design. + Two things the previous mechanism needed are gone with it: **The backdrop's trailing-line sentinel.** It existed to keep the two boxes' scroll extents equal — a textarea reserves a line box for the caret after a final newline while `white-space: pre-wrap` collapses a text node's trailing newline, so a draft ending in a newline made the backdrop one line shorter and clamped the mirrored offset a line above the caret. With one scrollport the backdrop's own extent decides nothing: the mirror div sizes the stack for both layers, both start at the same top, and a layer whose content ends earlier simply paints nothing on the last line. The shape is worth keeping in mind rather than the mechanism: it is the one that measured 628 against 652 when the two boxes had to agree on a height. diff --git a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md index 753d67d538..3ce8cc05dc 100644 --- a/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-07-31-composer-text-layers-share-one-scrollport.zh.md @@ -24,6 +24,8 @@ composer 的文本由两层叠放绘制（见 [InputBar](../../../../packages/cl 于是浏览器在同一帧、同一个合成器上，把同一个偏移施加给两层。光标与字形的绑定来自结构本身，而不是来自持续维护：没有代码要跑，没有事件要等，也没有任何状态可能落后一帧。滚轮接力处理器保留，只是从 textarea 改挂到滚动容器上，并且仍是这个盒子上唯一的监听。 +Safari 的原生文本控件存在一个引擎例外：跨过软换行阈值的删除可能在镜像层收缩后仍保留原先的行布局。[Safari 软换行恢复](2026-08-13-safari-textarea-soft-wrap-reflow.md)会在绘制前恢复零溢出不变量，而不改变单滚动容器设计。 + 上一版机制所需要的两样东西随它一起消失： **backdrop 的尾行哨兵。** 它的存在只是为了让两个盒子的滚动范围相等——textarea 会在末尾换行之后为光标保留一个行盒，而 `white-space: pre-wrap` 会折叠文本节点的尾随换行，因此以换行结尾的草稿会让 backdrop 少一行，把镜像偏移钳制在光标上方一行。改为单一滚动容器后，backdrop 自身的范围不再决定任何事：镜像层为两层统一定高，两层顶端对齐，内容更早结束的那一层只是在最后一行什么都不画。值得记住的是这类草稿形状而不是那套机制：正是它在「两个盒子必须就高度达成一致」的时代量出了 628 对 652。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.i18n.yaml new file mode 100644 index 0000000000..96fb51ced0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.md +2026-08-04-large-history-pagination-call-stack.md: 28c22121123a227c507c506683ae727d238d98bd +2026-08-04-large-history-pagination-call-stack.zh.md: 57dde9bdc0a4aa52e1af024eb606bf9258430fa7 diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.md b/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.md new file mode 100644 index 0000000000..28c2212112 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.md @@ -0,0 +1,27 @@ +# Agent Note: Large history provenance is scanned without argument expansion + +Status: implemented + +English | [中文](2026-08-04-large-history-pagination-call-stack.zh.md) + +## Problem + +A finalized assistant message can reference hundreds of thousands of streamed chunks through `sourceEventSeqs`. History pagination found the message group's first event with `Math.min(event.seq, ...sourceEventSeqs)`, so a valid session could exceed the JavaScript engine's function-argument limit and make `session.history` fail with HTTP 500. + +## Decision + +Pagination scans `sourceEventSeqs` and updates the earliest sequence number one element at a time. The algorithm remains linear in the provenance size and preserves the existing page boundary: a page starts before all recorded sources of its oldest included message. + +A regression test rejects multi-argument minimum calls and verifies that every provenance event remains on the page with its finalized message. This exercises the failure mechanism without making the default test suite allocate a production-sized chunk stream. + +## Alternatives considered + +- **Raise the JavaScript stack or argument limit** — rejected: the limit is engine- and deployment-dependent, and array expansion still makes valid history depend on an unrelated runtime ceiling. +- **Truncate `sourceEventSeqs` during pagination** — rejected: this could cut a page inside a message and violate replay grouping. +- **Cap streamed chunk count at the provider boundary** — rejected: providers may legitimately emit long streams, and pagination must handle every valid session representation. + +## Consequences + +- Large provenance arrays no longer make history pagination throw solely because of their length. +- Pagination semantics and wire responses are unchanged. +- This does not bound the byte size of a history page or the browser cost of replaying it; those performance concerns remain separate from the server-side call-stack failure. diff --git a/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.zh.md b/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.zh.md new file mode 100644 index 0000000000..57dde9bdc0 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-04-large-history-pagination-call-stack.zh.md @@ -0,0 +1,27 @@ +# Agent Note: 大规模历史记录的溯源信息通过扫描处理，不做参数展开 + +Status: implemented + +[English](2026-08-04-large-history-pagination-call-stack.md) | 中文 + +## 问题 + +一条已定稿的 assistant 消息可以通过 `sourceEventSeqs` 引用数十万个流式分片。历史记录分页使用 `Math.min(event.seq, ...sourceEventSeqs)` 查找消息组的首个事件，因此，有效会话可能超出 JavaScript 引擎的函数参数数量上限，导致 `session.history` 以 HTTP 500 失败。 + +## 决策 + +分页逻辑逐项扫描 `sourceEventSeqs`，每次使用一个元素更新最早的序号。该算法的复杂度相对溯源信息规模仍为线性，并保留现有的页面边界：页面起点位于其所含最早消息的所有已记录来源之前。 + +回归测试会拒绝以多个参数调用取最小值的做法，并验证每个溯源事件都会与其已定稿消息保留在同一页中。这既覆盖了故障机制，也避免默认测试套件分配生产规模的分片流。 + +## 考虑过的替代方案 + +- **提高 JavaScript 栈或参数上限**：不予采纳，因为该上限取决于引擎和部署环境，而且数组展开仍会让有效历史记录受制于无关的运行时上限。 +- **在分页时截断 `sourceEventSeqs`**：不予采纳，因为这可能会从消息中间切分页面，破坏回放分组。 +- **在提供方边界限制流式分片数量**：不予采纳，因为提供方可能会合理地产生长流，而分页必须处理每一种有效的会话表示。 + +## 后果 + +- 大型溯源数组不再仅因长度而使历史记录分页抛出异常。 +- 分页语义与协议响应保持不变。 +- 本决策不限制历史记录页面的字节大小，也不限制浏览器回放该页面的开销；这两项性能问题仍与服务端调用栈故障分开处理。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.i18n.yaml new file mode 100644 index 0000000000..1c650cc79c --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.md +2026-08-12-fix-pwsh-terminal-overlay-dup.md: 7a214ea093faf49141c66bfc2cbb065fbeb29825 +2026-08-12-fix-pwsh-terminal-overlay-dup.zh.md: 6d38ca58ad97e5ad04992e54a7938c9fea300863 diff --git a/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.md b/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.md new file mode 100644 index 0000000000..7a214ea093 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.md @@ -0,0 +1,55 @@ +# Agent Note: fix the pwsh terminal overlay duplicate-loader collision + +Status: implemented + +English | [中文](2026-08-12-fix-pwsh-terminal-overlay-dup.zh.md) + +## Problem + +`apps/web/tests/pwsh-terminal.e2e.ts` fails on every platform with `TypeError: duplicate loader entry id: tool-pwsh`, thrown from `vendor/loader/src/config/group.ts:64` while applying the web composition. The failing seed lane boots the full shipped bundle plus a test overlay, so the E2E never reaches its rendering assertion and every `check:ci:snapshot`/`test:web` run reports a red web test even though the feature under test is unrelated to the change under review. + +The web E2E scaffold applies an `extraOverlayPath` after the shipped Web surface and base patches. `pwsh-terminal.overlay.yml` used an `insert` block to add a `tool-pwsh` row: + +```yaml +- insert: + - id: pwsh-local + name: '@deepseek-ai/dsh-pwsh-local' + - id: tool-pwsh + name: '@deepseek-ai/dsh-tool-pwsh' +``` + +`insert` is correct only while `tool-pwsh` is absent from the composition. The id exists because `86b6979bdc` (refactor(bundle): fold the Windows shell platform layer into the base rows) moved both shell stacks into the base bundle with inverted platform gates — `packages/bundle/base/cordis.patch.yml` declares `tool-pwsh` with `disabled: !!js process.platform !== 'win32'`, so the row is present in the composition on every platform. Later, `42fc7c5ffb` (refactor(preset): gate tool-pwsh by platform alongside tool-bash) added a web-app patch row that disables `tool-pwsh` for surfaces that use presets; a patch row cannot introduce an id, so it is not the source of the collision. The overlay's `insert` delivers a second row with the same id in the same loader group, and the loader rejects the pair at boot. + +## Decision + +Replace the overlay's `insert` of `tool-pwsh` with a top-level id-targeted override: + +```yaml +- id: tool-pwsh + name: '@deepseek-ai/dsh-tool-pwsh' + disabled: false +``` + +The effective `tool-pwsh` state is a three-layer stack: the base row gates `disabled` on `process.platform !== 'win32'`, the web-app overlay sets `disabled: true` unconditionally for preset surfaces, and this lane's override clears it back to `disabled: false` regardless of platform. An `id`-targeted top-level override replaces the composed row; only an `insert` would collide. + +The lane also now disables `pwsh-sandbox` by id, symmetric with the existing `bash-sandbox` disable: the base gates `pwsh-sandbox` with `disabled: !!js process.platform !== 'win32'`, so on Windows it would otherwise mount beside the inserted `pwsh-local` and both would register the same executor service. Disabling it keeps `pwsh-local` the lone executor on every platform. + +The overlay header comment was updated to describe the full selection and the `tool-pwsh` inline comment now names the base row as the source of the id. + +## Alternatives considered + +**Keep the `insert` and change the web composition instead.** Rejected, because the shipped web composition should keep the host `tool-pwsh` row disabled for every surface that uses presets; the overlay is the lane that deliberately needs it, so the by-id enable belongs there. The base row itself cannot be removed either: it is the platform-gated shell-stack declaration shared by every bundle. + +**Enable `tool-pwsh` in the `insert` block.** Not possible: an `insert` of an id that already exists is the very duplicate being fixed. The row must be targeted by id, which is the top-level override form, not `insert`. + +**Patch `tool-pwsh` by id without setting `disabled: false`.** Insufficient: the web-app overlay sets `disabled: true` unconditionally, and the base row's platform gate only applies where the web-app override is absent, so an override that only restates `name` leaves the row disabled and the lane renders no terminal card. The `disabled: false` is required. + +**Only disable `bash-sandbox` and rely on the platform gate to keep `pwsh-sandbox` off.** Rejected: that holds on POSIX but breaks on Windows, where the base row leaves `pwsh-sandbox` enabled and it would collide with the inserted `pwsh-local` on the shared executor service. The lane's `pwsh-sandbox` disable keeps one executor on every platform. + +## Verification + +Reverting the fix (restoring the `insert` of `tool-pwsh`) reproduces the exact `duplicate loader entry id: tool-pwsh` boot failure, confirming the override is load-bearing. With the fix in place `pwsh-terminal.e2e.ts` passes 2/2 on the same head — this exercises the POSIX seam, where the seeded pwsh call renders through the enabled `tool-pwsh` and the inserted `pwsh-local`. The seed lane requires a usable `pwsh`, so it skips on hosts without one; a `pwsh` binary is present on this machine and the test ran. The Windows path (base `pwsh-sandbox` mounted beside the inserted `pwsh-local`) is not exercised by any CI lane, whose `test:web` runs only on Linux; the overlay disables `pwsh-sandbox` to keep that path composable if it ever runs on a Windows dev machine. + +## Consequences + +The web E2E seed lane that exercises PowerShell boot now composes instead of colliding, so `check:ci:snapshot` and `test:web` stop failing on the duplicate independently of the change under test. The pattern is general: a `--patch`/`extraOverlayPath` overlay must probe whether a row already exists in the bundle it augments before choosing `insert` over an id-targeted override; `insert` of an id that the base or shipped Web surface already declares is a boot-time duplicate. diff --git a/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.zh.md b/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.zh.md new file mode 100644 index 0000000000..6d38ca58ad --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-12-fix-pwsh-terminal-overlay-dup.zh.md @@ -0,0 +1,55 @@ +# Agent Note：修复 pwsh 终端 overlay 的重复 loader 冲突 + +Status: implemented + +[English](2026-08-12-fix-pwsh-terminal-overlay-dup.md) | 中文 + +## Problem + +`apps/web/tests/pwsh-terminal.e2e.ts` 在所有平台上都以 `TypeError: duplicate loader entry id: tool-pwsh` 失败，由 `vendor/loader/src/config/group.ts:64` 在应用 web 组合时抛出。该失败的 seed 通道会启动完整发布的 bundle 加一个测试 overlay，因此 E2E 永远到不了渲染断言，导致 `check:ci:snapshot` 与 `test:web` 每次运行都报一个红的 web 测试，即便被测功能与评审中的改动无关。 + +web E2E scaffold 在已发布的 Web 表面与 base patches 之后应用 `extraOverlayPath`。`pwsh-terminal.overlay.yml` 用 `insert` 块新增 `tool-pwsh` 行： + +```yaml +- insert: + - id: pwsh-local + name: '@deepseek-ai/dsh-pwsh-local' + - id: tool-pwsh + name: '@deepseek-ai/dsh-tool-pwsh' +``` + +`insert` 仅在组合中不存在 `tool-pwsh` 时才正确。该 id 存在是因为 `86b6979bdc`（refactor(bundle): fold the Windows shell platform layer into the base rows）把两套 shell 栈以互逆的平台门移进了 base bundle —— `packages/bundle/base/cordis.patch.yml` 声明 `tool-pwsh` 且 `disabled: !!js process.platform !== 'win32'`，于是该行在每个平台都存在于组合中。随后 `42fc7c5ffb`（refactor(preset): gate tool-pwsh by platform alongside tool-bash）往 web-app patch 里加了一行对使用 preset 的表面禁用 `tool-pwsh` 的行；patch 不能引入 id，因此它不是冲突来源。overlay 的 `insert` 于是在同一个 loader 组里再送一个同 id 的行，loader 在启动时拒绝这对重复。 + +## Decision + +把 overlay 对 `tool-pwsh` 的 `insert` 替换成顶层按 id override： + +```yaml +- id: tool-pwsh + name: '@deepseek-ai/dsh-tool-pwsh' + disabled: false +``` + +有效的 `tool-pwsh` 状态是三层栈：base 行把 `disabled` 门在 `process.platform !== 'win32'` 上，web-app overlay 对 preset 表面无条件设 `disabled: true`，本通道的 override 无论平台都把 `disabled: false` 还回去。`id` 定位的顶层 override 替换组合后的行；只有 `insert` 才会相撞。 + +该通道现在也按 id 禁用 `pwsh-sandbox`，与既有的 `bash-sandbox` 禁用对称：base 以 `disabled: !!js process.platform !== 'win32'` 门住 `pwsh-sandbox`，因此在 Windows 上它本会与插入的 `pwsh-local` 并存，两者会注册同一个 executor 服务。禁用它让 `pwsh-local` 在每个平台上都是唯一 executor。 + +overlay 头部注释已更新为完整描述选择，`tool-pwsh` 行内注释现在把 base 行标为该 id 的来源。 + +## Alternatives considered + +**保留 `insert`、改 web 组合。** 拒绝。已发布的 web 组合应在所有使用 preset 的表面上保持 host `tool-pwsh` 行禁用；overlay 才是那条刻意需要该行的通道，因此按 id 启用应放在那里。base 行本身也不能移除：它是所有 bundle 共享的平台门 shell 栈声明。 + +**在 `insert` 块里启用 `tool-pwsh`。** 不可行。对已存在的 id 做 `insert` 正是这里要修的重复。该行必须按 id 定位，即顶层 override 形式，而非 `insert`。 + +**只按 id 改 `tool-pwsh` 而不设 `disabled: false`。** 不充分。web-app 无条件设 `disabled: true`，base 行的平台门只在 web-app override 缺失处生效，因此只重申 `name` 的 override 会让行保持禁用，通道渲染不出终端卡。`disabled: false` 是必需的。 + +**只禁用 `bash-sandbox`、依赖平台门让 `pwsh-sandbox` 保持关闭。** 拒绝。在 POSIX 上成立，但在 Windows 上会失败：base 行让 `pwsh-sandbox` 启用，它会与插入的 `pwsh-local` 在共享 executor 服务上相撞。本通道禁用 `pwsh-sandbox` 让每个平台只有唯一 executor。 + +## Verification + +把修复还原（恢复对 `tool-pwsh` 的 `insert`）即复现同样的 `duplicate loader entry id: tool-pwsh` 启动失败，证实 override 是有效的。修复后同一 head 上 `pwsh-terminal.e2e.ts` 2/2 通过 —— 这作用于 POSIX seam，播种的 pwsh 调用经启用的 `tool-pwsh` 与插入的 `pwsh-local` 渲染出来。该 seed 通道需要可用的 `pwsh`，无此二进制的主机会跳过；本机有 `pwsh`，测试实际跑过。Windows 路径（base `pwsh-sandbox` 与插入的 `pwsh-local` 并存）没有任何 CI lane 覆盖，其 `test:web` 只在 Linux 上跑；overlay 禁用 `pwsh-sandbox` 让该路径在真到 Windows 开发机运行时可组合。 + +## Consequences + +用于执行 PowerShell 启动的 web E2E seed 通道现在能组合而非相撞，因此 `check:ci:snapshot` 与 `test:web` 不再与被测改动无关地在该 duplicate 上失败。该模式具有通用性：`--patch`/`extraOverlayPath` overlay 在决定用 `insert` 还是按 id override 之前，必须探测目标 bundle 是否已存在该行；对已由 base 或已发布 Web 表面声明的 id 做 `insert`，是启动期重复。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.i18n.yaml new file mode 100644 index 0000000000..f7fde5254a --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md +2026-08-13-safari-textarea-soft-wrap-reflow.md: fb264a8e6fbe24369584f2427bbb0c462b450ecf +2026-08-13-safari-textarea-soft-wrap-reflow.zh.md: 7f55a5260e825059e1f9a08db03f13e19484d14e diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md b/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md new file mode 100644 index 0000000000..fb264a8e6f --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md @@ -0,0 +1,47 @@ +# Agent Note: Safari textarea soft-wrap shrink recovery + +Status: implemented + +English | [中文](2026-08-13-safari-textarea-soft-wrap-reflow.zh.md) + +## Problem + +The composer keeps the caret and selection in a transparent native textarea while the backdrop paints visible glyphs and the hidden mirror determines the full draft height. The [single-scrollport decision](2026-07-31-composer-text-layers-share-one-scrollport.md) therefore depends on the textarea owning no scrollable overflow: after every draft commit, its `scrollHeight` and `clientHeight` are equal and its `scrollTop` is zero. + +Safari 26.5.2 can retain the textarea's former native line layout when Backspace moves a draft across a soft-wrap threshold at the same time that React updates the mirror. In the reproduced two-line-to-one-line transition, the mirror, backdrop, grow stack, and textarea box all become 28px high, but the textarea still reports `scrollHeight=52` and `scrollTop=20`. The caret remains in the stale native line while the backdrop correctly paints one line. + +The `color` declaration is not a layout input. Changing its inline style changes the computed color but leaves the stale `52/28/20` state intact. Editing the stylesheet rule happens to trigger broader rule invalidation and clears the state to `28/28/0`, which explains why Web Inspector makes the declaration appear causal. + +## Decision + +`InputBar` detects Safari once from the Apple vendor and the `Version/... Safari/...` user-agent form, while rejecting known alternate iOS browser tokens such as `CriOS`, `FxiOS`, `EdgiOS`, and `OPiOS`. A browser shell indistinguishable through these identity fields still has to violate the textarea overflow invariant before the recovery mutates layout. + +The native textarea change handler records whether an edit shortens the controlled draft. After that draft commits, a layout effect returns without reading geometry unless both the cached Safari identity and the native-shrink signal are present. It then checks the single-scrollport invariant: equal `scrollHeight` and `clientHeight` are settled and trigger no forced layout. A mismatch first changes the textarea's real height by one pixel, forces layout, restores the owned height, and forces layout again. This rebuilds Safari's native text-control layout without changing the value, selection, IME state, or undo transaction. + +The temporary native overflow can leave the draft scrollport's auto height at the former line count even after the textarea is correct. The recovery therefore repeats the one-pixel invalidation on `[data-input-scroll]` after repairing the textarea. Both elements return to their owned styles before paint; the settled one-line state is `scrollHeight=clientHeight=28`, `scrollTop=0`, and a 28px scrollport. + +## Verification + +Component tests synthesize Safari's stale metrics, assert the textarea-then-scrollport invalidation order, preserve selection, and prove that a growing native draft reads no geometry. Browser-identity tests cover desktop and mobile Safari, desktop Chromium, Chrome, Edge, and Opera on iOS, and an Apple web view. + +The assembled package is also exercised in Safari 26.5.2 through the native 51-character-to-50-character Backspace path. Playwright WebKit 26.5 settles correctly without the workaround in both the assembled app and a reduced page, so the repository's Chromium browser lane cannot reproduce this Safari application defect; the focused component test pins the engine state until an automatable Safari lane exists. + +## Alternatives considered + +**Change `color` or use `-webkit-text-fill-color`.** Rejected because inline color changes and transparent text fill leave the stale native geometry unchanged. Stylesheet-rule editing works only because its invalidation scope is broader than the declaration's paint semantics. + +**Set `scrollTop=0`.** Rejected because it moves the stale native content without rebuilding its two-line `scrollHeight`; the caret can become clipped instead of aligned. + +**Rewrite the textarea value.** Clearing and restoring the value rebuilds Safari's text control, but it mutates the editing state that owns IME composition and selection. The height invalidation leaves the value untouched. + +**Use `field-sizing: content`.** Rejected because Safari reproduces the stale two-line intrinsic height after the same deletion, and the composer still needs the mirror as the caret ruler and backdrop metric peer. + +**Invalidate only the textarea or only the scrollport.** Rejected because the textarea-only recovery clears `52/28/20` but can leave the scrollport at 52px, while the scrollport-only recovery leaves the textarea's native overflow untouched. The ordered pair is the smallest complete recovery. + +**Check geometry after every Safari draft commit.** Rejected because reading `scrollHeight` or `clientHeight` after React changes the mirror can synchronously lay out even a healthy growing draft. A native shortening signal limits the invariant read to edits that can produce the observed shrink defect. + +**Run the recovery in every browser.** Rejected because Chromium, Playwright WebKit, and Firefox maintain the invariant without forced layouts. The Safari identity and observed mismatch jointly bound the synchronous work. + +## Consequences + +Non-Safari browsers, programmatic draft updates, and native edits that do not shorten the draft perform no geometry read. A native Safari shortening reads the overflow invariant and pays the four forced layouts only when the textarea violates it. The exceptional path accepts rare local work before paint to preserve caret alignment, native editing semantics, and the single scrolling box. An equivalent stale state caused only by resize or sidebar width changes has not been observed and is outside this recovery trigger. The browser test gap remains explicit: real Safari evidence owns the engine defect, while deterministic component coverage owns the recovery and its browser gate. diff --git a/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.zh.md b/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.zh.md new file mode 100644 index 0000000000..7f55a5260e --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.zh.md @@ -0,0 +1,47 @@ +# Agent Note: Safari textarea 软换行收缩恢复 + +Status: implemented + +[English](2026-08-13-safari-textarea-soft-wrap-reflow.md) | 中文 + +## 问题 + +composer 把光标与选区留在透明的原生 textarea 中，由 backdrop 绘制可见字形，并由隐藏的镜像层决定完整草稿高度。因此，[单滚动容器决策](2026-07-31-composer-text-layers-share-one-scrollport.md)依赖 textarea 不持有可滚动溢出：每次草稿提交后，它的 `scrollHeight` 与 `clientHeight` 相等，`scrollTop` 为零。 + +当 Backspace 让草稿跨过软换行阈值，同时 React 更新镜像层时，Safari 26.5.2 可能保留 textarea 原先的原生行布局。在复现出的两行变一行转换中，镜像层、backdrop、自增高栈和 textarea 盒都变为 28px 高，但 textarea 仍报告 `scrollHeight=52` 与 `scrollTop=20`。光标留在陈旧的原生行中，而 backdrop 已正确绘制为一行。 + +`color` 声明不是布局输入。修改 inline style 会改变计算后的颜色，却让陈旧的 `52/28/20` 状态保持不变。编辑样式表规则会碰巧触发范围更广的规则失效，并把状态清为 `28/28/0`，这正是 Web Inspector 让该声明显得像成因的原因。 + +## 决策 + +`InputBar` 通过 Apple vendor 与 `Version/... Safari/...` 形式的 user agent 一次性识别 Safari，同时排除 `CriOS`、`FxiOS`、`EdgiOS`、`OPiOS` 等已知的 iOS 其他浏览器 token。仅凭这些 identity 字段无法区分的浏览器壳仍必须先违反 textarea 溢出不变量，恢复逻辑才会修改布局。 + +原生 textarea change handler 会记录本次编辑是否缩短受控草稿。草稿提交后，除非同时存在已缓存的 Safari identity 与原生缩短信号，否则 layout effect 会在读取几何前直接返回。随后它才检查单滚动容器不变量：`scrollHeight` 与 `clientHeight` 相等即为稳定态，不会触发强制布局。出现差异时，逻辑先把 textarea 的实际高度改变一个像素，强制布局，再恢复其自有高度并再次强制布局。这样无需改变值、选区、输入法组合状态或撤销事务，即可重建 Safari 的原生文本控件布局。 + +即使 textarea 已正确恢复，临时的原生溢出仍可能让草稿滚动容器的 auto 高度停在原行数。因此，恢复逻辑会在修复 textarea 后，对 `[data-input-scroll]` 重复一次单像素失效。两个元素都会在绘制前恢复各自拥有的样式；稳定的一行状态为 `scrollHeight=clientHeight=28`、`scrollTop=0`，滚动容器高度为 28px。 + +## 验证 + +组件测试会合成 Safari 的陈旧度量，断言先 textarea 后滚动容器的失效顺序，保留选区，并证明原生草稿增长不会读取几何。浏览器 identity 测试覆盖桌面与移动 Safari、桌面 Chromium、iOS Chrome／Edge／Opera 和 Apple web view。 + +组装后的包还会在 Safari 26.5.2 中通过原生的 51 字符到 50 字符 Backspace 路径验证。Playwright WebKit 26.5 在组装应用与最小化页面中都无需本绕法即可正确稳定，因此仓库的 Chromium 浏览器泳道无法复现这个 Safari 应用缺陷；在可自动化的 Safari 泳道出现之前，由聚焦组件测试固定该引擎状态。 + +## 备选方案 + +**修改 `color` 或使用 `-webkit-text-fill-color`。** 被否决，因为 inline color 修改与透明 text fill 都不会改变陈旧的原生几何。编辑样式表规则之所以有效，只是因为其失效范围比该声明的绘制语义更广。 + +**设置 `scrollTop=0`。** 被否决，因为这只会移动陈旧的原生内容，不会重建其两行 `scrollHeight`；光标可能从错位变为被裁剪。 + +**重写 textarea 的值。** 清空再恢复值能够重建 Safari 文本控件，但会改动拥有输入法组合与选区的编辑状态。高度失效不会触碰值。 + +**使用 `field-sizing: content`。** 被否决，因为相同删除后 Safari 的两行固有高度仍会陈旧，并且 composer 仍需要镜像层充当光标标尺与 backdrop 的度量对端。 + +**只让 textarea 或滚动容器失效。** 被否决，因为只恢复 textarea 虽能清除 `52/28/20`，却可能把滚动容器留在 52px；只恢复滚动容器则不会改变 textarea 的原生溢出。这个有序二元操作是最小的完整恢复。 + +**每次 Safari 草稿提交后都检查几何。** 被否决，因为 React 改变镜像层后读取 `scrollHeight` 或 `clientHeight`，即使草稿健康增长也可能同步执行布局。原生缩短信号把不变量读取限制在可能产生已观测收缩缺陷的编辑中。 + +**在所有浏览器中运行恢复逻辑。** 被否决，因为 Chromium、Playwright WebKit 与 Firefox 无需强制布局即可维持该不变量。Safari identity 与已观测到的差异共同限定同步工作范围。 + +## 影响 + +非 Safari 浏览器、程序化草稿更新，以及不会缩短草稿的原生编辑都不会读取几何。Safari 的原生缩短会读取溢出不变量，并且仅在 textarea 违反不变量时承担四次强制布局。例外路径以绘制前的罕见局部工作换取光标对齐、原生编辑语义与单一滚动盒。尚未观测到仅由 resize 或侧栏宽度变化引发的同类陈旧状态，本恢复触发器也不覆盖它。浏览器测试缺口保持显式：真实 Safari 证据负责引擎缺陷，确定性的组件覆盖负责恢复逻辑与浏览器门控。 diff --git a/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.i18n.yaml new file mode 100644 index 0000000000..af691f1175 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.md +2026-08-15-max-token-replay-state-alignment.md: 256a64403a08377cf35ba645175698678eaa7f8b +2026-08-15-max-token-replay-state-alignment.zh.md: a24f3e194dca100d2ea0faf659b1868c605c26c1 diff --git a/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.md b/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.md new file mode 100644 index 0000000000..256a64403a --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.md @@ -0,0 +1,33 @@ +# Agent Note: Replay state aligns with assembled content by construction + +Status: implemented + +English | [中文](2026-08-15-max-token-replay-state-alignment.zh.md) + +## Problem + +pi-ai recorded one opaque replay blob per response, projected from the provider's native message, while `BlockAssembler.blocks()` separately dropped tool calls from a `max-tokens` response because a truncated call is unsafe to execute. The durable assistant message therefore stored transformed content next to metadata describing the untransformed native block list. The next request failed during history reconstruction with `INVALID_REPLAY_STATE: block count does not match assistant content`, and because the mismatch was already on disk, every later request on that session failed the same way — the session was permanently stuck. The root cause is structural: two representations of one response were snapshotted at different pipeline points, with their index alignment enforced only by a read-time hard error. + +## Decision + +Two changes, one per side of the durable boundary. + +**Write side — one keep/drop decision.** The finish chunk's `replayState` becomes a typed `ReplayEnvelope`: an opaque `response` half plus optional opaque per-block entries aligned with the emitted block sequence. `BlockAssembler` computes its keep/drop decision once and applies it to blocks and envelope entries together, so any transformation assembly performs — today's max-token tool-call drop or a future one — prunes the matching metadata by construction. Retained blocks keep their entries, so a truncated response keeps signatures for the reasoning and text it kept. An envelope whose entries do not match the emitted block count is discarded whole (a misemitting adapter must not publish misattributed metadata). pi-ai splits its former flat state into a version-2 response half and per-block signature entries. + +**Read side — durable content is authoritative.** `toPiAssistant` treats replay state as fidelity metadata, not as a load-bearing input: any state the reading build cannot use — another adapter's kind, another version (including the flat version-1 form already on disk), malformed metadata, or a block shape that no longer matches the content — degrades that one message to the existing foreign provider-neutral conversion and reports the `INVALID_REPLAY_STATE` diagnostic through the plugin's `onReplayDegrade` hook (a logger warning). The request proceeds. This is what lets sessions poisoned before this change continue instead of erroring forever, and it bounds every future divergence source to a fidelity loss on one message. + +## Verification + +Assembler unit tests prove pruning, misalignment discard, and pass-through for untransformed and per-block-free envelopes. pi-ai unit tests prove the version-2 envelope round-trip and that every formerly-throwing invalid-state case now degrades to foreign conversion with the diagnostic. An agent-loop regression drives a truncated text-plus-tool-call response through persistence and shows the follow-up request carrying the pruned envelope. Keyless real-composition tests boot `dsh-llm-pi-ai` through the Loader and prove a native continuation without `tool_calls` after truncation, and a successful continuation over a legacy flat-state message whose block count no longer matches. The authored keyless snapshot scenario `max-tokens-continue` pins the assembled application's durable log — truncated turn, pruned envelope on the stored message, continued turn — through the real ACP subprocess path. + +## Alternatives considered + +**Suppress the whole replay state when assembly drops a tool call.** Works for today's one transformation, but re-derives the drop condition beside `blocks()` (the two drift silently), discards valid signatures for the retained blocks, and leaves read-time divergence — legacy sessions on disk foremost — a hard error. + +**Keep the state and relax pi-ai's block-count validation to attach what fits.** Rejected: index-aligned signatures attached to a different block list would present false native history to the provider. Degrading attaches nothing. + +**Teach each adapter to rewrite its state after assembly.** Rejected as an adapter obligation with an opaque blob; the envelope moves exactly the needed structure — and nothing else — into shared vocabulary, and the assembler's single decision does the rewrite mechanically. + +## Consequences + +Continuing after a max-token response that included a tool call works, retains the kept blocks' native signatures, and replays as a native pi-ai message. Sessions recorded before this change replay their affected assistant messages as provider-neutral content (with a diagnostic) instead of failing the turn; on-disk `replayState` values changed shape under the pre-release no-compatibility stance, with the old flat form handled by the same degrade path. This supersedes the read-time hard-error rule in the [provider-routed adapter decision](../architecture/2026-07-14-provider-routed-llm-adapters.md) for unusable state; validation itself is unchanged and still precedes any native reconstruction. diff --git a/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.zh.md b/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.zh.md new file mode 100644 index 0000000000..a24f3e194d --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-15-max-token-replay-state-alignment.zh.md @@ -0,0 +1,33 @@ +# Agent Note: 回放状态与组装内容按构造对齐 + +Status: implemented + +[English](2026-08-15-max-token-replay-state-alignment.md) | 中文 + +## 问题 + +pi-ai 为每个响应记录一个从提供方原生消息投影而来的不透明回放数据，而 `BlockAssembler.blocks()` 会另行从 `max-tokens` 响应中丢弃工具调用，因为被截断的调用不能安全执行。持久化的 assistant 消息因此把变换后的内容与描述未变换原生块清单的元数据存在一起。下一个请求在历史重建阶段以 `INVALID_REPLAY_STATE: block count does not match assistant content` 失败；由于不一致已经落盘，该会话之后的每个请求都以同样方式失败——会话被永久卡死。根因是结构性的：同一响应的两种表示在流水线的不同位置各自拍摄快照，其索引对齐只靠读取时的硬错误来维持。 + +## 决定 + +两处改动，各覆盖持久化边界的一侧。 + +**写侧——一次保留/丢弃决定。** finish 分片的 `replayState` 变为有类型的 `ReplayEnvelope`：一个不透明的 `response` 半区，加上与发射块序列对齐的可选不透明逐块条目。`BlockAssembler` 只计算一次保留/丢弃决定，并把它同时应用于块和逐块条目，因此组装执行的任何变换——今天的 max-token 工具调用丢弃或未来的其他变换——都按构造裁剪掉对应元数据。保留的块保留其条目，所以被截断的响应仍为其保留的推理（reasoning）与文本保有签名。条目数与发射块数不一致的数据整体丢弃（发射不当的适配器不得发布归属错误的元数据）。pi-ai 把原先的平铺状态拆为版本 2 的 response 半区和逐块签名条目。 + +**读侧——持久化内容是权威记录。** `toPiAssistant` 把回放状态当作保真度元数据，而非承重输入：读取方无法使用的任何状态——其他适配器的 kind、其他版本（包括已落盘的平铺版本 1 形式）、格式错误的元数据、或与内容不再匹配的块结构——都把这一条消息降级为既有的外来提供方无关转换，并通过插件的 `onReplayDegrade` 钩子（logger 警告）上报 `INVALID_REPLAY_STATE` 诊断。请求继续执行。正是这一点让本次改动之前已被毒化的会话得以继续而不是永远报错，也把未来一切分叉源约束为单条消息的保真度损失。 + +## 验证 + +组装器单元测试证明裁剪、错位丢弃、以及未变换与无逐块条目数据的透传。pi-ai 单元测试证明版本 2 数据的往返，以及先前每个抛错的无效状态用例现在都降级为外来转换并带出诊断。agent loop 回归用例驱动一个被截断的文本加工具调用响应穿过持久化，并证明后续请求携带裁剪后的数据。无密钥真实组合测试通过 loader 启动 `dsh-llm-pi-ai`，证明截断后不带 `tool_calls` 的原生续聊，以及在块数不再匹配的旧平铺状态消息之上成功续聊。手工编写的无密钥快照场景 `max-tokens-continue` 通过真实 ACP 子进程路径钉住组装应用的持久化日志——截断轮次、存储消息上裁剪后的数据、以及继续的轮次。 + +## 已考虑的替代方案 + +**组装丢弃工具调用时抑制整个回放状态。** 对今天唯一的变换有效，但在 `blocks()` 旁边重新推导丢弃条件（两处会无声漂移），丢掉保留块的有效签名，并让读取时的分叉——首当其冲是已落盘的旧会话——仍然是硬错误。 + +**保留状态并放宽 pi-ai 的块数校验、能贴多少贴多少。** 否决：索引对齐的签名贴到不同的块清单上，会向提供方呈现虚假的原生历史。降级则什么都不贴。 + +**让每个适配器在组装后改写自己的状态。** 否决：这把义务压给持有不透明数据的适配器；信封只把恰好需要的结构——不多一分——纳入共享词汇，组装器的单一决定即可机械完成改写。 + +## 影响 + +包含工具调用的 max-token 响应之后的续聊可以工作，保留块保有原生签名，并作为原生 pi-ai 消息回放。本次改动之前记录的会话，其受影响的 assistant 消息作为提供方无关内容回放（带诊断）而不是让轮次失败；`replayState` 落盘形状在预发布无兼容承诺立场下发生变化，旧平铺形式由同一降级路径处理。对不可用状态而言，这取代了[提供方路由适配器决定](../architecture/2026-07-14-provider-routed-llm-adapters.md)中读取时硬错误的规则；校验本身不变，仍先于任何原生重建执行。 diff --git a/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.i18n.yaml b/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.i18n.yaml index 8a9e7a0bda..6b4b469aba 100644 --- a/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.md -2026-08-10-web-plugin-configuration.md: bdb5a3cbddabb516a0921abc00f1be97be4d17d7 -2026-08-10-web-plugin-configuration.zh.md: ed8ced71ed50063f9b1702ff2a6601271712f910 +2026-08-10-web-plugin-configuration.md: 218d5ed4536c489f89cb53c62c457a988e451b7e +2026-08-10-web-plugin-configuration.zh.md: 999e785699741084e1e230c4a240a0605491cb04 diff --git a/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.md b/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.md index bdb5a3cbdd..218d5ed453 100644 --- a/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.md +++ b/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.md @@ -4,6 +4,8 @@ Status: implemented English | [中文](2026-08-10-web-plugin-configuration.zh.md) +> The three sections, the layering, and the staged-save form remain current. The Host allowlist and the unkeyed card list are superseded by the [plugin-owned settings surface](../architecture/2026-08-12-plugin-owned-settings-surface.md): every registered namespace is served, and cards are keyed on the namespace they edit. + ## Problem Everything a plugin can be configured with lived in `cordis.yml`. A user who wanted a longer shell timeout, a different search endpoint, or fewer parallel tool calls had to find the composition file, know its shape, and restart — while the Models page had shown for months that a settings namespace can be edited from the browser and take effect immediately. diff --git a/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.zh.md b/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.zh.md index ed8ced71ed..999e785699 100644 --- a/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.zh.md +++ b/.agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.zh.md @@ -4,6 +4,8 @@ Status: implemented [English](2026-08-10-web-plugin-configuration.md) | 中文 +> 三个分节、分层解析与暂存保存表单依然有效。Host 白名单与无键卡片列表已被[由插件自己拥有的设置表层](../architecture/2026-08-12-plugin-owned-settings-surface.md)取代：每一个已注册的命名空间都被服务，卡片以它所编辑的命名空间为键。 + ## 问题 插件的一切可配置项都只存在于 `cordis.yml`。想要更长的 shell 超时、不同的搜索端点或更少的并行工具调用，用户必须找到组装文件、了解它的形状，然后重启——而 Models 页几个月来一直在证明：settings 命名空间可以在浏览器里编辑并立即生效。 diff --git a/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.i18n.yaml b/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.i18n.yaml new file mode 100644 index 0000000000..e403530fec --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.md +2026-08-11-collapsible-ask-user-question-card.md: 5c7e62749e63a6042285b79751c400ba09038b49 +2026-08-11-collapsible-ask-user-question-card.zh.md: 5f4b5851e4b595e634841bf87827db70fe928afb diff --git a/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.md b/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.md new file mode 100644 index 0000000000..5c7e62749e --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.md @@ -0,0 +1,32 @@ +# Agent Note: Collapsible Ask-User Question Card + +Status: implemented + +English | [中文](2026-08-11-collapsible-ask-user-question-card.zh.md) + +## Problem + +`dsh`'s ask-user takeover renders the pending question set as a bottom card capped at `min(60vh, 520px)`, so a long batch or a user who wants to re-read the conversation above before deciding has no way to reduce the card — the conversation above becomes hard to read because only a few lines peek out at the top. + +## Decision + +Add a minimize/maximize toggle to the question card header, next to the existing dismiss action. Collapsing hides the option body and the footer actions, leaving a header strip (eyebrow, title, both icon buttons) so the user still sees that a question is pending; expanding restores the full card. + +- State lives in `QuestionFlow` local state (`minimized`), so drafts and the current question index survive collapse/expand — nothing is re-derived or reset, and the answers already picked remain submit-ready. +- The toggle is a plain `IconChevronDownOutline14` / `IconChevronUpOutline14` pair on the existing 24px icon-button grid; `aria-expanded` reflects the card state and the label flips between `nav.minimize` / `nav.maximize` (the collapsed button reads "expand" for screen readers). +- While minimized the option body and footer are unmounted (`{!minimized && ...}`), so no hidden interactive surface remains in the a11y tree. +- The collapse button is disabled while a submit/cancel is in flight (`busy !== null`), matching the dismiss button's existing guard. +- CSS: `.cardMinimized` drops the `max-height` cap and hides `.body` / `.footer`; `.header` gains bottom padding so the strip is not cramped. +- Scope: only the generic question flow (`QuestionFlow`) gets the toggle. The plan-review card (`PlanReviewPanel`) is a different shape (one decision over one plan) and keeps its current layout. + +## Consequences + +- Users can shrink the question card to read the conversation, then expand to answer — drafts and position are preserved because the state lives in the flow component, not in the DOM. +- The minimize action is visually adjacent to dismiss; both share the icon button style, so the header stays balanced. +- Product copy additions are confined to the `question` locale namespace (`nav.minimize` / `nav.maximize`), paired zh/en per the dictionary contract. + +## Alternatives considered + +- **Auto-collapse on scroll**: collapsing the card when the user scrolls the conversation would reclaim space without a button, but it fights the user mid-interaction and hides the pending-question signal unexpectedly; an explicit toggle keeps the decision with the user. +- **Resizable card**: a drag handle would let users size the card freely, but it is more machinery than the ask needs and does not address "I want the card out of the way entirely". +- **Persisting the collapsed state per session**: nice-to-have, but the ask is per-interaction; persisting adds storage and sync complexity without a clear win for this surface. diff --git a/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.zh.md b/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.zh.md new file mode 100644 index 0000000000..5f4b5851e4 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-11-collapsible-ask-user-question-card.zh.md @@ -0,0 +1,32 @@ +# Agent Note: 可收起的提问卡片 + +Status: implemented + +[English](2026-08-11-collapsible-ask-user-question-card.md) | 中文 + +## Problem + +`dsh` 的 ask-user 接管界面把待回答的问题组渲染为底部卡片，高度上限为 `min(60vh, 520px)`；当问题批次较长、或用户想先阅读上方的会话记录再决定时，卡片会占满大部分视口且无法缩小——上方会话几乎被遮住，只能看到顶部几行。 + +## Decision + +在提问卡片头部（现有的"放弃整组问题"按钮旁）增加收起/展开切换按钮。收起时隐藏选项主体和底部操作区，只保留一条头部（eyebrow、标题、两个图标按钮），用户仍能看到"有未答问题"的信号；展开后恢复完整卡片。 + +- 状态存放在 `QuestionFlow` 的本地 state（`minimized`），因此收起/展开不会丢失草稿和当前题目索引——已选答案仍可直接提交。 +- 切换按钮使用 `IconChevronDownOutline14` / `IconChevronUpOutline14`，复用现有 24px 图标按钮网格；`aria-expanded` 反映卡片状态，文案在 `nav.minimize` / `nav.maximize` 之间切换（收起后按钮对读屏器显示为"展开"）。 +- 收起时选项主体和底部通过 `{!minimized && ...}` 卸载，a11y 树中不残留隐藏的可交互面。 +- 提交/取消进行中（`busy !== null`）时收起按钮禁用，与现有放弃按钮的守卫一致。 +- CSS：`.cardMinimized` 去掉 `max-height` 上限并隐藏 `.body` / `.footer`；`.header` 增加底部 padding，避免折叠后过于局促。 +- 范围：只有通用提问流（`QuestionFlow`）获得该切换。计划评审卡片（`PlanReviewPanel`）是另一种形态（对一个计划做一次决策），保持现有布局。 + +## Consequences + +- 用户可以缩小提问卡片以阅读会话，再展开作答——草稿和位置因状态存放在流程组件中而得以保留。 +- 收起动作紧邻放弃按钮，二者共用图标按钮样式，头部保持平衡。 +- 新增产品文案仅落在 `question` locale 命名空间（`nav.minimize` / `nav.maximize`），按字典契约中英成对。 + +## Alternatives considered + +- **滚动时自动收起**：用户滚动会话时自动折叠卡片可以省空间，但会在交互中途与用户对抗，并意外隐藏"待答问题"信号；显式切换把决定权交给用户。 +- **可拖拽调整大小**：拖拽手柄让用户自由调整卡片大小，但比需求所需的机制更复杂，也没有解决"让卡片完全让开"的诉求。 +- **按会话持久化折叠状态**：锦上添花，但提问是单次交互；持久化引入存储与同步复杂度，对这个界面没有明确收益。 diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml index 17b2425233..85fa4810cd 100644 --- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md -2026-08-08-native-windows-pull-request-ci.md: 39dadfa9ba883bd9178091cf67a32dc44cf405f5 -2026-08-08-native-windows-pull-request-ci.zh.md: 14f21c3e97761a351621062a61636e5e9f33151f +2026-08-08-native-windows-pull-request-ci.md: 31a1a1893b0c6248a30ac6e12b409282f608a689 +2026-08-08-native-windows-pull-request-ci.zh.md: ba2520c2514580e5af367df86dd3195485a0a34c diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md index 39dadfa9ba..31a1a1893b 100644 --- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md +++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md @@ -14,7 +14,7 @@ A coverage audit found that stale branch state had restored temporary exclusions The required `windows` job in [ci.yml](../../../../.github/workflows/ci.yml) remains `windows node 24 / wine blocking` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries; when nodejs.org stalls on the large archive, a range-capable transport mirror resumes the same bytes, but nodejs.org remains the version and SHA-256 authority and the archive is never promoted before that checksum passes. The stable `windows` job id remains a dependency of `all checks passed`. The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology. -Every pull request also starts an ordinary independent `windows-native` job named `windows node 24 / native complete` on the organization-owned `dsh-windows-2025-16core` runner. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. A 60-minute timeout bounds a stuck gate without treating the measured performance target as a correctness deadline. +Every pull request also starts an ordinary independent `windows-native` job named `windows node 24 / native complete` on the organization-owned `dsh-windows-2025-16core` runner. It enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs `pnpm run check:ci:windows-complete` under native PowerShell. A 120-minute timeout bounds a stuck gate without treating the measured performance target as a correctness deadline. The native job is deliberately absent from `all-checks-passed.needs` and does not use `continue-on-error`: the aggregate neither waits for it nor changes conclusion because of it, while the job retains its own unmasked result. Workspace build, production-site, and 100%-per-file coverage failures make the native job fail. The broader static, documentation, package, and built-artifact portability inventory remains observational. Linux remains the owner of duplicate lint and snapshot enforcement, while native Windows independently enforces supported-source coverage. diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md index 14f21c3e97..ba2520c251 100644 --- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md +++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md @@ -14,7 +14,7 @@ Status: implemented [ci.yml](../../../../.github/workflows/ci.yml) 中必需的 `windows` 作业仍是在 `ubuntu-latest` 上运行的 `windows node 24 / wine blocking`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试；nodejs.org 的大文件传输停滞时，由支持范围请求的传输镜像续传相同字节，但版本和 SHA-256 权威仍属于 nodejs.org，归档通过该校验前绝不会投入使用。稳定的 `windows` 作业 ID 仍是 `all checks passed` 的依赖项。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。 -每个拉取请求还会在组织自有的 `dsh-windows-2025-16core` 运行器上启动一个常规且独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。门禁卡住时，60 分钟超时会为其设定上限，同时不把实测性能目标当作正确性截止时间。 +每个拉取请求还会在组织自有的 `dsh-windows-2025-16core` 运行器上启动一个常规且独立的 `windows-native` 作业，名称为 `windows node 24 / native complete`。该作业为工作区符号链接启用开发人员模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行 `pnpm run check:ci:windows-complete`。门禁卡住时，120 分钟超时会为其设定上限，同时不把实测性能目标当作正确性截止时间。 原生作业被刻意排除在 `all-checks-passed.needs` 之外，且不使用 `continue-on-error`：聚合流程既不等待它，也不会因它改变结论；该作业则保留自身未被掩盖的结果。工作区构建、生产网站和逐文件 100% 覆盖率检查失败会使原生作业失败。更广泛的静态检查、文档、包和构建产物可移植性清单仍作为观测项报告。重复的 lint 与快照强制检查仍由 Linux 负责，原生 Windows 则独立强制执行受支持源码覆盖率。 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7e9f6c3a21..1b3253389a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -452,7 +452,7 @@ jobs: && fromJSON('["self-hosted", "dsh-win-ci", "windows"]') || 'dsh-windows-2025-16core' }} name: windows node 24 / native complete - timeout-minutes: 60 + timeout-minutes: 120 env: DSH_COVERAGE_MAX_WORKERS: '2' # Instrumented process and polling fixtures can exceed Vitest's defaults @@ -662,7 +662,7 @@ jobs: if: github.event_name == 'push' && github.ref == 'refs/heads/master' name: serial / windows (self-hosted standby) runs-on: [self-hosted, dsh-win-ci, windows] - timeout-minutes: 60 + timeout-minutes: 120 steps: - uses: actions/checkout@v6 diff --git a/apps/web/tests/cordis-tool-round.e2e.ts b/apps/web/tests/cordis-tool-round.e2e.ts index a702a7f1ea..7d1d6ab3b5 100644 --- a/apps/web/tests/cordis-tool-round.e2e.ts +++ b/apps/web/tests/cordis-tool-round.e2e.ts @@ -47,8 +47,7 @@ function assertCompleteCordisLifecycle(events: readonly SessionEvent[]): void { (event): event is Extract => event.type === 'turn/end', ) const reason = turnEnd?.data.reason - const reasonSummary = { kind: reason?.kind } - expect(reasonSummary).toEqual({ kind: 'completed' }) + expect(reason).toEqual({ kind: 'completed' }) const calls = events.filter( (event): event is Extract => event.type === 'tool/call', diff --git a/apps/web/tests/pwsh-terminal.overlay.yml b/apps/web/tests/pwsh-terminal.overlay.yml index 43afe77e51..23b917c080 100644 --- a/apps/web/tests/pwsh-terminal.overlay.yml +++ b/apps/web/tests/pwsh-terminal.overlay.yml @@ -1,20 +1,30 @@ # The pwsh terminal-card lane swaps the shipped bash stack for the PowerShell -# twin: the bash executor row is disabled (patches cannot rename a row — `name` -# is a guard) and the pwsh executor + tool are inserted. The permission service -# refuses an unconfined executor by design (presets bundle a sandbox mode), so -# its row is disabled too — this lane renders a seeded session, never a -# permission decision. The seeded scenario renders the logged pwsh call/result -# through the real tools on replay; no command executes, but the composition -# must boot the pwsh executor, so the lane skips on hosts without a usable -# `pwsh`. +# twin: the bash executor row is disabled, the pwsh executor is inserted, and +# the host tool-pwsh row is enabled by id. The pwsh-sandbox row is disabled +# too so the inserted pwsh-local is the lone executor on every platform. The +# permission service refuses an unconfined executor by design (presets bundle +# a sandbox mode), so its row is disabled as well — this lane renders a seeded +# session, never a permission decision. The seeded scenario renders the logged +# pwsh call/result through the real tools on replay; no command executes, but +# the composition must boot the pwsh executor, so the lane skips on hosts +# without a usable `pwsh`. - id: bash-sandbox name: '@deepseek-ai/dsh-bash-sandbox' disabled: true +- id: pwsh-sandbox + name: '@deepseek-ai/dsh-pwsh-sandbox' + disabled: true - id: permission name: '@deepseek-ai/dsh-permission-presets' disabled: true - insert: - id: pwsh-local name: '@deepseek-ai/dsh-pwsh-local' - - id: tool-pwsh - name: '@deepseek-ai/dsh-tool-pwsh' + +# tool-pwsh already exists in the shipped composition: the base bundle declares +# it platform-gated on every platform, and the web-app overlay disables it for +# surfaces that use presets. So this lane enables it by id rather than +# inserting a second row to the same id. +- id: tool-pwsh + name: '@deepseek-ai/dsh-tool-pwsh' + disabled: false diff --git a/apps/web/tests/snapshots/question-composer/composed.expected.md b/apps/web/tests/snapshots/question-composer/composed.expected.md index c18e6225c6..66f3706af5 100644 --- a/apps/web/tests/snapshots/question-composer/composed.expected.md +++ b/apps/web/tests/snapshots/question-composer/composed.expected.md @@ -1,6 +1,8 @@ - region "Which color do you prefer?": - text: Pick one - heading "Which color do you prefer?" [level=2] + - button "Collapse the question card" [expanded]: + - img - button "Dismiss all questions": - img - group: diff --git a/apps/web/tests/snapshots/question-composer/ui.expected.md b/apps/web/tests/snapshots/question-composer/ui.expected.md index c2ee767319..1c7109702d 100644 --- a/apps/web/tests/snapshots/question-composer/ui.expected.md +++ b/apps/web/tests/snapshots/question-composer/ui.expected.md @@ -1,6 +1,8 @@ - region "Which color do you prefer?": - text: Pick one - heading "Which color do you prefer?" [level=2] + - button "Collapse the question card" [expanded]: + - img - button "Dismiss all questions": - img - group: diff --git a/apps/web/tests/snapshots/steering/mid-steer.expected.md b/apps/web/tests/snapshots/steering/mid-steer.expected.md index e3b82f0964..9a713be0e5 100644 --- a/apps/web/tests/snapshots/steering/mid-steer.expected.md +++ b/apps/web/tests/snapshots/steering/mid-steer.expected.md @@ -32,6 +32,8 @@ - region "Ready to continue?": - text: Checkpoint - heading "Ready to continue?" [level=2] + - button "Collapse the question card" [expanded]: + - img - button "Dismiss all questions": - img - radiogroup: diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index d1556bb542..ab7a7558b8 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/architecture.md -architecture.md: 77000ce9d4608d440e1d903eb80a42f2ed6435ef -architecture.zh.md: f2f5310f665b86b86587307e7ce31c5841b96317 +architecture.md: a1507fa5e54f6703e89f09a5d387e6c9afc81ade +architecture.zh.md: 4642a1e7691bccf4d52d9a84c92c8237c3c6658b diff --git a/docs/architecture.md b/docs/architecture.md index 77000ce9d4..a1507fa5e5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -126,4 +126,4 @@ New behavior attaches to a documented extension point. Changing the loop itself | Fork a live session | `ctx.sessions.fork(source, boundary?, childSessionId?)` | | Scope a registration to one agent | use that agent's `agent.ctx` | -The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities and indexes the step-by-step guides for [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), and [Chat nodes](cookbook/adding-a-conversation-node.md). +The [extension cookbook](cookbook/extension-cookbook.md) maps features to capabilities and indexes the step-by-step guides for [packages](cookbook/adding-a-package.md), [tools](cookbook/adding-a-tool.md), [LLM adapters](cookbook/adding-an-llm-adapter.md), [Chat nodes](cookbook/adding-a-conversation-node.md), and [settings cards](cookbook/adding-a-settings-card.md). diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index f2f5310f66..4642a1e769 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -130,4 +130,4 @@ seam 正是替换一个提供方就能改变整个产品的原因。文件系统 | fork 活跃会话 | `ctx.sessions.fork(source, boundary?, childSessionId?)` | | 将注册项限定到单个 agent | 使用该 agent 的 `agent.ctx` | -[扩展实操手册](cookbook/extension-cookbook.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.md)和 [Chat 节点](cookbook/adding-a-conversation-node.md)的分步指南。 +[扩展实操手册](cookbook/extension-cookbook.md)将功能映射到能力，并索引[包](cookbook/adding-a-package.md)、[工具](cookbook/adding-a-tool.md)、[LLM（大语言模型）适配器](cookbook/adding-an-llm-adapter.md)、[Chat 节点](cookbook/adding-a-conversation-node.md)和[设置卡片](cookbook/adding-a-settings-card.md)的分步指南。 diff --git a/docs/cookbook/adding-a-settings-card.i18n.yaml b/docs/cookbook/adding-a-settings-card.i18n.yaml new file mode 100644 index 0000000000..acaa9a598b --- /dev/null +++ b/docs/cookbook/adding-a-settings-card.i18n.yaml @@ -0,0 +1,6 @@ +# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each +# side as of the last confirmed-consistent state. Both languages carry equal authority; +# after editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write docs/cookbook/adding-a-settings-card.md +adding-a-settings-card.md: 56ec3be578bbc489bbb979a50bcaed063a35ace5 +adding-a-settings-card.zh.md: 4643303bfd76ba77676b7e508424f46082627b62 diff --git a/docs/cookbook/adding-a-settings-card.md b/docs/cookbook/adding-a-settings-card.md new file mode 100644 index 0000000000..56ec3be578 --- /dev/null +++ b/docs/cookbook/adding-a-settings-card.md @@ -0,0 +1,100 @@ +# Cookbook: adding a settings card + +English | [中文](adding-a-settings-card.zh.md) + +How a plugin puts its own configuration on the web settings page. Nothing in this path needs a change inside this repository: the Host serves every registered settings namespace, and the **Plugins** section keys its cards on the namespace they edit, so a plugin that registers both halves is paired up automatically. + +The two halves live in one package — the Host half under `src/`, the browser half under `src/client/`, exported as `./client` and declared with `dsh.client`. [`packages/client/ui-theme`](../../packages/client/ui-theme) is a worked example of that packaging; the cards this section ships live in [`packages/client/ui-settings-plugins`](../../packages/client/ui-settings-plugins). + +## 1. Register the namespace (Host half) + +The namespace is the join key, so pick it once and spell it in both halves. A consumer that already has a `cordis.yml` entry should register through `installSettingsSection`, which layers the entry under the user document and keeps working when no settings provider is mounted: + +```ts +import type { Context } from '@deepseek-ai/cordis' +import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings' +import z from '@deepseek-ai/schemastery' + +declare function assertReachable(endpoint: string | undefined): void +declare function rebuildFromSettings(config: Config): void + +export const MY_PLUGIN_NS = settingsNamespace('my-plugin') + +export interface Config { + endpoint?: string + retries?: number +} + +export const Config: z = z.object({ + endpoint: z.string(), + retries: z.number().step(1).min(0).default(3), +}) + +export function apply(ctx: Context, config: Config) { + let source = () => config + installSettingsSection(ctx, MY_PLUGIN_NS, Config, config, { + // Constraints the schema cannot express refuse the write, not the next use. + validate: value => void assertReachable(value.endpoint), + setSource: (current) => { source = current }, + onChange: () => { rebuildFromSettings(source()) }, + }) +} +``` + +`role('secret')` on a field keeps its value off every response; the card writes such a field into an `update`/`mutate` payload, or addresses a credential reference through the `credentials` domain instead. `applies: 'restart'` tells a configuration surface the owner acts on a change only at the next start. + +## 2. Register the card (browser half) + +The card registers into `settings.plugin.item` under its namespace and owns everything inside it — chrome, controls, and copy. It reads and writes through `ctx.settingsScope`, which fences each write with the revision it read: + +```ts ignore-check +import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client' +// Type-only: the keyed slot's declaration. Cross-plugin collaboration goes +// through cordis services; a value import fails the client bundle-purity gate. +import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client' + +export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope'] + +export function apply(ctx: ClientContext): void { + const card = new MyPluginCardController(ctx.settingsScope.bind({ namespace: 'my-plugin' })) + ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({ + name: 'settings.plugin.item', + key: 'my-plugin', + locale: 'settings.myPlugin', + inject: () => card.inject(), + }, MyPluginCard), + ) +} +``` + +The scope snapshot carries what a form needs: the resolved `value`, the composition `base`, and the raw `user` layer, whose key **presence** — not its value — is what marks a field overridden. `scope.set(field, value)` stores one field and `scope.unset(field)` clears it back to the composition layer. + +## 3. What the tab does with it + +The **Plugin configuration** tab reads which namespaces the Host serves and dispatches one slot key per namespace. A card is rendered when the Host serves its key and skipped when it does not, so a deployment that never composed the Host half shows no trace of the card. A served namespace no card claims renders nothing — that is how the namespaces owned by other pages (`ui-theme`, `permission`, `llm-*`) stay off this tab. + +Cards appear in the order they registered into the slot; a keyed entry declares no `order` of its own. + +## Packaging + +The browser half is served to the page by the [client module system](../../packages/client/modules), which scans the enabled Loader entries for packages declaring `dsh.client` and serves each one's built `./client` export. So the plugin appears on the page as soon as a `cordis.yml` mounts it — no rebuild of the web application. + +```jsonc +{ + "exports": { + ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" }, + "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" } + }, + "dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings-plugins"] } } +} +``` + +The bundle must be the loader's lazy-CJS factory artifact. Inside this repository `tsdown.config.ts` is three lines over the shared preset: + +```ts ignore-check +import { clientBundle } from '../tsdown.client.ts' + +export default clientBundle('@deepseek-ai/dsh-client-my-plugin', ['lib/types/index.js', 'lib/types/invariant.js']) +``` + +That preset is not published today, so a package outside this repository has to reproduce the same output format itself. The bundle-purity gate also rejects value imports across plugins, so a card cannot import this section's card chrome or its staged-form model — it renders its own, and owns its own staging and revision fencing. Both limits are recorded under [the section's known limitations](../../packages/client/ui-settings-plugins/README.md#known-limitations-and-deferred-work). diff --git a/docs/cookbook/adding-a-settings-card.zh.md b/docs/cookbook/adding-a-settings-card.zh.md new file mode 100644 index 0000000000..4643303bfd --- /dev/null +++ b/docs/cookbook/adding-a-settings-card.zh.md @@ -0,0 +1,100 @@ +# Cookbook: 新增设置卡片 + +[English](adding-a-settings-card.md) | 中文 + +插件如何把自己的配置放上 Web 设置页。这条路径上没有任何一步需要改动本仓库：Host 服务每一个已注册的 settings 命名空间，而**插件配置**分区以卡片所编辑的命名空间为键，因此同时注册了两个半侧的插件会被自动配对。 + +两个半侧住在同一个包里——Host 半侧在 `src/`，浏览器半侧在 `src/client/`，以 `./client` 导出并用 `dsh.client` 声明。[`packages/client/ui-theme`](../../packages/client/ui-theme) 是这种打包方式的现成例子；本分区自带的卡片在 [`packages/client/ui-settings-plugins`](../../packages/client/ui-settings-plugins)。 + +## 1. 注册命名空间（Host 半侧） + +命名空间就是配对用的键，所以只挑一次，并在两个半侧都写出它。已经有 `cordis.yml` entry 的消费方应通过 `installSettingsSection` 注册——它把 entry 层叠在用户文档之下，并在没有挂载 settings provider 时照常工作： + +```ts +import type { Context } from '@deepseek-ai/cordis' +import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings' +import z from '@deepseek-ai/schemastery' + +declare function assertReachable(endpoint: string | undefined): void +declare function rebuildFromSettings(config: Config): void + +export const MY_PLUGIN_NS = settingsNamespace('my-plugin') + +export interface Config { + endpoint?: string + retries?: number +} + +export const Config: z = z.object({ + endpoint: z.string(), + retries: z.number().step(1).min(0).default(3), +}) + +export function apply(ctx: Context, config: Config) { + let source = () => config + installSettingsSection(ctx, MY_PLUGIN_NS, Config, config, { + // Constraints the schema cannot express refuse the write, not the next use. + validate: value => void assertReachable(value.endpoint), + setSource: (current) => { source = current }, + onChange: () => { rebuildFromSettings(source()) }, + }) +} +``` + +字段上的 `role('secret')` 让它的值不出现在任何响应里；卡片把这类字段写进 `update`/`mutate` 载荷，或改为经 `credentials` 领域寻址一个凭据引用。`applies: 'restart'` 告诉配置表层：拥有方要到下次启动才会对变更生效。 + +## 2. 注册卡片（浏览器半侧） + +卡片以自己的命名空间为键注册进 `settings.plugin.item`，并拥有其中的一切——外观、控件与文案。它通过 `ctx.settingsScope` 读写，后者用读取时的 revision 为每次写入设栅： + +```ts ignore-check +import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client' +// Type-only: the keyed slot's declaration. Cross-plugin collaboration goes +// through cordis services; a value import fails the client bundle-purity gate. +import type {} from '@deepseek-ai/dsh-client-ui-settings-plugins/client' + +export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope'] + +export function apply(ctx: ClientContext): void { + const card = new MyPluginCardController(ctx.settingsScope.bind({ namespace: 'my-plugin' })) + ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({ + name: 'settings.plugin.item', + key: 'my-plugin', + locale: 'settings.myPlugin', + inject: () => card.inject(), + }, MyPluginCard), + ) +} +``` + +scope 快照携带表单所需的一切：解析后的 `value`、组装层 `base`，以及原始的 `user` 层——字段是否被覆盖，取决于它在 `user` 层中是否**出现**，而非它的值。`scope.set(field, value)` 存一个字段，`scope.unset(field)` 把它清回组装层。 + +## 3. 标签页拿它做什么 + +**插件配置**标签页读取 Host 服务了哪些命名空间，并为每个命名空间派发一个 slot 键。当 Host 服务了某卡片的键时它被渲染，否则被跳过，因此从未组装过 Host 半侧的部署不会留下这张卡片的任何痕迹。被服务却无人认领的命名空间什么都不渲染——归其他页面所有的那些命名空间（`ui-theme`、`permission`、`llm-*`）正是这样留在本标签页之外的。 + +卡片按其注册进该 slot 的顺序出现；keyed entry 不声明自己的 `order`。 + +## 打包 + +浏览器半侧由[客户端模块系统](../../packages/client/modules)提供给页面：它扫描已启用的 Loader entries 中声明了 `dsh.client` 的包，并提供每个包构建出的 `./client` 导出。因此只要 `cordis.yml` 挂载了该插件，它就会出现在页面上——无需重新构建 Web 应用。 + +```jsonc +{ + "exports": { + ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" }, + "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" } + }, + "dsh": { "client": { "platform": "web", "inject": ["@deepseek-ai/dsh-client-ui-settings-plugins"] } } +} +``` + +bundle 必须是 loader 的 lazy-CJS factory 产物。在本仓库内，`tsdown.config.ts` 就是基于共享预设的三行： + +```ts ignore-check +import { clientBundle } from '../tsdown.client.ts' + +export default clientBundle('@deepseek-ai/dsh-client-my-plugin', ['lib/types/index.js', 'lib/types/invariant.js']) +``` + +该预设目前未发布，因此本仓库之外的包得自行复刻同样的输出格式。bundle 纯净度门禁同时拒绝跨插件的值导入，所以卡片无法导入本分区的卡片外观或其暂存表单模型——它渲染自己的那一份，并自行拥有暂存与 revision 设栅。这两条限制都记在[本分区的已知限制](../../packages/client/ui-settings-plugins/README.md#known-limitations-and-deferred-work)里。 diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml index 5708a7b6d5..8f287e2a0f 100644 --- a/docs/subsystems/llm-streaming.i18n.yaml +++ b/docs/subsystems/llm-streaming.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/subsystems/llm-streaming.md -llm-streaming.md: 0d3a0d53c875c9d943146ba44b775d81fc9cae01 -llm-streaming.zh.md: fbaa47d14d57e7377be4db6ecaa04f11997572a6 +llm-streaming.md: 7c0e0865f8dcc0e7722bb2205d0129d9e0ca3086 +llm-streaming.zh.md: 5c31909ee79137c6c5eef101235b43a2419b1339 diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md index 0d3a0d53c8..7c0e0865f8 100644 --- a/docs/subsystems/llm-streaming.md +++ b/docs/subsystems/llm-streaming.md @@ -157,6 +157,29 @@ type ContextFormed = A streaming response interleaves several typed blocks (text, reasoning, multiple tool calls). `index` ties each delta to its block; `block-end` carries the fully-assembled `ContentBlock` so consumers don't have to re-assemble deltas themselves. It is a **closed** discriminated union — a `switch` over `type` ends with `assertNever`, so adding a variant breaks compilation at every consumer that must handle it. +```ts type-equiv +/** + * Adapter-private lossless-JSON state for replaying a successful response, + * carried by a terminal `finish` chunk and stored on the assembled assistant + * message's model source. Both halves stay opaque to the harness; only the + * split is shared vocabulary, so assembly can keep stored metadata aligned + * with stored content without reading either half. + */ +interface ReplayEnvelope { + /** Response-level adapter-private metadata (ids, native stop reason). */ + response: unknown + /** + * Per-block adapter-private metadata, one entry per emitted block in + * first-seen stream order. When assembly drops a block it drops the entry at + * the same position; entries whose length does not match the emitted block + * count discard the whole envelope. An adapter whose metadata is independent + * of block structure omits this field and the envelope passes through + * assembly unchanged. + */ + blocks?: readonly unknown[] +} +``` + ```ts type-equiv /** * Raw streaming protocol emitted by adapters. @@ -176,8 +199,8 @@ type StreamChunk = | { type: 'finish' reason: FinishReason - /** Adapter-private lossless-JSON state for replaying a successful response. */ - replayState?: unknown + /** Replay metadata for a successful response; see {@link ReplayEnvelope}. */ + replayState?: ReplayEnvelope } ``` @@ -213,7 +236,7 @@ Every adapter MUST obey these, and every consumer may rely on them: - **Context overflow has one canonical code.** Both DeepSeek adapters classify explicit provider detail through `isContextWindowExceededError()` and surface `CONTEXT_WINDOW_EXCEEDED`, whether the failure arrives as a thrown HTTP `LlmError` or an in-band finish error. Consumers route on the code, never provider text. - **An empty completion is a retryable error, not a silent success.** Both adapters map a terminal `stop` finish that carried no content blocks to `finish {kind:'error'}` with the canonical `EMPTY_RESPONSE` code, and `dsh-llm-retry` retries it by default; see [empty model responses are retryable](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md). - **Every provider HTTP request carries the app-attribution header.** Adapters send `attributionHeaders()` (below) - the `User-Agent` baseline - and prove it with a wire-level test. -- **Replay state is adapter-owned.** A successful `finish` may carry lossless-JSON state needed to reconstruct a native provider response. The loop stores it with the assembled assistant message. On a later request, `LlmRuntime` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state. +- **Replay state is adapter-owned; its split is shared.** A successful `finish` may carry a `ReplayEnvelope`: opaque response-level metadata plus optional per-block entries aligned with the emitted block sequence. The alignment is the harness's vocabulary — when assembly drops a block it drops the entry at the same position, so stored metadata always describes stored content. The loop stores the pruned envelope with the assembled assistant message. On a later request, `LlmRuntime` passes the state only when the historical provider and target provider are currently registered to the exact same adapter instance. That adapter validates the state and owns any cross-model or cross-provider conversion; other adapters receive the provider-neutral content plus provider/model fields without the private state. Durable content stays authoritative: a stored state the reading adapter cannot use degrades that one message to provider-neutral conversion with a diagnostic instead of failing the request. ## `ResolvedRetryPolicy` @@ -267,6 +290,8 @@ interface TokenUsage { `BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with the provider and model that produced it. A consumer that needs the assembled result without re-implementing the fold uses this. +One keep/drop decision covers content and metadata together: a `max-tokens` finish drops every tool call because a truncated call is unsafe to execute, and the same decision prunes the replay envelope's per-block entry at each dropped position. `blocks()` and `replayState` therefore cannot disagree, whatever assembly removes. + ```ts public-api /** * Incrementally assembles raw {@link StreamChunk}s into complete @@ -296,8 +321,12 @@ declare class BlockAssembler { get usage(): TokenUsage | undefined; /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */ get finish(): FinishReason; - /** Adapter-private replay state from the terminal finish chunk, if any. */ - get replayState(): unknown; + /** + * Replay metadata from the terminal finish chunk, if any, with per-block + * entries pruned in step with {@link blocks}. Undefined when the envelope's + * entries do not align with the emitted blocks. + */ + get replayState(): ReplayEnvelope | undefined; /** * The assembled assistant message. * @param source - producer attribution for the assembled message. diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md index fbaa47d14d..5c31909ee7 100644 --- a/docs/subsystems/llm-streaming.zh.md +++ b/docs/subsystems/llm-streaming.zh.md @@ -157,6 +157,29 @@ type ContextFormed = 一个流式响应交错包含多种类型的块（文本、推理（reasoning）、多个工具调用）。`index` 将每个 delta 关联到其所属块；`block-end` 携带完整组装好的 `ContentBlock`，消费方无需自行重新组装 delta。这是一个**封闭的**可辨识联合类型：对 `type` 的 `switch` 以 `assertNever` 结尾，因此新增变体会在每个必须处理它的消费方处触发编译错误。 +```ts type-equiv +/** + * Adapter-private lossless-JSON state for replaying a successful response, + * carried by a terminal `finish` chunk and stored on the assembled assistant + * message's model source. Both halves stay opaque to the harness; only the + * split is shared vocabulary, so assembly can keep stored metadata aligned + * with stored content without reading either half. + */ +interface ReplayEnvelope { + /** Response-level adapter-private metadata (ids, native stop reason). */ + response: unknown + /** + * Per-block adapter-private metadata, one entry per emitted block in + * first-seen stream order. When assembly drops a block it drops the entry at + * the same position; entries whose length does not match the emitted block + * count discard the whole envelope. An adapter whose metadata is independent + * of block structure omits this field and the envelope passes through + * assembly unchanged. + */ + blocks?: readonly unknown[] +} +``` + ```ts type-equiv /** * Raw streaming protocol emitted by adapters. @@ -176,8 +199,8 @@ type StreamChunk = | { type: 'finish' reason: FinishReason - /** Adapter-private lossless-JSON state for replaying a successful response. */ - replayState?: unknown + /** Replay metadata for a successful response; see {@link ReplayEnvelope}. */ + replayState?: ReplayEnvelope } ``` @@ -215,7 +238,7 @@ interface LlmFailure { - **上下文溢出只有一个规范 code。** 两个 DeepSeek 适配器都通过 `isContextWindowExceededError()` 对提供方的显式细节分类并暴露 `CONTEXT_WINDOW_EXCEEDED`，无论失败以抛出的 HTTP `LlmError` 还是带内 finish error 到达。消费方按 code 路由，绝不依赖提供方文本。 - **空 completion 是可重试错误，而不是静默的成功结果。** 两个适配器都把没有携带任何内容块的终止性 `stop` 结束映射为携带规范 `EMPTY_RESPONSE` code 的 `finish {kind:'error'}`，`dsh-llm-retry` 默认会重试它；详见[空模型响应可重试](../../.agents/notes/implemented/bug-fix/2026-07-24-empty-model-response-is-retryable.md)。 - **每个提供方 HTTP 请求都携带应用归属头。** 适配器发送 `attributionHeaders()`（见下文）作为 `User-Agent` 基线，并通过协议级测试加以证明。 -- **回放状态归适配器所有。** 成功的 `finish` 可以携带重建提供方原生响应所需的无损 JSON 状态。循环会将其与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmRuntime` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。 +- **回放状态归适配器所有；其切分是共享词汇。** 成功的 `finish` 可以携带一个 `ReplayEnvelope`：不透明的响应级元数据，加上与发射块序列对齐的可选逐块条目。对齐关系是 harness 的词汇——组装丢弃某个块时，同一位置的条目一并丢弃，因此存储的元数据始终描述存储的内容。循环把裁剪后的数据与组装后的 assistant 消息一起存储。后续请求中，仅当历史提供方与目标提供方当前注册到完全相同的适配器实例时，`LlmRuntime` 才会传递该状态。该适配器负责校验状态并拥有所有跨模型或跨提供方转换；其他适配器只会收到提供方无关的内容以及提供方／模型字段，不会收到私有状态。持久化内容保持权威：读取适配器无法使用的已存状态只会把这一条消息降级为提供方无关转换并带出诊断，而不是让请求失败。 ## `ResolvedRetryPolicy` @@ -273,6 +296,8 @@ interface TokenUsage { `BlockAssembler`（[`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)）是唯一的共享实现，负责把 `StreamChunk` 流折叠回 `ContentBlock`、usage、结束原因与回放状态。循环在记录原始分片的同时，把同一批分片送入 assembler，再将组装后的 assistant 内容连同生成它的提供方和模型一起存储。需要组装结果、又不想重新实现 fold 的消费方使用它。 +内容与元数据共用同一次保留/丢弃决定：`max-tokens` 结束会丢弃每个工具调用，因为被截断的调用不能安全执行，而同一决定会在每个被丢弃的位置裁剪回放数据的逐块条目。无论组装移除什么，`blocks()` 与 `replayState` 都不可能不一致。 + ```ts public-api /** * Incrementally assembles raw {@link StreamChunk}s into complete @@ -302,8 +327,12 @@ declare class BlockAssembler { get usage(): TokenUsage | undefined; /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */ get finish(): FinishReason; - /** Adapter-private replay state from the terminal finish chunk, if any. */ - get replayState(): unknown; + /** + * Replay metadata from the terminal finish chunk, if any, with per-block + * entries pruned in step with {@link blocks}. Undefined when the envelope's + * entries do not align with the emitted blocks. + */ + get replayState(): ReplayEnvelope | undefined; /** * The assembled assistant message. * @param source - producer attribution for the assembled message. diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index ee066aa386..173a903e1d 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -356,6 +356,13 @@ const SCENARIOS: Scenario[] = [ // reply, and a clean completed retry turn. Its overlay only pins a deterministic // 1 ms zero-jitter delay, so it shares the default header class. { name: 'empty-response-retry', hasModelTurn: true, recorded: false, configPath: RETRY_CONFIG }, + // Keyless, authored (like error-finish): a live model cannot be coaxed into + // a deterministic mid-tool-call output-limit truncation. Turn 1's script ends + // at `max-tokens` with an unfinished tool call and adapter replay metadata for + // both blocks; the durable assistant/message pins assembly dropping the tool + // call AND pruning its per-block replay entry in the same decision, and turn 2 + // proves the session continues past the truncated step. + { name: 'max-tokens-continue', hasModelTurn: true, recorded: false }, // Keyless, authored (like error-finish/cancel): deterministically forcing a // LIVE model to repeat one call three times is not a stable recording, so // the fixture scripts five identical todo_write calls and pins BOTH reminder diff --git a/examples/acp-agent/tests/snapshots/max-tokens-continue/input.json b/examples/acp-agent/tests/snapshots/max-tokens-continue/input.json new file mode 100644 index 0000000000..ebd0c642bb --- /dev/null +++ b/examples/acp-agent/tests/snapshots/max-tokens-continue/input.json @@ -0,0 +1,8 @@ +{ + "steps": [ + { "op": "initialize" }, + { "op": "newSession" }, + { "op": "prompt", "text": "This turn is cut off at the output limit while calling a tool." }, + { "op": "prompt", "text": "Continue: summarize what happened without retrying the tool." } + ] +} diff --git a/examples/acp-agent/tests/snapshots/max-tokens-continue/session.jsonl b/examples/acp-agent/tests/snapshots/max-tokens-continue/session.jsonl new file mode 100644 index 0000000000..6e2f7a6d1c --- /dev/null +++ b/examples/acp-agent/tests/snapshots/max-tokens-continue/session.jsonl @@ -0,0 +1,33 @@ +{"type":"session","version":0,"id":"7f1c9a04-5b52-4a7e-9a63-1d2ab7c90d11","createdAt":1786348800000,"cwd":"{{cwd}}","delegationDepth":0} +{"type":"agent/inbox/spliced","seq":0,"time":1786348800001,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"This turn is cut off at the output limit while calling a tool."}],"source":{"kind":"user"},"role":"user","id":"3a6a5c9e-0f9c-4c8f-9f57-6f2f7f3d5a01"}]}} +{"type":"turn/start","seq":1,"time":1786348800002,"data":{"turn":1}} +{"type":"agent/inbox/spliced","seq":2,"time":1786348800002,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","seq":3,"time":1786348800003,"data":{"turn":1,"step":1}} +{"type":"user/message","seq":4,"time":1786348800004,"data":{"content":[{"type":"text","text":"This turn is cut off at the output limit while calling a tool."}],"source":{"kind":"user"},"role":"user","id":"3a6a5c9e-0f9c-4c8f-9f57-6f2f7f3d5a01"},"surfaceOp":"append"} +{"type":"user/message","seq":5,"time":1786348800005,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"5b7f2d1c-9c44-4c58-8a3e-2f6f8b9d4c02"},"surfaceOp":"append"} +{"type":"session/title","seq":6,"time":1786348800005,"data":{"title":"This turn is cut off","messageSeqs":[4],"source":{"kind":"fallback"}}} +{"type":"request/header","seq":7,"time":1786348800006,"data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"request/context","seq":8,"time":1786348800006,"data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} +{"type":"assistant/chunk","seq":9,"time":1786348800010,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","seq":10,"time":1786348800011,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"Starting the write now."}}} +{"type":"assistant/chunk","seq":11,"time":1786348800012,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"Starting the write now."}}}} +{"type":"assistant/chunk","seq":12,"time":1786348800013,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":1,"blockType":"tool-call"}}} +{"type":"assistant/chunk","seq":13,"time":1786348800014,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":1,"id":"call-cut","name":"bash","argumentsDelta":"{\"command\":\"echo demo > "}}} +{"type":"assistant/chunk","seq":14,"time":1786348800015,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":2864,"outputTokens":12}}}} +{"type":"assistant/chunk","seq":15,"time":1786348800016,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"max-tokens"},"replayState":{"response":{"kind":"pi-ai","version":2,"api":"openai-completions","provider":"deepseek-official","model":"deepseek-v4-flash","stopReason":"length"},"blocks":[{"type":"text"},{"type":"tool-call"}]}}}} +{"type":"assistant/message","seq":16,"time":1786348800016,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"Starting the write now."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash","replayState":{"response":{"kind":"pi-ai","version":2,"api":"openai-completions","provider":"deepseek-official","model":"deepseek-v4-flash","stopReason":"length"},"blocks":[{"type":"text"}]}},"id":"9d5f7c2a-1e63-4d6b-8f14-7a2c5e9b3d03"},"usage":{"inputTokens":2864,"outputTokens":12}},"sourceEventSeqs":[9,10,11,12,13,14,15],"surfaceOp":"append"} +{"type":"step/end","seq":17,"time":1786348800016,"data":{"turn":1,"step":1}} +{"type":"turn/end","seq":18,"time":1786348800016,"data":{"turn":1,"reason":{"kind":"max-tokens"}}} +{"type":"agent/inbox/spliced","seq":19,"time":1786348800020,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Continue: summarize what happened without retrying the tool."}],"source":{"kind":"user"},"role":"user","id":"1c8e6b4f-3d27-4a91-b5c8-9e4f7a2d6c04"}]}} +{"type":"turn/start","seq":20,"time":1786348800021,"data":{"turn":2}} +{"type":"agent/inbox/spliced","seq":21,"time":1786348800021,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","seq":22,"time":1786348800022,"data":{"turn":2,"step":1}} +{"type":"user/message","seq":23,"time":1786348800023,"data":{"content":[{"type":"text","text":"Continue: summarize what happened without retrying the tool."}],"source":{"kind":"user"},"role":"user","id":"1c8e6b4f-3d27-4a91-b5c8-9e4f7a2d6c04"},"surfaceOp":"append"} +{"type":"assistant/chunk","seq":24,"time":1786348800030,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","seq":25,"time":1786348800031,"data":{"turn":2,"step":1,"chunk":{"type":"text-delta","index":0,"text":"The previous reply hit the output limit while a tool call was still streaming, so that call was discarded and no tool ran."}}} +{"type":"assistant/chunk","seq":26,"time":1786348800032,"data":{"turn":2,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"The previous reply hit the output limit while a tool call was still streaming, so that call was discarded and no tool ran."}}}} +{"type":"assistant/chunk","seq":27,"time":1786348800033,"data":{"turn":2,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":64,"outputTokens":28}}}} +{"type":"assistant/chunk","seq":28,"time":1786348800034,"data":{"turn":2,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","seq":29,"time":1786348800034,"data":{"turn":2,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"The previous reply hit the output limit while a tool call was still streaming, so that call was discarded and no tool ran."}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"7e3d9f6b-5a18-4c72-9b4e-1f8c6d2a7e05"},"usage":{"inputTokens":64,"outputTokens":28}},"sourceEventSeqs":[24,25,26,27,28],"surfaceOp":"append"} +{"type":"step/end","seq":30,"time":1786348800034,"data":{"turn":2,"step":1}} +{"type":"turn/end","seq":31,"time":1786348800034,"data":{"turn":2,"reason":{"kind":"completed"}}} diff --git a/examples/acp-agent/tests/snapshots/max-tokens-continue/stdout.expected.jsonl b/examples/acp-agent/tests/snapshots/max-tokens-continue/stdout.expected.jsonl new file mode 100644 index 0000000000..bf555a8d1c --- /dev/null +++ b/examples/acp-agent/tests/snapshots/max-tokens-continue/stdout.expected.jsonl @@ -0,0 +1,6 @@ +{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}} +{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"Starting the write now."}}}} +{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}} +{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"The previous reply hit the output limit while a tool call was still streaming, so that call was discarded and no tool ran."}}}} +{"jsonrpc":"2.0","id":4,"result":{"stopReason":"end_turn"}} diff --git a/packages/client/ui-agent-preset/src/client/settings-store.ts b/packages/client/ui-agent-preset/src/client/settings-store.ts index 4f4e26bdf8..9589d5c2bb 100644 --- a/packages/client/ui-agent-preset/src/client/settings-store.ts +++ b/packages/client/ui-agent-preset/src/client/settings-store.ts @@ -216,7 +216,7 @@ export class AgentPresetSettingsController { // The roster says what may be chosen; `settings.describe` says whether // this browser may write the choice down. A non-loopback browser reaches // neither method, so a refused describe leaves the row read-only rather - // than offering a control whose write answers `settings-not-exposed`. + // than offering a control whose write the Host would refuse. const described = await this.api.settings.describe({}) this.set({ status: 'ready', diff --git a/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts b/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts index 0a98138233..54fd600a60 100644 --- a/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts +++ b/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts @@ -67,8 +67,8 @@ describe('the agent-preset settings controller', () => { await controller.load() // `settings.describe` is loopback-only and reports a read-only provider; - // offering a control whose write answers `settings-not-exposed` would - // promise a switch the host refuses. + // offering a control whose write answers `settings-rejected` would promise + // a switch the host refuses. expect(controller.store.getSnapshot().writable).toBe(false) expect(controller.store.getSnapshot().currentValue).toBe('standard') }) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 954ba5d7af..6d866e05e7 100644 --- a/packages/client/ui-conversation/README.i18n.yaml +++ b/packages/client/ui-conversation/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-conversation/README.md -README.md: ecf463da619662fe158511079e7773ee3c627ac8 -README.zh.md: f8922b160cdc6feca94dea998163c25d803a5535 +README.md: d1a265b5789d9f1d9b5e630e0548ae5f619eebbf +README.zh.md: 3f303391d39bc040b4a6a5a2d1f6a34fe8891919 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index ecf463da61..d1a265b578 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -6,7 +6,7 @@ Conversation domain: skeleton (header/tabs/composer/empty state), chat view (gro Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. Automatic compaction uses the context-compacted title. Every completed marker with a loaded `compaction/summary` event shows the replaced-item and estimated-token counts and discloses the summary on click. Manual `/compact` starts as a running `compact` row; on successful settlement its explicit summary-event reference folds that command into the checkpoint row under the same React key. A completed checkpoint keeps the context-compaction icon at rest and replaces it with the collapsed or expanded disclosure only on hover or keyboard focus. Input rejection, no compactable history, cancellation, and failure retain the generic command row and its handler-authored text. Pairing never depends on adjacency because durable context may be injected while compaction is running. The framed checkpoint payload is model-facing and never renders; when the cited `compaction/summary` event is outside the loaded window, the checkpoint remains visible but non-expandable. -The resident conversation shell survives no-session and session transitions. Without a current session it locks message actions and presents the whole dashed composer card as a trigger for the root-scoped `conversation.hero.workspace` Workspace picker; the textarea remains read-only and keyboard-accessible. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host. +The resident conversation shell survives no-session and session transitions. Without a current session it locks message actions and presents the whole dashed composer card as a trigger for the root-scoped `conversation.hero.workspace` Workspace picker; the textarea remains read-only and keyboard-accessible. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host. Safari alone receives a pre-paint recovery when a native edit shortens the draft and leaves stale soft-wrap overflow; draft growth, programmatic updates, and other browsers never read layout for that recovery ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md)). Another plugin can make one session's composer inert through `ctx.conversation.blocks`: it sets a block carrying its own localized reason, and the bar renders the same disabled textarea with that reason as the placeholder — the no-workspace posture, reused. The push direction is the constraint, not a preference: the plugins that know a session cannot send (ui-model-selection, when no adapter serves its route) already depend on this package, so this package cannot read them. The model seat is the one control a block leaves live — every block this contract has is cleared by choosing a model, so locking it too would leave the composer asking for the only thing it prevents. A block is an affordance only; the Host refuses a prompt it cannot route regardless of what any client disables. The no-workspace state wins when both hold, because picking a workspace is the earlier prerequisite. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index f8922b160c..3f303391d3 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -6,7 +6,7 @@ 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。自动压缩使用「上下文已压缩」标题。每个已加载对应 `compaction/summary` 事件的完成标记都会显示被替换条目数量和估算 token 数量，并可点击展开摘要。手动 `/compact` 开始时显示为运行中的 `compact` 行；成功结算后，其显式摘要事件引用会在保持同一 React key 的前提下把该命令折叠进检查点行。完成的检查点静止时保留上下文压缩（context compaction）图标，仅在悬停或键盘聚焦时将其替换为收起／展开指示图标。输入被拒绝、没有可压缩历史、取消和失败时仍使用通用命令行及处理器撰写的文本。配对绝不依赖相邻关系，因为压缩运行期间可能注入持久上下文。面向模型的带框检查点载荷绝不渲染；被引用的 `compaction/summary` 事件位于已加载窗口之外时，检查点仍然可见但不可展开。 -常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会锁定消息操作，并让整张虚线编辑器卡片成为根作用域 `conversation.hero.workspace` Workspace picker 的入口；textarea 保持只读且支持键盘操作。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace picker、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。 +常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会锁定消息操作，并让整张虚线编辑器卡片成为根作用域 `conversation.hero.workspace` Workspace picker 的入口；textarea 保持只读且支持键盘操作。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace picker、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。只有 Safari 会在原生编辑缩短草稿并留下陈旧软换行溢出时执行绘制前恢复；草稿增长、程序化更新与其他浏览器都不会为这项恢复读取布局（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md)）。 别的插件可以经 `ctx.conversation.blocks` 让某个会话的编辑器变为惰性：它设置一个携带自己本地化理由的 block，输入栏就渲染同一个禁用的 textarea，并把该理由作为 placeholder——复用无 Workspace 时的那套姿态。推送方向是约束而非偏好：知道某会话发不出消息的插件（ui-model-selection，在没有适配器服务其路由时）本就依赖本包，因此本包读不到它们。模型 seat 是 block 唯一保留可用的控件——这份约定里的每个 block 都靠选模型来解除，把它一起锁上会让编辑器索要它自己拦下的那件事。block 只是提示性设计；无论客户端禁用了什么，宿主都会拒绝一个它无法路由的提示词。两者同时成立时以无 Workspace 姿态为准，因为选 Workspace 是更靠前的前提。 diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx index 9585677ae3..000174f513 100644 --- a/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx +++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.tsx @@ -6,7 +6,7 @@ * region-slot content) ride the owner props. Session facts * (running/removed/promptError) are self-selected via useSession. */ -import { useCallback, useEffect, useMemo, useRef, useState } from 'react' +import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react' import type { ChangeEvent, KeyboardEvent, MouseEvent, ReactNode } from 'react' import clsx from 'clsx' import { @@ -31,6 +31,7 @@ import { } from '../image-labels.ts' import { ContextMeter } from './ContextMeter.tsx' import { PermissionSelect } from './PermissionSelect.tsx' +import { isSafariBrowser, repairSafariTextareaLayout } from './safari.ts' import css from './InputBar.module.css' /** Decoration product of the no-session state (no machine, empty draft). */ @@ -106,6 +107,8 @@ export function InputBar({ const dragDepthRef = useRef(0) const scrollRef = useRef(null) const mirrorRef = useRef(null) + const safari = useMemo(() => isSafariBrowser(navigator), []) + const safariNativeShrinkRef = useRef(false) // IME guard: composition Enter picks a candidate, it must not send. The ref outlives renders; // clearing is deferred one tick because Safari delivers the closing keydown AFTER compositionend. const composingRef = useRef(false) @@ -154,6 +157,18 @@ export function InputBar({ } }, [attachments, input?.imageIds, inputActions]) + // A native Safari edit that shortens the draft may leave the previous + // soft-wrap layout behind after the mirror shrinks. The native-change signal + // keeps ordinary typing and programmatic draft updates from reading layout; + // the helper then repairs only measured overflow before paint while + // preserving native editing state. See + // .agents/notes/implemented/bug-fix/2026-08-13-safari-textarea-soft-wrap-reflow.md. + useLayoutEffect(() => { + const nativeShrink = safariNativeShrinkRef.current + safariNativeShrinkRef.current = false + if (safari && nativeShrink) repairSafariTextareaLayout(inputRef.current) + }, [draft, safari]) + useEffect(() => { if (preview !== null && !attachments.some(attachment => attachment.id === preview.id)) setPreview(null) }, [attachments, preview]) @@ -343,6 +358,7 @@ export function InputBar({ if (keyboard === undefined || locked) return // disabled/read-only states cannot edit the draft if (machineBusy) return // submitting is the read-only span; adjudicating holds the pending lock const next = e.target.value + safariNativeShrinkRef.current = safari && next.length < draft.length keyboard.setDraft(next) // selectionStart is number|null in lib.dom; the type-aware lint program narrows it. // oxlint-disable-next-line typescript/no-unnecessary-condition diff --git a/packages/client/ui-conversation/src/client/skeleton/safari.ts b/packages/client/ui-conversation/src/client/skeleton/safari.ts new file mode 100644 index 0000000000..d563b25e6c --- /dev/null +++ b/packages/client/ui-conversation/src/client/skeleton/safari.ts @@ -0,0 +1,42 @@ +/** Safari-specific textarea layout recovery for the conversation composer. */ + +/** Browser identity fields needed to distinguish Safari from other WebKit-based browsers. */ +export interface BrowserIdentity { + readonly userAgent: string + readonly vendor: string +} + +const ALTERNATE_IOS_BROWSER = /\b(?:CriOS|FxiOS|EdgiOS|OPiOS|OPT|DuckDuckGo|Brave)(?:\/|\b)/ + +/** + * Detect Safari's `Version/... Safari/...` form while excluding known alternate iOS browser tokens. + * @param identity - Browser user-agent and vendor values. + * @returns Whether the identity should use the Safari-specific recovery. + */ +export function isSafariBrowser(identity: BrowserIdentity): boolean { + return identity.vendor === 'Apple Computer, Inc.' + && /\bVersion\/[\d.]+.*\bSafari\/[\d.]+/.test(identity.userAgent) + && !ALTERNATE_IOS_BROWSER.test(identity.userAgent) +} + +/** + * Repair Safari's stale native textarea layout and the scrollport auto height it can contaminate. + * @param input - Composer textarea whose own scrollable overflow must stay zero. + */ +export function repairSafariTextareaLayout(input: HTMLTextAreaElement | null): void { + if (input === null || input.scrollHeight <= input.clientHeight) return + const scrollport = input.closest('[data-input-scroll]') + if (scrollport === null) return + + const inputHeight = input.style.height + input.style.height = `${String(input.clientHeight + 1)}px` + void input.offsetHeight + input.style.height = inputHeight + void input.offsetHeight + + const scrollportHeight = scrollport.style.height + scrollport.style.height = `${String(scrollport.clientHeight + 1)}px` + void scrollport.offsetHeight + scrollport.style.height = scrollportHeight + void scrollport.offsetHeight +} diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx index 94354bd316..f7d5e02a7f 100644 --- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx +++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx @@ -824,6 +824,116 @@ describe('running and lock semantics', () => { expect(backdrop.textContent).toBe('line\n'.repeat(40)) }) + it('repairs Safari native overflow after the mirror shrinks the draft', () => { + const vendor = vi.spyOn(window.navigator, 'vendor', 'get').mockReturnValue('Apple Computer, Inc.') + const userAgent = vi.spyOn(window.navigator, 'userAgent', 'get').mockReturnValue( + 'Mozilla/5.0 (Macintosh) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.5 Safari/605.1.15', + ) + onTestFinished(() => { + vendor.mockRestore() + userAgent.mockRestore() + }) + const { textarea } = bench({ draft: 'two wrapped lines' }) + const scrollport = textarea.closest('[data-input-scroll]')! + let inputRepaired = false + let scrollportRepaired = false + const inputLayouts: string[] = [] + const scrollportLayouts: string[] = [] + Object.defineProperty(textarea, 'clientHeight', { + configurable: true, + get: () => textarea.style.height === '29px' ? 29 : 28, + }) + Object.defineProperty(textarea, 'scrollHeight', { + configurable: true, + get: () => inputRepaired ? 28 : 52, + }) + Object.defineProperty(textarea, 'offsetHeight', { + configurable: true, + get: () => { + inputLayouts.push(textarea.style.height) + if (textarea.style.height === '') inputRepaired = true + return textarea.clientHeight + }, + }) + Object.defineProperty(scrollport, 'clientHeight', { + configurable: true, + get: () => { + if (scrollport.style.height === '53px') return 53 + if (inputRepaired && !scrollportRepaired) return 52 + return 28 + }, + }) + Object.defineProperty(scrollport, 'offsetHeight', { + configurable: true, + get: () => { + scrollportLayouts.push(scrollport.style.height) + if (scrollport.style.height === '') scrollportRepaired = true + return scrollport.clientHeight + }, + }) + textarea.setSelectionRange(5, 5) + + fireEvent.change(textarea, { target: { value: 'one line' } }) + + expect(inputLayouts).toEqual(['29px', '']) + expect(scrollportLayouts).toEqual(['53px', '']) + expect(textarea.style.height).toBe('') + expect(scrollport.style.height).toBe('') + expect(textarea.scrollHeight).toBe(textarea.clientHeight) + expect(scrollport.clientHeight).toBe(28) + }) + + it('does not force the Safari recovery for another iOS browser', () => { + const vendor = vi.spyOn(window.navigator, 'vendor', 'get').mockReturnValue('Apple Computer, Inc.') + const userAgent = vi.spyOn(window.navigator, 'userAgent', 'get').mockReturnValue( + 'Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/140.0.0.0 Mobile/15E148 Safari/604.1', + ) + onTestFinished(() => { + vendor.mockRestore() + userAgent.mockRestore() + }) + const { textarea } = bench({ draft: 'two wrapped lines' }) + const scrollport = textarea.closest('[data-input-scroll]')! + Object.defineProperty(textarea, 'clientHeight', { configurable: true, value: 28 }) + Object.defineProperty(textarea, 'scrollHeight', { configurable: true, value: 52 }) + Object.defineProperty(textarea, 'offsetHeight', { + configurable: true, + get: () => { throw new Error('non-Safari browser must not force textarea layout') }, + }) + Object.defineProperty(scrollport, 'offsetHeight', { + configurable: true, + get: () => { throw new Error('non-Safari browser must not force scrollport layout') }, + }) + + fireEvent.change(textarea, { target: { value: 'one line' } }) + + expect(scrollport.style.height).toBe('') + }) + + it('does not read Safari layout while a native edit grows the draft', () => { + const vendor = vi.spyOn(window.navigator, 'vendor', 'get').mockReturnValue('Apple Computer, Inc.') + const userAgent = vi.spyOn(window.navigator, 'userAgent', 'get').mockReturnValue( + 'Mozilla/5.0 (Macintosh) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.5 Safari/605.1.15', + ) + onTestFinished(() => { + vendor.mockRestore() + userAgent.mockRestore() + }) + const { textarea, shell } = bench({ draft: 'one line' }) + Object.defineProperty(textarea, 'clientHeight', { + configurable: true, + get: () => { throw new Error('growing Safari input must not read layout') }, + }) + Object.defineProperty(textarea, 'scrollHeight', { + configurable: true, + get: () => { throw new Error('growing Safari input must not read layout') }, + }) + + fireEvent.change(textarea, { target: { value: 'one line grows' } }) + + expect(shell.snapshot.draft).toBe('one line grows') + }) + it('an edit the composer performs itself scrolls the caret back into view', async () => { // Paste and cut suppress the native edit, so no engine reveals the caret // for them. jsdom has no layout: the rects are stubbed, diff --git a/packages/client/ui-conversation/tests/safari.client.spec.ts b/packages/client/ui-conversation/tests/safari.client.spec.ts new file mode 100644 index 0000000000..895680d693 --- /dev/null +++ b/packages/client/ui-conversation/tests/safari.client.spec.ts @@ -0,0 +1,131 @@ +// @vitest-environment jsdom + +import { describe, expect, it } from 'vitest' +import { isSafariBrowser, repairSafariTextareaLayout } from '../src/client/skeleton/safari.ts' + +describe('Safari browser detection', () => { + it.each([ + { + name: 'desktop Safari', + vendor: 'Apple Computer, Inc.', + userAgent: 'Mozilla/5.0 (Macintosh) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.5 Safari/605.1.15', + expected: true, + }, + { + name: 'mobile Safari', + vendor: 'Apple Computer, Inc.', + userAgent: 'Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 Mobile/15E148 Safari/604.1', + expected: true, + }, + { + name: 'desktop Chromium', + vendor: 'Google Inc.', + userAgent: 'Mozilla/5.0 (Macintosh) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0.0.0 Safari/537.36', + expected: false, + }, + { + name: 'Chrome on iOS', + vendor: 'Apple Computer, Inc.', + userAgent: 'Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/140.0.0.0 Mobile/15E148 Safari/604.1', + expected: false, + }, + { + name: 'Edge on iOS with Safari tokens', + vendor: 'Apple Computer, Inc.', + userAgent: 'Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 EdgiOS/140.0 Mobile/15E148 Safari/604.1', + expected: false, + }, + { + name: 'Opera on iOS with Safari tokens', + vendor: 'Apple Computer, Inc.', + userAgent: 'Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.0 OPiOS/6.0 Mobile/15E148 Safari/604.1', + expected: false, + }, + { + name: 'Apple web view', + vendor: 'Apple Computer, Inc.', + userAgent: 'Mozilla/5.0 (iPhone) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148', + expected: false, + }, + ])('identifies $name', ({ vendor, userAgent, expected }) => { + expect(isSafariBrowser({ vendor, userAgent })).toBe(expected) + }) +}) + +describe('Safari textarea layout recovery', () => { + it('does nothing while the textarea owns no scrollable overflow', () => { + const input = document.createElement('textarea') + Object.defineProperty(input, 'clientHeight', { value: 28 }) + Object.defineProperty(input, 'scrollHeight', { value: 28 }) + + repairSafariTextareaLayout(input) + + expect(input.style.height).toBe('') + }) + + it('invalidates a stale native layout and restores the owned height', () => { + const input = document.createElement('textarea') + const scrollport = document.createElement('div') + scrollport.setAttribute('data-input-scroll', '') + scrollport.appendChild(input) + input.value = 'abcdef' + input.setSelectionRange(3, 3) + input.style.height = '100%' + scrollport.style.height = '100%' + let inputRepaired = false + let scrollportRepaired = false + const inputLayouts: string[] = [] + const scrollportLayouts: string[] = [] + Object.defineProperty(input, 'clientHeight', { + get: () => input.style.height === '29px' ? 29 : 28, + }) + Object.defineProperty(input, 'scrollHeight', { + get: () => inputRepaired ? 28 : 52, + }) + Object.defineProperty(input, 'offsetHeight', { + get: () => { + inputLayouts.push(input.style.height) + if (input.style.height === '100%') inputRepaired = true + return input.clientHeight + }, + }) + Object.defineProperty(scrollport, 'clientHeight', { + get: () => { + if (scrollport.style.height === '53px') return 53 + if (inputRepaired && !scrollportRepaired) return 52 + return 28 + }, + }) + Object.defineProperty(scrollport, 'offsetHeight', { + get: () => { + scrollportLayouts.push(scrollport.style.height) + if (scrollport.style.height === '100%') scrollportRepaired = true + return scrollport.clientHeight + }, + }) + + repairSafariTextareaLayout(input) + + expect(inputLayouts).toEqual(['29px', '100%']) + expect(scrollportLayouts).toEqual(['53px', '100%']) + expect(input.style.height).toBe('100%') + expect(scrollport.style.height).toBe('100%') + expect(input.scrollHeight).toBe(input.clientHeight) + expect(scrollport.clientHeight).toBe(28) + expect([input.selectionStart, input.selectionEnd]).toEqual([3, 3]) + }) + + it('does nothing outside the composer scrollport', () => { + const input = document.createElement('textarea') + Object.defineProperty(input, 'clientHeight', { value: 28 }) + Object.defineProperty(input, 'scrollHeight', { value: 52 }) + + repairSafariTextareaLayout(input) + + expect(input.style.height).toBe('') + }) + + it('accepts an absent textarea during teardown', () => { + expect(() => { repairSafariTextareaLayout(null) }).not.toThrow() + }) +}) diff --git a/packages/client/ui-settings-plugins/README.i18n.yaml b/packages/client/ui-settings-plugins/README.i18n.yaml index 09e742cf23..ae8c3a78bf 100644 --- a/packages/client/ui-settings-plugins/README.i18n.yaml +++ b/packages/client/ui-settings-plugins/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write packages/client/ui-settings-plugins/README.md -README.md: 53418f8939649bae4413625a37630e46e7060d15 -README.zh.md: 8d4a2bf8d1af662e9f8e05ccc607cc8b66731731 +README.md: 92ba426b6bee3ae73e184dfcfd418e889bd47086 +README.zh.md: dc319ea9f128016b6df821575cb4d75740f04579 diff --git a/packages/client/ui-settings-plugins/README.md b/packages/client/ui-settings-plugins/README.md index 53418f8939..92ba426b6b 100644 --- a/packages/client/ui-settings-plugins/README.md +++ b/packages/client/ui-settings-plugins/README.md @@ -6,13 +6,13 @@ The **Plugins** settings section and its **Plugin configuration** tab. The secti ## What appears here -A card renders only when its namespace is both registered by a live Host plugin and served to the browser. A deployment that does not compose the owning plugin — or serves the namespace to no client — renders nothing for it rather than an empty or disabled card, so the configurable tab reflects what this deployment actually runs. +The configurable tab reads which settings namespaces the Host serves and dispatches one slot key per namespace, so what renders is the intersection of two ledgers: the namespaces a live Host plugin registered, and the cards registered under those keys. A served namespace no card claims renders nothing — another surface owns it, or this deployment ships no browser half for it — and a card whose namespace this deployment does not serve is never dispatched, so an uncomposed plugin leaves no trace and does not hold the tab back from its empty line. The empty line waits for the Host's first answer, so an unanswered read never reads as "this deployment configures no plugin". Cards appear in the order they registered, which is stable for the cards one package installs together and not stable across plugins: apply order between packages is unconstrained. -The first batch covers the shell executor (`bash`), the agent loop's tool-call parallelism (`agent-loop`), and the DeepSeek search provider (`web-search-deepseek`). +The cards this package ships cover the shell executor (`bash`), the agent loop's tool-call parallelism (`agent-loop`), and the DeepSeek search provider (`web-search-deepseek`). ## Extension point -The section declares `settings.plugins.tab`, a root list slot whose labels become ordered tabs. It keeps a tab mounted after its first selection, so local drafts and read-only snapshots survive tab switches. The package registers its own `configurable` contribution, which declares the nested `settings.plugin.item` list slot. A plugin that ships a browser half registers its own card into that nested slot and owns its controls; this package neither enumerates namespaces nor renders a form it was not given. Both levels follow the contribution's `order`. +The section declares `settings.plugins.tab`, a root list slot whose labels become ordered tabs. It keeps a tab mounted after its first selection, so local drafts and read-only snapshots survive tab switches. The package registers its own `configurable` contribution, which declares the nested `settings.plugin.item` slot — keyed on the settings namespace a card edits. A plugin that ships a browser half registers its own card under its own namespace and owns every part of it: chrome, controls, and copy. Keying on the namespace is what lets a plugin distributed outside this repository appear here — it registers the namespace on the Host and the card in the browser, and the tab pairs the two without learning what the namespace means. Tabs follow the contribution's `order`; cards follow registration order. ## Writes @@ -35,6 +35,6 @@ None; this package neither assembles nor sends a provider request. ## Known Limitations and Deferred Work - **Only host-plane plugins appear** — a plugin an agent preset mounts carries its configuration inline in that preset's `agent.cordis.yml` and cannot register a settings namespace at all (a second session mounting the same preset would fail on a duplicate registration), so this section lists nothing for it. Editing those values remains the preset editor's job. -- **Exposure is a Host allowlist, not a plugin declaration** — a namespace absent from the api-proxy's allowlist answers `settings-not-exposed` even when its owner registered it, so a plugin distributed outside this repository cannot surface its own configuration here without a change in `packages/host/apiproxy`. +- **A card still needs a browser bundle** — the browser half must be a `dsh.client` package built in the client module system's lazy-CJS factory format, and the `clientBundle` preset that emits it lives in `packages/client/tsdown.client.ts` rather than a published package, so a plugin outside this repository has to reproduce that build itself. The bundle-purity gate also forbids importing this package's card chrome or form model as values, so such a card owns its own staging and revision fencing. +- **The served namespaces re-read on two signals only** — the wire announces settings-document commits and connection resets, not registrations, so a namespace whose owner registers after the tab's read joins the list on the next document commit or reconnect. - **The shell card follows the composed executor** — the POSIX and PowerShell executor families share the `bash` namespace because a host composes exactly one of them, so the served schema differs by platform (PowerShell adds `pwshPath`) even though the card edits the same two fields on both, and a deployment composing neither shows no card. -- **The empty line counts registered cards, not visible ones** — a card whose namespace this deployment does not expose renders nothing, but still counts, so a deployment that exposes none shows an empty list rather than the empty line. The count is also read once, because the renderer caches a root entry's inject face; a card registered later does not raise it. diff --git a/packages/client/ui-settings-plugins/README.zh.md b/packages/client/ui-settings-plugins/README.zh.md index 8d4a2bf8d1..dc319ea9f1 100644 --- a/packages/client/ui-settings-plugins/README.zh.md +++ b/packages/client/ui-settings-plugins/README.zh.md @@ -6,13 +6,13 @@ ## 这里会出现什么 -只有当某个命名空间既被存活的 Host 插件注册、又被服务给浏览器时，它的卡片才会渲染。未组装该插件的部署——或未向任何客户端服务该命名空间的部署——不会渲染空卡片或禁用卡片，而是什么都不渲染，因此“插件配置”标签页反映的是该部署实际运行的东西。 +“插件配置”标签页读取 Host 服务了哪些 settings 命名空间，并为每个命名空间派发一个 slot 键，因此渲染出来的是两份账本的交集：存活 Host 插件注册的命名空间，以及注册在这些键上的卡片。被服务却无人认领的命名空间什么都不渲染——它归别的界面所有，或本部署没有为它提供浏览器半侧；而命名空间未被本部署服务的卡片根本不会被派发，因此未组装的插件不留任何痕迹，也不会挡住那行空态文案。空态文案要等 Host 的第一次答复，因此一次尚未答复的读取绝不会被读成“本部署没有可配置的插件”。卡片按自身注册的顺序出现；对同一个包一起安装的卡片这是稳定的，对跨插件的卡片则不稳定：包与包之间的 apply 顺序是无约束的。 -第一批覆盖 shell 执行器（`bash`）、agent 循环的工具调用并行度（`agent-loop`）以及 DeepSeek 搜索提供方（`web-search-deepseek`）。 +本包自带的卡片覆盖 shell 执行器（`bash`）、agent 循环的工具调用并行度（`agent-loop`）以及 DeepSeek 搜索提供方（`web-search-deepseek`）。 ## 扩展点 -本分区声明根级列表 slot `settings.plugins.tab`，其标签会成为有序标签页。某个标签页首次被选择后会保持挂载，因此本地草稿与只读快照在切换标签页时不会丢失。本包注册自己的 `configurable` 贡献，由它声明嵌套的 `settings.plugin.item` 列表 slot。带浏览器半侧的插件把自己的卡片注册进这个嵌套 slot 并拥有其控件；本包既不枚举命名空间，也不渲染未被交给它的表单。两层排序都遵循贡献的 `order`。 +本分区声明根级列表 slot `settings.plugins.tab`，其标签会成为有序标签页。某个标签页首次被选择后会保持挂载，因此本地草稿与只读快照在切换标签页时不会丢失。本包注册自己的 `configurable` 贡献，由它声明嵌套的 `settings.plugin.item` slot——以卡片所编辑的 settings 命名空间为键。带浏览器半侧的插件把自己的卡片注册在自己的命名空间上，并拥有它的全部：外观、控件与文案。以命名空间为键，正是在本仓库之外分发的插件能出现在这里的原因——它在 Host 上注册命名空间、在浏览器里注册卡片，由标签页把两者配对，而无需知道命名空间意味着什么。标签页遵循贡献的 `order`；卡片遵循注册顺序。 ## 写入 @@ -35,6 +35,6 @@ ## 已知限制与暂缓事项 - **只有宿主平面的插件会出现**——由 agent preset 挂载的插件把配置内联在该 preset 的 `agent.cordis.yml` 中，且根本无法注册 settings 命名空间（同一 preset 挂载第二个会话时会因重复注册而失败），因此本分区不会列出它。编辑那些值仍是 preset 编辑器的职责。 -- **暴露是 Host 的白名单，而非插件的声明**——不在 api-proxy 白名单中的命名空间，即便其拥有方已注册，也只会得到 `settings-not-exposed`，因此在本仓库之外分发的插件无法在不改动 `packages/host/apiproxy` 的前提下让自己的配置出现在这里。 +- **卡片仍然需要一份浏览器 bundle**——浏览器半侧必须是按客户端模块系统的 lazy-CJS factory 格式构建的 `dsh.client` 包，而产出它的 `clientBundle` 预设位于 `packages/client/tsdown.client.ts`，并非已发布的包，因此本仓库之外的插件得自行复刻该构建。bundle 纯净度门禁同时禁止以值的形式导入本包的卡片外观与表单模型，所以这样的卡片要自行拥有暂存与 revision 设栅。 +- **被服务的命名空间只在两种信号上重读**——协议通告的是 settings 文档提交与连接重置，而非注册行为，因此在标签页读取之后才被其拥有方注册的命名空间，要等下一次文档提交或重连才会加入列表。 - **shell 卡片跟随被组装的执行器**——POSIX 与 PowerShell 两个执行器家族共用 `bash` 命名空间，因为一个宿主只组装其中之一，所以被服务的 schema 随平台不同（PowerShell 多出 `pwshPath`），尽管卡片在两者下编辑的都是同样两个字段；而两者都不组装的部署不会显示这张卡片。 -- **空态数的是已注册卡片，不是可见卡片**——命名空间未被本部署暴露的卡片什么都不渲染，但仍计入数量，因此一个都不暴露的部署看到的是空列表而非那行空态文案。该计数还只读取一次，因为渲染器会缓存根级 entry 的 inject face；之后注册的卡片不会让它变大。 diff --git a/packages/client/ui-settings-plugins/src/client/ConfigurablePluginsTab.tsx b/packages/client/ui-settings-plugins/src/client/ConfigurablePluginsTab.tsx index 4e7b575fd5..c9b4365a3a 100644 --- a/packages/client/ui-settings-plugins/src/client/ConfigurablePluginsTab.tsx +++ b/packages/client/ui-settings-plugins/src/client/ConfigurablePluginsTab.tsx @@ -1,25 +1,43 @@ -/** Configurable Host plugins contributed to the shared Plugins section. */ +/** + * Configurable Host plugins contributed to the shared Plugins section. + * + * The tab enumerates settings namespaces but never interprets one — a card + * arrives through `settings.plugin.item` keyed by the namespace it edits, so a + * plugin that ships a browser half owns its own card and this tab only decides + * which keys to dispatch. + */ +import { Fragment } from 'react' import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import type {} from './slot-contract.ts' +import type { ConfigurablePluginsTabFace } from './tab-store.ts' import css from './PluginsSettingsSection.module.css' -/** Registration-side business face for the configurable tab. */ -export interface ConfigurablePluginsTabInjected { - /** How many cards the slot ledger held when the tab registration mounted. */ - cardCount: number -} - /** Props the renderer binds for the configurable tab. */ export type ConfigurablePluginsTabProps = PropsRuntime<'settings.plugins.tab'> & PropsLocale<'settings.plugins'> & PropsRenderSlots<'settings.plugin.item'> - & InjectFace + & InjectFace -/** Render cards registered by plugins that expose editable settings. */ -export function ConfigurablePluginsTab({ t, renderSlot, cardCount }: ConfigurablePluginsTabProps) { - return cardCount === 0 - ?

{t('empty')}

- :
    {renderSlot('settings.plugin.item', {})}
+/** + * Render cards registered by plugins that expose editable settings. + * @param props - locale copy, slot rendering, and the namespaces to dispatch. + * @returns the card list, or the empty line once the Host has answered. + */ +export function ConfigurablePluginsTab(props: ConfigurablePluginsTabProps) { + const { t, renderSlot } = props + const { loaded, namespaces } = props.useConfigurablePlugins(snapshot => snapshot) + if (namespaces.length > 0) { + return ( +
    + {namespaces.map(ns => ( + // One dispatch per namespace, so the list identity is the namespace + // rather than a position that shifts as cards arrive. + {renderSlot('settings.plugin.item', {}, { entryKey: ns })} + ))} +
+ ) + } + return loaded ?

{t('empty')}

: null } diff --git a/packages/client/ui-settings-plugins/src/client/index.ts b/packages/client/ui-settings-plugins/src/client/index.ts index dd0b80d89a..82dea6d796 100644 --- a/packages/client/ui-settings-plugins/src/client/index.ts +++ b/packages/client/ui-settings-plugins/src/client/index.ts @@ -23,17 +23,18 @@ import type {} from '@deepseek-ai/dsh-api-remotes/client' import { AgentLoopCard } from './AgentLoopCard.tsx' import { BashCard } from './BashCard.tsx' import { ConfigurablePluginsTab } from './ConfigurablePluginsTab.tsx' -import type { ConfigurablePluginsTabInjected } from './ConfigurablePluginsTab.tsx' import { PluginsSettingsSection } from './PluginsSettingsSection.tsx' import type { PluginsSettingsSectionInjected, PluginsSettingsTabEntry } from './PluginsSettingsSection.tsx' import { WebSearchCard } from './WebSearchCard.tsx' import { AGENT_LOOP_NS, AgentLoopCardController } from './agent-loop-card-controller.ts' import { SHELL_NS, BashCardController } from './bash-card-controller.ts' +import { ConfigurablePluginsTabController } from './tab-store.ts' import { WEB_SEARCH_NS, WebSearchCardController } from './web-search-card-controller.ts' import { en, zh } from './locales.ts' export type { PluginsSettingsSectionInjected, PluginsSettingsSectionProps } from './PluginsSettingsSection.tsx' -export type { ConfigurablePluginsTabInjected, ConfigurablePluginsTabProps } from './ConfigurablePluginsTab.tsx' +export type { ConfigurablePluginsTabProps } from './ConfigurablePluginsTab.tsx' +export type { ConfigurablePluginsTabFace, ConfigurablePluginsTabState } from './tab-store.ts' export type { PluginCardProps } from './PluginCard.tsx' export type { SettingsPluginItemOwnerProps } from './slot-contract.ts' export type { FieldProps } from './fields.tsx' @@ -71,6 +72,27 @@ export function apply(ctx: ClientContext): void { 'ui-settings-plugins: credential invalidations', ) + // Which namespaces the Host serves is a registration fact the wire does not + // announce, so the directory re-reads on the two signals that can carry a + // changed composition: a settings document commit and a reconnect. + const configurable = new ConfigurablePluginsTabController( + api, () => ctx.slots.entries('settings.plugin.item')) + ctx.effect(() => () => { configurable.dispose() }, 'ui-settings-plugins: tab directory') + ctx.effect( + () => ctx.remote.$on('settings/document-updated', () => { void configurable.load() }), + 'ui-settings-plugins: served-namespace invalidations', + ) + ctx.effect( + () => ctx.on('connection/reset', () => { void configurable.load() }), + 'ui-settings-plugins: served-namespace reconnect', + ) + // A card registered after the first read joins the list without a wire call. + ctx.effect( + () => ctx.slots.subscribe('settings.plugin.item', () => { configurable.refresh() }), + 'ui-settings-plugins: card ledger', + ) + void configurable.load() + let tabsVersion = -1 let tabsRevision = -1 let tabs: readonly PluginsSettingsTabEntry[] = [] @@ -126,31 +148,26 @@ export function apply(ctx: ClientContext): void { order: 0, label: () => t('configurableTab'), locale: NS, - inject: (): ConfigurablePluginsTabInjected => ({ - cardCount: ctx.slots.entries('settings.plugin.item').length, - }), - children: { 'settings.plugin.item': { kind: 'list', scope: 'root' } }, + inject: () => configurable.inject(), + children: { 'settings.plugin.item': { kind: 'keyed', scope: 'root' } }, }, ConfigurablePluginsTab)) ctx.slots.inject('settings.plugin.item', function* () { yield ctx.slots.register({ name: 'settings.plugin.item', - id: 'bash', - order: 0, + key: SHELL_NS, locale: NS, inject: () => bash.inject(), }, BashCard) yield ctx.slots.register({ name: 'settings.plugin.item', - id: 'agent-loop', - order: 10, + key: AGENT_LOOP_NS, locale: NS, inject: () => agentLoop.inject(), }, AgentLoopCard) yield ctx.slots.register({ name: 'settings.plugin.item', - id: 'web-search', - order: 20, + key: WEB_SEARCH_NS, locale: NS, inject: () => webSearch.inject(), }, WebSearchCard) diff --git a/packages/client/ui-settings-plugins/src/client/slot-contract.ts b/packages/client/ui-settings-plugins/src/client/slot-contract.ts index 02b00ea35b..ecb84acadc 100644 --- a/packages/client/ui-settings-plugins/src/client/slot-contract.ts +++ b/packages/client/ui-settings-plugins/src/client/slot-contract.ts @@ -1,19 +1,22 @@ /** - * The `settings.plugin.item` slot type — one plugin's card inside the plugin - * configuration section. Options: `id` (card key), `order` (card position). - * A card draws its own internals; the section only stacks them and reports - * how many there are. + * The `settings.plugin.item` slot type — one plugin's card inside the + * configurable-plugins tab, keyed by the settings namespace the card edits. + * Options: `key` (the namespace). A card draws its own internals; the tab only + * decides which namespaces to dispatch and stacks what comes back. * - * TYPE HOME RATIONALE: unlike `settings.general.item`, whose registrants span - * packages that cannot reference its declarer, every current registrant of - * this slot ships in this package, and a plugin registering its own card - * already depends on this package for the card chrome. The type therefore - * lives with the section that declares it at runtime. + * Keying on the namespace is what lets a plugin distributed outside this + * repository contribute a card: it registers its own settings namespace on the + * Host and its own card under that key in the browser, and the tab pairs the + * two without ever learning what the namespace means. + * + * TYPE HOME RATIONALE: the tab declares this slot at runtime, and a plugin + * registering its own card already depends on this package for the slot's + * declaration. The type therefore lives with its declarer. */ declare module '@deepseek-ai/dsh-client-ui-slots' { interface SlotMap { /** One plugin's card inside the plugin configuration section (see module JSDoc). */ - 'settings.plugin.item': { kind: 'list'; scope: 'root'; owner: SettingsPluginItemOwnerProps } + 'settings.plugin.item': { kind: 'keyed'; scope: 'root'; owner: SettingsPluginItemOwnerProps } } } diff --git a/packages/client/ui-settings-plugins/src/client/tab-store.ts b/packages/client/ui-settings-plugins/src/client/tab-store.ts new file mode 100644 index 0000000000..a4ed4439f2 --- /dev/null +++ b/packages/client/ui-settings-plugins/src/client/tab-store.ts @@ -0,0 +1,123 @@ +/** + * The configurable-plugins tab's card list. + * + * The tab dispatches its slot by settings namespace, so what it renders is + * the intersection of two ledgers: the namespaces the Host serves and the + * cards registered into `settings.plugin.item`. A served namespace no card + * claims renders nothing — another surface owns it, or this deployment ships + * no browser half for it — and a card whose namespace the Host does not serve + * is never dispatched, so a plugin this deployment did not compose leaves no + * trace and does not count toward the empty line. + */ + +import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client' +import type { StoredEntry } from '@deepseek-ai/dsh-client-ui-slots' +import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client' + +/** What the section renders. */ +export interface ConfigurablePluginsTabState { + /** + * Whether the Host has answered once. The empty line waits for it: an + * unanswered read is not the same statement as "this deployment configures + * no plugin", and saying the second while the first is true would flash a + * wrong answer on every open. + */ + loaded: boolean + /** + * Namespaces to dispatch, in the order their cards registered, narrowed to + * those the Host serves. Card registration order rather than the Host's + * description order: the latter follows plugin activation, which async + * settings injection can reorder between boots, and a settings page whose + * cards move between visits is worse than one whose order a registrant + * chose. + */ + namespaces: string[] +} + +/** The registration-side face the tab's slot entry injects. */ +export interface ConfigurablePluginsTabFace { + hooks: { + /** Section snapshot bound by the renderer as usePluginConfigSection. */ + configurablePlugins: SnapshotStore + } +} + +/** Reads the served namespaces and pairs them with the cards that claim them. */ +export class ConfigurablePluginsTabController { + private readonly store = createSnapshotStore({ loaded: false, namespaces: [] }) + /** Last Host answer; kept so a slot mutation republishes without a wire read. */ + private served: readonly string[] = [] + private loaded = false + private generation = 0 + private disposed = false + + /** + * @param api - settings wire face. + * @param entries - reads the cards currently registered into the section's slot. + */ + constructor( + private readonly api: Pick, + private readonly entries: () => readonly StoredEntry[], + ) {} + + /** Opaque read of {@link disposed}: control flow cannot narrow it across awaits. */ + private isDisposed(): boolean { + return this.disposed + } + + /** + * Re-read the served namespaces from the Host and republish. + * @returns settlement after the read, or immediately once disposed. + */ + async load(): Promise { + if (this.isDisposed()) return + const generation = ++this.generation + let response: Awaited> + try { + response = await this.api.settings.describe({}) + } catch (_settingsReadFailure) { + // The tab keeps the namespaces it last knew; the next invalidation + // or reconnect reads again. + return + } + if (this.isDisposed() || generation !== this.generation || !response.result.ok) return + this.served = response.result.value.namespaces.map(view => view.ns) + this.loaded = true + this.publish() + } + + /** Republish after the slot ledger changed; a card registered late joins here. */ + refresh(): void { + if (this.disposed) return + this.publish() + } + + /** Stop publishing; an in-flight read settles without touching the store. */ + dispose(): void { + this.disposed = true + this.generation += 1 + } + + /** + * Build the face the tab's slot registration injects. + * @returns the tab's snapshot source. + */ + inject(): ConfigurablePluginsTabFace { + return { hooks: { configurablePlugins: this.store } } + } + + private publish(): void { + const served = new Set(this.served) + const namespaces = this.entries().flatMap(entry => + entry.options.key !== undefined && served.has(entry.options.key) ? [entry.options.key] : []) + const previous = this.store.getSnapshot() + // Every settings-document commit re-reads, and most of them change nothing + // this section shows. An observable source must keep its snapshot + // reference until the fact moves, or each unrelated save re-renders the + // whole card list (packages/client/AGENTS.md reactive rule 5). + if (previous.loaded === this.loaded + && previous.namespaces.length === namespaces.length + && previous.namespaces.every((ns, index) => ns === namespaces[index])) return + this.store.set({ loaded: this.loaded, namespaces }) + } +} diff --git a/packages/client/ui-settings-plugins/src/invariant.ts b/packages/client/ui-settings-plugins/src/invariant.ts index 5e21f38157..4b0eba850c 100644 --- a/packages/client/ui-settings-plugins/src/invariant.ts +++ b/packages/client/ui-settings-plugins/src/invariant.ts @@ -16,8 +16,8 @@ export const inject = ['invariants'] /** * No runtime invariant: this is a browser-side settings surface whose node half owns no event - * stream or mutable runtime data; the layering, write refusals, and exposure boundary are Host - * contracts covered by the owning plugins and the api-proxy. + * stream or mutable runtime data; the layering and write refusals are Host contracts covered by + * the owning plugins and the api-proxy. */ const install: InvariantInstaller = () => {} diff --git a/packages/client/ui-settings-plugins/tests/apply.client.spec.ts b/packages/client/ui-settings-plugins/tests/apply.client.spec.ts index 112f088006..2934097b94 100644 --- a/packages/client/ui-settings-plugins/tests/apply.client.spec.ts +++ b/packages/client/ui-settings-plugins/tests/apply.client.spec.ts @@ -9,19 +9,38 @@ import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-t import { SettingsScopeBinder } from '@deepseek-ai/dsh-client-ui-settings/client' import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-plugins/client' import type { - ConfigurablePluginsTabInjected, PluginsSettingsSectionInjected, + ConfigurablePluginsTabFace, PluginsSettingsSectionInjected, } from '@deepseek-ai/dsh-client-ui-settings-plugins/client' // The service reads its initial locale from the browser; these specs assert // the shipped Chinese copy, so they state the browser they assume. usePinnedBrowserLanguages('zh-CN') -async function bench() { +/** + * @param served - namespaces the Host describes; omitted answers a failed read, + * which is what most of these specs want (no card has anything to render). + */ +async function bench(served?: string[]) { const ctx = new Context() await ctx.plugin(SlotRegistry).await() const locale = new LocaleRuntime(ctx) ctx.provide('locale', locale) const describeCredentials = vi.fn(() => Promise.resolve({ rpcId: 'c', result: { ok: false, error: {} } })) + const describeSettings = vi.fn(() => Promise.resolve(served === undefined + ? { rpcId: 's', result: { ok: false, error: {} } } + : { + rpcId: 's', + result: { + ok: true, + value: { + writable: true, + hasDocument: true, + namespaces: served.map(ns => ({ + ns, schema: {}, value: {}, applies: 'live', secrets: [], revision: 0, + })), + }, + }, + })) // The section binds its scopes through the Settings surface's service, and // forwarded Host events reach it through the same `$dispatch` handoff the // connection sink makes. @@ -29,12 +48,12 @@ async function bench() { ctx.provide('connection', { isLoopback: true, api: { - settings: { describe: vi.fn(() => Promise.resolve({ rpcId: 's', result: { ok: false, error: {} } })) }, + settings: { describe: describeSettings }, credentials: { describe: describeCredentials }, }, } as never) await ctx.plugin(SettingsScopeBinder).await() - return { ctx, slots: ctx.get('slots') as SlotRegistry, describeCredentials } + return { ctx, slots: ctx.get('slots') as SlotRegistry, describeCredentials, describeSettings } } function declareRoot(slots: SlotRegistry): () => void { @@ -63,20 +82,11 @@ describe('ui-settings-plugins apply', () => { const tab = slots.entries('settings.plugins.tab')[0]! expect(tab.options).toMatchObject({ id: 'configurable', order: 0 }) expect(resolveSlotLabel(tab.options.label)).toBe('插件配置') - expect(slots.spec('settings.plugin.item')).toMatchObject({ kind: 'list', scope: 'root' }) + expect(slots.spec('settings.plugin.item')).toMatchObject({ kind: 'keyed', scope: 'root' }) }) - it('registers one card per host-plane section it ships, in a stable order', async () => { - const { ctx, slots } = await bench() - declareRoot(slots) - await ctx.plugin({ inject: [...inject], apply }).await() - - expect(slots.entries('settings.plugin.item').map(entry => entry.options.id)) - .toEqual(['bash', 'agent-loop', 'web-search']) - }) - - it('injects a live tab projection, a card count, and one business face per card', async () => { + it('injects a live tab projection, the card directory, and one business face per card', async () => { const { ctx, slots } = await bench() declareRoot(slots) await ctx.plugin({ inject: [...inject], apply }).await() @@ -99,7 +109,8 @@ describe('ui-settings-plugins apply', () => { unsubscribe() const tab = slots.entries('settings.plugins.tab')[0]! - expect((tab.inject as unknown as () => ConfigurablePluginsTabInjected)()).toEqual({ cardCount: 3 }) + const tabFace = (tab.inject as unknown as () => ConfigurablePluginsTabFace)() + expect(Object.keys(tabFace.hooks)).toEqual(['configurablePlugins']) for (const entry of slots.entries('settings.plugin.item')) { const face = (entry as { inject?: () => unknown }).inject?.() as { hooks: Record } // Each card injects exactly one snapshot store plus its own actions. @@ -107,6 +118,58 @@ describe('ui-settings-plugins apply', () => { } }) + it('keys each card it ships on the settings namespace that card edits', async () => { + const { ctx, slots } = await bench() + declareRoot(slots) + + await ctx.plugin({ inject: [...inject], apply }).await() + + expect(slots.entries('settings.plugin.item').map(entry => entry.options.key)) + .toEqual(['shell', 'agent-loop', 'web-search-deepseek']) + }) + + it('dispatches the served namespaces its cards claim, and no others', async () => { + // ui-theme is served but belongs to another surface, and a deployment + // composing no PowerShell/POSIX executor serves no `bash` at all. + const { ctx, slots } = await bench(['agent-loop', 'ui-theme', 'web-search-deepseek']) + declareRoot(slots) + await ctx.plugin({ inject: [...inject], apply }).await() + + const tab = slots.entries('settings.plugins.tab')[0]! + const face = (tab.inject as unknown as () => ConfigurablePluginsTabFace)() + await vi.waitFor(() => { + expect(face.hooks.configurablePlugins.getSnapshot().namespaces) + .toEqual(['agent-loop', 'web-search-deepseek']) + }) + }) + + it('re-reads the served namespaces when the Host commits a settings document', async () => { + // Which namespaces the Host serves is a registration fact the wire never + // announces on its own, so the tab rides the invalidation that can + // accompany a changed composition. + const { ctx, slots, describeSettings } = await bench(['bash']) + declareRoot(slots) + await ctx.plugin({ inject: [...inject], apply }).await() + await vi.waitFor(() => { expect(describeSettings).toHaveBeenCalled() }) + describeSettings.mockClear() + + ctx.remote.$dispatch('settings/document-updated', ['bash', 1]) + + await vi.waitFor(() => { expect(describeSettings).toHaveBeenCalled() }) + }) + + it('re-reads the served namespaces after a reconnect', async () => { + const { ctx, slots, describeSettings } = await bench(['bash']) + declareRoot(slots) + await ctx.plugin({ inject: [...inject], apply }).await() + await vi.waitFor(() => { expect(describeSettings).toHaveBeenCalled() }) + describeSettings.mockClear() + + ctx.emit('connection/reset') + + await vi.waitFor(() => { expect(describeSettings).toHaveBeenCalled() }) + }) + it('re-reads the credential when the Host reports the watched reference changed', async () => { const { ctx, slots, describeCredentials } = await bench() declareRoot(slots) diff --git a/packages/client/ui-settings-plugins/tests/section.client.spec.tsx b/packages/client/ui-settings-plugins/tests/section.client.spec.tsx index fda55c3bf1..f521d7189f 100644 --- a/packages/client/ui-settings-plugins/tests/section.client.spec.tsx +++ b/packages/client/ui-settings-plugins/tests/section.client.spec.tsx @@ -22,6 +22,7 @@ import type { WebSearchCardProps } from '../src/client/WebSearchCard.tsx' import type { AgentLoopCardState } from '../src/client/agent-loop-card-controller.ts' import type { BashCardState } from '../src/client/bash-card-controller.ts' import type { CardFieldState, CardShell } from '../src/client/card-form.ts' +import type { ConfigurablePluginsTabState } from '../src/client/tab-store.ts' import type { WebSearchCardState } from '../src/client/web-search-card-controller.ts' import { en } from '../src/client/locales.ts' @@ -59,11 +60,20 @@ function renderSection(rows: readonly PluginsSettingsTabEntry[]) { render() } -function renderConfigurable(cardCount: number, cards = 'cards') { +/** + * Render the tab over the namespaces it was told to dispatch, with `cards` + * standing in for the slot ledger: a key it names renders that text, and one + * it does not renders nothing, exactly as an unclaimed key does. + */ +function renderConfigurable(namespaces: string[], cards: Record = {}, loaded = true) { + const store = createSnapshotStore({ loaded, namespaces }) const props = { t, - cardCount, - renderSlot: () =>
  • {cards}
    • , + useConfigurablePlugins: bindSnapshotSelector(store), + renderSlot: (_name: string, _owner: object, opts?: { entryKey?: string }) => { + const card = opts?.entryKey === undefined ? undefined : cards[opts.entryKey] + return card === undefined ? null :
  • {card}
    • + }, } as unknown as ConfigurablePluginsTabProps render() } @@ -153,16 +163,24 @@ describe('PluginsSettingsSection', () => { describe('ConfigurablePluginsTab', () => { it('says so when no plugin contributed a card', () => { - renderConfigurable(0) + renderConfigurable([], { bash: 'shell' }) expect(screen.getByText(en.empty)).toBeTruthy() - expect(screen.queryByText('cards')).toBeNull() + expect(screen.queryByText('shell')).toBeNull() }) - it('renders the card list once a plugin contributed one', () => { - renderConfigurable(1) + it('withholds the empty line until the Host has answered once', () => { + // An unanswered read is not the statement that this deployment configures + // no plugin; saying it anyway would flash a wrong answer on every open. + renderConfigurable([], { bash: 'shell' }, false) - expect(screen.getByText('cards')).toBeTruthy() + expect(screen.queryByText(en.empty)).toBeNull() + }) + + it('dispatches one card per namespace, keyed by it', () => { + renderConfigurable(['bash', 'agent-loop'], { bash: 'shell', 'agent-loop': 'loop' }) + + expect(screen.getAllByRole('listitem').map(item => item.textContent)).toEqual(['shell', 'loop']) expect(screen.queryByText(en.empty)).toBeNull() }) }) diff --git a/packages/client/ui-settings-plugins/tests/stores.client.spec.ts b/packages/client/ui-settings-plugins/tests/stores.client.spec.ts index 15ad7cf76a..9901bc5eb1 100644 --- a/packages/client/ui-settings-plugins/tests/stores.client.spec.ts +++ b/packages/client/ui-settings-plugins/tests/stores.client.spec.ts @@ -8,6 +8,7 @@ import { stubSettingsScope, type StubSettingsScope } from '@deepseek-ai/dsh-clie import { CardForm, numberField, textField } from '../src/client/card-form.ts' import { AgentLoopCardController, type AgentLoopSettings } from '../src/client/agent-loop-card-controller.ts' import { BashCardController, type BashSettings } from '../src/client/bash-card-controller.ts' +import { ConfigurablePluginsTabController } from '../src/client/tab-store.ts' import { WebSearchCardController, type WebSearchSettings } from '../src/client/web-search-card-controller.ts' /** Make the stub behave like a Host that accepts every write. */ @@ -380,7 +381,7 @@ describe('AgentLoopCardController', () => { }) describe('WebSearchCardController', () => { - it('reads the credential state for the reference the section names', async () => { + it('reads the credential state for the reference the tab names', async () => { const host = stubSettingsScope() const credentials = credentialsApi(true) const controller = new WebSearchCardController(host.scope, credentials.api) @@ -460,7 +461,7 @@ describe('WebSearchCardController', () => { }) }) - it('addresses the reference the section declares rather than the default', async () => { + it('addresses the reference the tab declares rather than the default', async () => { const host = stubSettingsScope() const credentials = credentialsApi(false) const controller = new WebSearchCardController(host.scope, credentials.api) @@ -538,3 +539,131 @@ describe('WebSearchCardController', () => { expect(credentials.set).not.toHaveBeenCalled() }) }) + +describe('ConfigurablePluginsTabController', () => { + function settingsApi(namespaces: string[]) { + const describe = vi.fn(() => Promise.resolve({ + rpcId: 's-1' as never, + result: { + ok: true as const, + value: { + writable: true, + hasDocument: true, + namespaces: namespaces.map(ns => ({ + ns, schema: {}, value: {}, applies: 'live' as const, secrets: [], revision: 0, + })), + }, + }, + })) + return { api: { settings: { describe } } as never, describe } + } + + /** Slot ledger stand-in: one stored entry per registered card key. */ + function ledger(...keys: string[]) { + return keys.map(key => ({ component: null, options: { key } })) + } + + it('dispatches the served namespaces a card claims, in card registration order', async () => { + const settings = settingsApi(['bash', 'ui-theme', 'agent-loop']) + const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('agent-loop', 'bash')) + + await controller.load() + + // ui-theme is served but claimed by no card here — another surface owns + // it. The order is the cards', not the Host's: plugin activation can + // reorder the description between boots. + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces) + .toEqual(['agent-loop', 'bash']) + }) + + it('never dispatches a card whose namespace this deployment does not serve', async () => { + const settings = settingsApi(['bash']) + const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash', 'web-search-deepseek')) + + await controller.load() + + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash']) + }) + + it('takes a card registered after the read without asking the Host again', async () => { + const settings = settingsApi(['bash']) + let entries = ledger() + const controller = new ConfigurablePluginsTabController(settings.api, () => entries) + await controller.load() + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual([]) + + entries = ledger('bash') + controller.refresh() + + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash']) + expect(settings.describe).toHaveBeenCalledOnce() + }) + + it('keeps the namespaces it knew when a read fails', async () => { + const settings = settingsApi(['bash']) + const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash')) + await controller.load() + settings.describe.mockRejectedValueOnce(new Error('offline')) + + await controller.load() + + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash']) + }) + + it('publishes nothing once disposed, and never claims it was answered', async () => { + const settings = settingsApi(['bash']) + const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash')) + + controller.dispose() + await controller.load() + + expect(controller.inject().hooks.configurablePlugins.getSnapshot()) + .toEqual({ loaded: false, namespaces: [] }) + expect(settings.describe).not.toHaveBeenCalled() + }) + + it('ignores a slot-ledger change that arrives after disposal', async () => { + const settings = settingsApi(['bash']) + let entries = ledger() + const controller = new ConfigurablePluginsTabController(settings.api, () => entries) + await controller.load() + + controller.dispose() + entries = ledger('bash') + controller.refresh() + + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual([]) + }) + + it('drops a read a newer one superseded', async () => { + // The section re-reads on every settings-document invalidation, so a slow + // first answer must not overwrite the newer one that already landed. + const settings = settingsApi(['bash']) + const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash', 'agent-loop')) + const slow = Promise.withResolvers() + settings.describe.mockReturnValueOnce(slow.promise as never) + const stale = controller.load() + + await controller.load() + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash']) + slow.resolve({ + rpcId: 's-0', + result: { ok: true, value: { writable: true, hasDocument: true, namespaces: [ + { ns: 'agent-loop', schema: {}, value: {}, applies: 'live', secrets: [], revision: 0 }, + ] } }, + }) + await stale + + expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash']) + }) + + it('reports the Host answered even when it serves nothing this tab shows', async () => { + const settings = settingsApi(['ui-theme']) + const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash')) + + await controller.load() + + expect(controller.inject().hooks.configurablePlugins.getSnapshot()) + .toEqual({ loaded: true, namespaces: [] }) + }) +}) diff --git a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css index c0b83182d2..8d01f8e3df 100644 --- a/packages/client/ui-user-questions/src/client/QuestionComposer.module.css +++ b/packages/client/ui-user-questions/src/client/QuestionComposer.module.css @@ -39,6 +39,28 @@ box-sizing: border-box; } +/* Collapsed to the header strip: drop the height cap and the inner scroll + seat so the card hugs the title row, freeing the viewport for the + conversation above while the question stays pending. */ +.cardMinimized { + max-height: none; +} + +/* The header strip is the whole card when collapsed: the title row needs + bottom padding once the body that normally carries it is hidden. */ +.cardMinimized .header { + padding-bottom: 14px; +} + +/* Header button group: minimize sits next to the close action, both on the + same 24px icon-button grid. */ +.headerActions { + display: flex; + align-items: center; + gap: 4px; + flex-shrink: 0; +} + /* Figma 1019:36938 header, user-tuned: heading block left, close right; the pager sits in the footer to balance the card. */ .header { diff --git a/packages/client/ui-user-questions/src/client/QuestionComposer.tsx b/packages/client/ui-user-questions/src/client/QuestionComposer.tsx index 596e1ec727..8aa7f0daef 100644 --- a/packages/client/ui-user-questions/src/client/QuestionComposer.tsx +++ b/packages/client/ui-user-questions/src/client/QuestionComposer.tsx @@ -1,8 +1,9 @@ -import { useMemo, useState, type ChangeEvent, type KeyboardEvent } from 'react' +import { useMemo, useRef, useState, type ChangeEvent, type KeyboardEvent } from 'react' import clsx from 'clsx' import { - Button, IconCheckOutline14, IconChevronLeftOutline14, IconChevronRightOutline14, - IconCloseOutline16, IconEditOutline16, MarkdownText, + Button, IconCheckOutline14, IconChevronDownOutline14, IconChevronLeftOutline14, + IconChevronRightOutline14, IconChevronUpOutline14, IconCloseOutline16, + IconEditOutline16, MarkdownText, } from '@deepseek-ai/dsh-client-ui-primitives' import { PendingQuestion, planReviewOf, @@ -75,6 +76,13 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick(null) const [error, setError] = useState(null) + // Collapsed to the header strip so the conversation above stays readable + // while the user decides; the drafts survive because the state lives here. + const [minimized, setMinimized] = useState(false) + // The free-form textarea autofocuses on first presentation; re-expanding a + // collapsed question must not steal focus from the expand toggle back into + // the input, so focus is granted once per question index. + const focusedQuestions = useRef(new Set()) // index stays in bounds (every setIndex site clamps) and drafts mirrors questions 1:1. // oxlint-disable-next-line typescript/no-non-null-assertion const question = questions[index]! @@ -191,7 +199,10 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick -
    +
    {question.header !== undefined &&
    {question.header}
    } @@ -199,138 +210,155 @@ function QuestionFlow({ pending, t }: { pending: PendingQuestion } & Pick
    - +
    + + +
    -
    - {question.detail !== undefined && ( -
    - )} -
    - {(question.options ?? []).map((option, optionIndex) => { - const selected = draft.selected.includes(option.label) - const display = parseRecommendedLabel(option.label) - return ( - - ) - })} - - {hasOptions - ? ( -
    - {question.multiSelect === true - ? ( - - ) - : ( - - )} - -
    - ) - : ( -