From 7c38fd8102be7a8a36adf63e8049afd265acda46 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 15:30:35 +0800 Subject: [PATCH 01/63] fix: deliver images reliably with steer and follow-up messages A steer or follow-up accepted while a turn is closing is now claimed by a fresh turn at the driver's clean exit instead of stranding in the inbox; cancellation and pre-step rejection still park accepted work. Continuable subagent follow-ups accept image parts: the wire is upload-shaped, the Host admits and persists each batch before inbox acceptance, and delivery is refused when the child model declines image input. The queue dock renders durable image thumbnails instead of an [image] text marker. Fixes #3186 --- ...27-steer-followup-image-delivery.i18n.yaml | 6 + ...026-08-27-steer-followup-image-delivery.md | 41 +++++ ...-08-27-steer-followup-image-delivery.zh.md | 41 +++++ apps/web/tests/queue-image.e2e.ts | 147 ++++++++++++++++++ apps/web/tsconfig.json | 1 + docs/architecture.i18n.yaml | 4 +- docs/architecture.md | 2 +- docs/architecture.zh.md | 2 +- docs/subsystems/subagent.i18n.yaml | 4 +- docs/subsystems/subagent.md | 8 +- docs/subsystems/subagent.zh.md | 8 +- .../src/client/contract/session.ts | 4 +- .../src/client/sessions/queue-mirror.ts | 3 + .../src/client/sessions/session.ts | 31 ++-- .../api/session-controller/src/commands.ts | 23 +-- packages/api/session-controller/src/types.ts | 12 +- .../tests/queue-store.client.spec.ts | 6 +- .../tests/session-models.host.spec.ts | 52 +++++++ .../tests/session.client.spec.ts | 26 ++++ packages/attachment/attachment/src/index.ts | 1 + packages/attachment/attachment/src/types.ts | 15 ++ .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 2 +- .../src/client/image-labels.ts | 1 - .../ui-conversation/src/client/locales.ts | 4 +- .../src/client/queue/QueueDock.module.css | 15 ++ .../src/client/queue/QueueDock.tsx | 63 +++++++- .../tests/image-labels.client.spec.ts | 1 - .../tests/queue-dock.client.spec.tsx | 64 +++++++- packages/core/agent-loop/src/agent.ts | 49 +++++- packages/core/agent-loop/tests/loop.spec.ts | 80 ++++++++++ .../src/client/api-catalog.ts | 4 - .../extensions/tool-cordis/src/api-catalog.ts | 6 +- packages/llm/llm/src/content.ts | 28 +++- packages/llm/llm/tests/content.spec.ts | 31 ++++ packages/subagent/subagent/README.i18n.yaml | 4 +- packages/subagent/subagent/README.md | 2 +- packages/subagent/subagent/README.zh.md | 2 +- packages/subagent/subagent/package.json | 2 + .../subagent/subagent/src/continuation.ts | 41 ++++- .../subagent/subagent/src/control-types.ts | 12 +- packages/subagent/subagent/src/control.ts | 6 + packages/subagent/subagent/src/index.ts | 13 +- .../subagent/tests/continuation.spec.ts | 68 ++++++++ .../subagent/subagent/tests/control.spec.ts | 67 +++++++- pnpm-lock.yaml | 3 + .../web/queued-image/delivered.expected.md | 82 ++++++++++ snapshots/web/queued-image/queued.expected.md | 42 +++++ snapshots/web/queued-image/snapshot.yml | 9 ++ tsconfig.host.json | 1 + 51 files changed, 1037 insertions(+), 108 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md create mode 100644 .agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md create mode 100644 apps/web/tests/queue-image.e2e.ts create mode 100644 snapshots/web/queued-image/delivered.expected.md create mode 100644 snapshots/web/queued-image/queued.expected.md create mode 100644 snapshots/web/queued-image/snapshot.yml diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml new file mode 100644 index 0000000000..8f4d10d9e8 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.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-27-steer-followup-image-delivery.md +2026-08-27-steer-followup-image-delivery.md: fb93612254381b589c8adfe44e46c51dfe232c3e +2026-08-27-steer-followup-image-delivery.zh.md: 35284aba89a7df5da5d472f078d2c2d3ea2e307d diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md new file mode 100644 index 0000000000..fb93612254 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md @@ -0,0 +1,41 @@ +# Agent Note: Steer and follow-up image delivery + +Status: implemented + +English | [中文](2026-08-27-steer-followup-image-delivery.zh.md) + +## Problem + +Images submitted while an agent is running did not reliably reach the model context (#3186), for three independent reasons. + +First, a steer or follow-up spliced into a live driver latched no wake: the live driver was expected to claim it, but a turn that finished or failed between the splice and the claim exited without re-checking, stranding the accepted message until an unrelated waking send. Image admission widens this window because the Host awaits attachment normalization before `agent.steer()`/`agent.followup()` runs. + +Second, continuable-subagent follow-ups rejected images in the Client (`SUBAGENT_IMAGE_UNSUPPORTED`) before any RPC, and stripped image parts from the text-only call. The Host route had no admission at all, and its wire content was `ContentBlock[]`, so lifting the Client rejection alone would have let a browser cite any `attachmentId` it never uploaded. + +Third, the browser queue projection reduced a queued image to the text `[image]` even though the durable reference was already present and readable through the session attachment authorization. + +## Decision + +**Closing-turn wake delivery.** `ReactLoopAgent` tracks the identities of waking sends still awaiting a claim (`pendingWakes`); claim and discard notifications prune the set. At a driver exit whose turn loop returned without throwing, a non-empty set re-wakes the driver, so a steer or follow-up that lost the race with a normally closing turn is claimed by a fresh turn. Cancellation and `agent/pre-step` rejection instead clear the set: accepted-but-unclaimed input parks until the next waking send, preserving the tested `cancel({ keepInbox: true })` semantics and keeping rejected claims from being re-offered to the rejecting policy. Injected context never enters the set. The turn-flow section of [docs/architecture.md](../../../../docs/architecture.md) records the delivery/parking rule. + +**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]`, whose single home moved from `dsh-api-session-controller` to `dsh-attachment`; the shared `durablePromptContent()` conversion lives in `dsh-llm/content` and is used by both the Session prompt endpoint and `SubagentRuntime.prompt`. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. + +**Queue presentation.** The queue mirror's text preview excludes image blocks, and the queue dock renders each durable image part as a thumbnail resolved through `ctx.uiConversation.imageUrl` — the same session-authorized read the transcript uses. Editing queued image messages stays refused (#3072). + +## Alternatives considered + +**Re-wake on every driver exit with pending input.** Rejected: it breaks the deliberate parking semantics of `cancel({ keepInbox: true })` and pre-step rejection, and a pre-commit `turn/start` failure would re-enter a hot loop because the failing turn never claims the message. + +**Latch `wakeRequested` for sends to a live driver.** Rejected: the latch is not pruned on claim, so a claimed steer plus leftover injected context would open a context-only turn at exit, violating the rule that injected context waits for a waking message. + +**Keep the wire content `ContentBlock[]` and admit refs on the Host.** Rejected: a reference-shaped wire lets a Client fabricate `attachmentId` citations; an upload-shaped wire makes Host admission the only way an attachment reference can exist in a child message. + +**Check child image capability in `SubagentRuntime.prompt`.** Rejected: the route may address a cold child whose agent does not exist yet; the continuation manager sees the live or freshly materialized agent in both arms and inside the per-child delivery lock, so the check cannot race a concurrent delivery. + +## Testing + +Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, queue thumbnails (load, failure placeholder, unmount), and the image-free preview. + +## Consequences + +A steer or follow-up accepted during a turn's final microtasks is now delivered by a fresh turn instead of hanging in the inbox, while user cancellation still parks pending work — delivery after a stop remains an explicit next waking send. The subagent package now depends on `dsh-attachment` and reads `ctx.llm` optionally. Images persisted by a batch whose delivery is later refused stay as unreachable content-addressed objects under the existing retention rules. Queue thumbnails add one authorized attachment read per queued image, shared with the transcript cache. diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md new file mode 100644 index 0000000000..35284aba89 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md @@ -0,0 +1,41 @@ +# Agent Note: steer 与 follow-up 的图片投递 + +Status: implemented + +[English](2026-08-27-steer-followup-image-delivery.md) | 中文 + +## Problem + +agent 运行期间提交的图片没有可靠进入模型上下文（#3186），原因有三个，彼此独立。 + +第一，splice 进在线 driver 的 steer 或 follow-up 不会锁存唤醒：预期由在线 driver 自行认领，但轮次在 splice 与认领之间正常结束或失败时，退出路径不再复查，已接受的消息就滞留到下一次无关的唤醒发送。图片准入放大了这个窗口，因为 Host 在执行 `agent.steer()`/`agent.followup()` 之前要先等待附件规范化完成。 + +第二，可继续子代理的 follow-up 在客户端就拒绝图片（`SUBAGENT_IMAGE_UNSUPPORTED`），并把图片部分从纯文本调用中剥掉。Host 路由完全没有准入，wire 内容又是 `ContentBlock[]`，单独放开客户端拒绝会允许浏览器引用任何它从未上传过的 `attachmentId`。 + +第三，浏览器队列投影把已排队的图片折叠成文本 `[image]`，尽管持久化引用已经存在，并且可以通过会话附件授权读取。 + +## Decision + +**轮次收尾期的唤醒投递。** `ReactLoopAgent` 用 `pendingWakes` 记录尚未被认领的唤醒发送的身份；认领与丢弃通知会移除对应条目。当 driver 的轮次循环无异常返回并退出时，集合非空就重新拉起 driver，输掉与正常收尾轮次竞态的 steer 或 follow-up 由新轮次认领。取消与 `agent/pre-step` 拒绝则清空该集合：已接受但未认领的输入停放到下一次唤醒发送，既保留了有测试保护的 `cancel({ keepInbox: true })` 语义，也避免把被拒绝的认领重新塞给同一个拒绝策略。注入的上下文从不进入该集合。投递与停放规则记录在 [docs/architecture.md](../../../../docs/architecture.zh.md) 的 turn-flow 一节。 + +**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`，该类型的唯一定义处从 `dsh-api-session-controller` 移到 `dsh-attachment`；共享的 `durablePromptContent()` 转换位于 `dsh-llm/content`，Session prompt 端点与 `SubagentRuntime.prompt` 共用。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 + +**队列展示。** 队列镜像的文本预览不再包含图片块，queue dock 把每个持久化图片部分渲染为缩略图，经 `ctx.uiConversation.imageUrl` 解析，与会话记录使用同一个会话授权读取。已排队图片消息的编辑仍然拒绝（#3072）。 + +## Alternatives considered + +**任何 driver 退出都在有滞留输入时重新拉起。** 拒绝：这破坏 `cancel({ keepInbox: true })` 与 pre-step 拒绝的刻意停放语义，而且 `turn/start` 提交前失败的轮次永远不会认领消息，会进入热循环。 + +**对发给在线 driver 的发送也锁存 `wakeRequested`。** 拒绝：锁存不随认领清除，被认领的 steer 加上剩余的注入上下文会在退出时开出一个只有上下文的轮次，违反注入上下文必须等待唤醒消息的规则。 + +**wire 内容保持 `ContentBlock[]`，由 Host 准入引用。** 拒绝：引用形态的 wire 允许客户端伪造 `attachmentId`；上传形态的 wire 使 Host 准入成为子级消息里附件引用的唯一来源。 + +**在 `SubagentRuntime.prompt` 里做子级图片能力检查。** 拒绝：该路由可能寻址冷的子级，其 agent 尚不存在；continuation 管理器在两条分支里都拿得到在线或刚物化的 agent，并且处于逐子级投递锁内，检查不会与并发投递竞态。 + +## Testing + +agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、队列缩略图（加载、失败占位、卸载）与不含图片的预览。 + +## Consequences + +在轮次最后几个微任务里被接受的 steer 或 follow-up 现在由新轮次投递，而不是挂在 inbox 里；用户取消仍然停放待处理工作，停止之后的投递依旧需要一次显式的唤醒发送。subagent 包新增对 `dsh-attachment` 的依赖，并可选读取 `ctx.llm`。整批持久化后投递被拒绝的图片按现有保留规则保持为不可达的内容寻址对象。队列缩略图对每张排队图片增加一次授权附件读取，与会话记录缓存共享。 diff --git a/apps/web/tests/queue-image.e2e.ts b/apps/web/tests/queue-image.e2e.ts new file mode 100644 index 0000000000..e5a4794d82 --- /dev/null +++ b/apps/web/tests/queue-image.e2e.ts @@ -0,0 +1,147 @@ +// Keyless browser coverage for image attachments submitted while a turn is +// running, through the shipped Web composition and real HTTP/SSE wire. A +// text-plus-image submission queues as one occurrence whose dock row renders +// the durable thumbnail, survives a stop as parked work, and delivers as the +// next turn's user message with its image intact — while the session log holds +// only durable attachment references, never base64. +import { existsSync } from 'node:fs' +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { fileURLToPath } from 'node:url' +import { join } from 'node:path' +import type { Browser, Page } from 'playwright' +import { chromium } from 'playwright' +import { afterEach, describe, expect, it, onTestFailed } from 'vitest' +import { deriveReplayScript, parseSessionLog, type ReplayEntry } from '@deepseek-ai/dsh-llm-replay' +import type { SessionEvent } from '@deepseek-ai/dsh-session' +import { + captureStableAria, compareOrRefreshGolden, + launchWebScaffold, watchConsole, webSnapshotMode, type WebScaffold, +} from './scaffold.ts' +import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts' + +const SNAPSHOT_DIR = fileURLToPath(new URL('../../../snapshots/web/queued-image', import.meta.url)) +const FIXTURE = fileURLToPath(new URL('../../../snapshots/web/live-interactions/session.jsonl', import.meta.url)) +const PNG = fileURLToPath(new URL('../../../snapshots/session/read-image/workspace/red.png', import.meta.url)) +const QUEUED_EXPECTED = join(SNAPSHOT_DIR, 'queued.expected.md') +const DELIVERED_EXPECTED = join(SNAPSHOT_DIR, 'delivered.expected.md') +const MODE = webSnapshotMode() + +const ACTIVE_PROMPT = 'Reply with a one-sentence description of event sourcing, then stop.' +const QUEUED_TEXT = 'Compare with this screenshot' + +/** Paste one real PNG into the composer through a genuine clipboard event. */ +async function pasteImage(page: Page, bytes: Uint8Array): Promise { + await page.locator('[data-composer-input]').first().evaluate((surface, data) => { + const transfer = new DataTransfer() + transfer.items.add(new File([new Uint8Array(data)], 'queued.png', { type: 'image/png' })) + surface.dispatchEvent(new ClipboardEvent('paste', { + clipboardData: transfer, bubbles: true, cancelable: true, + })) + }, [...bytes]) +} + +describe('web e2e: queued image submission', () => { + let scaffold: WebScaffold | undefined + let browser: Browser | undefined + let page: Page + let overrideDir: string | undefined + + afterEach(async () => { + const failures: unknown[] = [] + await browser?.close().catch((error: unknown) => failures.push(error)) + browser = undefined + const closing = scaffold + scaffold = undefined + await closing?.close().catch((error: unknown) => failures.push(error)) + if (overrideDir !== undefined) { + await rm(overrideDir, { recursive: true, force: true }) + .catch((error: unknown) => failures.push(error)) + } + overrideDir = undefined + if (failures.length === 1) throw failures[0] + if (failures.length > 1) throw new AggregateError(failures, 'queued-image teardown failed') + }) + + it.skipIf(MODE === 'record')('queues a text-plus-image submission with a thumbnail and delivers it as the next turn', async () => { + overrideDir = await mkdtemp(join(tmpdir(), 'dsh-web-queued-image-')) + const readyFile = join(overrideDir, '.hang-ready') + const overridePath = join(overrideDir, 'replay.override.json') + const recorded = deriveReplayScript(parseSessionLog(await readFile(FIXTURE, 'utf8'))) + expect(recorded).toHaveLength(1) + const replay: ReplayEntry[] = [ + { kind: 'hang', readyFile }, + recorded[0]!, + recorded[0]!, + ] + await writeFile(overridePath, JSON.stringify(replay)) + + const sessionEvents: SessionEvent[] = [] + scaffold = await launchWebScaffold({ replayFixture: FIXTURE, replayOverride: overridePath, compareReplaySession: false }) + scaffold.ctx.on('session/event', (_session, event: SessionEvent) => { sessionEvents.push(event) }) + browser = await chromium.launch() + page = await newEnglishPage(browser) + const tripwire = watchConsole(page) + await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) + await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) + await connectFreshWorkspace(page, scaffold.workspaceCwd) + onTestFailed(() => saveFailureShot(page, 'web-e2e-queued-image')) + + const input = page.locator('[data-composer-input]').first() + const firstSettled = scaffold.whenTurnSettled() + await input.fill(ACTIVE_PROMPT) + await input.press('Enter') + await expect.poll(() => existsSync(readyFile), { timeout: 15_000 }).toBe(true) + + // A just-submitted composer is read-only for the prompt round-trip. + await page.locator('[data-composer-input][contenteditable="true"]').first().waitFor({ timeout: 10_000 }) + await pasteImage(page, await readFile(PNG)) + await page.getByRole('img', { name: 'queued.png' }).waitFor({ timeout: 10_000 }) + await input.fill(QUEUED_TEXT) + await input.press('Enter') + + // The queued row renders the durable thumbnail beside the text preview. + const dockThumb = page.locator('[data-queue-dock] img[alt="Queued message image"]') + await dockThumb.waitFor({ timeout: 15_000 }) + await expect.poll(() => dockThumb.getAttribute('src')).toMatch(/^blob:/) + await page.getByText(QUEUED_TEXT, { exact: true }).waitFor() + const queuedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(QUEUED_EXPECTED, queuedSnapshot, MODE) + + // Stop parks the accepted queue; the next waking send delivers the image + // message first (FIFO), then its own text as the following turn. + await page.getByRole('button', { name: 'Stop generating' }).click() + await firstSettled + await expect.poll(() => page.getByRole('button', { name: 'Stop generating' }).count()).toBe(0) + await dockThumb.waitFor({ timeout: 10_000 }) + + const settled = scaffold.whenTurnSettled() + await input.fill('Continue with the queued comparison') + await input.press('Enter') + await settled + + // The delivered user message renders its image in Chat from the durable + // reference, and the dock row is gone. + await expect.poll( + () => page.locator('[data-queue-dock]').count(), + { timeout: 15_000 }, + ).toBe(0) + const chatImage = page.locator('[class*="userRow"] img') + await chatImage.first().waitFor({ timeout: 15_000 }) + const deliveredSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) + await compareOrRefreshGolden(DELIVERED_EXPECTED, deliveredSnapshot, MODE) + + // Model-visible means logged: the delivered message carries the durable + // reference (never base64), in the composer's canonical images-then-text order. + const delivered = sessionEvents.find(event => event.type === 'user/message' + && event.data.content.some(block => block.type === 'image')) + expect(delivered?.type === 'user/message' && delivered.data.content.map(block => block.type)).toEqual(['image', 'text']) + const imageBlock = delivered?.type === 'user/message' + ? delivered.data.content.find(block => block.type === 'image') + : undefined + expect(imageBlock?.type === 'image' && imageBlock.attachment.name).toBe('queued.png') + expect(JSON.stringify(sessionEvents)).not.toContain('base64') + expect(tripwire.pageErrors).toEqual([]) + expect(tripwire.warnings).toEqual([]) + }, 120_000) +}) diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json index f261db5614..03f5a08a75 100644 --- a/apps/web/tsconfig.json +++ b/apps/web/tsconfig.json @@ -73,6 +73,7 @@ "tests/markdown-cjk-strong.e2e.ts", "tests/markdown-inline-code-links.e2e.ts", "tests/queue-actions.e2e.ts", + "tests/queue-image.e2e.ts", "tests/skill-invocation-policy.e2e.ts", "tests/skill-user-invoke.e2e.ts", "tests/permission-policy-context.e2e.ts", diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index 5169a54f8b..9c98358b90 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: 20d03c079fa8e1f73f733992b6e938f0f539a60f -architecture.zh.md: 5448036ad6e11902e32f89d0a65be99230e27e02 +architecture.md: 5717bf62b0967ff860dee9db5265d8dd56242a1d +architecture.zh.md: 279d8c4cc040bc18f7adfd1ae1b782447c3333d6 diff --git a/docs/architecture.md b/docs/architecture.md index 20d03c079f..5717bf62b0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -94,7 +94,7 @@ turn/end `turn/*`, `step/*`, `user/message`, `assistant/*`, and `tool/*` are durable session events; the rest are live extension points across three domains. `agent/pre-step`, `agent/request`, `llm/stream`, and the three `tools/*` events are waterfalls, whose listeners must call `next()` to delegate; `agent/turn-stopping` is serial and has no `next()`. -Input reaches the driver through one inbox. Some messages wake it immediately; injected context waits in the inbox until another message does. +Input reaches the driver through one inbox. Some messages wake it immediately; injected context waits in the inbox until another message does. A waking message that arrives while a turn is closing is claimed by a fresh turn at the driver's clean exit, while cancellation and step rejection park accepted-but-unclaimed input until the next waking send. `agent/pre-step` decides what the model sees. Listeners may rewrite the claimed messages or reject them outright; a rejected or empty first claim still closes a durable turn that spent no step, so the log records the attempt. An enter decision may also set `startsRequestSeries` to begin a distinct model-message series: the loop then logs a fresh `request/header` (reason `series`, or `change` carrying `startsSeries: true` when the envelope changed too). A listener that rebuilds a downstream enter decision must spread it (`{ ...decision, messages }`) so the declaration survives. Each step reads the prompt sections and tool schemas that plugins registered. diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index 5448036ad6..279d8c4cc0 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -98,7 +98,7 @@ turn/end `turn/*`、`step/*`、`user/message`、`assistant/*` 和 `tool/*` 是持久会话事件；其余是分属三个事件域的实时扩展点。`agent/pre-step`、`agent/request`、`llm/stream` 和三个 `tools/*` 事件是 waterfall（瀑布式事件），其监听器必须调用 `next()` 才能委托下去；`agent/turn-stopping` 是 serial 事件，没有 `next()`。 -输入通过同一个 inbox 到达驱动器。有些消息会立即唤醒它；注入的上下文会留在 inbox 中，直到另一条消息将其唤醒。 +输入通过同一个 inbox 到达驱动器。有些消息会立即唤醒它；注入的上下文会留在 inbox 中，直到另一条消息将其唤醒。在轮次收尾期间到达的唤醒消息会在驱动器干净退出时由新轮次认领；取消与步骤拒绝则把已接受但未认领的输入停放到下一次唤醒发送。 `agent/pre-step` 决定模型看到什么。监听器可以改写已领取的消息，也可以直接拒绝它们；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，因此日志会记录这次尝试。enter 决策还可以设置 `startsRequestSeries` 来开启独立的模型消息序列：loop 会随之记录一个新的 `request/header`（原因为 `series`，或在封装同时变化时为携带 `startsSeries: true` 的 `change`）。重建下游 enter 决策的监听器必须展开它（`{ ...decision, messages }`），该声明才能存活。每个步骤读取插件注册的提示词片段和工具 schema。 diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml index f4414983b1..8aa69ce9a2 100644 --- a/docs/subsystems/subagent.i18n.yaml +++ b/docs/subsystems/subagent.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/subagent.md -subagent.md: f854711f1161ba1c533fdbc43d7d6c35681f2f7f -subagent.zh.md: 960d9b099d915fcf5b1e321ab74374664bb8e468 +subagent.md: 03d32139157b2f2c2bf9b58ce8f0ea36d2187a66 +subagent.zh.md: 61bb2f32d1eb85a894dfbd40fc259fbdab8924de diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md index f854711f11..03d3213915 100644 --- a/docs/subsystems/subagent.md +++ b/docs/subsystems/subagent.md @@ -669,13 +669,15 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise diff --git a/docs/subsystems/subagent.zh.md b/docs/subsystems/subagent.zh.md index 960d9b099d..61bb2f32d1 100644 --- a/docs/subsystems/subagent.zh.md +++ b/docs/subsystems/subagent.zh.md @@ -673,13 +673,15 @@ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts index 6ac4182bb9..fc97dbff8e 100644 --- a/packages/api/session-controller/src/client/contract/session.ts +++ b/packages/api/session-controller/src/client/contract/session.ts @@ -7,12 +7,12 @@ * must stub); implementation-internal entry points (history staging, wire-frame * dispatch) stay on the class, invisible out here. */ -import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' +import type { AttachmentIdType, ImageAttachmentRef, PromptContentPart } from '@deepseek-ai/dsh-attachment' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store' -import type { PromptContentPart, QueueAction } from '../../types.ts' +import type { QueueAction } from '../../types.ts' import type { ClientResult } from './result.ts' import type { SessionSnapshot } from './snapshot.ts' diff --git a/packages/api/session-controller/src/client/sessions/queue-mirror.ts b/packages/api/session-controller/src/client/sessions/queue-mirror.ts index 209349af2c..8ae4539607 100644 --- a/packages/api/session-controller/src/client/sessions/queue-mirror.ts +++ b/packages/api/session-controller/src/client/sessions/queue-mirror.ts @@ -5,8 +5,11 @@ import type { QueuedMessage } from '../contract/snapshot.ts' const QUEUE_PREVIEW_CHARS = 200 +// Image blocks are excluded: queue presentation renders them as thumbnails +// from `content`, so the text preview covers only what has no visual form. function previewOf(content: readonly ContentBlock[]): string { const flat = content + .filter(block => block.type !== 'image') .map(block => (block.type === 'text' ? block.text : `[${block.type}]`)) .join(' ').replace(/\s+/g, ' ').trim() const chars = Array.from(flat) diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts index db7cf9a997..4645d7d334 100644 --- a/packages/api/session-controller/src/client/sessions/session.ts +++ b/packages/api/session-controller/src/client/sessions/session.ts @@ -208,28 +208,15 @@ export class Session implements SessionFace { }, } } else { - if (content.some(part => part.type === 'image')) { - result = { - ok: false, - error: { - code: 'attachment-error', - message: 'Image input is unavailable for subagent continuations.', - details: { reason: 'SUBAGENT_IMAGE_UNSUPPORTED' }, - }, - } - } else { - const routed = toSessionResult(await this.remote.subagents.prompt({ - requestId: randomUUID() as SessionRequestId, - parentSessionId: this.address.parentSessionId, - childSessionId: this.address.childSessionId, - mode: this.address.mode, - content: content.flatMap(part => part.type === 'text' - ? [{ type: 'text' as const, text: part.text }] - : []), - clientTimeZone: resolvedClientTimeZone(), - }, signal)) - result = routed.ok ? { ok: true, value: { accepted: true } } : routed - } + const routed = toSessionResult(await this.remote.subagents.prompt({ + requestId: randomUUID() as SessionRequestId, + parentSessionId: this.address.parentSessionId, + childSessionId: this.address.childSessionId, + mode: this.address.mode, + content, + clientTimeZone: resolvedClientTimeZone(), + }, signal)) + result = routed.ok ? { ok: true, value: { accepted: true } } : routed } } catch (error) { result = transportResult(error) diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts index 48c41f3aa1..be2b8304e2 100644 --- a/packages/api/session-controller/src/commands.ts +++ b/packages/api/session-controller/src/commands.ts @@ -4,12 +4,12 @@ import { randomUUID } from 'node:crypto' import type { Context } from '@deepseek-ai/cordis' import type { Agent, ModelSelection as AgentModelSelection } from '@deepseek-ai/dsh-agent' import { PresetMountError, UnknownPresetError } from '@deepseek-ai/dsh-agent-presets' -import { AttachmentError, admitEncodedImages } from '@deepseek-ai/dsh-attachment' +import { AttachmentError } from '@deepseek-ai/dsh-attachment' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import { - ReasoningEffortId, createUserMessage, freezeMessage, + ReasoningEffortId, createUserMessage, durablePromptContent, freezeMessage, } from '@deepseek-ai/dsh-llm' -import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm' +import type { MessageSource } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { SessionEvent, SessionHeader, UserMessage } from '@deepseek-ai/dsh-session' import { SessionQueryError, type SessionObservation } from '@deepseek-ai/dsh-session-query' @@ -319,7 +319,7 @@ export class SessionCommandController { ) } } - const content = await durablePromptContent(this.ctx, request.content) + const content = await durablePromptContent(this.ctx.attachments, request.content) const message: UserMessage = createUserMessage({ content, source }) if (request.mode === 'steer') agent.steer(message) else agent.followup(message) @@ -511,21 +511,6 @@ function reject(code: string, message: string, details: object): never { throw new TypertRemoteFailure({ code, message, details }) } -async function durablePromptContent( - ctx: Context, - content: readonly SessionPromptRequest['content'][number][], -): Promise { - if (content.every(part => part.type === 'text')) { - return content.map(part => ({ type: 'text', text: part.text })) - } - const refs = await admitEncodedImages(ctx.attachments, content.filter(part => part.type === 'image')) - let next = 0 - return content.map(part => part.type === 'text' - ? { type: 'text', text: part.text } - // admitEncodedImages returns one reference per image part in order. - : { type: 'image', attachment: refs[next++] as ImageAttachmentRef }) -} - function imageBlockIn( content: unknown, match: (ref: ImageAttachmentRef) => boolean, diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index c045e00707..c58eb419ca 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -1,7 +1,7 @@ /** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */ import type { - AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, + AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, PromptContentPart, } from '@deepseek-ai/dsh-attachment' import type { Branded } from '@deepseek-ai/dsh-brand' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' @@ -67,15 +67,7 @@ export interface SessionProjectionBaseline { export type SessionProjectionValues = Partial & Readonly> -/** Browser-submitted prompt content; the Host promotes image bytes to durable references. */ -export type PromptContentPart = - | { readonly type: 'text'; readonly text: string } - | { - readonly type: 'image' - readonly mediaType: ImageMediaType - readonly data: string - readonly name?: string - } +export type { PromptContentPart } from '@deepseek-ai/dsh-attachment' /** Complete model selection for one Session. */ export interface ModelSelection { diff --git a/packages/api/session-controller/tests/queue-store.client.spec.ts b/packages/api/session-controller/tests/queue-store.client.spec.ts index 6fc045cf70..856a861d5a 100644 --- a/packages/api/session-controller/tests/queue-store.client.spec.ts +++ b/packages/api/session-controller/tests/queue-store.client.spec.ts @@ -73,7 +73,7 @@ describe('Session queue snapshot intake', () => { ]) }) - it('marks mixed-content messages non-editable while retaining their preview', () => { + it('marks mixed-content messages non-editable and keeps image blocks out of the text preview', () => { const session = makeSession() session.handleControlFrame(queueFrame([{ id: 'q-image', @@ -86,7 +86,9 @@ describe('Session queue snapshot intake', () => { { id: 'q-image', placement: 'queued', content: [{ type: 'text', text: 'hi' }, { type: 'image', data: 'x' }], - preview: 'hi [image]', text: null, + // Image blocks render as thumbnails from `content`, so the preview + // carries only the text; non-image foreign blocks keep their marker. + preview: 'hi', text: null, }, ]) }) diff --git a/packages/api/session-controller/tests/session-models.host.spec.ts b/packages/api/session-controller/tests/session-models.host.spec.ts index d203585459..b38ee0f94c 100644 --- a/packages/api/session-controller/tests/session-models.host.spec.ts +++ b/packages/api/session-controller/tests/session-models.host.spec.ts @@ -231,6 +231,58 @@ describe('Web session model selection', () => { await ctx.fiber.dispose() }) + it('delivers an admitted image batch through steer with the same ordered content as queue', async () => { + const { ctx, agent, sessionId } = await harness() + const attachments = { + imageLimits: { + maxImageBytes: 4, + maxImagesPerMessage: 2, + maxMessageImageBytes: 4, + maxImagePixels: 4, + maxImageDimension: 2000, + mediaTypes: ['image/png'], + }, + validateImage: vi.fn(() => Promise.resolve()), + saveImage: vi.fn((input: { data: Uint8Array; mediaType: 'image/png'; name?: string }) => Promise.resolve({ + attachmentId: `att-${String(input.data[0])}`, + mediaType: input.mediaType, + bytes: input.data.byteLength, + width: 1, + height: 1, + ...input.name === undefined ? {} : { name: input.name }, + })), + } + ctx.provide('attachments', Object.setPrototypeOf(attachments, AttachmentStore.prototype) as never) + const steer = vi.fn() + const followup = vi.fn() + Object.assign(agent, { steer, followup }) + const remote = createSessionTestRemote(ctx, { + defaultModelSelection: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), + cwd: '/tmp', + }) + + const result = await remote.prompt(promptRequest({ + sessionId, + mode: 'steer' as const, + content: [ + { type: 'text' as const, text: 'look at this' }, + { type: 'image' as const, mediaType: 'image/png' as const, data: 'AQ==', name: 'mid-turn.png' }, + ], + })) + expect(result.ok).toBe(true) + expect(followup).not.toHaveBeenCalled() + expect((steer.mock.calls[0]?.[0] as UserMessage).content).toEqual([ + { type: 'text', text: 'look at this' }, + { + type: 'image', + attachment: { + attachmentId: 'att-1', mediaType: 'image/png', bytes: 1, width: 1, height: 1, name: 'mid-turn.png', + }, + }, + ]) + await ctx.fiber.dispose() + }) + it('allows a text-only selection while durable or pending images remain available for later models', async () => { const { ctx, agent, sessionId } = await harness() registerTextOnly(ctx) diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts index 150e6813d1..ad436779e1 100644 --- a/packages/api/session-controller/tests/session.client.spec.ts +++ b/packages/api/session-controller/tests/session.client.spec.ts @@ -281,6 +281,32 @@ describe('prompt and cancel errors', () => { }) }) + it('forwards continuation image parts to the subagent prompt Remote unstripped', async () => { + const api = new FakeApiClient() + const session = new Session(SID, fakeRemote(api), { + address: { parentSessionId: PARENT, childSessionId: SID, mode: 'continuable' }, + parentAvailable: true, + }) + await session.open() + const content = [ + { type: 'text' as const, text: '看这张图' }, + { type: 'image' as const, mediaType: 'image/png' as const, data: 'aGk=', name: 'shot.png' }, + ] + const prompted = await session.prompt(content, 'queue') + + expect(prompted).toEqual({ ok: true, value: { accepted: true } }) + expect(api.callsOf('subagents.prompt')).toEqual([ + { + requestId: expect.any(String) as unknown as string, + parentSessionId: PARENT, childSessionId: SID, + mode: 'continuable', + content, + clientTimeZone: new Intl.DateTimeFormat().resolvedOptions().timeZone, + }, + ]) + expect(session.getSnapshot().promptError).toBeNull() + }) + it('lands an interrupt business failure in promptError with op=stop', async () => { const api = new FakeApiClient() api.onSubagentInterrupt = () => Promise.resolve(remoteErr({ diff --git a/packages/attachment/attachment/src/index.ts b/packages/attachment/attachment/src/index.ts index 4ee001b86c..1c0f76b9e0 100644 --- a/packages/attachment/attachment/src/index.ts +++ b/packages/attachment/attachment/src/index.ts @@ -23,6 +23,7 @@ export type { ImageAttachmentRef, ImageRequestPolicy, ImageMediaType, + PromptContentPart, RequestImageAttachment, SaveImageAttachment, StoredImageAttachment, diff --git a/packages/attachment/attachment/src/types.ts b/packages/attachment/attachment/src/types.ts index 046444cd76..64c199eaf1 100644 --- a/packages/attachment/attachment/src/types.ts +++ b/packages/attachment/attachment/src/types.ts @@ -52,6 +52,21 @@ export interface EncodedImageAttachment { name?: string } +/** + * Browser-submitted prompt content accepted by Host prompt endpoints; the + * accepting Host promotes image parts to durable references through + * `admitEncodedImages` before any message is created, so a wire caller can + * never cite an attachment it did not upload. + */ +export type PromptContentPart = + | { readonly type: 'text'; readonly text: string } + | { + readonly type: 'image' + readonly mediaType: ImageMediaType + readonly data: string + readonly name?: string + } + /** Request to validate and durably commit one image. */ export interface SaveImageAttachment { data: Uint8Array diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index d7a0420bec..63e2a89061 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: 188a4461c1ab46e8be4f96c402c4707b1c66c415 -README.zh.md: 63356b04ef07ddd8c037d46d0ad105ed01afda80 +README.md: 3a51c20caaa78f1e638d5117a9153112ce530fe2 +README.zh.md: be5b5396620566b356cc51aedc3fed21779cccd9 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 188a4461c1..3a51c20caa 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -38,7 +38,7 @@ The package registers the optional-Session `conversation` shell, strict Session View selection is deterministic: a registered persisted selection wins, otherwise registered `chat` wins, otherwise no View renders. It never chooses the first registered View. Shell phase combines Session lifecycle with the active-target set; no target-specific snapshot is read by the shell. -The resident composer survives no-Session and Session transitions. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label), while an edit exposes the literal sent text. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. +The resident composer survives no-Session and Session transitions. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label) and show each durable image part as a thumbnail resolved through the session image URL cache, while an edit exposes the literal sent text. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Queue Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting continues to select the Queue or Steer keyboard action. Continuable subagents keep separate Send and Stop actions ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-20-running-draft-primary-send.md)). diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 63356b04ef..be5b539662 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -38,7 +38,7 @@ target package 通过 declaration merge 扩展 snapshot 与 Location data map， View 选择规则固定：有效且已注册的持久化选择优先，其次是已注册的 `chat`，否则不渲染 View；绝不选择第一个已注册 View。Shell phase 只组合 Session lifecycle 与 active-target set，不读取任何 target-specific snapshot。 -常驻 composer 在无 Session 与有 Session 之间保持挂载。无 Session 时，同一个编辑器表面保持 inert，Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器：引用 chip 是携带 owner 序列化身份的原子 decorator 节点（提交时经 owner codec 展开），已认领的 slash command 保持为带样式的行首文本，文件夹文本引用以图标前缀携带文件夹图形，草稿的剪贴板投影镜像到逐 Session Conversation store。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence；queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本（wire 会话形式折叠为其标签），编辑态则展示字面发送文本。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 +常驻 composer 在无 Session 与有 Session 之间保持挂载。无 Session 时，同一个编辑器表面保持 inert，Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器：引用 chip 是携带 owner 序列化身份的原子 decorator 节点（提交时经 owner codec 展开），已认领的 slash command 保持为带样式的行首文本，文件夹文本引用以图标前缀携带文件夹图形，草稿的剪贴板投影镜像到逐 Session Conversation store。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence；queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本（wire 会话形式折叠为其标签），并把每个持久化图片部分经会话图片 URL 缓存解析为缩略图展示，编辑态则展示字面发送文本。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Queue Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置继续选择 Queue 或 Steer 键盘操作。可继续 subagent 保留独立的 Send 与 Stop 操作（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-20-running-draft-primary-send.zh.md)）。 diff --git a/packages/client/ui-conversation/src/client/image-labels.ts b/packages/client/ui-conversation/src/client/image-labels.ts index 6d4ee7a130..d2333c324c 100644 --- a/packages/client/ui-conversation/src/client/image-labels.ts +++ b/packages/client/ui-conversation/src/client/image-labels.ts @@ -31,7 +31,6 @@ export function attachmentErrorText( ): string { switch (reason) { case 'MODEL_DOES_NOT_SUPPORT_IMAGES': return t('image.modelUnsupported') - case 'SUBAGENT_IMAGE_UNSUPPORTED': return t('image.subagentUnsupported') case 'IMAGE_TOO_MANY_PIXELS': return t('image.tooManyPixels') case 'IMAGE_DIMENSION_TOO_LARGE': if (limits !== undefined) return t('image.dimensionTooLarge', { size: limits.maxImageDimension }) diff --git a/packages/client/ui-conversation/src/client/locales.ts b/packages/client/ui-conversation/src/client/locales.ts index 480f73764b..e8509b2c6f 100644 --- a/packages/client/ui-conversation/src/client/locales.ts +++ b/packages/client/ui-conversation/src/client/locales.ts @@ -45,7 +45,6 @@ export const zh = { 'image.tooManyPixels': '图片分辨率过大，请压缩后重试', 'image.dimensionTooLarge': '图片宽高不能超过 {size}px，请缩小后重试', 'image.modelUnsupported': '当前模型不支持图片，请切换支持图片的模型', - 'image.subagentUnsupported': '子智能体会话暂不支持图片', 'image.sendFailed': '图片发送失败（{reason}），请重新添加图片后再试', 'context.aria': '上下文已用 {percent}', 'context.used': '上下文已用', @@ -126,6 +125,7 @@ export const zh = { 'web.contentTruncated': '内容已截断', 'details.running': '运行中…', 'queue.count': '{n} 条排队消息', + 'queue.image': '排队消息图片', 'queue.edit': '编辑排队消息', 'queue.edit.unsupported': '包含非文本内容，暂不支持编辑', 'queue.save': '保存排队消息', @@ -190,7 +190,6 @@ export const en = { 'image.tooManyPixels': 'Image resolution is too high; compress it and try again', 'image.dimensionTooLarge': 'Image sides must be at most {size}px; downscale it and try again', 'image.modelUnsupported': 'The current model does not support images; switch to a model that does', - 'image.subagentUnsupported': 'Subagent sessions do not support images yet', 'image.sendFailed': 'Sending images failed ({reason}); re-add them and try again', 'context.aria': '{percent} of context used', 'context.used': 'of context used', @@ -271,6 +270,7 @@ export const en = { 'web.contentTruncated': 'Content truncated', 'details.running': 'Running…', 'queue.count': '{n} queued messages', + 'queue.image': 'Queued message image', 'queue.edit': 'Edit queued message', 'queue.edit.unsupported': 'Contains non-text content; editing is not supported yet', 'queue.save': 'Save queued message', diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css index eca51941ca..81ea205b5e 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.module.css +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.module.css @@ -122,6 +122,21 @@ box-shadow: inset 0 1px 0 var(--dsw-alias-border-l1); } +.thumbs { + display: flex; + flex: none; + gap: 4px; +} + +.thumb { + width: 24px; + height: 24px; + border: 1px solid var(--dsw-alias-border-l1); + border-radius: 4px; + background: var(--dsw-alias-bg-base); + object-fit: cover; +} + .preview, .editor { flex: 1 1 auto; diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx index aadedd7d29..a42b8cea68 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx @@ -1,12 +1,13 @@ import type { Context } from '@deepseek-ai/cordis' import { useEffect, useId, useMemo, useState } from 'react' +import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { IconCheckOutline16, IconChevronDownOutline14, IconChevronUpOutline14, IconCloseOutline16, IconEditOutline16, IconQueueOutline14, IconSendOutline14, IconTrashOutline16, projectUserText, Tooltip, } from '@deepseek-ai/dsh-client-ui-primitives' -import type { QueueAction, QueueItemId } from '../contract/queue.ts' +import type { QueueAction, QueueItemId, QueueRow } from '../contract/queue.ts' import { NS } from '../locales.ts' import css from './QueueDock.module.css' @@ -14,6 +15,43 @@ import css from './QueueDock.module.css' export interface QueueDockInjected { updateQueue: (itemId: QueueItemId, action: QueueAction) => Promise notify: (level: 'info' | 'error', text: string) => void + /** Resolve one durable queued image into a session-scoped browser URL. */ + loadImage: (attachment: ImageAttachmentRef) => Promise +} + +/** + * Durable references carried by one queued row. Queue frames are wire data + * despite their typed face, so an image block without a reference is skipped + * rather than trusted. + * @param content - the row's wire content blocks. + * @returns the row's durable image references in block order. + */ +function queueImageRefs(content: QueueRow['content']): ImageAttachmentRef[] { + return content.flatMap((block) => { + if (block.type !== 'image') return [] + const { attachment } = block as { attachment?: ImageAttachmentRef } + return attachment === undefined ? [] : [attachment] + }) +} + +/** One durable queued image as a fixed-size thumbnail; a load failure keeps the empty placeholder. */ +function QueueThumb({ attachment, loadImage, label }: { + attachment: ImageAttachmentRef + loadImage: QueueDockInjected['loadImage'] + label: string +}) { + const [url, setUrl] = useState(null) + useEffect(() => { + let alive = true + loadImage(attachment).then( + (resolved) => { if (alive) setUrl(resolved) }, + () => { /* placeholder retained; the durable transcript surfaces read errors */ }, + ) + return () => { alive = false } + }, [attachment, loadImage]) + return url === null + ? + : {label} } /** Full props of a dock entry: InputZone owner share + session standard kit + global seat + the locale seat. */ @@ -23,7 +61,7 @@ export type QueueDockProps = PropsRuntime<'conversation.input.dock'> & QueueDock * Queue strip: one item renders directly; multiple items default to a * collapsible count header; an empty queue renders nothing. */ -export function QueueDock({ useSession, updateQueue, notify, t }: QueueDockProps) { +export function QueueDock({ useSession, updateQueue, notify, loadImage, t }: QueueDockProps) { const inbox = useSession(s => s.queue) const queue = useMemo(() => inbox.filter(row => row.placement === 'queued'), [inbox]) const running = useSession(s => s.running) @@ -114,7 +152,23 @@ export function QueueDock({ useSession, updateQueue, notify, t }: QueueDockProps }} /> ) - : {projectUserText(row.preview, [])}} + : ( + <> + {queueImageRefs(row.content).length > 0 && ( + + {queueImageRefs(row.content).map((attachment, index) => ( + + ))} + + )} + {projectUserText(row.preview, [])} + + )} {queueMutable &&
{editing?.id === row.id ? ( @@ -210,7 +264,7 @@ export function QueueDock({ useSession, updateQueue, notify, t }: QueueDockProps /** Registers queue actions backed by the session-scoped conversation service. */ export const queueDockEntry = { name: 'conversation-queue-dock', - inject: ['slots', 'conversation', 'sessions'], + inject: ['slots', 'conversation', 'sessions', 'uiConversation'], apply(ctx: Context): void { ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({ name: 'conversation.input.dock', @@ -225,6 +279,7 @@ export const queueDockEntry = { return { updateQueue: (itemId, action) => conversation.updateQueue(itemId, action), notify: (level, text) => { conversation.input.for(actx).notify(level, text) }, + loadImage: attachment => ctx.uiConversation.imageUrl(sessionId, attachment), } }, }, QueueDock)) diff --git a/packages/client/ui-conversation/tests/image-labels.client.spec.ts b/packages/client/ui-conversation/tests/image-labels.client.spec.ts index 8e1ff4409d..0244c134db 100644 --- a/packages/client/ui-conversation/tests/image-labels.client.spec.ts +++ b/packages/client/ui-conversation/tests/image-labels.client.spec.ts @@ -24,7 +24,6 @@ describe('attachment rejection copy', () => { it('maps user-solvable reasons to limit-naming copy', () => { expect(attachmentErrorText(t, 'MODEL_DOES_NOT_SUPPORT_IMAGES')).toBe('当前模型不支持图片，请切换支持图片的模型') - expect(attachmentErrorText(t, 'SUBAGENT_IMAGE_UNSUPPORTED')).toBe('子智能体会话暂不支持图片') expect(attachmentErrorText(t, 'IMAGE_TOO_MANY_PIXELS')).toBe('图片分辨率过大，请压缩后重试') expect(attachmentErrorText(t, 'INVALID_IMAGE')).toBe('仅支持 PNG、JPG、WebP、GIF 格式的图片') expect(attachmentErrorText(t, 'IMAGE_TYPE_MISMATCH')).toBe('仅支持 PNG、JPG、WebP、GIF 格式的图片') diff --git a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx index 6a30ed4d8a..75701f7076 100644 --- a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx +++ b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx @@ -87,10 +87,26 @@ function kitFor(snapshot: SessionSnapshot, injected: Partial input: INPUT_STATE, updateQueue: vi.fn(() => Promise.resolve()), notify: vi.fn(), + loadImage: vi.fn(() => Promise.resolve('blob:unused')), ...injected, } } +/** One queued row carrying a durable image reference (plus optional leading text). */ +function imageRow(id: string, refId: string, text = ''): QueuedMessage { + return { + id: iid(id), messageId: `message-${id}` as never, placement: 'queued', + content: [ + ...text === '' ? [] : [{ type: 'text' as const, text }], + { + type: 'image', + attachment: { attachmentId: refId, mediaType: 'image/png', bytes: 1, width: 1, height: 1 }, + } as never, + ], + preview: text, text: null, + } +} + describe('QueueDock', () => { it('renders null while the queue is empty', () => { const snap = snapshotWith([]) @@ -223,6 +239,52 @@ describe('QueueDock', () => { .toBe('包含非文本内容，暂不支持编辑') }) + it('renders queued image thumbnails from durable references beside the text preview', async () => { + const loadImage = vi.fn(() => Promise.resolve('blob:thumb-1')) + const snap = snapshotWith([imageRow('i-img', 'att-9', '带图消息')]) + const source = liveSession(snap) + const { container } = render( + , + ) + + await waitFor(() => { + expect(container.querySelector('img')?.getAttribute('src')).toBe('blob:thumb-1') + }) + expect(loadImage).toHaveBeenCalledWith(expect.objectContaining({ attachmentId: 'att-9' })) + expect(container.querySelector('img')?.getAttribute('alt')).toBe('排队消息图片') + expect(container.querySelector('li')?.textContent).toBe('带图消息') + }) + + it('keeps the empty thumbnail placeholder when the image read fails', async () => { + const loadImage = vi.fn(() => Promise.reject(new Error('read denied'))) + const snap = snapshotWith([imageRow('i-broken', 'att-x')]) + const source = liveSession(snap) + const { container } = render( + , + ) + + await act(async () => { await Promise.resolve() }) + expect(loadImage).toHaveBeenCalled() + expect(container.querySelector('img')).toBeNull() + }) + + it('ignores a thumbnail resolution landing after unmount', async () => { + let resolveUrl: ((url: string) => void) | undefined + const loadImage = vi.fn(() => new Promise((resolve) => { resolveUrl = resolve })) + const snap = snapshotWith([imageRow('i-late', 'att-late')]) + const source = liveSession(snap) + const { unmount } = render( + , + ) + + unmount() + await act(async () => { + resolveUrl?.('blob:late') + await Promise.resolve() + }) + expect(loadImage).toHaveBeenCalledTimes(1) + }) + it('edits text inline with save and cancel controls, then saves with the same item identity', async () => { const snap = snapshotWith([row('i-edit', 'before')]) const source = liveSession(snap) @@ -388,7 +450,7 @@ describe('QueueDock', () => { it('registers as the terminal composer-context entry', () => { expect(queueDockEntry.name).toBe('conversation-queue-dock') - expect(queueDockEntry.inject).toEqual(['slots', 'conversation', 'sessions']) + expect(queueDockEntry.inject).toEqual(['slots', 'conversation', 'sessions', 'uiConversation']) const register = vi.fn(() => () => undefined) const inject = vi.fn((_name: string, callback: () => () => void) => callback()) queueDockEntry.apply({ slots: { inject, register } } as never) diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 0d3af9663b..9bac17bff0 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -70,6 +70,17 @@ export class ReactLoopAgent implements Agent { readonly inbox: Inbox private phase: Phase private activityDone: Promise = Promise.resolve() + /** + * Identities of waking sends still awaiting a claim. Claim and discard + * notifications prune the set, and {@link cancel} clears it because a + * cancellation parks accepted-but-unclaimed input for a later waking send. + * A non-empty set at driver exit therefore means a steer or follow-up lost + * the race with a normally or erroneously closing turn, and the exit must + * start a fresh driver to deliver it. Injected context never enters the + * set, so it keeps waiting for a waking message instead of opening a turn + * by itself. + */ + private readonly pendingWakes = new Set() /** The agent-scoped registration boundary; the lifecycle owner unwinds it after the driver exits. */ readonly scope: Scope @@ -93,8 +104,14 @@ export class ReactLoopAgent implements Agent { this.dispatch = agentEvents(loopCtx, this) this.inbox = new Inbox(session, { inserted: (message) => { this.dispatch.emit('agent/inbox/inserted', { message }) }, - discarded: (message) => { this.dispatch.emit('agent/inbox/discarded', { message }) }, - claimed: (message, turn) => { this.dispatch.emit('agent/inbox/claimed', { message, turn }) }, + discarded: (message) => { + this.pendingWakes.delete(message.id) + this.dispatch.emit('agent/inbox/discarded', { message }) + }, + claimed: (message, turn) => { + this.pendingWakes.delete(message.id) + this.dispatch.emit('agent/inbox/claimed', { message, turn }) + }, }) const lastTurn = session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 0 this.phase = { kind: 'idle', lastTurn } @@ -122,7 +139,15 @@ export class ReactLoopAgent implements Agent { // Captured before the insertion so a reentrant cancel from a splice observer cannot reclassify it. const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted const resolvedTarget = wakingAfterAbort ? 'next-turn' : target - this.inbox.splice(resolvedTarget, Infinity, 0, [message]) + // Registered before the splice so a reentrant discard inside the splice + // dispatch still prunes it; a refused splice never leaves an entry behind. + if (wakeup) this.pendingWakes.add(message.id) + try { + this.inbox.splice(resolvedTarget, Infinity, 0, [message]) + } catch (error: unknown) { + this.pendingWakes.delete(message.id) + throw error + } if (wakeup) this.wakeDriver(wakingAfterAbort) } @@ -143,6 +168,10 @@ export class ReactLoopAgent implements Agent { this.inbox.clear() if (this.phase.kind !== 'idle') this.phase.wakeRequested = false } + // Cancellation consumes outstanding wakes: kept inbox work parks until + // the next waking send resumes the queue, and a cleared inbox has nothing + // left to deliver. + this.pendingWakes.clear() if (this.phase.kind !== 'idle') this.phase.abort.abort(cause) } @@ -215,8 +244,14 @@ export class ReactLoopAgent implements Agent { } private async kick(): Promise { + // Set only when the turn loop returns without throwing: an abort or driver + // failure parks unclaimed waking input for the next waking send, while a + // clean exit must deliver a steer or follow-up that lost the race with the + // closing turn (its send saw a live driver, so no wake was latched). + let cleanExit = false try { while (await this.turn()) {} + cleanExit = true } catch (_error) { // Reported failures and cancellation are contained at the driver boundary. } finally { @@ -224,7 +259,9 @@ export class ReactLoopAgent implements Agent { if (this.phase.kind === 'running') { const { turn, wakeRequested } = this.phase this.setPhase({ kind: 'idle', lastTurn: turn }) - if (wakeRequested && this.inbox.hasPending) this.wakeDriver() + if ((wakeRequested || (cleanExit && this.pendingWakes.size > 0)) && this.inbox.hasPending) { + this.wakeDriver() + } } } } @@ -272,6 +309,10 @@ export class ReactLoopAgent implements Agent { const step = phase.step + 1 const decision = await this.preStep(target, { turn, step }) if (decision.kind === 'reject') { + // The rejecting listener owns resumption: input staged behind the + // rejected claim parks until the next waking send, exactly like a + // cancellation, instead of being re-offered to the same policy. + this.pendingWakes.clear() turnEnds = { kind: 'blocked' } return false } diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index 487fc60181..3ca29d6450 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -1530,3 +1530,83 @@ describe('agent loop', () => { expect(replayed.events.at(-1)?.type).toBe('session/end-seed') }) }) + +describe('closing-turn wake races', () => { + /** + * Schedule one send in the closing turn's final microtask window: the + * synchronous turn/end dispatch queues the microtask before the driver's + * exit continuation, so it lands after the final inbox check and before the + * driver boundary — the race a live send cannot latch a wake for. + */ + function sendOnTurnEnd(ctx: Context, agent: Agent, deliver: () => void): void { + const dispose = ctx.on('session/event', (session, event) => { + if (session !== agent.session || event.type !== 'turn/end') return + dispose() + queueMicrotask(deliver) + }) + } + + it('delivers a steer that lands while a clean turn is closing', async () => { + const adapter = new MockAdapter([textResponse('first'), textResponse('second')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(SessionId('closing-steer'), { provider: 'mock', model: 'mock' }) + sendOnTurnEnd(ctx, agent, () => { + agent.steer(createUserMessage({ content: [{ type: 'text', text: 'late steer' }], source: { kind: 'user' } })) + }) + + send(agent, 'first') + await waitForIdle(ctx, agent) + await agent.whenIdle() + + expect(userTexts(agent)).toEqual(['first', 'late steer']) + expect(adapter.requests).toHaveLength(2) + expect(agent.inbox.hasPending).toBe(false) + }) + + it('delivers a follow-up that lands while a clean turn is closing', async () => { + const adapter = new MockAdapter([textResponse('first'), textResponse('second')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(SessionId('closing-followup'), { provider: 'mock', model: 'mock' }) + sendOnTurnEnd(ctx, agent, () => { send(agent, 'late follow-up') }) + + send(agent, 'first') + await waitForIdle(ctx, agent) + await agent.whenIdle() + + expect(userTexts(agent)).toEqual(['first', 'late follow-up']) + expect(adapter.requests).toHaveLength(2) + expect(agent.inbox.hasPending).toBe(false) + }) + + it('leaves injected context parked when a clean turn closes without a waking message', async () => { + const adapter = new MockAdapter([textResponse('only')]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(SessionId('closing-inject'), { provider: 'mock', model: 'mock' }) + sendOnTurnEnd(ctx, agent, () => { + agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'user' } })) + }) + + send(agent, 'only') + await waitForIdle(ctx, agent) + await agent.whenIdle() + + expect(userTexts(agent)).toEqual(['only']) + expect(adapter.requests).toHaveLength(1) + expect(agent.inbox.nextStep).toHaveLength(1) + }) + + it('a refused duplicate splice keeps the parked injection and registers no wake', async () => { + const adapter = new MockAdapter([]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(SessionId('duplicate-splice'), { provider: 'mock', model: 'mock' }) + const message = createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'user' } }) + agent.inject(message) + + expect(() => { agent.steer(message) }).toThrow(`message "${message.id}" is already pending`) + await agent.whenIdle() + + expect(agent.inbox.nextStep).toHaveLength(1) + expect(agent.status).toBe('idle') + expect(adapter.requests).toHaveLength(0) + }) +}) diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts index 7dd28e586b..c5317882b4 100644 --- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts @@ -606,10 +606,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ProjectionsFace', declaration: 'export interface ProjectionsFace {\n faceOf(key: string): ObservableSnapshot;\n}', }, - { - name: 'PromptContentPart', - declaration: 'export type PromptContentPart = {\n readonly type: \'text\';\n readonly text: string;\n} | {\n readonly type: \'image\';\n readonly mediaType: ImageMediaType;\n readonly data: string;\n readonly name?: string;\n};', - }, { name: 'PromptError', declaration: 'export interface PromptError {\n readonly op: \'send\' | \'stop\';\n readonly error: ClientFailure;\n}', diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 5412e025cd..cdd4de1213 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -2168,10 +2168,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ }, { signature: '@Remote(\'prompt\') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise', - description: 'Deliver one browser-authored message to a continuable child through the exact live direct parent, retaining the caller-minted request identity and validated browser zone on the accepted message. Success identifies the message the child\'s FIFO inbox accepted; later execution is independent of this call.', + description: 'Deliver one browser-authored message to a continuable child through the exact live direct parent, retaining the caller-minted request identity and validated browser zone on the accepted message. Success identifies the message the child\'s FIFO inbox accepted; later execution is independent of this call. Image parts are admitted and persisted through the attachment store before delivery, and the child\'s model must accept image input.', parameters: [{ name: 'request', description: 'durable address, minted identity, content, and optional browser zone.' }, { name: 'signal', description: 'carrier cancellation, owning the call until inbox acceptance.' }], returns: 'the accepted message\'s inbox identity.', - throws: ['{TypertRemoteFailure} `bad-request`, `invalid-time-zone`, `subagent-parent-unavailable`, `subagent-not-resumable`, `subagent-unauthorized`, `subagent-delivery-unavailable`, `cancelled`, or `internal`.'], + throws: ['{TypertRemoteFailure} `bad-request`, `invalid-time-zone`, `attachment-error`, `subagent-parent-unavailable`, `subagent-not-resumable`, `subagent-unauthorized`, `subagent-delivery-unavailable`, `cancelled`, or `internal`.'], }, { signature: '@Remote(\'interruptByParent\') interruptByParent( childSessionId: SessionId, parentSessionId: SessionId, mode: \'continuable\', ): SubagentInterruptReceipt', @@ -5228,7 +5228,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SubagentPromptRequest', - declaration: 'export interface SubagentPromptRequest {\n readonly requestId: SubagentPromptRequestId;\n readonly parentSessionId: SessionId;\n readonly childSessionId: SessionId;\n readonly mode: \'continuable\';\n readonly content: ContentBlock[];\n readonly clientTimeZone?: string;\n}', + declaration: 'export interface SubagentPromptRequest {\n readonly requestId: SubagentPromptRequestId;\n readonly parentSessionId: SessionId;\n readonly childSessionId: SessionId;\n readonly mode: \'continuable\';\n readonly content: readonly PromptContentPart[];\n readonly clientTimeZone?: string;\n}', }, { name: 'SubagentPromptRequestId', diff --git a/packages/llm/llm/src/content.ts b/packages/llm/llm/src/content.ts index 43c392a641..faac6249af 100644 --- a/packages/llm/llm/src/content.ts +++ b/packages/llm/llm/src/content.ts @@ -2,7 +2,8 @@ import type { ContentBlock } from './types.ts' import type { Message } from './message.ts' -import type { AttachmentStore, ImageAttachmentRef, ImageMediaType, RequestImageAttachment } from '@deepseek-ai/dsh-attachment' +import type { AttachmentStore, ImageAttachmentRef, ImageMediaType, PromptContentPart, RequestImageAttachment } from '@deepseek-ai/dsh-attachment' +import { admitEncodedImages } from '@deepseek-ai/dsh-attachment' import { assertNever } from './never.ts' /** Execution-world path that model tools can use to read one normalized attachment. */ @@ -39,6 +40,31 @@ export function resolveImageAttachmentAccess( return readonlyPath === undefined ? undefined : { readonlyPath } } +/** + * Promote one browser-submitted prompt into durable model content: every image + * part is admitted through the attachment store before any block exists, so a + * caller-supplied part can never cite an attachment it did not upload here. + * The shared conversion for every Host prompt endpoint accepting uploads. + * @param attachments - the deployment attachment store owning admission policy. + * @param content - ordered browser prompt parts. + * @returns content blocks in part order, image parts replaced by durable references. + * @throws AttachmentError when the image batch is refused. + */ +export async function durablePromptContent( + attachments: AttachmentStore, + content: readonly PromptContentPart[], +): Promise { + if (content.every(part => part.type === 'text')) { + return content.map(part => ({ type: 'text', text: part.text })) + } + const refs = await admitEncodedImages(attachments, content.filter(part => part.type === 'image')) + let next = 0 + return content.map(part => part.type === 'text' + ? { type: 'text', text: part.text } + // admitEncodedImages returns one reference per image part in order. + : { type: 'image', attachment: refs[next++] as ImageAttachmentRef }) +} + function quoted(value: string): string { return JSON.stringify(value) } diff --git a/packages/llm/llm/tests/content.spec.ts b/packages/llm/llm/tests/content.spec.ts index 748e20f412..bb0492b0af 100644 --- a/packages/llm/llm/tests/content.spec.ts +++ b/packages/llm/llm/tests/content.spec.ts @@ -4,6 +4,7 @@ import type { AttachmentStore, ImageMediaType } from '@deepseek-ai/dsh-attachmen import { ToolCallId, createUserMessage, + durablePromptContent, offloadedImageText, offloadedImagePrefixCount, offloadRequestImagesWithPolicy, @@ -360,3 +361,33 @@ describe('projectImagesForTextModel', () => { ]) }) }) + +describe('durablePromptContent', () => { + it('converts text-only prompts without touching the attachment store', async () => { + const store = { saveImages: () => { throw new Error('text-only prompts must not reach the store') } } + await expect(durablePromptContent(store as unknown as AttachmentStore, [ + { type: 'text', text: 'hello' }, + ])).resolves.toEqual([{ type: 'text', text: 'hello' }]) + }) + + it('replaces image parts with admitted references in part order', async () => { + const store = { + saveImages: (inputs: readonly { data: Uint8Array }[]) => Promise.resolve(inputs.map((input, index) => ({ + attachmentId: AttachmentId(`att-${index}`), + mediaType: 'image/png' as ImageMediaType, + bytes: input.data.byteLength, + width: 1, + height: 1, + }))), + } + await expect(durablePromptContent(store as unknown as AttachmentStore, [ + { type: 'image', mediaType: 'image/png', data: 'AQ==' }, + { type: 'text', text: 'between' }, + { type: 'image', mediaType: 'image/png', data: 'Ag==' }, + ])).resolves.toEqual([ + { type: 'image', attachment: { attachmentId: 'att-0', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } }, + { type: 'text', text: 'between' }, + { type: 'image', attachment: { attachmentId: 'att-1', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } }, + ]) + }) +}) diff --git a/packages/subagent/subagent/README.i18n.yaml b/packages/subagent/subagent/README.i18n.yaml index e807931e2c..9277bc689f 100644 --- a/packages/subagent/subagent/README.i18n.yaml +++ b/packages/subagent/subagent/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/subagent/subagent/README.md -README.md: 76df70351d711d580d3ab1a89d0f929b85eab172 -README.zh.md: c4deb001c47435d29a5ca18cc0f8c0d26e48941e +README.md: f13de661015f3aa59b776273376f07653f6bbba5 +README.zh.md: 42923504ed11b8eff7c0bdcd9d0c9505d741f42e diff --git a/packages/subagent/subagent/README.md b/packages/subagent/subagent/README.md index 76df70351d..f13de66101 100644 --- a/packages/subagent/subagent/README.md +++ b/packages/subagent/subagent/README.md @@ -48,7 +48,7 @@ One-shot children run once and settle with a single result, plus an optional str ### Following up, interrupting, and discovering -Continuable children answer follow-up messages as their next turns, and the parent can interrupt a running turn or list its children at any time. Discovery covers both shapes: the service lists direct children and the full descendant tree — mode, activity, and lineage — reading live session state and optional persistence, without loading any child. +Continuable children answer follow-up messages as their next turns, and the parent can interrupt a running turn or list its children at any time. A browser continuation prompt may carry image parts: the Host admits and persists each image batch through the attachment store before the child inbox accepts the message, and refuses delivery when the child's declared model does not accept image input. Discovery covers both shapes: the service lists direct children and the full descendant tree — mode, activity, and lineage — reading live session state and optional persistence, without loading any child. ### Failure and recovery diff --git a/packages/subagent/subagent/README.zh.md b/packages/subagent/subagent/README.zh.md index c4deb001c4..42923504ed 100644 --- a/packages/subagent/subagent/README.zh.md +++ b/packages/subagent/subagent/README.zh.md @@ -48,7 +48,7 @@ kind: "package-reference" ### 后续消息、中断与发现 -可继续子 agent 把后续消息作为下一个轮次回答，父级随时可以中断运行中的轮次或列举自己的子级。发现覆盖两种形态：服务列举直接子级与完整后代树——模式、活动状态与血缘——直接读取在线会话状态与可选持久化，不加载任何子 agent。 +可继续子 agent 把后续消息作为下一个轮次回答，父级随时可以中断运行中的轮次或列举自己的子级。浏览器发出的继续执行 prompt 可以携带图片部分：Host 先通过附件存储完成整批图片的准入与持久化，子级 inbox 才接受这条消息；当子级声明的模型不接受图片输入时拒绝投递。发现覆盖两种形态：服务列举直接子级与完整后代树——模式、活动状态与血缘——直接读取在线会话状态与可选持久化，不加载任何子 agent。 ### 失败与恢复 diff --git a/packages/subagent/subagent/package.json b/packages/subagent/subagent/package.json index c89f11eee7..49f28fb095 100644 --- a/packages/subagent/subagent/package.json +++ b/packages/subagent/subagent/package.json @@ -54,6 +54,7 @@ "peerDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", + "@deepseek-ai/dsh-attachment": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", @@ -104,6 +105,7 @@ "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", + "@deepseek-ai/dsh-attachment": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts index 6b50947060..f3b90a8075 100644 --- a/packages/subagent/subagent/src/continuation.ts +++ b/packages/subagent/subagent/src/continuation.ts @@ -30,7 +30,7 @@ import type { AgentSetupCommit, CreateAgentOptions, } from '@deepseek-ai/dsh-agent' -import { ReasoningEffortId, boundContextSummary, createUserMessage, errorChain } from '@deepseek-ai/dsh-llm' +import { ReasoningEffortId, boundContextSummary, contentHasImage, createUserMessage, errorChain } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import type { SessionEvent } from '@deepseek-ai/dsh-session' @@ -523,6 +523,11 @@ export class SubagentContinuationManager { if (activation.disposal !== undefined) { return activation.disposal.then(() => undefined, () => undefined) } + // Guarded call: text-only delivery must not gain an await hop inside + // the per-child lock, where it would reorder against drain admission. + if (contentHasImage(content)) { + await this.assertImageCapable(activation.handle.agent, options.signal) + } return this.submitAdmitted(activation, content, options.source, parent, options.signal) }) /* v8 ignore start -- only the lost-cutoff arm above returns undefined, so only that @@ -1021,6 +1026,9 @@ export class SubagentContinuationManager { signal: AbortSignal, ): Promise { try { + if (contentHasImage(content)) { + await this.assertImageCapable(activation.handle.agent, signal) + } return this.submitAdmitted(activation, content, source, parent, signal) } catch (error: unknown) { /* v8 ignore next -- rollback disposal failures must not mask the @@ -1030,6 +1038,37 @@ export class SubagentContinuationManager { } } + /** + * Refuse image content addressed to a child whose model accepts text only. + * Callers guard with `contentHasImage`, so text-only delivery never awaits. + * The check runs inside the per-child delivery lock, before the message + * exists, so a rejection leaves no partial user message. When the child's + * route is not fixed by its options (a request-waterfall listener owns it) + * or no LLM registry is composed, delivery proceeds and the LLM layer's + * text-only projection replaces each image with its stable placeholder. + * @param agent - the live or freshly materialized child agent. + * @param signal - caller cancellation bounding the model-info read. + * @throws {SubagentError} `MODEL_DOES_NOT_SUPPORT_IMAGES` when the child's resolved model declines image input. + */ + private async assertImageCapable( + agent: Agent, + signal: AbortSignal, + ): Promise { + const { provider, model } = agent.options + if (provider === undefined || model === undefined) return + const llm = this.ctx.get('llm') + /* v8 ignore next -- a deployment without the LLM registry serves no model + * to refuse against; delivery then defers to the text-only projection. */ + if (llm === undefined) return + const info = await llm.resolveModelInfo(provider, model, signal) + if (info.inputModalities !== undefined && !info.inputModalities.includes('image')) { + throw new SubagentError( + `Model "${model}" does not support image input.`, + 'MODEL_DOES_NOT_SUPPORT_IMAGES', + ) + } + } + /** * Create or resume the child Agent through the private activation-owner * scope, install the handle in a fresh Activation, and register ownership on diff --git a/packages/subagent/subagent/src/control-types.ts b/packages/subagent/subagent/src/control-types.ts index ea02674413..e8707cc13e 100644 --- a/packages/subagent/subagent/src/control-types.ts +++ b/packages/subagent/subagent/src/control-types.ts @@ -6,9 +6,9 @@ * @module @deepseek-ai/dsh-subagent/control-types */ +import type { PromptContentPart } from '@deepseek-ai/dsh-attachment/types' import type { Branded } from '@deepseek-ai/dsh-brand' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' -import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { z as zCore } from 'zod' @@ -103,8 +103,12 @@ export interface SubagentPromptRequest { readonly childSessionId: SessionId /** Required discriminator retained from the browser control address. */ readonly mode: 'continuable' - /** Content delivered as the child's user message. */ - readonly content: ContentBlock[] + /** + * Browser prompt parts delivered as the child's user message. The Host + * admits and persists image parts before delivery, so the wire never + * carries a durable attachment reference the caller could fabricate. + */ + readonly content: readonly PromptContentPart[] /** Optional browser zone sampled for this exact human prompt. */ readonly clientTimeZone?: string } @@ -127,6 +131,8 @@ export interface SubagentInterruptReceipt { */ export interface SubagentControlErrorDetailsMap { 'bad-request': { readonly issues: zCore.core.$ZodIssue[] } + /** Image admission or model image-capability refusal; `reason` carries the stable admission code. */ + 'attachment-error': { readonly reason: string } cancelled: Record 'invalid-time-zone': { readonly value: string } 'subagent-parent-unavailable': { readonly parentSessionId: SessionId } diff --git a/packages/subagent/subagent/src/control.ts b/packages/subagent/subagent/src/control.ts index 661a43153a..0c6bd9d7a4 100644 --- a/packages/subagent/subagent/src/control.ts +++ b/packages/subagent/subagent/src/control.ts @@ -7,6 +7,7 @@ */ import type { Context } from '@deepseek-ai/cordis' +import { AttachmentError } from '@deepseek-ai/dsh-attachment' import type { SessionId } from '@deepseek-ai/dsh-session' import { TypertRemoteFailure } from '@deepseek-ai/dsh-typert-protocol' import { z } from 'zod' @@ -148,8 +149,13 @@ export function rejectPrompt(error: unknown, childSessionId: SessionId, signal: if (isCancellation(error, signal)) { return rejectControl('cancelled', 'subagent prompt was cancelled', {}) } + if (error instanceof AttachmentError) { + return rejectControl('attachment-error', error.message, { reason: error.code }) + } if (error instanceof SubagentError) { switch (error.code) { + case 'MODEL_DOES_NOT_SUPPORT_IMAGES': + return rejectControl('attachment-error', error.message, { reason: error.code }) case 'NOT_RESUMABLE': return rejectControl('subagent-not-resumable', 'subagent cannot be resumed', { childSessionId }) case 'UNAUTHORIZED': diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts index 444f4ee857..f1a8689131 100644 --- a/packages/subagent/subagent/src/index.ts +++ b/packages/subagent/subagent/src/index.ts @@ -34,6 +34,7 @@ import { scopeTarget } from '@deepseek-ai/dsh-scope' import type { Scoped } from '@deepseek-ai/dsh-scope' import { assertObjectJsonSchema } from '@deepseek-ai/dsh-tools' import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm' +import { durablePromptContent } from '@deepseek-ai/dsh-llm' import type { Agent } from '@deepseek-ai/dsh-agent' import type { SessionId } from '@deepseek-ai/dsh-session' import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' @@ -418,13 +419,15 @@ export class SubagentRuntime extends TypertRemoteService { * validated browser zone on the accepted message. Success identifies the * message the child's FIFO inbox accepted; later execution is independent of * this call. + * Image parts are admitted and persisted through the attachment store + * before delivery, and the child's model must accept image input. * @param request - durable address, minted identity, content, and optional browser zone. * @param signal - carrier cancellation, owning the call until inbox acceptance. * @returns the accepted message's inbox identity. * @throws {TypertRemoteFailure} `bad-request`, `invalid-time-zone`, - * `subagent-parent-unavailable`, `subagent-not-resumable`, - * `subagent-unauthorized`, `subagent-delivery-unavailable`, `cancelled`, or - * `internal`. + * `attachment-error`, `subagent-parent-unavailable`, + * `subagent-not-resumable`, `subagent-unauthorized`, + * `subagent-delivery-unavailable`, `cancelled`, or `internal`. */ @Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise { @@ -453,8 +456,10 @@ export class SubagentRuntime extends TypertRemoteService { rpcId: request.requestId, ...(canonicalTimeZone === undefined ? {} : { clientTimeZone: canonicalTimeZone }), } - const content: ContentBlock[] = [...request.content] try { + // Admission precedes delivery: image parts become durable references + // here, so the child inbox only ever accepts Host-persisted attachments. + const content: ContentBlock[] = await durablePromptContent(this.ctx.attachments, request.content) return { messageId: await this.followup(parent, childSessionId, content, { source, signal }) } } catch (error: unknown) { return rejectPrompt(error, childSessionId, signal) diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts index 9508065197..505da10ff2 100644 --- a/packages/subagent/subagent/tests/continuation.spec.ts +++ b/packages/subagent/subagent/tests/continuation.spec.ts @@ -523,6 +523,74 @@ describe('SubagentRuntime.startContinuable', () => { }) }) +describe('continuable image follow-ups', () => { + const imageBlock = { + type: 'image' as const, + attachment: { + attachmentId: 'att-1' as never, mediaType: 'image/png' as const, bytes: 1, width: 1, height: 1, + }, + } + + it('refuses an image follow-up when the child model declines image input, leaving no partial message', async () => { + const { ctx, parent } = await setup([textResponse('child work')]) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await waitNoActivation(ctx, started.childId) + const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo') + .mockResolvedValue({ inputModalities: ['text'] } as never) + + await expect(ctx.subagents.followup(parent, started.childId, [ + { type: 'text' as const, text: 'see this' }, + imageBlock, + ], { source: { kind: 'user' }, signal: testSignal })) + .rejects.toMatchObject({ code: 'MODEL_DOES_NOT_SUPPORT_IMAGES' }) + + expect(resolve).toHaveBeenCalledWith('mock', 'mock', testSignal) + const loaded = await ctx.sessionPersistence.load(started.childId) + expect(hasUserText(loaded.events, 'see this')).toBe(false) + await drainManager(ctx) + }) + + it('delivers an image follow-up when the child model accepts image input', async () => { + const { ctx, parent } = await setup([textResponse('child work'), textResponse('image reply')]) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await waitNoActivation(ctx, started.childId) + vi.spyOn(ctx.llm, 'resolveModelInfo') + .mockResolvedValue({ inputModalities: ['text', 'image'] } as never) + + await ctx.subagents.followup(parent, started.childId, [ + { type: 'text' as const, text: 'compare' }, + imageBlock, + ], { source: { kind: 'user' }, signal: testSignal }) + await waitNoActivation(ctx, started.childId) + + const loaded = await ctx.sessionPersistence.load(started.childId) + const delivered = loaded.events.find(event => event.type === 'user/message' + && event.data.content.some(block => block.type === 'image')) + expect(delivered?.type === 'user/message' && delivered.data.content).toEqual([ + { type: 'text', text: 'compare' }, + imageBlock, + ]) + await drainManager(ctx) + }) + + it('defers to the text-only projection when the descriptor declares no model route', async () => { + const { ctx } = await setup([]) + const routeless = ctx.agentLoop.create(SessionId('routeless-image'), {}) + const started = await ctx.subagents.startContinuable(startSpec(routeless)) + await waitNoActivation(ctx, started.childId) + const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo') + + // Acceptance is the success boundary: with no declared route there is no + // model to refuse against, so the image message enters the child inbox. + await ctx.subagents.followup(routeless, started.childId, [imageBlock], { + source: { kind: 'user' }, signal: testSignal, + }) + + expect(resolve).not.toHaveBeenCalled() + await drainManager(ctx) + }) +}) + describe('SubagentRuntime.followup residency routing', () => { it('fails a cold follow-up when Session query is unavailable', async () => { const { ctx, parent } = await setupWith(new MockAdapter([]), { diff --git a/packages/subagent/subagent/tests/control.spec.ts b/packages/subagent/subagent/tests/control.spec.ts index dd04d549b1..99c534dd49 100644 --- a/packages/subagent/subagent/tests/control.spec.ts +++ b/packages/subagent/subagent/tests/control.spec.ts @@ -5,6 +5,7 @@ import { describe, expect, it, vi } from 'vitest' import { Context } from '@deepseek-ai/cordis' +import { AttachmentError } from '@deepseek-ai/dsh-attachment' import type { MessageId } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' import SubagentRuntime, { @@ -19,6 +20,8 @@ const OTHER = SessionId('other') const BROKEN = SessionId('broken') const REQUEST_ID = 'req-1' as SubagentPromptRequestId const signal = new AbortController().signal +/** Durable-reference base for the fake store; per-test ids and media types override. */ +const IMAGE_REF = { attachmentId: 'att', mediaType: 'image/png', bytes: 2, width: 1, height: 1 } /** The runtime plus a programmable live-Agent registry, omitted to compose none. */ async function bench(live?: Record) { @@ -158,14 +161,70 @@ describe('subagent prompt Remote', () => { expect(followup).not.toHaveBeenCalled() }) - it('forwards non-text content blocks without narrowing them', async () => { - const { subagents } = await bench({ [PARENT]: { status: 'idle' } }) + it('admits ordered image parts into durable references before delivery', async () => { + const { ctx, subagents } = await bench({ [PARENT]: { status: 'idle' } }) + const saveImages = vi.fn(async (inputs: readonly { mediaType: string }[]) => + inputs.map((input, index) => ({ ...IMAGE_REF, attachmentId: `att-${index}`, mediaType: input.mediaType }))) + ctx.provide('attachments', { saveImages } as never) const followup = vi.spyOn(subagents, 'followup').mockResolvedValue('m-content' as MessageId) - const content = [{ type: 'reasoning' as const, text: 'retain this block' }] + const content = [ + { type: 'text' as const, text: 'before' }, + { type: 'image' as const, mediaType: 'image/png' as const, data: 'aGk=' }, + { type: 'text' as const, text: 'after' }, + ] await expect(subagents.prompt({ ...promptRequest(), content }, signal)) .resolves.toEqual({ messageId: 'm-content' }) - expect(followup.mock.calls[0]?.[2]).toEqual(content) + expect(followup.mock.calls[0]?.[2]).toEqual([ + { type: 'text', text: 'before' }, + { type: 'image', attachment: { ...IMAGE_REF, attachmentId: 'att-0', mediaType: 'image/png' } }, + { type: 'text', text: 'after' }, + ]) + }) + + it('maps a refused image batch to attachment-error and delivers nothing', async () => { + const { ctx, subagents } = await bench({ [PARENT]: { status: 'idle' } }) + ctx.provide('attachments', { + saveImages: async () => { + throw new AttachmentError('Image batch exceeds the configured image-count limit.', 'TOO_MANY_IMAGES') + }, + } as never) + const followup = vi.spyOn(subagents, 'followup') + + await expect(subagents.prompt({ + ...promptRequest(), + content: [{ type: 'image' as const, mediaType: 'image/png' as const, data: 'aGk=' }], + }, signal)).rejects.toMatchObject({ + failure: { code: 'attachment-error', details: { reason: 'TOO_MANY_IMAGES' } }, + }) + expect(followup).not.toHaveBeenCalled() + }) + + it('maps non-canonical base64 to attachment-error without touching the store', async () => { + const { ctx, subagents } = await bench({ [PARENT]: { status: 'idle' } }) + const saveImages = vi.fn() + ctx.provide('attachments', { saveImages } as never) + const followup = vi.spyOn(subagents, 'followup') + + await expect(subagents.prompt({ + ...promptRequest(), + content: [{ type: 'image' as const, mediaType: 'image/png' as const, data: 'not base64!' }], + }, signal)).rejects.toMatchObject({ + failure: { code: 'attachment-error', details: { reason: 'INVALID_IMAGE_BASE64' } }, + }) + expect(saveImages).not.toHaveBeenCalled() + expect(followup).not.toHaveBeenCalled() + }) + + it('maps a text-only child model refusal to attachment-error', async () => { + const { subagents } = await bench({ [PARENT]: { status: 'idle' } }) + vi.spyOn(subagents, 'followup').mockRejectedValue( + new SubagentError('Model "text-only" does not support image input.', 'MODEL_DOES_NOT_SUPPORT_IMAGES'), + ) + + await expect(subagents.prompt(promptRequest(), signal)).rejects.toMatchObject({ + failure: { code: 'attachment-error', details: { reason: 'MODEL_DOES_NOT_SUPPORT_IMAGES' } }, + }) }) it('delivers the content under the caller-minted identity and canonical browser zone', async () => { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f271832de3..432036f26a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -8239,6 +8239,9 @@ importers: '@deepseek-ai/dsh-agent-presets': specifier: workspace:^ version: link:../../preset/agent-presets + '@deepseek-ai/dsh-attachment': + specifier: workspace:^ + version: link:../../attachment/attachment '@deepseek-ai/dsh-brand': specifier: workspace:^ version: link:../../util/brand diff --git a/snapshots/web/queued-image/delivered.expected.md b/snapshots/web/queued-image/delivered.expected.md new file mode 100644 index 0000000000..332f611048 --- /dev/null +++ b/snapshots/web/queued-image/delivered.expected.md @@ -0,0 +1,82 @@ +- banner: + - navigation "Session hierarchy": + - button "Reply with a one-sentence description" [disabled] + - img + - text: Standard mode + - button "Session log": + - text: Session log + - img + - tablist: + - tab "Chat" [selected] + - tab "Trajectory" +- navigation "Turn navigation": + - button "Jump to turn 1" + - button "Jump to turn 2" + - button "Jump to turn 3" +- button "System prompt": + - img + - img + - text: System prompt +- text: Reply with a one-sentence description of event sourcing, then stop. {{clock}} +- button "Copy": + - img +- button "Context injection @deepseek-ai/dsh-system-prompt": + - img + - img + - text: Context injection @deepseek-ai/dsh-system-prompt +- paragraph: partial +- text: Stopped +- button "Copy": + - img +- button "Good response": + - img +- button "Bad response": + - img +- button "Branch into a new conversation": + - img +- text: {{clock}} Ran for {{duration}} TTFT {{duration}} +- button "queued.png, click to view original": + - img "queued.png" +- text: Compare with this screenshot {{clock}} +- button "Copy": + - img +- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls.": + - img + - img + - text: Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls. +- paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures. +- button "Copy": + - img +- button "Good response": + - img +- button "Bad response": + - img +- button "Branch into a new conversation": + - img +- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s Continue with the queued comparison {{clock}} +- button "Copy": + - img +- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls.": + - img + - img + - text: Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls. +- paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures. +- button "Copy": + - img +- button "Good response": + - img +- button "Bad response": + - img +- button "Branch into a new conversation": + - img +- text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s +- textbox "Message or run a task... / commands, @ files or sessions" +- button "Commands": + - img +- 'button "Access mode, current: Workspace Write"': Workspace Write +- button "Select model, current DeepSeek-V4-Flash": + - text: DeepSeek-V4-Flash + - img +- button "6% of context used" +- button "Send message" [disabled] +- text: 3 turns · 3 steps LLM {{duration}} TTFT avg {{duration}} · {{throughput}} tok/s Cache hit 99% Input 15.6K tok · Output 158 tok diff --git a/snapshots/web/queued-image/queued.expected.md b/snapshots/web/queued-image/queued.expected.md new file mode 100644 index 0000000000..462b6d03d1 --- /dev/null +++ b/snapshots/web/queued-image/queued.expected.md @@ -0,0 +1,42 @@ +- banner: + - navigation "Session hierarchy": + - button "Reply with a one-sentence description" [disabled] + - img + - text: Standard mode + - button "Session log": + - text: Session log + - img + - tablist: + - tab "Chat" [selected] + - tab "Trajectory" +- button "System prompt": + - img + - img + - text: System prompt +- text: Reply with a one-sentence description of event sourcing, then stop. {{clock}} +- button "Copy": + - img +- button "Context injection @deepseek-ai/dsh-system-prompt": + - img + - img + - text: Context injection @deepseek-ai/dsh-system-prompt +- paragraph: partial +- status: Deep diving... +- list: + - listitem: + - img "Queued message image" + - text: Compare with this screenshot + - button "Edit queued message" [disabled]: + - img + - button "Remove queued message": + - img + - button "Steer queued message": + - img +- textbox "Cmd/Ctrl+Enter steers all queued messages" +- button "Commands": + - img +- 'button "Access mode, current: Workspace Write"': Workspace Write +- button "Select model, current DeepSeek-V4-Flash": + - text: DeepSeek-V4-Flash + - img +- button "Stop generating" diff --git a/snapshots/web/queued-image/snapshot.yml b/snapshots/web/queued-image/snapshot.yml new file mode 100644 index 0000000000..69c492d2b2 --- /dev/null +++ b/snapshots/web/queued-image/snapshot.yml @@ -0,0 +1,9 @@ +version: 1 +scenario: queued-image +profile: web +composition: web-default +recording: authored +header: + class: web-default +session: + source: ../live-interactions/session.jsonl diff --git a/tsconfig.host.json b/tsconfig.host.json index b91be8e6ca..9b1f3cde4e 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -60,6 +60,7 @@ "apps/web/tests/markdown-cjk-strong.e2e.ts", "apps/web/tests/markdown-inline-code-links.e2e.ts", "apps/web/tests/queue-actions.e2e.ts", + "apps/web/tests/queue-image.e2e.ts", "apps/web/tests/skill-invocation-policy.e2e.ts", "apps/web/tests/skill-user-invoke.e2e.ts", "apps/web/tests/permission-policy-context.e2e.ts", From 2951512e182b84a67a3c0f271c99ab89a57b11a2 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 15:59:03 +0800 Subject: [PATCH 02/63] docs: refresh module graph for subagent attachments --- docs/module-graph.i18n.yaml | 4 ++-- docs/module-graph.md | 3 ++- docs/module-graph.zh.md | 3 ++- 3 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 5d08c21d3e..12ac07a710 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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/module-graph.md -module-graph.md: 28885c4bde3215075f213135ad64db8feadb4a9a -module-graph.zh.md: 68d22f46c645dd62426f893bec4a0b5399d5ef6e +module-graph.md: c04dcb31589389e61f14d2fd37af56a61e600c03 +module-graph.zh.md: 2dad35fdb08790ad6e613e06bf5f1e64d1b1611f diff --git a/docs/module-graph.md b/docs/module-graph.md index 28885c4bde..c04dcb3158 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -1059,6 +1059,7 @@ flowchart TD pkg_webhook --> pkg_workspace pkg_subagent --> pkg_agent pkg_subagent --> pkg_agent_presets + pkg_subagent --> pkg_attachment pkg_subagent --> pkg_brand pkg_subagent --> pkg_invariants pkg_subagent --> pkg_jobs @@ -1864,7 +1865,7 @@ flowchart TD | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | -| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) | +| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`host-apiproxy`](../packages/host/apiproxy), [`host-directory-picker`](../packages/host/directory-picker), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`tool-todo`](../packages/todo/tool-todo) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 68d22f46c6..2dad35fdb0 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -1061,6 +1061,7 @@ flowchart TD pkg_webhook --> pkg_workspace pkg_subagent --> pkg_agent pkg_subagent --> pkg_agent_presets + pkg_subagent --> pkg_attachment pkg_subagent --> pkg_brand pkg_subagent --> pkg_invariants pkg_subagent --> pkg_jobs @@ -1866,7 +1867,7 @@ flowchart TD | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | -| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) | +| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`host-apiproxy`](../packages/host/apiproxy), [`host-directory-picker`](../packages/host/directory-picker), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`tool-todo`](../packages/todo/tool-todo) | From ba810b35394ebef91d1d48db2d3295d11455b1bd Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 16:31:04 +0800 Subject: [PATCH 03/63] fix: harden subagent image follow-up admission --- ...27-steer-followup-image-delivery.i18n.yaml | 4 +- ...026-08-27-steer-followup-image-delivery.md | 2 +- ...-08-27-steer-followup-image-delivery.zh.md | 2 +- ...07-27-web-subagent-conversations.i18n.yaml | 4 +- .../2026-07-27-web-subagent-conversations.md | 4 +- ...026-07-27-web-subagent-conversations.zh.md | 4 +- apps/web/tests/queue-image.e2e.ts | 7 + .../src/client/queue/QueueDock.tsx | 243 +++++++++--------- packages/core/agent-loop/src/agent.ts | 6 +- .../subagent/subagent/src/continuation.ts | 22 +- packages/subagent/subagent/src/index.ts | 9 +- .../subagent/tests/continuation.spec.ts | 58 ++++- .../subagent/subagent/tests/control.spec.ts | 13 + 13 files changed, 238 insertions(+), 140 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml index 8f4d10d9e8..318e44996e 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.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-08-27-steer-followup-image-delivery.md -2026-08-27-steer-followup-image-delivery.md: fb93612254381b589c8adfe44e46c51dfe232c3e -2026-08-27-steer-followup-image-delivery.zh.md: 35284aba89a7df5da5d472f078d2c2d3ea2e307d +2026-08-27-steer-followup-image-delivery.md: 71f1d470fa6435758a22baaf9630f5c241aabc47 +2026-08-27-steer-followup-image-delivery.zh.md: 72c47d5e3366b181b1ffbdb112cac06292616f2f diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md index fb93612254..71f1d470fa 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md @@ -18,7 +18,7 @@ Third, the browser queue projection reduced a queued image to the text `[image]` **Closing-turn wake delivery.** `ReactLoopAgent` tracks the identities of waking sends still awaiting a claim (`pendingWakes`); claim and discard notifications prune the set. At a driver exit whose turn loop returned without throwing, a non-empty set re-wakes the driver, so a steer or follow-up that lost the race with a normally closing turn is claimed by a fresh turn. Cancellation and `agent/pre-step` rejection instead clear the set: accepted-but-unclaimed input parks until the next waking send, preserving the tested `cancel({ keepInbox: true })` semantics and keeping rejected claims from being re-offered to the rejecting policy. Injected context never enters the set. The turn-flow section of [docs/architecture.md](../../../../docs/architecture.md) records the delivery/parking rule. -**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]`, whose single home moved from `dsh-api-session-controller` to `dsh-attachment`; the shared `durablePromptContent()` conversion lives in `dsh-llm/content` and is used by both the Session prompt endpoint and `SubagentRuntime.prompt`. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. +**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]` (updating the wire contract in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)), whose single home moved from `dsh-api-session-controller` to `dsh-attachment`; the shared `durablePromptContent()` conversion lives in `dsh-llm/content` and is used by both the Session prompt endpoint and `SubagentRuntime.prompt`. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. **Queue presentation.** The queue mirror's text preview excludes image blocks, and the queue dock renders each durable image part as a thumbnail resolved through `ctx.uiConversation.imageUrl` — the same session-authorized read the transcript uses. Editing queued image messages stays refused (#3072). diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md index 35284aba89..72c47d5e33 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md @@ -18,7 +18,7 @@ agent 运行期间提交的图片没有可靠进入模型上下文（#3186）， **轮次收尾期的唤醒投递。** `ReactLoopAgent` 用 `pendingWakes` 记录尚未被认领的唤醒发送的身份；认领与丢弃通知会移除对应条目。当 driver 的轮次循环无异常返回并退出时，集合非空就重新拉起 driver，输掉与正常收尾轮次竞态的 steer 或 follow-up 由新轮次认领。取消与 `agent/pre-step` 拒绝则清空该集合：已接受但未认领的输入停放到下一次唤醒发送，既保留了有测试保护的 `cancel({ keepInbox: true })` 语义，也避免把被拒绝的认领重新塞给同一个拒绝策略。注入的上下文从不进入该集合。投递与停放规则记录在 [docs/architecture.md](../../../../docs/architecture.zh.md) 的 turn-flow 一节。 -**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`，该类型的唯一定义处从 `dsh-api-session-controller` 移到 `dsh-attachment`；共享的 `durablePromptContent()` 转换位于 `dsh-llm/content`，Session prompt 端点与 `SubagentRuntime.prompt` 共用。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 +**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`（同步更新 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 的 wire 契约），该类型的唯一定义处从 `dsh-api-session-controller` 移到 `dsh-attachment`；共享的 `durablePromptContent()` 转换位于 `dsh-llm/content`，Session prompt 端点与 `SubagentRuntime.prompt` 共用。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 **队列展示。** 队列镜像的文本预览不再包含图片块，queue dock 把每个持久化图片部分渲染为缩略图，经 `ctx.uiConversation.imageUrl` 解析，与会话记录使用同一个会话授权读取。已排队图片消息的编辑仍然拒绝（#3072）。 diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml index 684ebea047..9b8b530bdc 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.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-07-27-web-subagent-conversations.md -2026-07-27-web-subagent-conversations.md: c897d345d9749facfb2046104b7a95076cf2df95 -2026-07-27-web-subagent-conversations.zh.md: 0fdfd19b6dac56c275bb2d2306ed492a269e70d2 +2026-07-27-web-subagent-conversations.md: 8998d6c5b828efbe3a817f50b272ee17ef5afb46 +2026-07-27-web-subagent-conversations.zh.md: f890bca9eb7a0d78813109fcee771b0e2518dc19 diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md index c897d345d9..8998d6c5b8 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md @@ -55,9 +55,9 @@ Agent-bound auxiliary controls are unavailable in addressed child views. In part - `subagent.list` takes `parentSessionId`, calls `ctx.subagents.listChildren(parentSessionId, signal)`, returns the complete ordered entries with each healthy row's boolean `hasChildren` snapshot, replaces each healthy row's corpus activity with whether its exact Agent driver is running, and includes whether the exact parent currently resolves from `ctx.agents`. - `subagent.history` takes the full mode-bearing address plus ordinary page arguments. It verifies the child and mode against the direct catalog, reads through `ctx.sessionQuery.readSession()`, rechecks direct lineage, and returns the ordinary raw-event, render-intent, pagination, and host-computed session-projection baseline without publishing an Agent. -- `subagent.prompt` accepts only a `mode: 'continuable'` address and `ContentBlock[]`. It requires the exact live parent, revalidates the catalog address, calls `ctx.subagents.followup(parent, childId, content, { source, signal })`, and returns the accepted `MessageId`. +- `subagent.prompt` accepts only a `mode: 'continuable'` address and upload-shaped `PromptContentPart[]`; the Host admits and persists image parts into durable references before delivery ([image delivery](../bug-fix/2026-08-27-steer-followup-image-delivery.md)). It requires the exact live parent, revalidates the catalog address, calls `ctx.subagents.followup(parent, childId, content, { source, signal })`, and returns the accepted `MessageId`. -The gateway maps missing parent, missing or diagnostic catalog entries, not-resumable and unauthorized children, request cancellation, and temporarily unavailable continuation admission to typed RPC errors. It does not expose descriptor or provider details. A list/prompt race is normal: the prompt result, not the earlier availability or activity snapshot, is authoritative. +The gateway maps missing parent, missing or diagnostic catalog entries, not-resumable and unauthorized children, request cancellation, image admission and image-capability refusals (`attachment-error`), and temporarily unavailable continuation admission to typed RPC errors. It does not expose descriptor or provider details. A list/prompt race is normal: the prompt result, not the earlier availability or activity snapshot, is authoritative. Viewing persisted history creates no mux subscription by itself. When a follow-up materializes a cold child Activation, the existing Host and mux streams publish its lifecycle and events. Reconnect rebuilds the addressed window through `subagent.history`. diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md index 0fdfd19b6d..f890bca9eb 100644 --- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md +++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md @@ -55,9 +55,9 @@ one-shot 行始终会用文案替代输入框，说明执行记录为只读。 - `subagent.list` 接受 `parentSessionId`，调用 `ctx.subagents.listChildren(parentSessionId, signal)`，返回完整有序的条目以及每个健康行的布尔 `hasChildren` 快照，把每个健康行的语料活动状态替换为其确切 Agent driver 是否正在运行，并说明当前能否从 `ctx.agents` 解析出确切 parent。 - `subagent.history` 接受包含 mode 的完整地址与普通页参数。它对照直接目录校验 child 与 mode，通过 `ctx.sessionQuery.readSession()` 读取，再次检查直接谱系，并在不发布 agent 的情况下返回普通原始事件、渲染意图、分页与由 Host 计算的会话投影基线。 -- `subagent.prompt` 只接受 `mode: 'continuable'` 地址与 `ContentBlock[]`。它要求确切的存活 parent，重新校验目录地址，调用 `ctx.subagents.followup(parent, childId, content, { source, signal })`，并返回已接受的 `MessageId`。 +- `subagent.prompt` 只接受 `mode: 'continuable'` 地址与上传形态的 `PromptContentPart[]`；Host 在投递前把图片部分准入并持久化为持久引用（[图片投递](../bug-fix/2026-08-27-steer-followup-image-delivery.zh.md)）。它要求确切的存活 parent，重新校验目录地址，调用 `ctx.subagents.followup(parent, childId, content, { source, signal })`，并返回已接受的 `MessageId`。 -网关会将 parent 缺失、目录条目缺失或为 diagnostic、child 不可恢复或未授权、请求取消以及继续执行准入暂时不可用等失败映射为类型化 RPC 错误。它不会公开描述符或提供方细节。list／prompt 竞态属于正常情况：权威依据是提示词操作的结果，而不是更早的可用性或活动快照。 +网关会将 parent 缺失、目录条目缺失或为 diagnostic、child 不可恢复或未授权、请求取消、图片准入或图片能力拒绝（`attachment-error`）以及继续执行准入暂时不可用等失败映射为类型化 RPC 错误。它不会公开描述符或提供方细节。list／prompt 竞态属于正常情况：权威依据是提示词操作的结果，而不是更早的可用性或活动快照。 查看持久化历史本身不会创建 mux 订阅。当后续消息物化冷态 child Activation 时，现有 Host 与 mux 流会发布其生命周期与事件。重新连接时，系统通过 `subagent.history` 重建已寻址窗口。 diff --git a/apps/web/tests/queue-image.e2e.ts b/apps/web/tests/queue-image.e2e.ts index e5a4794d82..37f30c167b 100644 --- a/apps/web/tests/queue-image.e2e.ts +++ b/apps/web/tests/queue-image.e2e.ts @@ -119,6 +119,13 @@ describe('web e2e: queued image submission', () => { await input.fill('Continue with the queued comparison') await input.press('Enter') await settled + // The queued image message and the waking text run as two further turns; + // wait for both to end so the final snapshot never captures a mid-reply + // frame (the aborted first turn precedes them). + await expect.poll( + () => sessionEvents.flatMap(event => event.type === 'turn/end' ? [event.data.reason.kind] : []), + { timeout: 15_000 }, + ).toEqual(['aborted', 'completed', 'completed']) // The delivered user message renders its image in Chat from the durable // reference, and the dock row is gone. diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx index a42b8cea68..c90c699c51 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx @@ -128,133 +128,136 @@ export function QueueDock({ useSession, updateQueue, notify, loadImage, t }: Que )}
} - - ))} + {queueMutable &&
+ {editing?.id === row.id + ? ( + <> + + + + + + + + ) + : ( + <> + + + + + + + + + + + )} +
} + + ) + })} diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 9bac17bff0..0c99d38fbb 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -72,8 +72,10 @@ export class ReactLoopAgent implements Agent { private activityDone: Promise = Promise.resolve() /** * Identities of waking sends still awaiting a claim. Claim and discard - * notifications prune the set, and {@link cancel} clears it because a - * cancellation parks accepted-but-unclaimed input for a later waking send. + * notifications prune the set per message, while {@link cancel} and a + * pre-step rejection clear the set. Parking consumes every outstanding + * wake, including follow-ups unrelated to the rejected claim, + * because the next waking send resumes the complete parked queue anyway. * A non-empty set at driver exit therefore means a steer or follow-up lost * the race with a normally or erroneously closing turn, and the exit must * start a fresh driver to deliver it. Injected context never enters the diff --git a/packages/subagent/subagent/src/continuation.ts b/packages/subagent/subagent/src/continuation.ts index f3b90a8075..68641655ec 100644 --- a/packages/subagent/subagent/src/continuation.ts +++ b/packages/subagent/subagent/src/continuation.ts @@ -516,17 +516,25 @@ export class SubagentContinuationManager { if (activation === undefined) return this.coldResume(parent, childId, content, options) // A delivery that arrives after the disposal transaction began must not // reach a handle being torn down; wait for release, then cold-resume. + const disposal = activation.disposal /* v8 ignore next 3 -- the send-versus-dispose cutoff: reaching this arm needs a * delivery to observe the transaction inside the same critical section that opened it, * which no test can schedule deterministically. The behavior is covered end-to-end by * "cold-resumes a delivery that lost the race with final disposal". */ - if (activation.disposal !== undefined) { - return activation.disposal.then(() => undefined, () => undefined) + if (disposal !== undefined) { + return disposal.then(() => undefined, () => undefined) } - // Guarded call: text-only delivery must not gain an await hop inside - // the per-child lock, where it would reorder against drain admission. + // Text-only delivery stays await-free, so the disposal-cutoff check + // above and the submit share one critical window. The image path + // awaits a capability read, so it re-checks the cutoff afterwards; a + // disposal that began during the read is waited out and retried like + // one observed on entry. if (contentHasImage(content)) { await this.assertImageCapable(activation.handle.agent, options.signal) + if (activation.disposal !== undefined) { + await Promise.allSettled([activation.disposal]) + return undefined + } } return this.submitAdmitted(activation, content, options.source, parent, options.signal) }) @@ -1027,7 +1035,13 @@ export class SubagentContinuationManager { ): Promise { try { if (contentHasImage(content)) { + // The capability read awaits with the activation already published, so + // the disposal cutoff is re-checked before the submit; a drain that + // began during the read turns into a clean closing rejection. await this.assertImageCapable(activation.handle.agent, signal) + if (activation.disposal !== undefined) { + throw new SubagentError(`subagent "${activation.childId}" is closing`, 'ACTIVATION_CLOSING') + } } return this.submitAdmitted(activation, content, source, parent, signal) } catch (error: unknown) { diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts index f1a8689131..aeeeca3829 100644 --- a/packages/subagent/subagent/src/index.ts +++ b/packages/subagent/subagent/src/index.ts @@ -459,7 +459,14 @@ export class SubagentRuntime extends TypertRemoteService { try { // Admission precedes delivery: image parts become durable references // here, so the child inbox only ever accepts Host-persisted attachments. - const content: ContentBlock[] = await durablePromptContent(this.ctx.attachments, request.content) + let content: ContentBlock[] + if (request.content.every((part): part is { readonly type: 'text'; readonly text: string } => part.type === 'text')) { + content = request.content.map(part => ({ type: 'text', text: part.text })) + } else { + const attachments = this.ctx.get('attachments') + if (attachments === undefined) throw new Error('subagent image prompt requires an attachment store') + content = await durablePromptContent(attachments, request.content) + } return { messageId: await this.followup(parent, childSessionId, content, { source, signal }) } } catch (error: unknown) { return rejectPrompt(error, childSessionId, signal) diff --git a/packages/subagent/subagent/tests/continuation.spec.ts b/packages/subagent/subagent/tests/continuation.spec.ts index 505da10ff2..6779c11e99 100644 --- a/packages/subagent/subagent/tests/continuation.spec.ts +++ b/packages/subagent/subagent/tests/continuation.spec.ts @@ -550,10 +550,17 @@ describe('continuable image follow-ups', () => { await drainManager(ctx) }) - it('delivers an image follow-up when the child model accepts image input', async () => { - const { ctx, parent } = await setup([textResponse('child work'), textResponse('image reply')]) + it('delivers an image follow-up to a resident child when its model accepts image input', async () => { + const releaseFirst = Promise.withResolvers() + const adapter = new GatedAdapter([ + { chunks: textResponse('child work'), gate: releaseFirst.promise }, + { chunks: textResponse('image reply') }, + ]) + const { ctx, parent } = await setupWith(adapter) const started = await ctx.subagents.startContinuable(startSpec(parent)) - await waitNoActivation(ctx, started.childId) + await vi.waitFor(() => { + expect(adapter.requests).toHaveLength(1) + }) vi.spyOn(ctx.llm, 'resolveModelInfo') .mockResolvedValue({ inputModalities: ['text', 'image'] } as never) @@ -561,6 +568,7 @@ describe('continuable image follow-ups', () => { { type: 'text' as const, text: 'compare' }, imageBlock, ], { source: { kind: 'user' }, signal: testSignal }) + releaseFirst.resolve(undefined) await waitNoActivation(ctx, started.childId) const loaded = await ctx.sessionPersistence.load(started.childId) @@ -573,6 +581,50 @@ describe('continuable image follow-ups', () => { await drainManager(ctx) }) + it('re-checks the disposal cutoff when a drain begins during a live image capability read', async () => { + const releaseFirst = Promise.withResolvers() + const adapter = new GatedAdapter([{ chunks: textResponse('child work'), gate: releaseFirst.promise }]) + const { ctx, parent } = await setupWith(adapter) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await vi.waitFor(() => { expect(adapter.requests).toHaveLength(1) }) + const capability = Promise.withResolvers<{ inputModalities: string[] }>() + const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo').mockReturnValue(capability.promise as never) + + const delivery = ctx.subagents.followup(parent, started.childId, [imageBlock], { + source: { kind: 'user' }, signal: testSignal, + }) + delivery.catch(() => undefined) + await vi.waitFor(() => { expect(resolve).toHaveBeenCalled() }) + releaseFirst.resolve(undefined) + const draining = drainManager(ctx) + capability.resolve({ inputModalities: ['text', 'image'] }) + + await expect(delivery).rejects.toMatchObject({ code: 'DRAINING' }) + await draining + }) + + it('rejects a materialized image follow-up whose capability read raced a drain', async () => { + const { ctx, parent } = await setup([textResponse('child work')]) + const started = await ctx.subagents.startContinuable(startSpec(parent)) + await waitNoActivation(ctx, started.childId) + const capability = Promise.withResolvers<{ inputModalities: string[] }>() + const resolve = vi.spyOn(ctx.llm, 'resolveModelInfo').mockReturnValue(capability.promise as never) + + const delivery = ctx.subagents.followup(parent, started.childId, [imageBlock], { + source: { kind: 'user' }, signal: testSignal, + }) + delivery.catch(() => undefined) + await vi.waitFor(() => { expect(resolve).toHaveBeenCalled() }) + const draining = drainManager(ctx) + capability.resolve({ inputModalities: ['text', 'image'] }) + + await expect(delivery).rejects.toMatchObject({ code: 'ACTIVATION_CLOSING' }) + await draining + const loaded = await ctx.sessionPersistence.load(started.childId) + expect(loaded.events.some(event => event.type === 'user/message' + && event.data.content.some(block => block.type === 'image'))).toBe(false) + }) + it('defers to the text-only projection when the descriptor declares no model route', async () => { const { ctx } = await setup([]) const routeless = ctx.agentLoop.create(SessionId('routeless-image'), {}) diff --git a/packages/subagent/subagent/tests/control.spec.ts b/packages/subagent/subagent/tests/control.spec.ts index 99c534dd49..aaa2e022c6 100644 --- a/packages/subagent/subagent/tests/control.spec.ts +++ b/packages/subagent/subagent/tests/control.spec.ts @@ -216,6 +216,19 @@ describe('subagent prompt Remote', () => { expect(followup).not.toHaveBeenCalled() }) + it('rejects an image prompt when no attachment store is composed', async () => { + const { subagents } = await bench({ [PARENT]: { status: 'idle' } }) + const followup = vi.spyOn(subagents, 'followup') + + await expect(subagents.prompt({ + ...promptRequest(), + content: [{ type: 'image' as const, mediaType: 'image/png' as const, data: 'aGk=' }], + }, signal)).rejects.toMatchObject({ + failure: { code: 'internal', message: 'subagent prompt failed' }, + }) + expect(followup).not.toHaveBeenCalled() + }) + it('maps a text-only child model refusal to attachment-error', async () => { const { subagents } = await bench({ [PARENT]: { status: 'idle' } }) vi.spyOn(subagents, 'followup').mockRejectedValue( From b67663c58323fd04173cc347b2dbc60daf47ee6d Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 16:42:11 +0800 Subject: [PATCH 04/63] fix: retain prompt parts in client catalog --- ...026-08-27-steer-followup-image-delivery.i18n.yaml | 4 ++-- .../2026-08-27-steer-followup-image-delivery.md | 4 ++-- .../2026-08-27-steer-followup-image-delivery.zh.md | 4 ++-- .../src/client/contract/session.ts | 6 ++---- packages/api/session-controller/src/types.ts | 12 ++++++++++-- .../tests/client-contract.client.spec.ts | 8 +++++++- .../cordis-client-runner/src/client/api-catalog.ts | 4 ++++ .../tests/api-catalog.client.spec.ts | 8 +++++++- 8 files changed, 36 insertions(+), 14 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml index 318e44996e..201b7451e6 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.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-08-27-steer-followup-image-delivery.md -2026-08-27-steer-followup-image-delivery.md: 71f1d470fa6435758a22baaf9630f5c241aabc47 -2026-08-27-steer-followup-image-delivery.zh.md: 72c47d5e3366b181b1ffbdb112cac06292616f2f +2026-08-27-steer-followup-image-delivery.md: e5b3f516e45588a865c87a1d8188b50208fbff33 +2026-08-27-steer-followup-image-delivery.zh.md: 37e55b7148841634e306b2a9d17f7f48b099c1eb diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md index 71f1d470fa..e5b3f516e4 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md @@ -18,7 +18,7 @@ Third, the browser queue projection reduced a queued image to the text `[image]` **Closing-turn wake delivery.** `ReactLoopAgent` tracks the identities of waking sends still awaiting a claim (`pendingWakes`); claim and discard notifications prune the set. At a driver exit whose turn loop returned without throwing, a non-empty set re-wakes the driver, so a steer or follow-up that lost the race with a normally closing turn is claimed by a fresh turn. Cancellation and `agent/pre-step` rejection instead clear the set: accepted-but-unclaimed input parks until the next waking send, preserving the tested `cancel({ keepInbox: true })` semantics and keeping rejected claims from being re-offered to the rejecting policy. Injected context never enters the set. The turn-flow section of [docs/architecture.md](../../../../docs/architecture.md) records the delivery/parking rule. -**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]` (updating the wire contract in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)), whose single home moved from `dsh-api-session-controller` to `dsh-attachment`; the shared `durablePromptContent()` conversion lives in `dsh-llm/content` and is used by both the Session prompt endpoint and `SubagentRuntime.prompt`. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. +**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]` (updating the wire contract in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)). `dsh-attachment` owns the shared upload vocabulary used by the subagent route; `dsh-api-session-controller` retains a structurally identical Client-face declaration so the generated Client Cordis catalog contains the complete prompt-part fields, with a compile-time equality test preventing drift. The shared `durablePromptContent()` conversion lives in `dsh-llm/content` and is used by both the Session prompt endpoint and `SubagentRuntime.prompt`. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. **Queue presentation.** The queue mirror's text preview excludes image blocks, and the queue dock renders each durable image part as a thumbnail resolved through `ctx.uiConversation.imageUrl` — the same session-authorized read the transcript uses. Editing queued image messages stays refused (#3072). @@ -34,7 +34,7 @@ Third, the browser queue projection reduced a queued image to the text `[image]` ## Testing -Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, queue thumbnails (load, failure placeholder, unmount), and the image-free preview. +Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, the catalog-visible upload declaration, queue thumbnails (load, failure placeholder, unmount), and the image-free preview. ## Consequences diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md index 72c47d5e33..37e55b7148 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md @@ -18,7 +18,7 @@ agent 运行期间提交的图片没有可靠进入模型上下文（#3186）， **轮次收尾期的唤醒投递。** `ReactLoopAgent` 用 `pendingWakes` 记录尚未被认领的唤醒发送的身份；认领与丢弃通知会移除对应条目。当 driver 的轮次循环无异常返回并退出时，集合非空就重新拉起 driver，输掉与正常收尾轮次竞态的 steer 或 follow-up 由新轮次认领。取消与 `agent/pre-step` 拒绝则清空该集合：已接受但未认领的输入停放到下一次唤醒发送，既保留了有测试保护的 `cancel({ keepInbox: true })` 语义，也避免把被拒绝的认领重新塞给同一个拒绝策略。注入的上下文从不进入该集合。投递与停放规则记录在 [docs/architecture.md](../../../../docs/architecture.zh.md) 的 turn-flow 一节。 -**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`（同步更新 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 的 wire 契约），该类型的唯一定义处从 `dsh-api-session-controller` 移到 `dsh-attachment`；共享的 `durablePromptContent()` 转换位于 `dsh-llm/content`，Session prompt 端点与 `SubagentRuntime.prompt` 共用。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 +**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`（同步更新 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 的 wire 契约）。`dsh-attachment` 负责子代理路由使用的共享上传词汇；`dsh-api-session-controller` 保留结构相同的 Client face 声明，使生成的 Client Cordis 目录包含完整的 prompt part 字段，并用编译期等价测试防止两处定义偏离。共享的 `durablePromptContent()` 转换位于 `dsh-llm/content`，Session prompt 端点与 `SubagentRuntime.prompt` 共用。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 **队列展示。** 队列镜像的文本预览不再包含图片块，queue dock 把每个持久化图片部分渲染为缩略图，经 `ctx.uiConversation.imageUrl` 解析，与会话记录使用同一个会话授权读取。已排队图片消息的编辑仍然拒绝（#3072）。 @@ -34,7 +34,7 @@ agent 运行期间提交的图片没有可靠进入模型上下文（#3186）， ## Testing -agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、队列缩略图（加载、失败占位、卸载）与不含图片的预览。 +agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、目录可见的上传声明、队列缩略图（加载、失败占位、卸载）与不含图片的预览。 ## Consequences diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts index 7284f86603..9b8ed3f7ec 100644 --- a/packages/api/session-controller/src/client/contract/session.ts +++ b/packages/api/session-controller/src/client/contract/session.ts @@ -7,14 +7,12 @@ * must stub); implementation-internal entry points (history staging, wire-frame * dispatch) stay on the class, invisible out here. */ -import type { - AttachmentIdType, ImageAttachmentRef, PromptContentPart, -} from '@deepseek-ai/dsh-attachment' +import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store' -import type { QueueAction, SessionRequestId } from '../../types.ts' +import type { PromptContentPart, QueueAction, SessionRequestId } from '../../types.ts' import type { ClientResult } from './result.ts' import type { PendingSubmissionImage, SessionSnapshot } from './snapshot.ts' diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index 08b412ce46..e9e416777c 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -1,7 +1,7 @@ /** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */ import type { - AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, PromptContentPart, + AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, } from '@deepseek-ai/dsh-attachment' import type { Branded } from '@deepseek-ai/dsh-brand' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' @@ -67,7 +67,15 @@ export interface SessionProjectionBaseline { export type SessionProjectionValues = Partial & Readonly> -export type { PromptContentPart } from '@deepseek-ai/dsh-attachment' +/** Browser-submitted prompt content; the Host promotes image bytes to durable references. */ +export type PromptContentPart = + | { readonly type: 'text'; readonly text: string } + | { + readonly type: 'image' + readonly mediaType: ImageMediaType + readonly data: string + readonly name?: string + } /** Complete model selection for one Session. */ export interface ModelSelection { diff --git a/packages/api/session-controller/tests/client-contract.client.spec.ts b/packages/api/session-controller/tests/client-contract.client.spec.ts index 789fe04d6d..19814e8f93 100644 --- a/packages/api/session-controller/tests/client-contract.client.spec.ts +++ b/packages/api/session-controller/tests/client-contract.client.spec.ts @@ -1,8 +1,10 @@ -import { describe, expect, it, vi } from 'vitest' +import { describe, expect, expectTypeOf, it, vi } from 'vitest' +import type { PromptContentPart as AttachmentPromptContentPart } from '@deepseek-ai/dsh-attachment/types' import { MutableSessionEventSource, type SessionLiveEventEntry, } from '../src/client/contract/events.ts' import { transportResult } from '../src/client/contract/result.ts' +import type { PromptContentPart as SessionPromptContentPart } from '../src/types.ts' function entry(seq: number): SessionLiveEventEntry { return { @@ -17,6 +19,10 @@ function entry(seq: number): SessionLiveEventEntry { } describe('Client Session contracts', () => { + it('keeps its catalog-visible prompt parts identical to attachment intake', () => { + expectTypeOf().toEqualTypeOf() + }) + it('publishes exact replace, prepend, and append event-window changes', () => { const feed = new MutableSessionEventSource() const listener = vi.fn() diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts index 7c9c11b781..633c553557 100644 --- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts @@ -622,6 +622,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'ProjectionsFace', declaration: 'export interface ProjectionsFace {\n faceOf(key: string): ObservableSnapshot;\n}', }, + { + name: 'PromptContentPart', + declaration: 'export type PromptContentPart = {\n readonly type: \'text\';\n readonly text: string;\n} | {\n readonly type: \'image\';\n readonly mediaType: ImageMediaType;\n readonly data: string;\n readonly name?: string;\n};', + }, { name: 'PromptError', declaration: 'export interface PromptError {\n readonly op: \'send\' | \'stop\';\n readonly error: ClientFailure;\n}', diff --git a/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts b/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts index 019d34ac90..4d9239da45 100644 --- a/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts +++ b/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts @@ -30,9 +30,15 @@ describe('Client Cordis inspect catalog', () => { it('includes the current referenced type closure for the Sessions service', () => { const result = queryServiceApi('sessions') as { - referencedTypes: readonly { name: string }[] + referencedTypes: readonly { name: string; declaration: string }[] } expect(result.referencedTypes.length).toBeGreaterThan(0) + expect(result.referencedTypes).toEqual(expect.arrayContaining([ + expect.objectContaining({ + name: 'PromptContentPart', + declaration: expect.stringContaining("readonly type: 'image'"), + }), + ])) expect(result.referencedTypes.map(type => type.name)).not.toEqual(expect.arrayContaining([ 'ConversationSnapshot', 'PendingInteraction', From abe185205bbcce29e54e0cb5ade2f05217ee6304 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 16:49:15 +0800 Subject: [PATCH 05/63] fix: scope prompt catalog type to client --- .../src/client/contract/session.ts | 14 ++++++++++++-- packages/api/session-controller/src/types.ts | 12 ++---------- .../tests/client-contract.client.spec.ts | 2 +- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts index 9b8ed3f7ec..7007ffc070 100644 --- a/packages/api/session-controller/src/client/contract/session.ts +++ b/packages/api/session-controller/src/client/contract/session.ts @@ -7,15 +7,25 @@ * must stub); implementation-internal entry points (history staging, wire-frame * dispatch) stay on the class, invisible out here. */ -import type { AttachmentIdType, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' +import type { AttachmentIdType, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' import type { SessionId } from '@deepseek-ai/dsh-session/types' import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store' -import type { PromptContentPart, QueueAction, SessionRequestId } from '../../types.ts' +import type { QueueAction, SessionRequestId } from '../../types.ts' import type { ClientResult } from './result.ts' import type { PendingSubmissionImage, SessionSnapshot } from './snapshot.ts' +/** Browser-submitted prompt content; the Host promotes image bytes to durable references. */ +export type PromptContentPart = + | { readonly type: 'text'; readonly text: string } + | { + readonly type: 'image' + readonly mediaType: ImageMediaType + readonly data: string + readonly name?: string + } + /** * Why a local submission echo left the snapshot: `observed` when its durable * `user/message` event or host queue occurrence arrived (with the admitted diff --git a/packages/api/session-controller/src/types.ts b/packages/api/session-controller/src/types.ts index e9e416777c..08b412ce46 100644 --- a/packages/api/session-controller/src/types.ts +++ b/packages/api/session-controller/src/types.ts @@ -1,7 +1,7 @@ /** Browser-safe request, result, and lifecycle vocabulary for the Session Remote service. */ import type { - AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, ImageMediaType, + AttachmentIdType, ImageAttachmentLimits, ImageAttachmentRef, PromptContentPart, } from '@deepseek-ai/dsh-attachment' import type { Branded } from '@deepseek-ai/dsh-brand' import type { MessageId } from '@deepseek-ai/dsh-llm/brand' @@ -67,15 +67,7 @@ export interface SessionProjectionBaseline { export type SessionProjectionValues = Partial & Readonly> -/** Browser-submitted prompt content; the Host promotes image bytes to durable references. */ -export type PromptContentPart = - | { readonly type: 'text'; readonly text: string } - | { - readonly type: 'image' - readonly mediaType: ImageMediaType - readonly data: string - readonly name?: string - } +export type { PromptContentPart } from '@deepseek-ai/dsh-attachment' /** Complete model selection for one Session. */ export interface ModelSelection { diff --git a/packages/api/session-controller/tests/client-contract.client.spec.ts b/packages/api/session-controller/tests/client-contract.client.spec.ts index 19814e8f93..e977d8a21f 100644 --- a/packages/api/session-controller/tests/client-contract.client.spec.ts +++ b/packages/api/session-controller/tests/client-contract.client.spec.ts @@ -3,8 +3,8 @@ import type { PromptContentPart as AttachmentPromptContentPart } from '@deepseek import { MutableSessionEventSource, type SessionLiveEventEntry, } from '../src/client/contract/events.ts' +import type { PromptContentPart as SessionPromptContentPart } from '../src/client/contract/session.ts' import { transportResult } from '../src/client/contract/result.ts' -import type { PromptContentPart as SessionPromptContentPart } from '../src/types.ts' function entry(seq: number): SessionLiveEventEntry { return { From 5bb24c03f1048c98687c202a577e84d6e3fb4c9e Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 16:57:12 +0800 Subject: [PATCH 06/63] test: avoid untyped catalog matcher --- .../cordis-client-runner/tests/api-catalog.client.spec.ts | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts b/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts index 4d9239da45..49411941f6 100644 --- a/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts +++ b/packages/extensions/cordis-client-runner/tests/api-catalog.client.spec.ts @@ -33,12 +33,8 @@ describe('Client Cordis inspect catalog', () => { referencedTypes: readonly { name: string; declaration: string }[] } expect(result.referencedTypes.length).toBeGreaterThan(0) - expect(result.referencedTypes).toEqual(expect.arrayContaining([ - expect.objectContaining({ - name: 'PromptContentPart', - declaration: expect.stringContaining("readonly type: 'image'"), - }), - ])) + const promptContentPart = result.referencedTypes.find(type => type.name === 'PromptContentPart') + expect(promptContentPart?.declaration).toContain("readonly type: 'image'") expect(result.referencedTypes.map(type => type.name)).not.toEqual(expect.arrayContaining([ 'ConversationSnapshot', 'PendingInteraction', From 53f5418a72c97fc5354939f668fb574984b65135 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 17:25:36 +0800 Subject: [PATCH 07/63] =?UTF-8?q?fix:=20=E7=A8=B3=E5=AE=9A=20steer=20?= =?UTF-8?q?=E6=8F=90=E4=BA=A4=E5=9B=9E=E6=98=BE=E4=BD=8D=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...27-steer-followup-image-delivery.i18n.yaml | 4 +- ...026-08-27-steer-followup-image-delivery.md | 10 +++- ...-08-27-steer-followup-image-delivery.zh.md | 10 +++- .../api/session-controller/README.i18n.yaml | 4 +- packages/api/session-controller/README.md | 2 +- packages/api/session-controller/README.zh.md | 2 +- .../src/client/contract/session.ts | 6 +- .../src/client/contract/snapshot.ts | 5 ++ .../session-controller/src/client/index.ts | 1 + .../src/client/sessions/session.ts | 1 + ...session-pending-submissions.client.spec.ts | 18 ++++-- packages/client/ui-chat/README.i18n.yaml | 4 +- packages/client/ui-chat/README.md | 2 +- packages/client/ui-chat/README.zh.md | 2 +- .../ui-chat/src/client/chat/ChatView.tsx | 4 +- .../ui-chat/src/client/chat/MessageItem.tsx | 9 +-- .../ui-chat/tests/chat-view.client.spec.tsx | 55 +++++++++++++++++-- .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 4 +- packages/client/ui-conversation/README.zh.md | 4 +- .../src/client/queue/QueueDock.tsx | 40 +++++++++++--- .../ui-conversation/src/client/service.ts | 4 +- .../tests/queue-dock.client.spec.tsx | 26 +++++++++ .../service-orchestration.client.spec.ts | 24 ++++++++ .../src/client/api-catalog.ts | 8 ++- 25 files changed, 205 insertions(+), 48 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml index 201b7451e6..e9541319ae 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.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-08-27-steer-followup-image-delivery.md -2026-08-27-steer-followup-image-delivery.md: e5b3f516e45588a865c87a1d8188b50208fbff33 -2026-08-27-steer-followup-image-delivery.zh.md: 37e55b7148841634e306b2a9d17f7f48b099c1eb +2026-08-27-steer-followup-image-delivery.md: 37160f19f561f060c6eb3f6b5b3360bba83b0e5c +2026-08-27-steer-followup-image-delivery.zh.md: b5c0467733e1551761bed417fd2da53d86b0b05e diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md index e5b3f516e4..37160f19f5 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md @@ -6,7 +6,7 @@ English | [中文](2026-08-27-steer-followup-image-delivery.zh.md) ## Problem -Images submitted while an agent is running did not reliably reach the model context (#3186), for three independent reasons. +Images submitted while an agent is running did not reliably reach the model context or retain their intended browser placement (#3186), for four independent reasons. First, a steer or follow-up spliced into a live driver latched no wake: the live driver was expected to claim it, but a turn that finished or failed between the splice and the claim exited without re-checking, stranding the accepted message until an unrelated waking send. Image admission widens this window because the Host awaits attachment normalization before `agent.steer()`/`agent.followup()` runs. @@ -14,6 +14,8 @@ Second, continuable-subagent follow-ups rejected images in the Client (`SUBAGENT Third, the browser queue projection reduced a queued image to the text `[image]` even though the durable reference was already present and readable through the session attachment authorization. +Fourth, every local submission echo rendered at the Chat flow tail while the browser serialized image bytes. A direct steer therefore appeared as an ordinary chat message during the pre-admission wait, then moved to the pending-steering position when the Host queue snapshot arrived. Busy Queue sends had the same transition into QueueDock. + ## Decision **Closing-turn wake delivery.** `ReactLoopAgent` tracks the identities of waking sends still awaiting a claim (`pendingWakes`); claim and discard notifications prune the set. At a driver exit whose turn loop returned without throwing, a non-empty set re-wakes the driver, so a steer or follow-up that lost the race with a normally closing turn is claimed by a fresh turn. Cancellation and `agent/pre-step` rejection instead clear the set: accepted-but-unclaimed input parks until the next waking send, preserving the tested `cancel({ keepInbox: true })` semantics and keeping rejected claims from being re-offered to the rejecting policy. Injected context never enters the set. The turn-flow section of [docs/architecture.md](../../../../docs/architecture.md) records the delivery/parking rule. @@ -22,6 +24,8 @@ Third, the browser queue projection reduced a queued image to the text `[image]` **Queue presentation.** The queue mirror's text preview excludes image blocks, and the queue dock renders each durable image part as a thumbnail resolved through `ctx.uiConversation.imageUrl` — the same session-authorized read the transcript uses. Editing queued image messages stays refused (#3072). +**Stable optimistic placement.** `PendingSubmission` records the surface selected when submission begins: `transcript` for an idle send, `queued` for a busy Queue send, and `steering` for a busy Steer send. Chat renders transcript and steering echoes on their respective surfaces, while QueueDock renders queued echoes with browser-owned image previews. The existing `rpcId` correlation suppresses the local echo in the same render that introduces the Host queue occurrence or durable user node. If the turn closes while images serialize and the Host places a requested steer in the next-turn queue, the later move from steering to QueueDock reflects the authoritative delivery decision. + ## Alternatives considered **Re-wake on every driver exit with pending input.** Rejected: it breaks the deliberate parking semantics of `cancel({ keepInbox: true })` and pre-step rejection, and a pre-commit `turn/start` failure would re-enter a hot loop because the failing turn never claims the message. @@ -34,8 +38,8 @@ Third, the browser queue projection reduced a queued image to the text `[image]` ## Testing -Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, the catalog-visible upload declaration, queue thumbnails (load, failure placeholder, unmount), and the image-free preview. +Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, the catalog-visible upload declaration, queue thumbnails (load, failure placeholder, unmount), the image-free preview, placement capture before serialization, local steering presentation, queued echo presentation, and `rpcId` handoff on both surfaces. ## Consequences -A steer or follow-up accepted during a turn's final microtasks is now delivered by a fresh turn instead of hanging in the inbox, while user cancellation still parks pending work — delivery after a stop remains an explicit next waking send. The subagent package now depends on `dsh-attachment` and reads `ctx.llm` optionally. Images persisted by a batch whose delivery is later refused stay as unreachable content-addressed objects under the existing retention rules. Queue thumbnails add one authorized attachment read per queued image, shared with the transcript cache. +A steer or follow-up accepted during a turn's final microtasks is delivered by a fresh turn instead of hanging in the inbox, while user cancellation still parks pending work — delivery after a stop remains an explicit next waking send. Slow image serialization leaves optimistic messages on their selected transcript, QueueDock, or pending-steering surface until the Host handoff. The subagent package depends on `dsh-attachment` and reads `ctx.llm` optionally. Images persisted by a batch whose delivery is later refused stay as unreachable content-addressed objects under the existing retention rules. Queue thumbnails add one authorized attachment read per queued image, shared with the transcript cache. diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md index 37e55b7148..b5c0467733 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md @@ -6,7 +6,7 @@ Status: implemented ## Problem -agent 运行期间提交的图片没有可靠进入模型上下文（#3186），原因有三个，彼此独立。 +agent 运行期间提交的图片没有可靠进入模型上下文，也没有保持预期的浏览器显示位置（#3186），原因有四个，彼此独立。 第一，splice 进在线 driver 的 steer 或 follow-up 不会锁存唤醒：预期由在线 driver 自行认领，但轮次在 splice 与认领之间正常结束或失败时，退出路径不再复查，已接受的消息就滞留到下一次无关的唤醒发送。图片准入放大了这个窗口，因为 Host 在执行 `agent.steer()`/`agent.followup()` 之前要先等待附件规范化完成。 @@ -14,6 +14,8 @@ agent 运行期间提交的图片没有可靠进入模型上下文（#3186）， 第三，浏览器队列投影把已排队的图片折叠成文本 `[image]`，尽管持久化引用已经存在，并且可以通过会话附件授权读取。 +第四，浏览器序列化图片字节期间，所有本地提交回显都位于 Chat 消息流末尾。直接 steer 会在准入前等待阶段显示为普通聊天消息，Host queue snapshot 到达后才移到 pending-steering 位置。繁忙时 Queue 发送也会发生同类跳动，最终进入 QueueDock。 + ## Decision **轮次收尾期的唤醒投递。** `ReactLoopAgent` 用 `pendingWakes` 记录尚未被认领的唤醒发送的身份；认领与丢弃通知会移除对应条目。当 driver 的轮次循环无异常返回并退出时，集合非空就重新拉起 driver，输掉与正常收尾轮次竞态的 steer 或 follow-up 由新轮次认领。取消与 `agent/pre-step` 拒绝则清空该集合：已接受但未认领的输入停放到下一次唤醒发送，既保留了有测试保护的 `cancel({ keepInbox: true })` 语义，也避免把被拒绝的认领重新塞给同一个拒绝策略。注入的上下文从不进入该集合。投递与停放规则记录在 [docs/architecture.md](../../../../docs/architecture.zh.md) 的 turn-flow 一节。 @@ -22,6 +24,8 @@ agent 运行期间提交的图片没有可靠进入模型上下文（#3186）， **队列展示。** 队列镜像的文本预览不再包含图片块，queue dock 把每个持久化图片部分渲染为缩略图，经 `ctx.uiConversation.imageUrl` 解析，与会话记录使用同一个会话授权读取。已排队图片消息的编辑仍然拒绝（#3072）。 +**稳定的乐观显示位置。** `PendingSubmission` 记录提交开始时选定的区域：空闲发送是 `transcript`，繁忙时 Queue 发送是 `queued`，繁忙时 Steer 发送是 `steering`。Chat 分别在 transcript 与 steering 区域渲染对应回显，QueueDock 用浏览器持有的图片预览渲染 queued 回显。现有 `rpcId` 关联会在 Host queue occurrence 或持久化 user node 出现的同一次渲染中隐藏本地回显。如果图片序列化期间轮次关闭，Host 把请求的 steer 放入 next-turn queue，消息随后从 steering 移到 QueueDock，反映实际投递决定。 + ## Alternatives considered **任何 driver 退出都在有滞留输入时重新拉起。** 拒绝：这破坏 `cancel({ keepInbox: true })` 与 pre-step 拒绝的刻意停放语义，而且 `turn/start` 提交前失败的轮次永远不会认领消息，会进入热循环。 @@ -34,8 +38,8 @@ agent 运行期间提交的图片没有可靠进入模型上下文（#3186）， ## Testing -agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、目录可见的上传声明、队列缩略图（加载、失败占位、卸载）与不含图片的预览。 +agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、目录可见的上传声明、队列缩略图（加载、失败占位、卸载）、不含图片的预览、序列化前的位置捕获、steering 本地显示、queued 回显显示，以及两个区域的 `rpcId` 交接。 ## Consequences -在轮次最后几个微任务里被接受的 steer 或 follow-up 现在由新轮次投递，而不是挂在 inbox 里；用户取消仍然停放待处理工作，停止之后的投递依旧需要一次显式的唤醒发送。subagent 包新增对 `dsh-attachment` 的依赖，并可选读取 `ctx.llm`。整批持久化后投递被拒绝的图片按现有保留规则保持为不可达的内容寻址对象。队列缩略图对每张排队图片增加一次授权附件读取，与会话记录缓存共享。 +在轮次最后几个微任务里被接受的 steer 或 follow-up 由新轮次投递，不会挂在 inbox 里；用户取消仍然停放待处理工作，停止之后的投递依旧需要一次显式的唤醒发送。图片序列化较慢时，乐观消息停留在选定的 transcript、QueueDock 或 pending-steering 区域，直到与 Host 状态交接。subagent 包依赖 `dsh-attachment`，并可选读取 `ctx.llm`。整批持久化后投递被拒绝的图片按现有保留规则保持为不可达的内容寻址对象。队列缩略图对每张排队图片增加一次授权附件读取，与会话记录缓存共享。 diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 4f66278d0d..e68454d854 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/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/api/session-controller/README.md -README.md: dc04e595c9c4bf029ed427d5a1214802041c11c0 -README.zh.md: b34c8ad018e4e2c0d95ac0b8aa1954742f9ecfa4 +README.md: e4a4ed9918c0d469876da7db8d37c0e00554d5b2 +README.zh.md: a9a20cc88873f56567a411459f27e9baf5132ff1 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index dc04e595c9..e4a4ed9918 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -29,7 +29,7 @@ Each endpoint states its activation policy. List, search, attachment, history pa The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. -The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. The prompt's `requestId` is the correlation identity — the Host already echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the transcript node is), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only — reload and reconnect rebuild the conversation from durable events alone. +The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Each echo records its expected `transcript`, `queued`, or `steering` placement; this keeps slow serialization on the surface selected when submission began. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. ----- diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index b34c8ad018..a9a20cc888 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend` 和 `append` 变更，并通过 tail page 修复重连或 seq 缺口。普通 record 覆盖 `[event.seq, event.seq]`，packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs 和 projection 状态，而不会把瞬态值当作 durable event。 -Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。prompt 的 `requestId` 就是关联标识，Host 本就把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休（该延迟保证 transcript 节点可渲染之前回显仍在），带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休；每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存，刷新与重连只从 durable event 重建会话。 +Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。每条回显记录预期的 `transcript`、`queued` 或 `steering` 位置，使较慢的序列化过程始终显示在提交开始时选定的区域。prompt 的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，该延迟保证替代内容就绪前回显仍可渲染；带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休；每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存；刷新与重连只从 durable event 重建会话。 ----- diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts index 7007ffc070..cb0290eccc 100644 --- a/packages/api/session-controller/src/client/contract/session.ts +++ b/packages/api/session-controller/src/client/contract/session.ts @@ -14,7 +14,9 @@ import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol' import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store' import type { QueueAction, SessionRequestId } from '../../types.ts' import type { ClientResult } from './result.ts' -import type { PendingSubmissionImage, SessionSnapshot } from './snapshot.ts' +import type { + PendingSubmissionImage, PendingSubmissionPlacement, SessionSnapshot, +} from './snapshot.ts' /** Browser-submitted prompt content; the Host promotes image bytes to durable references. */ export type PromptContentPart = @@ -38,6 +40,8 @@ export type PendingSubmissionRetirement = /** Input registering one local submission echo ahead of its prompt call. */ export interface BeginSubmissionInput { + /** Expected surface selected from the submission mode and running state. */ + readonly placement: PendingSubmissionPlacement /** Prompt text exactly as the upcoming prompt will send it. */ readonly text: string /** Ordered image previews matching the upcoming prompt's image parts. */ diff --git a/packages/api/session-controller/src/client/contract/snapshot.ts b/packages/api/session-controller/src/client/contract/snapshot.ts index 8aacc0d5d6..da10cf07be 100644 --- a/packages/api/session-controller/src/client/contract/snapshot.ts +++ b/packages/api/session-controller/src/client/contract/snapshot.ts @@ -30,6 +30,9 @@ export interface PendingSubmissionImage { readonly height?: number } +/** Client surface selected when a local submission begins. */ +export type PendingSubmissionPlacement = 'transcript' | 'queued' | 'steering' + /** * One local prompt-submission echo: inserted synchronously when a submission * begins, so the conversation can show the message before serialization, @@ -39,6 +42,8 @@ export interface PendingSubmissionImage { export interface PendingSubmission { /** The prompt RPC identity; the durable `user/message` source echoes it as `rpcId`. */ readonly requestId: SessionRequestId + /** Expected surface until the Host reports the admitted queue or durable occurrence. */ + readonly placement: PendingSubmissionPlacement /** Client wall-clock ms when the submission began. */ readonly time: number /** Prompt text exactly as it will be sent (one text block). */ diff --git a/packages/api/session-controller/src/client/index.ts b/packages/api/session-controller/src/client/index.ts index bca9f9d3d0..1713896b61 100644 --- a/packages/api/session-controller/src/client/index.ts +++ b/packages/api/session-controller/src/client/index.ts @@ -62,6 +62,7 @@ export type { OpenState, PendingSubmission, PendingSubmissionImage, + PendingSubmissionPlacement, PromptError, QueuedMessage, SessionSnapshot, diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts index 535f6574fa..4eaf353b50 100644 --- a/packages/api/session-controller/src/client/sessions/session.ts +++ b/packages/api/session-controller/src/client/sessions/session.ts @@ -189,6 +189,7 @@ export class Session implements SessionFace { const requestId = randomUUID() as SessionRequestId this.pendingSubmissions = [...this.pendingSubmissions, { requestId, + placement: input.placement, time: Date.now(), text: input.text, images: input.images, diff --git a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts index 261bddbb78..8c108624c2 100644 --- a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts +++ b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts @@ -69,12 +69,14 @@ describe('beginSubmission', () => { const { session } = makeSession() expect(session.getSnapshot()).toMatchObject({ pendingSubmissions: [], promptAttempted: false }) const handle = session.beginSubmission({ + placement: 'transcript', text: '你好', images: [{ previewUrl: 'blob:p1', name: 'a.png', width: 4, height: 3 }], }) expect(session.getSnapshot().promptAttempted).toBe(true) expect(session.getSnapshot().pendingSubmissions).toMatchObject([{ requestId: handle.requestId, + placement: 'transcript', text: '你好', images: [{ previewUrl: 'blob:p1', name: 'a.png', width: 4, height: 3 }], }]) @@ -84,6 +86,7 @@ describe('beginSubmission', () => { const { session } = makeSession() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ + placement: 'transcript', text: '放弃', images: [], onRetire: retirement => retirements.push(retirement), @@ -101,6 +104,7 @@ describe('prompt-coupled retirement', () => { api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: '忙', details: { reason: 'busy' } })) const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ + placement: 'transcript', text: '失败的', images: [], onRetire: retirement => retirements.push(retirement), @@ -114,7 +118,7 @@ describe('prompt-coupled retirement', () => { it('sends the echo identity as the prompt requestId', async () => { const { api, session } = makeSession() - const handle = session.beginSubmission({ text: '带 id', images: [] }) + const handle = session.beginSubmission({ placement: 'transcript', text: '带 id', images: [] }) await session.prompt([{ type: 'text', text: '带 id' }], 'queue', undefined, handle.requestId) expect(api.callsOf('session.prompt')).toMatchObject([{ requestId: handle.requestId }]) }) @@ -122,7 +126,7 @@ describe('prompt-coupled retirement', () => { it('an unidentified prompt failure leaves registered echoes alone', async () => { const { api, session } = makeSession() api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: '忙', details: { reason: 'busy' } })) - session.beginSubmission({ text: '还在', images: [] }) + session.beginSubmission({ placement: 'transcript', text: '还在', images: [] }) await session.prompt([{ type: 'text', text: '另一个' }], 'queue') expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) }) @@ -135,6 +139,7 @@ describe('observed retirement', () => { await session.open() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ + placement: 'transcript', text: '发送', images: [{ previewUrl: 'blob:p1' }], onRetire: retirement => retirements.push(retirement), @@ -153,6 +158,7 @@ describe('observed retirement', () => { const { session } = makeSession() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ + placement: 'queued', text: '排队', images: [{ previewUrl: 'blob:p1' }], onRetire: retirement => retirements.push(retirement), @@ -168,7 +174,7 @@ describe('observed retirement', () => { it('a full-window install (reconnect resync) retires echoes observed in the window', async () => { const { api, session } = makeSession() - const handle = session.beginSubmission({ text: '重连', images: [] }) + const handle = session.beginSubmission({ placement: 'transcript', text: '重连', images: [] }) api.onHistory = () => Promise.resolve(ok(historyValue([promptEvent(12, handle.requestId)]))) await session.open() await settleFrames() @@ -181,6 +187,7 @@ describe('observed retirement', () => { await session.open() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ + placement: 'transcript', text: '先观察', images: [], onRetire: retirement => retirements.push(retirement), @@ -197,6 +204,7 @@ describe('observed retirement', () => { await session.open() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ + placement: 'transcript', text: '同一请求', images: [], onRetire: retirement => retirements.push(retirement), @@ -221,7 +229,7 @@ describe('observed retirement', () => { const { api, session } = makeSession() api.onHistory = () => Promise.resolve(ok(historyValue([]))) await session.open() - const handle = session.beginSubmission({ text: '帧', images: [] }) + const handle = session.beginSubmission({ placement: 'transcript', text: '帧', images: [] }) await api.pushFollow(SID, { type: 'event', event: promptEvent(0, handle.requestId) as never }) expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) expect(frames).toHaveLength(1) @@ -237,11 +245,13 @@ describe('disposal', () => { await session.open() const retirements: { text: string; retirement: PendingSubmissionRetirement }[] = [] const observed = session.beginSubmission({ + placement: 'transcript', text: '已观察', images: [], onRetire: retirement => retirements.push({ text: '已观察', retirement }), }) session.beginSubmission({ + placement: 'transcript', text: '未settle', images: [], onRetire: retirement => retirements.push({ text: '未settle', retirement }), diff --git a/packages/client/ui-chat/README.i18n.yaml b/packages/client/ui-chat/README.i18n.yaml index 5919181d67..be67d6ce37 100644 --- a/packages/client/ui-chat/README.i18n.yaml +++ b/packages/client/ui-chat/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-chat/README.md -README.md: cd69eb7fdf704bb0e138e1f2aad88782e26aeeff -README.zh.md: 3e9d1ccab71f2516f92ec5402eac49baaaccdf77 +README.md: 5e365593b054c6826de817e3e0d83734b1c8410d +README.zh.md: 0f1569ab877acd465f41baedb9a626e42eb29983 diff --git a/packages/client/ui-chat/README.md b/packages/client/ui-chat/README.md index cd69eb7fdf..5e365593b0 100644 --- a/packages/client/ui-chat/README.md +++ b/packages/client/ui-chat/README.md @@ -8,7 +8,7 @@ English | [中文](README.zh.md) ## Summary -The browser Chat target for Conversation assembly. It registers Chat event definitions and snapshot construction, supplies `useChat`, renders transcript nodes and details, and owns Chat-specific stores, actions, localization, and scroll restoration; historical image URLs resolve through the Conversation-owned per-session cache (`ctx.uiConversation.imageUrl`). Its Assistant and Turn Tail definitions fold packed historical Assistant runs without expanding their members. The flow tail renders the session's local submission echoes (`SessionSnapshot.pendingSubmissions`) with the same bubble as their eventual durable user nodes, hidden per render once a user/steering node or queue occurrence carries the echo's prompt `rpcId`, so the echo-to-durable swap is atomic. +The browser Chat target for Conversation assembly. It registers Chat event definitions and snapshot construction, supplies `useChat`, renders transcript nodes and details, and owns Chat-specific stores, actions, localization, and scroll restoration; historical image URLs resolve through the Conversation-owned per-session cache (`ctx.uiConversation.imageUrl`). Its Assistant and Turn Tail definitions fold packed historical Assistant runs without expanding their members. Local submission echoes (`SessionSnapshot.pendingSubmissions`) retain the surface selected when the submit begins: transcript echoes render at the flow tail, steering echoes render with the pending-steering marker, and queued echoes stay out of Chat. Each echo is hidden per render once a user/steering node or queue occurrence carries its prompt `rpcId`, so the handoff is atomic. ## Table of Contents diff --git a/packages/client/ui-chat/README.zh.md b/packages/client/ui-chat/README.zh.md index 3e9d1ccab7..0f1569ab87 100644 --- a/packages/client/ui-chat/README.zh.md +++ b/packages/client/ui-chat/README.zh.md @@ -8,7 +8,7 @@ kind: "package-reference" ## 概述 -Conversation 组装的浏览器 Chat target。本包注册 Chat event definition 与 snapshot 构造、提供 `useChat`、渲染 transcript node 和详情，并拥有 Chat 专属 store、action、本地化与滚动位置恢复；历史图片 URL 通过 Conversation 持有的按会话缓存（`ctx.uiConversation.imageUrl`）解析。其中 Assistant 与 Turn Tail definition 会直接 fold packed Assistant 历史 run，不展开其成员。消息流尾部渲染 session 的本地提交回显（`SessionSnapshot.pendingSubmissions`），气泡与其最终的 durable user 节点一致；一旦某个 user/steering 节点或 queue occurrence 携带回显的 prompt `rpcId`，该回显即在同一渲染中隐藏，因此回显到 durable 的替换是原子的。 +Conversation 组装的浏览器 Chat target。本包注册 Chat event definition 与 snapshot 构造、提供 `useChat`、渲染 transcript node 和详情，并拥有 Chat 专属 store、action、本地化与滚动位置恢复；历史图片 URL 通过 Conversation 持有的按会话缓存（`ctx.uiConversation.imageUrl`）解析。其中 Assistant 与 Turn Tail definition 会直接 fold packed Assistant 历史 run，不展开其成员。本地提交回显（`SessionSnapshot.pendingSubmissions`）保留提交开始时选定的区域：transcript 回显位于消息流末尾，steering 回显带 pending-steering 标记，queued 回显不进入 Chat。一旦 user/steering 节点或 queue occurrence 携带回显的 prompt `rpcId`，该回显即在同一渲染中隐藏，因此交接是原子的。 ## 目录 diff --git a/packages/client/ui-chat/src/client/chat/ChatView.tsx b/packages/client/ui-chat/src/client/chat/ChatView.tsx index 7b370666f9..bd5a14cf5e 100644 --- a/packages/client/ui-chat/src/client/chat/ChatView.tsx +++ b/packages/client/ui-chat/src/client/chat/ChatView.tsx @@ -268,7 +268,9 @@ export function ChatView({ const visibleSubmissions = useMemo(() => { if (pendingSubmissions.length === 0) return pendingSubmissions const observed = observedRpcIds(order, nodeStore, inbox) - return pendingSubmissions.filter(submission => !observed.has(submission.requestId)) + return pendingSubmissions.filter(submission => ( + submission.placement !== 'queued' && !observed.has(submission.requestId) + )) }, [pendingSubmissions, order, nodeStore, inbox]) const renderMessageImages = useCallback( owner => renderSlot('conversation.message.images', { ...owner, loadImage }), diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.tsx b/packages/client/ui-chat/src/client/chat/MessageItem.tsx index 467e486ecb..d9dd4d8e44 100644 --- a/packages/client/ui-chat/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-chat/src/client/chat/MessageItem.tsx @@ -222,10 +222,10 @@ export function PendingSteeringBubble({ content, renderMessageImages, t }: { } /** - * Render one local submission echo with the exact visual language of the - * durable user node that replaces it: draft text plus object-URL previews, - * visible from the submit click until the durable `user/message` (or its - * queue occurrence) renders. + * Render one local transcript or steering submission echo with the same + * visual language and surface marker as the Host occurrence that replaces + * it: draft text plus object-URL previews, visible from the submit click + * until the durable `user/message` or steering occurrence renders. * @param props - the session snapshot's pending submission and render seats. * @returns the echoed user bubble. */ @@ -254,6 +254,7 @@ export function PendingSubmissionBubble({ submission, renderMessageImages, t }: content={content} previewImages={previewImages} renderMessageImages={renderMessageImages} + pending={submission.placement === 'steering'} echo t={t} actions={text => ( diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx index 58b31b4d8e..c71ba1c94b 100644 --- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx +++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx @@ -762,7 +762,10 @@ describe('ChatView', () => { { nodes: [assistant(1, 'working')] }, { pendingSubmissions: [ - { requestId: 'req-1' as never, time: 5_000, text: '即发即显', images: [] }, + { + requestId: 'req-1' as never, placement: 'transcript', + time: 5_000, text: '即发即显', images: [], + }, ], }, ) @@ -791,18 +794,57 @@ describe('ChatView', () => { expect(view.getAllByText('即发即显')).toHaveLength(1) }) - it('hides an echo once its queue occurrence carries the rpcId (running-turn submission)', () => { + it('renders a local steer echo as pending steering before Host image admission completes', () => { + const h = makeHarness( + { nodes: [assistant(1, 'working')] }, + { + running: true, + pendingSubmissions: [{ + requestId: 'req-steer' as never, + placement: 'steering', + time: 5_500, + text: '带图纠偏', + images: [{ previewUrl: 'blob:steer-preview', name: 'steer.png' }], + }], + }, + ) + const view = render() + const local = view.getByText('带图纠偏').closest('[data-submission-echo]') + expect(local?.hasAttribute('data-pending-steering')).toBe(true) + + act(() => { + h.setSession({ + queue: [{ + id: 'steer-occurrence' as never, + messageId: 'steer-message' as never, + placement: 'steering', + rpcId: 'req-steer' as never, + content: [{ type: 'text', text: '带图纠偏' }], + preview: '带图纠偏', + text: '带图纠偏', + }], + }) + }) + expect(view.getAllByText('带图纠偏')).toHaveLength(1) + expect(view.container.querySelector('[data-submission-echo]')).toBeNull() + expect(view.container.querySelector('[data-pending-steering]')).not.toBeNull() + }) + + it('keeps a queued echo out of the Chat flow before and after Host admission', () => { const h = makeHarness( { nodes: [assistant(1, 'working')] }, { running: true, pendingSubmissions: [ - { requestId: 'req-q' as never, time: 6_000, text: '排队中', images: [] }, + { + requestId: 'req-q' as never, placement: 'queued', + time: 6_000, text: '排队中', images: [], + }, ], }, ) const view = render() - expect(view.getByText('排队中')).toBeTruthy() + expect(view.queryByText('排队中')).toBeNull() act(() => { h.setSession({ queue: [{ @@ -816,8 +858,8 @@ describe('ChatView', () => { }], }) }) - // The queued occurrence renders in the queue dock, not the flow; the - // flow-tail echo yields to it in the same snapshot. + // The queued occurrence and its local predecessor both belong to the + // queue dock, never the Chat flow. expect(view.queryByText('排队中')).toBeNull() }) @@ -827,6 +869,7 @@ describe('ChatView', () => { { pendingSubmissions: [{ requestId: 'req-img' as never, + placement: 'transcript', time: 7_000, text: '', images: [ diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 656c55e85f..1a2eaf3aae 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: 6e26991dcefa8eb922f3913feb3db4750258646a -README.zh.md: 99cacf47995552bc35e2414ee64283186f2076d2 +README.md: cd410bbdb6ee403cf246962d9b8f3d17d1bc30ad +README.zh.md: a8ab2a1ea10698c1d191db6e75e222d4d19b5fb4 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 6e26991dce..cd410bbdb6 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -38,9 +38,9 @@ The package registers the optional-Session `conversation` shell, strict Session View selection is deterministic: a registered persisted selection wins, otherwise registered `chat` wins, otherwise no View renders. It never chooses the first registered View. Shell phase combines Session lifecycle with the active-target set; no target-specific snapshot is read by the shell. -The resident composer survives no-Session and Session transitions. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label) and show each durable image part as a thumbnail resolved through the session image URL cache, while an edit exposes the literal sent text. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. +The resident composer survives no-Session and Session transitions. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label) and show local image previews or durable image parts as thumbnails, while an edit exposes the literal sent text. Durable thumbnails resolve through the session image URL cache. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. -Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) before serializing, yields one paint so the echo renders on the click's own frame, and encodes images through the browser's native `FileReader` data-URL path. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their image ids through admission and Session scope disposal. When an echo retires as observed, the durable image cache exposes its preview immediately, fetches the admitted attachment, replaces the preview with the canonical URL, and revokes each URL after its use ends. Direct subagent continuations skip local echoes because their transport does not preserve the browser request id. +Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) before serializing and records the surface selected from the current running state and delivery mode: idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint and encodes images through the browser's native `FileReader` data-URL path. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their image ids through admission and Session scope disposal. When an echo retires as observed, the durable image cache exposes its preview immediately, fetches the admitted attachment, replaces the preview with the canonical URL, and revokes each URL after its use ends. Direct subagent continuations skip local echoes because their transport does not preserve the browser request id. While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Queue Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting continues to select the Queue or Steer keyboard action. Continuable subagents keep separate Send and Stop actions ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-20-running-draft-primary-send.md)). diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 99cacf4799..a8ab2a1ea1 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -38,9 +38,9 @@ target package 通过 declaration merge 扩展 snapshot 与 Location data map， View 选择规则固定：有效且已注册的持久化选择优先，其次是已注册的 `chat`，否则不渲染 View；绝不选择第一个已注册 View。Shell phase 只组合 Session lifecycle 与 active-target set，不读取任何 target-specific snapshot。 -常驻 composer 在无 Session 与有 Session 之间保持挂载。无 Session 时，同一个编辑器表面保持 inert，Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器：引用 chip 是携带 owner 序列化身份的原子 decorator 节点（提交时经 owner codec 展开），已认领的 slash command 保持为带样式的行首文本，文件夹文本引用以图标前缀携带文件夹图形，草稿的剪贴板投影镜像到逐 Session Conversation store。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence；queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本（wire 会话形式折叠为其标签），并把每个持久化图片部分经会话图片 URL 缓存解析为缩略图展示，编辑态则展示字面发送文本。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 +常驻 composer 在无 Session 与有 Session 之间保持挂载。无 Session 时，同一个编辑器表面保持 inert，Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器：引用 chip 是携带 owner 序列化身份的原子 decorator 节点（提交时经 owner codec 展开），已认领的 slash command 保持为带样式的行首文本，文件夹文本引用以图标前缀携带文件夹图形，草稿的剪贴板投影镜像到逐 Session Conversation store。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence；queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本（wire 会话形式折叠为其标签），并把本地图片预览或持久化图片部分显示为缩略图，编辑态则展示字面发送文本。持久化缩略图通过会话图片 URL 缓存解析。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 -默认发送采用乐观提交：Enter 在同一事务里清空草稿、occurrence 表和撤销历史，composer 保持 `plain`，发送作为 detached attempt 运行，发送期间可以继续输入和提交。`sendSession` 在序列化之前注册 Session 提交回显（`session.beginSubmission`），让出一帧使回显在点击当帧渲染，图片经浏览器原生 `FileReader` data-URL 路径编码。多个并发发送失败时，在用户编辑还原内容之前按提交顺序合并还原；命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有图片 id，直到 admission 完成或 Session scope 销毁。回显以 observed 退休时，durable 图片缓存立即公开预览 URL，同时读取 admitted 附件，随后用规范化 URL 替换预览，并在两个 URL 各自停止使用后撤销。直接 subagent continuation 不创建本地回显，因为其 transport 不保留浏览器 request id。 +默认发送采用乐观提交：Enter 在同一事务里清空草稿、occurrence 表和撤销历史，composer 保持 `plain`，发送作为 detached attempt 运行，发送期间可以继续输入和提交。`sendSession` 在序列化之前注册 Session 提交回显（`session.beginSubmission`），并按当前运行状态与投递模式记录选定区域：空闲发送进入 transcript，繁忙时 Queue 进入 QueueDock，繁忙时 Steer 进入 pending-steering 区域。随后让出一帧，图片经浏览器原生 `FileReader` data-URL 路径编码。多个并发发送失败时，在用户编辑还原内容之前按提交顺序合并还原；命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有图片 id，直到 admission 完成或 Session scope 销毁。回显以 observed 退休时，durable 图片缓存立即公开预览 URL，同时读取 admitted 附件，随后用规范化 URL 替换预览，并在两个 URL 各自停止使用后撤销。直接 subagent continuation 不创建本地回显，因为其 transport 不保留浏览器 request id。 普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Queue Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置继续选择 Queue 或 Steer 键盘操作。可继续 subagent 保留独立的 Send 与 Stop 操作（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-20-running-draft-primary-send.zh.md)）。 diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx index c90c699c51..2840268034 100644 --- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx +++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx @@ -64,6 +64,14 @@ export type QueueDockProps = PropsRuntime<'conversation.input.dock'> & QueueDock export function QueueDock({ useSession, updateQueue, notify, loadImage, t }: QueueDockProps) { const inbox = useSession(s => s.queue) const queue = useMemo(() => inbox.filter(row => row.placement === 'queued'), [inbox]) + const pendingSubmissions = useSession(s => s.pendingSubmissions) + const pendingQueue = useMemo(() => { + const admitted = new Set(queue.flatMap(row => row.rpcId === undefined ? [] : [row.rpcId])) + return pendingSubmissions.filter(submission => ( + submission.placement === 'queued' && !admitted.has(submission.requestId) + )) + }, [pendingSubmissions, queue]) + const rowCount = queue.length + pendingQueue.length const running = useSession(s => s.running) const queueMutable = useSession(s => s.subagent === null) const [editing, setEditing] = useState<{ id: QueueItemId; text: string } | null>(null) @@ -72,15 +80,15 @@ export function QueueDock({ useSession, updateQueue, notify, loadImage, t }: Que const listId = useId() useEffect(() => { - if (queue.length === 0 && !collapsed) setCollapsed(true) + if (rowCount === 0 && !collapsed) setCollapsed(true) if (editing !== null && (!queueMutable || !queue.some(row => row.id === editing.id))) setEditing(null) - }, [collapsed, editing, queue, queueMutable]) + }, [collapsed, editing, queue, queueMutable, rowCount]) - if (queue.length === 0) return null + if (rowCount === 0) return null const interactionActive = queueMutable && (editing !== null || busy !== null) const expanded = !collapsed || interactionActive - const listVisible = queue.length === 1 || expanded + const listVisible = rowCount === 1 || expanded const applyAction = async ( itemId: QueueItemId, @@ -111,7 +119,7 @@ export function QueueDock({ useSession, updateQueue, notify, loadImage, t }: Que return (
- {queue.length > 1 && ( + {rowCount > 1 && (
diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts index 2fb0c99b51..ad56938253 100644 --- a/packages/client/ui-conversation/src/client/service.ts +++ b/packages/client/ui-conversation/src/client/service.ts @@ -207,7 +207,8 @@ export class ConversationController extends Service implements IConversation { if (attachments.length !== imageIds.length) { throw new Error('conversation.sendSession: one or more draft images are no longer available') } - if (session.getSnapshot().subagent !== null) { + const snapshot = session.getSnapshot() + if (snapshot.subagent !== null) { const uploaded = await this.serializeImages(attachments.map(attachment => attachment.file)) const content = [...uploaded, ...(text === '' ? [] : [{ type: 'text' as const, text }])] const result = await session.prompt(content, mode, signal) @@ -218,6 +219,7 @@ export class ConversationController extends Service implements IConversation { ? undefined : new Promise((resolve) => { finishRetirement = resolve }) const submission = session.beginSubmission({ + placement: snapshot.running ? mode === 'steer' ? 'steering' : 'queued' : 'transcript', text, images: attachments.map(attachment => ({ previewUrl: attachment.previewUrl, diff --git a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx index f1308c05c5..492bc16151 100644 --- a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx +++ b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx @@ -116,6 +116,32 @@ describe('QueueDock', () => { expect(container.innerHTML).toBe('') }) + it('renders a queued local echo in the dock and hands off by rpcId', () => { + const pending = { + ...snapshotWith([]), + pendingSubmissions: [{ + requestId: 'req-local-queue' as never, + placement: 'queued' as const, + time: 1, + text: '等待上传', + images: [{ previewUrl: 'blob:queue-preview', name: 'queue.png' }], + }], + } + const source = liveSession(pending) + const view = render() + expect(view.getByText('等待上传').closest('[data-submission-echo]')).not.toBeNull() + expect(view.getByRole('img', { name: '排队消息图片' }).getAttribute('src')).toBe('blob:queue-preview') + + act(() => { + source.push({ + ...pending, + queue: [{ ...row('accepted', '等待上传'), rpcId: 'req-local-queue' as never }], + }) + }) + expect(view.getAllByText('等待上传')).toHaveLength(1) + expect(view.container.querySelector('[data-submission-echo]')).toBeNull() + }) + it('leaves pending steering to the conversation flow', () => { const steering = { ...row('s-1', 'interrupt'), placement: 'steering' as const } const snap = snapshotWith([steering]) diff --git a/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts index a6582d42b8..7ecbb9679e 100644 --- a/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts +++ b/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts @@ -185,6 +185,7 @@ describe('sendSession submission echo', () => { const sending = b.root.sendSession(session, '带图', [attachment!.id], 'queue') // Synchronous: the echo is registered before any encoding starts. expect(b.beginSubmission).toHaveBeenCalledWith(expect.objectContaining({ + placement: 'transcript', text: '带图', images: [expect.objectContaining({ previewUrl: 'blob:echo-1', name: 'a.png' })], })) @@ -211,6 +212,29 @@ describe('sendSession submission echo', () => { await b.runtime.dispose() }) + it('captures the busy submission surface before image serialization', async () => { + const b = await echoBench() + try { + await b.runtime.sessions.updateSessionSnapshot('s1', (draft) => { draft.running = true }) + const session = b.runtime.sessions.binding('s1')!.session + await expect(b.root.sendSession(session, '立即纠偏', [], 'steer')) + .resolves.toEqual({ kind: 'success' }) + expect(b.beginSubmission).toHaveBeenLastCalledWith(expect.objectContaining({ + placement: 'steering', + text: '立即纠偏', + })) + await expect(b.root.sendSession(session, '稍后处理', [], 'queue')) + .resolves.toEqual({ kind: 'success' }) + expect(b.beginSubmission).toHaveBeenLastCalledWith(expect.objectContaining({ + placement: 'queued', + text: '稍后处理', + })) + } finally { + b.restore() + } + await b.runtime.dispose() + }) + it('hands the preview URL to the image cache on observed retirement instead of revoking it', async () => { const b = await echoBench() try { diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts index 633c553557..43a19880a2 100644 --- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts @@ -444,7 +444,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'BeginSubmissionInput', - declaration: 'export interface BeginSubmissionInput {\n readonly text: string;\n readonly images: readonly PendingSubmissionImage[];\n readonly onRetire?: (retirement: PendingSubmissionRetirement) => void;\n}', + declaration: 'export interface BeginSubmissionInput {\n readonly placement: PendingSubmissionPlacement;\n readonly text: string;\n readonly images: readonly PendingSubmissionImage[];\n readonly onRetire?: (retirement: PendingSubmissionRetirement) => void;\n}', }, { name: 'BoundActions', @@ -608,12 +608,16 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'PendingSubmission', - declaration: 'export interface PendingSubmission {\n readonly requestId: SessionRequestId;\n readonly time: number;\n readonly text: string;\n readonly images: readonly PendingSubmissionImage[];\n}', + declaration: 'export interface PendingSubmission {\n readonly requestId: SessionRequestId;\n readonly placement: PendingSubmissionPlacement;\n readonly time: number;\n readonly text: string;\n readonly images: readonly PendingSubmissionImage[];\n}', }, { name: 'PendingSubmissionImage', declaration: 'export interface PendingSubmissionImage {\n readonly previewUrl: string;\n readonly name?: string;\n readonly width?: number;\n readonly height?: number;\n}', }, + { + name: 'PendingSubmissionPlacement', + declaration: 'export type PendingSubmissionPlacement = \'transcript\' | \'queued\' | \'steering\';', + }, { name: 'PendingSubmissionRetirement', declaration: 'export type PendingSubmissionRetirement = {\n readonly reason: \'observed\';\n readonly attachments: readonly ImageAttachmentRef[];\n} | {\n readonly reason: \'failed\';\n};', From 2c1cc3e7781b0b83dda2418bac92d17b429dd425 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 19:37:25 +0800 Subject: [PATCH 08/63] refactor: narrow closing-turn wake tracking --- packages/core/agent-loop/src/agent.ts | 32 ++++++--------------------- 1 file changed, 7 insertions(+), 25 deletions(-) diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 0c99d38fbb..ecf921ccbd 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -71,16 +71,8 @@ export class ReactLoopAgent implements Agent { private phase: Phase private activityDone: Promise = Promise.resolve() /** - * Identities of waking sends still awaiting a claim. Claim and discard - * notifications prune the set per message, while {@link cancel} and a - * pre-step rejection clear the set. Parking consumes every outstanding - * wake, including follow-ups unrelated to the rejected claim, - * because the next waking send resumes the complete parked queue anyway. - * A non-empty set at driver exit therefore means a steer or follow-up lost - * the race with a normally or erroneously closing turn, and the exit must - * start a fresh driver to deliver it. Injected context never enters the - * set, so it keeps waiting for a waking message instead of opening a turn - * by itself. + * Waking message ids awaiting claim; cancel, rejection, and driver failure + * clear only this bookkeeping so retained inbox input parks. */ private readonly pendingWakes = new Set() @@ -141,8 +133,7 @@ export class ReactLoopAgent implements Agent { // Captured before the insertion so a reentrant cancel from a splice observer cannot reclassify it. const wakingAfterAbort = wakeup && this.phase.kind !== 'idle' && this.phase.abort.signal.aborted const resolvedTarget = wakingAfterAbort ? 'next-turn' : target - // Registered before the splice so a reentrant discard inside the splice - // dispatch still prunes it; a refused splice never leaves an entry behind. + // Track before splice so a reentrant discard prunes the wake; roll back a refused insertion. if (wakeup) this.pendingWakes.add(message.id) try { this.inbox.splice(resolvedTarget, Infinity, 0, [message]) @@ -170,9 +161,7 @@ export class ReactLoopAgent implements Agent { this.inbox.clear() if (this.phase.kind !== 'idle') this.phase.wakeRequested = false } - // Cancellation consumes outstanding wakes: kept inbox work parks until - // the next waking send resumes the queue, and a cleared inbox has nothing - // left to deliver. + // Kept inbox work parks until the next waking send. this.pendingWakes.clear() if (this.phase.kind !== 'idle') this.phase.abort.abort(cause) } @@ -246,22 +235,17 @@ export class ReactLoopAgent implements Agent { } private async kick(): Promise { - // Set only when the turn loop returns without throwing: an abort or driver - // failure parks unclaimed waking input for the next waking send, while a - // clean exit must deliver a steer or follow-up that lost the race with the - // closing turn (its send saw a live driver, so no wake was latched). - let cleanExit = false try { while (await this.turn()) {} - cleanExit = true } catch (_error) { // Reported failures and cancellation are contained at the driver boundary. + this.pendingWakes.clear() } finally { /* v8 ignore next -- kick owns a running phase until this driver boundary */ if (this.phase.kind === 'running') { const { turn, wakeRequested } = this.phase this.setPhase({ kind: 'idle', lastTurn: turn }) - if ((wakeRequested || (cleanExit && this.pendingWakes.size > 0)) && this.inbox.hasPending) { + if ((wakeRequested || this.pendingWakes.size > 0) && this.inbox.hasPending) { this.wakeDriver() } } @@ -311,9 +295,7 @@ export class ReactLoopAgent implements Agent { const step = phase.step + 1 const decision = await this.preStep(target, { turn, step }) if (decision.kind === 'reject') { - // The rejecting listener owns resumption: input staged behind the - // rejected claim parks until the next waking send, exactly like a - // cancellation, instead of being re-offered to the same policy. + // The rejecting listener owns resumption; later input stays parked. this.pendingWakes.clear() turnEnds = { kind: 'blocked' } return false From 21d2d9395d6d61c720d380f6d18069e43dfb4b9e Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 20:14:18 +0800 Subject: [PATCH 09/63] refactor: align prompt admission and echo ownership --- ...27-steer-followup-image-delivery.i18n.yaml | 4 +- ...026-08-27-steer-followup-image-delivery.md | 6 +-- ...-08-27-steer-followup-image-delivery.zh.md | 6 +-- .../api/session-controller/README.i18n.yaml | 4 +- packages/api/session-controller/README.md | 2 +- packages/api/session-controller/README.zh.md | 2 +- .../src/client/contract/session.ts | 6 +-- .../src/client/sessions/session.ts | 4 +- .../api/session-controller/src/commands.ts | 6 +-- ...session-pending-submissions.client.spec.ts | 41 +++++++++++++------ .../attachment/attachment/README.i18n.yaml | 4 +- packages/attachment/attachment/README.md | 2 +- packages/attachment/attachment/README.zh.md | 2 +- .../attachment/attachment/src/admission.ts | 31 +++++++++++++- packages/attachment/attachment/src/index.ts | 3 +- packages/attachment/attachment/src/types.ts | 7 +++- .../attachment/tests/admission.spec.ts | 24 ++++++++++- .../client/ui-conversation/README.i18n.yaml | 4 +- packages/client/ui-conversation/README.md | 2 +- packages/client/ui-conversation/README.zh.md | 2 +- .../ui-conversation/src/client/service.ts | 2 +- .../service-orchestration.client.spec.ts | 8 ++-- .../src/client/api-catalog.ts | 2 +- packages/llm/llm/src/content.ts | 28 +------------ packages/llm/llm/tests/content.spec.ts | 31 -------------- packages/subagent/subagent/src/index.ts | 4 +- 26 files changed, 127 insertions(+), 110 deletions(-) diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml index e9541319ae..f52fe97496 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.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-08-27-steer-followup-image-delivery.md -2026-08-27-steer-followup-image-delivery.md: 37160f19f561f060c6eb3f6b5b3360bba83b0e5c -2026-08-27-steer-followup-image-delivery.zh.md: b5c0467733e1551761bed417fd2da53d86b0b05e +2026-08-27-steer-followup-image-delivery.md: a7b6cdc52073b5083bee4d25ed584503ad50554f +2026-08-27-steer-followup-image-delivery.zh.md: 57f5ace239051cbe349b9c6e8231fc6b57a3d3a2 diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md index 37160f19f5..a7b6cdc520 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.md @@ -20,11 +20,11 @@ Fourth, every local submission echo rendered at the Chat flow tail while the bro **Closing-turn wake delivery.** `ReactLoopAgent` tracks the identities of waking sends still awaiting a claim (`pendingWakes`); claim and discard notifications prune the set. At a driver exit whose turn loop returned without throwing, a non-empty set re-wakes the driver, so a steer or follow-up that lost the race with a normally closing turn is claimed by a fresh turn. Cancellation and `agent/pre-step` rejection instead clear the set: accepted-but-unclaimed input parks until the next waking send, preserving the tested `cancel({ keepInbox: true })` semantics and keeping rejected claims from being re-offered to the rejecting policy. Injected context never enters the set. The turn-flow section of [docs/architecture.md](../../../../docs/architecture.md) records the delivery/parking rule. -**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]` (updating the wire contract in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)). `dsh-attachment` owns the shared upload vocabulary used by the subagent route; `dsh-api-session-controller` retains a structurally identical Client-face declaration so the generated Client Cordis catalog contains the complete prompt-part fields, with a compile-time equality test preventing drift. The shared `durablePromptContent()` conversion lives in `dsh-llm/content` and is used by both the Session prompt endpoint and `SubagentRuntime.prompt`. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. +**Host-side subagent image admission.** `SubagentPromptRequest.content` is now upload-shaped `PromptContentPart[]` (updating the wire contract in [Web subagent conversations](../feature/2026-07-27-web-subagent-conversations.md)). `dsh-attachment` owns the shared upload vocabulary and the `admitPromptContent()` conversion used by both the Session prompt endpoint and `SubagentRuntime.prompt`; `dsh-api-session-controller` retains a structurally identical Client-face declaration so the generated Client Cordis catalog contains the complete prompt-part fields, with a compile-time equality test preventing drift. The subagent route admits and persists image batches through `ctx.attachments` before `followup()`, and the continuation manager refuses delivery inside the per-child lock when the child's `agent.options` route resolves to a model without image input (`MODEL_DOES_NOT_SUPPORT_IMAGES`, surfaced as `attachment-error` with the same reason vocabulary as the Session route). A child without a fixed options route, or a deployment without the LLM registry, delivers and relies on the LLM layer's text-only projection. The Client forwards image parts unchanged and the `SUBAGENT_IMAGE_UNSUPPORTED` copy is gone. **Queue presentation.** The queue mirror's text preview excludes image blocks, and the queue dock renders each durable image part as a thumbnail resolved through `ctx.uiConversation.imageUrl` — the same session-authorized read the transcript uses. Editing queued image messages stays refused (#3072). -**Stable optimistic placement.** `PendingSubmission` records the surface selected when submission begins: `transcript` for an idle send, `queued` for a busy Queue send, and `steering` for a busy Steer send. Chat renders transcript and steering echoes on their respective surfaces, while QueueDock renders queued echoes with browser-owned image previews. The existing `rpcId` correlation suppresses the local echo in the same render that introduces the Host queue occurrence or durable user node. If the turn closes while images serialize and the Host places a requested steer in the next-turn queue, the later move from steering to QueueDock reflects the authoritative delivery decision. +**Stable optimistic placement.** Session derives a `PendingSubmission` placement synchronously from its running state and the requested delivery mode: `transcript` for an idle send, `queued` for a busy Queue send, and `steering` for a busy Steer send. The captured placement remains stable while serialization is in flight. Chat renders transcript and steering echoes on their respective surfaces, while QueueDock renders queued echoes with browser-owned image previews. The existing `rpcId` correlation suppresses the local echo in the same render that introduces the Host queue occurrence or durable user node. If the turn closes while images serialize and the Host places a requested steer in the next-turn queue, the later move from steering to QueueDock reflects the authoritative delivery decision. ## Alternatives considered @@ -38,7 +38,7 @@ Fourth, every local submission echo rendered at the Chat flow tail while the bro ## Testing -Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, the catalog-visible upload declaration, queue thumbnails (load, failure placeholder, unmount), the image-free preview, placement capture before serialization, local steering presentation, queued echo presentation, and `rpcId` handoff on both surfaces. +Agent-loop tests pin the closing-turn window deterministically (a `turn/end` listener queues the send as a microtask ahead of the driver's exit continuation) for steer, follow-up, and the inject non-delivery case. Host tests cover `mode: 'steer'` image admission; subagent control tests cover ordered admission, batch refusal, non-canonical base64, and the capability refusal mapping; continuation tests cover refusal without a partial message, capable delivery, and the routeless deferral. Client tests cover unstripped forwarding, the catalog-visible upload declaration, queue thumbnails (load, failure placeholder, unmount), the image-free preview, Session-owned placement derivation and capture, local steering presentation, queued echo presentation, and `rpcId` handoff on both surfaces. ## Consequences diff --git a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md index b5c0467733..57f5ace239 100644 --- a/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md +++ b/.agents/notes/implemented/bug-fix/2026-08-27-steer-followup-image-delivery.zh.md @@ -20,11 +20,11 @@ agent 运行期间提交的图片没有可靠进入模型上下文，也没有 **轮次收尾期的唤醒投递。** `ReactLoopAgent` 用 `pendingWakes` 记录尚未被认领的唤醒发送的身份；认领与丢弃通知会移除对应条目。当 driver 的轮次循环无异常返回并退出时，集合非空就重新拉起 driver，输掉与正常收尾轮次竞态的 steer 或 follow-up 由新轮次认领。取消与 `agent/pre-step` 拒绝则清空该集合：已接受但未认领的输入停放到下一次唤醒发送，既保留了有测试保护的 `cancel({ keepInbox: true })` 语义，也避免把被拒绝的认领重新塞给同一个拒绝策略。注入的上下文从不进入该集合。投递与停放规则记录在 [docs/architecture.md](../../../../docs/architecture.zh.md) 的 turn-flow 一节。 -**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`（同步更新 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 的 wire 契约）。`dsh-attachment` 负责子代理路由使用的共享上传词汇；`dsh-api-session-controller` 保留结构相同的 Client face 声明，使生成的 Client Cordis 目录包含完整的 prompt part 字段，并用编译期等价测试防止两处定义偏离。共享的 `durablePromptContent()` 转换位于 `dsh-llm/content`，Session prompt 端点与 `SubagentRuntime.prompt` 共用。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 +**Host 侧子代理图片准入。** `SubagentPromptRequest.content` 改为上传形态的 `PromptContentPart[]`（同步更新 [Web 子代理会话](../feature/2026-07-27-web-subagent-conversations.zh.md) 的 wire 契约）。`dsh-attachment` 负责共享上传词汇，以及 Session prompt 端点与 `SubagentRuntime.prompt` 共用的 `admitPromptContent()` 转换；`dsh-api-session-controller` 保留结构相同的 Client face 声明，使生成的 Client Cordis 目录包含完整的 prompt part 字段，并用编译期等价测试防止两处定义偏离。子代理路由在 `followup()` 之前经 `ctx.attachments` 完成整批图片的准入与持久化；continuation 管理器在逐子级锁内，当子级 `agent.options` 路由解析到不接受图片输入的模型时拒绝投递（`MODEL_DOES_NOT_SUPPORT_IMAGES`，以与 Session 路由一致的 `attachment-error` 词汇表上抛）。子级没有固定 options 路由，或部署未挂载 LLM 注册表时照常投递，交给 LLM 层的纯文本投影。客户端原样转发图片部分，`SUBAGENT_IMAGE_UNSUPPORTED` 文案删除。 **队列展示。** 队列镜像的文本预览不再包含图片块，queue dock 把每个持久化图片部分渲染为缩略图，经 `ctx.uiConversation.imageUrl` 解析，与会话记录使用同一个会话授权读取。已排队图片消息的编辑仍然拒绝（#3072）。 -**稳定的乐观显示位置。** `PendingSubmission` 记录提交开始时选定的区域：空闲发送是 `transcript`，繁忙时 Queue 发送是 `queued`，繁忙时 Steer 发送是 `steering`。Chat 分别在 transcript 与 steering 区域渲染对应回显，QueueDock 用浏览器持有的图片预览渲染 queued 回显。现有 `rpcId` 关联会在 Host queue occurrence 或持久化 user node 出现的同一次渲染中隐藏本地回显。如果图片序列化期间轮次关闭，Host 把请求的 steer 放入 next-turn queue，消息随后从 steering 移到 QueueDock，反映实际投递决定。 +**稳定的乐观显示位置。** Session 根据运行状态和请求的投递模式同步推导 `PendingSubmission` 位置：空闲发送是 `transcript`，繁忙时 Queue 发送是 `queued`，繁忙时 Steer 发送是 `steering`。该位置在序列化期间保持不变。Chat 分别在 transcript 与 steering 区域渲染对应回显，QueueDock 用浏览器持有的图片预览渲染 queued 回显。现有 `rpcId` 关联会在 Host queue occurrence 或持久化 user node 出现的同一次渲染中隐藏本地回显。如果图片序列化期间轮次关闭，Host 把请求的 steer 放入 next-turn queue，消息随后从 steering 移到 QueueDock，反映实际投递决定。 ## Alternatives considered @@ -38,7 +38,7 @@ agent 运行期间提交的图片没有可靠进入模型上下文，也没有 ## Testing -agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、目录可见的上传声明、队列缩略图（加载、失败占位、卸载）、不含图片的预览、序列化前的位置捕获、steering 本地显示、queued 回显显示，以及两个区域的 `rpcId` 交接。 +agent-loop 测试确定性地钉住收尾窗口（`turn/end` 监听器把发送排为微任务，先于 driver 的退出续体执行），覆盖 steer、follow-up 与注入不投递。Host 测试覆盖 `mode: 'steer'` 的图片准入；subagent control 测试覆盖有序准入、整批拒绝、非规范 base64 与能力拒绝映射；continuation 测试覆盖拒绝时不留半条消息、能力通过时投递、无路由时的顺延。客户端测试覆盖不剥离的转发、目录可见的上传声明、队列缩略图（加载、失败占位、卸载）、Session 负责的位置推导与捕获、steering 本地显示、queued 回显显示，以及两个区域的 `rpcId` 交接。 ## Consequences diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index e68454d854..3b521194ac 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/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/api/session-controller/README.md -README.md: e4a4ed9918c0d469876da7db8d37c0e00554d5b2 -README.zh.md: a9a20cc88873f56567a411459f27e9baf5132ff1 +README.md: 50427d3072f88cc29ae9f4f8a3f8bf8f31354a64 +README.zh.md: c273fb23a9896ad002cd985c496504a0e9be1265 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index e4a4ed9918..50427d3072 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -29,7 +29,7 @@ Each endpoint states its activation policy. List, search, attachment, history pa The Client adapter exposes `SessionEventStream`, a Gateway `RemoteJournalStream` bound to one ordinary or direct-subagent address. It opens follow before the initial page, publishes only contiguous `replace`, `prepend`, and `append` changes, and repairs reconnect or sequence gaps through a tail page. Ordinary records cover `[event.seq, event.seq]`; packed rows cover `[event.seq, event.seq + memberCount - 1]`. A business, persistence, or unresolved continuity failure terminates the stream, while only physical carrier loss selects automatic resumption. `SessionControlStream` is a Gateway `RemoteSnapshotStream`; every generation opens with a complete process-local baseline, so reconnect replaces queue, jobs, and projection state instead of treating transient values as durable events. -The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Each echo records its expected `transcript`, `queued`, or `steering` placement; this keeps slow serialization on the surface selected when submission began. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. +The Session object also carries local submission echoes: `session.beginSubmission` inserts one into `SessionSnapshot.pendingSubmissions` synchronously, before the caller serializes and prompts, so a conversation UI can show the message on the submit click's own frame. Session derives each echo's `transcript`, `queued`, or `steering` placement from its current running state and the requested delivery mode, then retains that placement while serialization is in flight. The prompt's `requestId` is the correlation identity: the Host echoes it as the durable user source's `rpcId`, and queue occurrences project it as `SessionQueuedItem.rpcId`. An echo retires one animation frame after its durable event or queue occurrence is observed (the delay keeps it renderable until the replacement is ready), immediately when its identified prompt fails or is abandoned, and as failed on disposal; each retirement fires the registered `onRetire` callback exactly once. Echoes are Client memory only; reload and reconnect rebuild the conversation from durable events alone. ----- diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index a9a20cc888..c273fb23a9 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -29,7 +29,7 @@ kind: "package-reference" Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend` 和 `append` 变更，并通过 tail page 修复重连或 seq 缺口。普通 record 覆盖 `[event.seq, event.seq]`，packed row 覆盖 `[event.seq, event.seq + memberCount - 1]`。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs 和 projection 状态，而不会把瞬态值当作 durable event。 -Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。每条回显记录预期的 `transcript`、`queued` 或 `steering` 位置，使较慢的序列化过程始终显示在提交开始时选定的区域。prompt 的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，该延迟保证替代内容就绪前回显仍可渲染；带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休；每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存；刷新与重连只从 durable event 重建会话。 +Session 对象还承载本地提交回显：`session.beginSubmission` 在调用方序列化与 prompt 之前，同步把一条回显写入 `SessionSnapshot.pendingSubmissions`，会话 UI 因此能在点击提交的当帧显示消息。Session 根据当前运行状态与请求的投递模式推导每条回显的 `transcript`、`queued` 或 `steering` 位置，并在序列化期间保留该位置。prompt 的 `requestId` 是关联标识：Host 把它回显为 durable user source 的 `rpcId`，queue occurrence 也把它投影为 `SessionQueuedItem.rpcId`。回显在观察到其 durable event 或 queue occurrence 后延迟一个动画帧退休，该延迟保证替代内容就绪前回显仍可渲染；带标识的 prompt 失败或被放弃时立即退休，销毁时按 failed 退休；每次退休恰好触发一次注册的 `onRetire` 回调。回显只存在于 Client 内存；刷新与重连只从 durable event 重建会话。 ----- diff --git a/packages/api/session-controller/src/client/contract/session.ts b/packages/api/session-controller/src/client/contract/session.ts index cb0290eccc..5fec89bc44 100644 --- a/packages/api/session-controller/src/client/contract/session.ts +++ b/packages/api/session-controller/src/client/contract/session.ts @@ -15,7 +15,7 @@ import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store' import type { QueueAction, SessionRequestId } from '../../types.ts' import type { ClientResult } from './result.ts' import type { - PendingSubmissionImage, PendingSubmissionPlacement, SessionSnapshot, + PendingSubmissionImage, SessionSnapshot, } from './snapshot.ts' /** Browser-submitted prompt content; the Host promotes image bytes to durable references. */ @@ -40,8 +40,8 @@ export type PendingSubmissionRetirement = /** Input registering one local submission echo ahead of its prompt call. */ export interface BeginSubmissionInput { - /** Expected surface selected from the submission mode and running state. */ - readonly placement: PendingSubmissionPlacement + /** Delivery mode used with the upcoming prompt. */ + readonly mode: 'queue' | 'steer' /** Prompt text exactly as the upcoming prompt will send it. */ readonly text: string /** Ordered image previews matching the upcoming prompt's image parts. */ diff --git a/packages/api/session-controller/src/client/sessions/session.ts b/packages/api/session-controller/src/client/sessions/session.ts index 4eaf353b50..2dbd38b230 100644 --- a/packages/api/session-controller/src/client/sessions/session.ts +++ b/packages/api/session-controller/src/client/sessions/session.ts @@ -189,7 +189,9 @@ export class Session implements SessionFace { const requestId = randomUUID() as SessionRequestId this.pendingSubmissions = [...this.pendingSubmissions, { requestId, - placement: input.placement, + placement: this.running + ? input.mode === 'steer' ? 'steering' : 'queued' + : 'transcript', time: Date.now(), text: input.text, images: input.images, diff --git a/packages/api/session-controller/src/commands.ts b/packages/api/session-controller/src/commands.ts index be2b8304e2..206ebc34b8 100644 --- a/packages/api/session-controller/src/commands.ts +++ b/packages/api/session-controller/src/commands.ts @@ -4,10 +4,10 @@ import { randomUUID } from 'node:crypto' import type { Context } from '@deepseek-ai/cordis' import type { Agent, ModelSelection as AgentModelSelection } from '@deepseek-ai/dsh-agent' import { PresetMountError, UnknownPresetError } from '@deepseek-ai/dsh-agent-presets' -import { AttachmentError } from '@deepseek-ai/dsh-attachment' +import { AttachmentError, admitPromptContent } from '@deepseek-ai/dsh-attachment' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import { - ReasoningEffortId, createUserMessage, durablePromptContent, freezeMessage, + ReasoningEffortId, createUserMessage, freezeMessage, } from '@deepseek-ai/dsh-llm' import type { MessageSource } from '@deepseek-ai/dsh-llm' import { SessionId } from '@deepseek-ai/dsh-session' @@ -319,7 +319,7 @@ export class SessionCommandController { ) } } - const content = await durablePromptContent(this.ctx.attachments, request.content) + const content = await admitPromptContent(this.ctx.attachments, request.content) const message: UserMessage = createUserMessage({ content, source }) if (request.mode === 'steer') agent.steer(message) else agent.followup(message) diff --git a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts index 8c108624c2..3191949dbe 100644 --- a/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts +++ b/packages/api/session-controller/tests/session-pending-submissions.client.spec.ts @@ -69,7 +69,7 @@ describe('beginSubmission', () => { const { session } = makeSession() expect(session.getSnapshot()).toMatchObject({ pendingSubmissions: [], promptAttempted: false }) const handle = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '你好', images: [{ previewUrl: 'blob:p1', name: 'a.png', width: 4, height: 3 }], }) @@ -82,11 +82,25 @@ describe('beginSubmission', () => { }]) }) + it('derives and captures the echo placement from running state and delivery mode', () => { + const { session } = makeSession() + session.beginSubmission({ mode: 'queue', text: '空闲', images: [] }) + session.handleRunning(true) + session.beginSubmission({ mode: 'queue', text: '排队', images: [] }) + session.beginSubmission({ mode: 'steer', text: '纠偏', images: [] }) + session.handleRunning(false) + expect(session.getSnapshot().pendingSubmissions.map(({ text, placement }) => ({ text, placement }))).toEqual([ + { text: '空闲', placement: 'transcript' }, + { text: '排队', placement: 'queued' }, + { text: '纠偏', placement: 'steering' }, + ]) + }) + it('abandon retires the echo as failed exactly once', () => { const { session } = makeSession() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '放弃', images: [], onRetire: retirement => retirements.push(retirement), @@ -104,7 +118,7 @@ describe('prompt-coupled retirement', () => { api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: '忙', details: { reason: 'busy' } })) const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '失败的', images: [], onRetire: retirement => retirements.push(retirement), @@ -118,7 +132,7 @@ describe('prompt-coupled retirement', () => { it('sends the echo identity as the prompt requestId', async () => { const { api, session } = makeSession() - const handle = session.beginSubmission({ placement: 'transcript', text: '带 id', images: [] }) + const handle = session.beginSubmission({ mode: 'queue', text: '带 id', images: [] }) await session.prompt([{ type: 'text', text: '带 id' }], 'queue', undefined, handle.requestId) expect(api.callsOf('session.prompt')).toMatchObject([{ requestId: handle.requestId }]) }) @@ -126,7 +140,7 @@ describe('prompt-coupled retirement', () => { it('an unidentified prompt failure leaves registered echoes alone', async () => { const { api, session } = makeSession() api.onPrompt = () => Promise.resolve(err({ code: 'agent-busy', message: '忙', details: { reason: 'busy' } })) - session.beginSubmission({ placement: 'transcript', text: '还在', images: [] }) + session.beginSubmission({ mode: 'queue', text: '还在', images: [] }) await session.prompt([{ type: 'text', text: '另一个' }], 'queue') expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) }) @@ -139,7 +153,7 @@ describe('observed retirement', () => { await session.open() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '发送', images: [{ previewUrl: 'blob:p1' }], onRetire: retirement => retirements.push(retirement), @@ -157,8 +171,9 @@ describe('observed retirement', () => { it('a queue occurrence carrying the rpcId retires the echo (running-turn submissions)', async () => { const { session } = makeSession() const retirements: PendingSubmissionRetirement[] = [] + session.handleRunning(true) const handle = session.beginSubmission({ - placement: 'queued', + mode: 'queue', text: '排队', images: [{ previewUrl: 'blob:p1' }], onRetire: retirement => retirements.push(retirement), @@ -174,7 +189,7 @@ describe('observed retirement', () => { it('a full-window install (reconnect resync) retires echoes observed in the window', async () => { const { api, session } = makeSession() - const handle = session.beginSubmission({ placement: 'transcript', text: '重连', images: [] }) + const handle = session.beginSubmission({ mode: 'queue', text: '重连', images: [] }) api.onHistory = () => Promise.resolve(ok(historyValue([promptEvent(12, handle.requestId)]))) await session.open() await settleFrames() @@ -187,7 +202,7 @@ describe('observed retirement', () => { await session.open() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '先观察', images: [], onRetire: retirement => retirements.push(retirement), @@ -204,7 +219,7 @@ describe('observed retirement', () => { await session.open() const retirements: PendingSubmissionRetirement[] = [] const handle = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '同一请求', images: [], onRetire: retirement => retirements.push(retirement), @@ -229,7 +244,7 @@ describe('observed retirement', () => { const { api, session } = makeSession() api.onHistory = () => Promise.resolve(ok(historyValue([]))) await session.open() - const handle = session.beginSubmission({ placement: 'transcript', text: '帧', images: [] }) + const handle = session.beginSubmission({ mode: 'queue', text: '帧', images: [] }) await api.pushFollow(SID, { type: 'event', event: promptEvent(0, handle.requestId) as never }) expect(session.getSnapshot().pendingSubmissions).toHaveLength(1) expect(frames).toHaveLength(1) @@ -245,13 +260,13 @@ describe('disposal', () => { await session.open() const retirements: { text: string; retirement: PendingSubmissionRetirement }[] = [] const observed = session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '已观察', images: [], onRetire: retirement => retirements.push({ text: '已观察', retirement }), }) session.beginSubmission({ - placement: 'transcript', + mode: 'queue', text: '未settle', images: [], onRetire: retirement => retirements.push({ text: '未settle', retirement }), diff --git a/packages/attachment/attachment/README.i18n.yaml b/packages/attachment/attachment/README.i18n.yaml index e67d95604d..6cc6a74eeb 100644 --- a/packages/attachment/attachment/README.i18n.yaml +++ b/packages/attachment/attachment/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/attachment/attachment/README.md -README.md: 01a5d6ee143ff53175dd7327cd6d419af61938a3 -README.zh.md: 1a1d297297a6815ce5338391af0182e471f99000 +README.md: 709189ac8dd9591d89c0b0082ea0ae0247c97f97 +README.zh.md: 24eee83874d2ad12025d4457f1fad74aadb73446 diff --git a/packages/attachment/attachment/README.md b/packages/attachment/attachment/README.md index 01a5d6ee14..709189ac8d 100644 --- a/packages/attachment/attachment/README.md +++ b/packages/attachment/attachment/README.md @@ -75,7 +75,7 @@ The service family runs one admission-and-storage flow: every entry point enforc |---|---| | [`src/index.ts`](src/index.ts) | Plugin entry: abstract `AttachmentStore` service and re-exports | | [`src/types.ts`](src/types.ts) | Durable vocabulary: references, limits, upload and store payloads | -| [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`: canonical-base64 enforcement, then `saveImages` delegation | +| [`src/admission.ts`](src/admission.ts) | Browser prompt admission: canonical-base64 enforcement, `saveImages` delegation, and durable prompt-part projection | | [`src/error.ts`](src/error.ts) | `AttachmentError` class and the `isImageAdmissionError` runtime subset | | [`src/brand.ts`](src/brand.ts) | `AttachmentId` branded opaque identifier | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; implementations enforce immutable-store checks) | diff --git a/packages/attachment/attachment/README.zh.md b/packages/attachment/attachment/README.zh.md index 1a1d297297..24eee83874 100644 --- a/packages/attachment/attachment/README.zh.md +++ b/packages/attachment/attachment/README.zh.md @@ -75,7 +75,7 @@ kind: "package-reference" |---|---| | [`src/index.ts`](src/index.ts) | 插件入口：抽象 `AttachmentStore` 服务与再导出 | | [`src/types.ts`](src/types.ts) | 持久词汇：引用、限额、上传与存储载荷 | -| [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`：规范 base64 强制，随后委托 `saveImages` | +| [`src/admission.ts`](src/admission.ts) | 浏览器 prompt 准入：强制规范 base64、委托 `saveImages` 并投影持久 prompt part | | [`src/error.ts`](src/error.ts) | `AttachmentError` 类与 `isImageAdmissionError` 运行时子集 | | [`src/brand.ts`](src/brand.ts) | `AttachmentId` 带类型标记的不透明标识符 | | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；实现负责强制不可变存储检查） | diff --git a/packages/attachment/attachment/src/admission.ts b/packages/attachment/attachment/src/admission.ts index d31bc6d831..155b3644d8 100644 --- a/packages/attachment/attachment/src/admission.ts +++ b/packages/attachment/attachment/src/admission.ts @@ -3,7 +3,13 @@ import { Buffer } from 'node:buffer' import { AttachmentError } from './error.ts' import type { AttachmentStore } from './index.ts' -import type { EncodedImageAttachment, ImageAttachmentRef, SaveImageAttachment } from './types.ts' +import type { + AdmittedPromptContentPart, + EncodedImageAttachment, + ImageAttachmentRef, + PromptContentPart, + SaveImageAttachment, +} from './types.ts' /** Decode one upload payload while rejecting non-canonical base64 forms. */ function decodeBase64(data: string): Uint8Array { @@ -39,3 +45,26 @@ export async function admitEncodedImages( ): Promise { return attachments.saveImages(images.map(saveInput)) } + +/** + * Admit one browser prompt and replace each uploaded image with its durable reference. + * Text-only prompts do not access the attachment store. + * @param attachments - the deployment attachment store owning batch policy. + * @param content - browser prompt parts in message order. + * @returns admitted prompt parts in the same order as `content`. + * @throws AttachmentError when the image batch is refused. + */ +export async function admitPromptContent( + attachments: AttachmentStore, + content: readonly PromptContentPart[], +): Promise { + if (content.every(part => part.type === 'text')) { + return content.map(part => ({ type: 'text', text: part.text })) + } + const refs = await admitEncodedImages(attachments, content.filter(part => part.type === 'image')) + let next = 0 + return content.map(part => part.type === 'text' + ? { type: 'text', text: part.text } + // admitEncodedImages returns one reference per image part in order. + : { type: 'image', attachment: refs[next++] as ImageAttachmentRef }) +} diff --git a/packages/attachment/attachment/src/index.ts b/packages/attachment/attachment/src/index.ts index 1c0f76b9e0..9dcddeae65 100644 --- a/packages/attachment/attachment/src/index.ts +++ b/packages/attachment/attachment/src/index.ts @@ -14,10 +14,11 @@ import type { export { AttachmentId, ImageVariantId } from './brand.ts' export { AttachmentError, isImageAdmissionError } from './error.ts' export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts' -export { admitEncodedImages } from './admission.ts' +export { admitEncodedImages, admitPromptContent } from './admission.ts' export { requestImageDimensions } from './request-projection.ts' export type { AttachmentId as AttachmentIdType, + AdmittedPromptContentPart, EncodedImageAttachment, ImageAttachmentLimits, ImageAttachmentRef, diff --git a/packages/attachment/attachment/src/types.ts b/packages/attachment/attachment/src/types.ts index 64c199eaf1..7a55c6a68f 100644 --- a/packages/attachment/attachment/src/types.ts +++ b/packages/attachment/attachment/src/types.ts @@ -55,7 +55,7 @@ export interface EncodedImageAttachment { /** * Browser-submitted prompt content accepted by Host prompt endpoints; the * accepting Host promotes image parts to durable references through - * `admitEncodedImages` before any message is created, so a wire caller can + * `admitPromptContent` before any message is created, so a wire caller can * never cite an attachment it did not upload. */ export type PromptContentPart = @@ -67,6 +67,11 @@ export type PromptContentPart = readonly name?: string } +/** Host-admitted prompt content with each uploaded image replaced by its durable reference. */ +export type AdmittedPromptContentPart = + | { readonly type: 'text'; readonly text: string } + | { readonly type: 'image'; readonly attachment: ImageAttachmentRef } + /** Request to validate and durably commit one image. */ export interface SaveImageAttachment { data: Uint8Array diff --git a/packages/attachment/attachment/tests/admission.spec.ts b/packages/attachment/attachment/tests/admission.spec.ts index 4c929b6d5c..ba24d8fa20 100644 --- a/packages/attachment/attachment/tests/admission.spec.ts +++ b/packages/attachment/attachment/tests/admission.spec.ts @@ -1,6 +1,6 @@ import { describe, expect, it, vi } from 'vitest' import type { AttachmentStore } from '@deepseek-ai/dsh-attachment' -import { admitEncodedImages } from '@deepseek-ai/dsh-attachment' +import { admitEncodedImages, admitPromptContent } from '@deepseek-ai/dsh-attachment' import type { ImageAttachmentRef, SaveImageAttachment } from '@deepseek-ai/dsh-attachment/types' const PNG = 'AAAA' // canonical base64, 3 bytes @@ -64,3 +64,25 @@ describe('admitEncodedImages', () => { await expect(admitEncodedImages(store, [{ mediaType: 'image/png', data: PNG }])).rejects.toBe(refused) }) }) + +describe('admitPromptContent', () => { + it('converts text-only prompts without touching the attachment store', async () => { + const store = { saveImages: () => { throw new Error('text-only prompts must not reach the store') } } + await expect(admitPromptContent(store as unknown as AttachmentStore, [ + { type: 'text', text: 'hello' }, + ])).resolves.toEqual([{ type: 'text', text: 'hello' }]) + }) + + it('replaces image parts with admitted references in part order', async () => { + const { store } = storeOf() + await expect(admitPromptContent(store, [ + { type: 'image', mediaType: 'image/png', data: 'AQ==' }, + { type: 'text', text: 'between' }, + { type: 'image', mediaType: 'image/png', data: 'Ag==' }, + ])).resolves.toEqual([ + { type: 'image', attachment: { attachmentId: 'att-1', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } }, + { type: 'text', text: 'between' }, + { type: 'image', attachment: { attachmentId: 'att-2', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } }, + ]) + }) +}) diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index 1a2eaf3aae..26499140f2 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: cd410bbdb6ee403cf246962d9b8f3d17d1bc30ad -README.zh.md: a8ab2a1ea10698c1d191db6e75e222d4d19b5fb4 +README.md: 629b8b4f7987fc072066e58692396354f7b6ad6a +README.zh.md: cb622f0308ddb0a978cfb665105d79aadfb3135a diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index cd410bbdb6..629b8b4f79 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -40,7 +40,7 @@ View selection is deterministic: a registered persisted selection wins, otherwis The resident composer survives no-Session and Session transitions. The no-Session state keeps the same composer surface mounted but inert while the Workspace picker connects a blank Session. The surface is a shell-owned Lexical editor: reference chips are atomic decorator nodes carrying the owner's serialization identity (submission expands them through the owner codec), claimed slash commands stay styled leading text, folder text references carry the folder glyph as an icon prefix, and the draft's clipboard projection is mirrored into the per-Session Conversation store. Queue operations address exact queue occurrences through the scoped `ctx.conversation` service; queue previews render sent text through the shared inline reference projection from `ui-primitives` (wire session forms fold to their label) and show local image previews or durable image parts as thumbnails, while an edit exposes the literal sent text. Durable thumbnails resolve through the session image URL cache. Busy Enter behavior is stored in the Host-backed `ui-conversation` settings namespace. -Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) before serializing and records the surface selected from the current running state and delivery mode: idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint and encodes images through the browser's native `FileReader` data-URL path. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their image ids through admission and Session scope disposal. When an echo retires as observed, the durable image cache exposes its preview immediately, fetches the admitted attachment, replaces the preview with the canonical URL, and revokes each URL after its use ends. Direct subagent continuations skip local echoes because their transport does not preserve the browser request id. +Default sends commit optimistically: Enter clears the draft, occurrence table, and undo history in the same transaction, keeps the composer in `plain`, and runs the send as a detached attempt, so typing and further sends continue during the flight. `sendSession` registers a Session submission echo (`session.beginSubmission`) with the delivery mode before serializing; Session derives the placement from that mode and its current running state, so idle sends use the transcript, busy Queue sends use QueueDock, and busy Steer sends use the pending-steering surface. It then yields one paint and encodes images through the browser's native `FileReader` data-URL path. Concurrent failures are restored together in submission order until the user edits the restored content; command submissions keep the frozen `submitting` phase. Detached attempts retain their image ids through admission and Session scope disposal. When an echo retires as observed, the durable image cache exposes its preview immediately, fetches the admitted attachment, replaces the preview with the canonical URL, and revokes each URL after its use ends. Direct subagent continuations skip local echoes because their transport does not preserve the browser request id. While a normal composer is running, its primary pointer action remains Stop when the draft is empty or input is unavailable. Actionable text or attachments switch the same seat to Queue Send; clearing or successfully submitting the draft restores Stop. The busy-Enter setting continues to select the Queue or Steer keyboard action. Continuable subagents keep separate Send and Stop actions ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-20-running-draft-primary-send.md)). diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index a8ab2a1ea1..cb622f0308 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -40,7 +40,7 @@ View 选择规则固定：有效且已注册的持久化选择优先，其次是 常驻 composer 在无 Session 与有 Session 之间保持挂载。无 Session 时，同一个编辑器表面保持 inert，Workspace picker 连接 blank Session。该表面是 shell 所有的 Lexical 编辑器：引用 chip 是携带 owner 序列化身份的原子 decorator 节点（提交时经 owner codec 展开），已认领的 slash command 保持为带样式的行首文本，文件夹文本引用以图标前缀携带文件夹图形，草稿的剪贴板投影镜像到逐 Session Conversation store。Queue 操作通过 scoped `ctx.conversation` service 寻址准确的 queue occurrence；queue 预览经 `ui-primitives` 的共享行内引用投影渲染已发送文本（wire 会话形式折叠为其标签），并把本地图片预览或持久化图片部分显示为缩略图，编辑态则展示字面发送文本。持久化缩略图通过会话图片 URL 缓存解析。繁忙时 Enter 行为保存在 Host-backed `ui-conversation` settings namespace。 -默认发送采用乐观提交：Enter 在同一事务里清空草稿、occurrence 表和撤销历史，composer 保持 `plain`，发送作为 detached attempt 运行，发送期间可以继续输入和提交。`sendSession` 在序列化之前注册 Session 提交回显（`session.beginSubmission`），并按当前运行状态与投递模式记录选定区域：空闲发送进入 transcript，繁忙时 Queue 进入 QueueDock，繁忙时 Steer 进入 pending-steering 区域。随后让出一帧，图片经浏览器原生 `FileReader` data-URL 路径编码。多个并发发送失败时，在用户编辑还原内容之前按提交顺序合并还原；命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有图片 id，直到 admission 完成或 Session scope 销毁。回显以 observed 退休时，durable 图片缓存立即公开预览 URL，同时读取 admitted 附件，随后用规范化 URL 替换预览，并在两个 URL 各自停止使用后撤销。直接 subagent continuation 不创建本地回显，因为其 transport 不保留浏览器 request id。 +默认发送采用乐观提交：Enter 在同一事务里清空草稿、occurrence 表和撤销历史，composer 保持 `plain`，发送作为 detached attempt 运行，发送期间可以继续输入和提交。`sendSession` 在序列化之前用投递模式注册 Session 提交回显（`session.beginSubmission`）；Session 根据该模式与当前运行状态推导位置，因此空闲发送进入 transcript，繁忙时 Queue 进入 QueueDock，繁忙时 Steer 进入 pending-steering 区域。随后让出一帧，图片经浏览器原生 `FileReader` data-URL 路径编码。多个并发发送失败时，在用户编辑还原内容之前按提交顺序合并还原；命令提交保持冻结的 `submitting` 阶段。Detached attempt 持有图片 id，直到 admission 完成或 Session scope 销毁。回显以 observed 退休时，durable 图片缓存立即公开预览 URL，同时读取 admitted 附件，随后用规范化 URL 替换预览，并在两个 URL 各自停止使用后撤销。直接 subagent continuation 不创建本地回显，因为其 transport 不保留浏览器 request id。 普通 composer 运行时，如果草稿为空或输入不可用，主指针操作保持为 Stop。可提交的文字或附件会把同一位置切换为 Queue Send；清空或成功提交草稿后恢复 Stop。繁忙态 Enter 设置继续选择 Queue 或 Steer 键盘操作。可继续 subagent 保留独立的 Send 与 Stop 操作（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-20-running-draft-primary-send.zh.md)）。 diff --git a/packages/client/ui-conversation/src/client/service.ts b/packages/client/ui-conversation/src/client/service.ts index ad56938253..1b7a17c629 100644 --- a/packages/client/ui-conversation/src/client/service.ts +++ b/packages/client/ui-conversation/src/client/service.ts @@ -219,7 +219,7 @@ export class ConversationController extends Service implements IConversation { ? undefined : new Promise((resolve) => { finishRetirement = resolve }) const submission = session.beginSubmission({ - placement: snapshot.running ? mode === 'steer' ? 'steering' : 'queued' : 'transcript', + mode, text, images: attachments.map(attachment => ({ previewUrl: attachment.previewUrl, diff --git a/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts b/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts index 7ecbb9679e..2823d45dc0 100644 --- a/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts +++ b/packages/client/ui-conversation/tests/service-orchestration.client.spec.ts @@ -185,7 +185,7 @@ describe('sendSession submission echo', () => { const sending = b.root.sendSession(session, '带图', [attachment!.id], 'queue') // Synchronous: the echo is registered before any encoding starts. expect(b.beginSubmission).toHaveBeenCalledWith(expect.objectContaining({ - placement: 'transcript', + mode: 'queue', text: '带图', images: [expect.objectContaining({ previewUrl: 'blob:echo-1', name: 'a.png' })], })) @@ -212,7 +212,7 @@ describe('sendSession submission echo', () => { await b.runtime.dispose() }) - it('captures the busy submission surface before image serialization', async () => { + it('passes each delivery mode before image serialization', async () => { const b = await echoBench() try { await b.runtime.sessions.updateSessionSnapshot('s1', (draft) => { draft.running = true }) @@ -220,13 +220,13 @@ describe('sendSession submission echo', () => { await expect(b.root.sendSession(session, '立即纠偏', [], 'steer')) .resolves.toEqual({ kind: 'success' }) expect(b.beginSubmission).toHaveBeenLastCalledWith(expect.objectContaining({ - placement: 'steering', + mode: 'steer', text: '立即纠偏', })) await expect(b.root.sendSession(session, '稍后处理', [], 'queue')) .resolves.toEqual({ kind: 'success' }) expect(b.beginSubmission).toHaveBeenLastCalledWith(expect.objectContaining({ - placement: 'queued', + mode: 'queue', text: '稍后处理', })) } finally { diff --git a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts index 43a19880a2..011bfd337a 100644 --- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts @@ -444,7 +444,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'BeginSubmissionInput', - declaration: 'export interface BeginSubmissionInput {\n readonly placement: PendingSubmissionPlacement;\n readonly text: string;\n readonly images: readonly PendingSubmissionImage[];\n readonly onRetire?: (retirement: PendingSubmissionRetirement) => void;\n}', + declaration: 'export interface BeginSubmissionInput {\n readonly mode: \'queue\' | \'steer\';\n readonly text: string;\n readonly images: readonly PendingSubmissionImage[];\n readonly onRetire?: (retirement: PendingSubmissionRetirement) => void;\n}', }, { name: 'BoundActions', diff --git a/packages/llm/llm/src/content.ts b/packages/llm/llm/src/content.ts index faac6249af..43c392a641 100644 --- a/packages/llm/llm/src/content.ts +++ b/packages/llm/llm/src/content.ts @@ -2,8 +2,7 @@ import type { ContentBlock } from './types.ts' import type { Message } from './message.ts' -import type { AttachmentStore, ImageAttachmentRef, ImageMediaType, PromptContentPart, RequestImageAttachment } from '@deepseek-ai/dsh-attachment' -import { admitEncodedImages } from '@deepseek-ai/dsh-attachment' +import type { AttachmentStore, ImageAttachmentRef, ImageMediaType, RequestImageAttachment } from '@deepseek-ai/dsh-attachment' import { assertNever } from './never.ts' /** Execution-world path that model tools can use to read one normalized attachment. */ @@ -40,31 +39,6 @@ export function resolveImageAttachmentAccess( return readonlyPath === undefined ? undefined : { readonlyPath } } -/** - * Promote one browser-submitted prompt into durable model content: every image - * part is admitted through the attachment store before any block exists, so a - * caller-supplied part can never cite an attachment it did not upload here. - * The shared conversion for every Host prompt endpoint accepting uploads. - * @param attachments - the deployment attachment store owning admission policy. - * @param content - ordered browser prompt parts. - * @returns content blocks in part order, image parts replaced by durable references. - * @throws AttachmentError when the image batch is refused. - */ -export async function durablePromptContent( - attachments: AttachmentStore, - content: readonly PromptContentPart[], -): Promise { - if (content.every(part => part.type === 'text')) { - return content.map(part => ({ type: 'text', text: part.text })) - } - const refs = await admitEncodedImages(attachments, content.filter(part => part.type === 'image')) - let next = 0 - return content.map(part => part.type === 'text' - ? { type: 'text', text: part.text } - // admitEncodedImages returns one reference per image part in order. - : { type: 'image', attachment: refs[next++] as ImageAttachmentRef }) -} - function quoted(value: string): string { return JSON.stringify(value) } diff --git a/packages/llm/llm/tests/content.spec.ts b/packages/llm/llm/tests/content.spec.ts index bb0492b0af..748e20f412 100644 --- a/packages/llm/llm/tests/content.spec.ts +++ b/packages/llm/llm/tests/content.spec.ts @@ -4,7 +4,6 @@ import type { AttachmentStore, ImageMediaType } from '@deepseek-ai/dsh-attachmen import { ToolCallId, createUserMessage, - durablePromptContent, offloadedImageText, offloadedImagePrefixCount, offloadRequestImagesWithPolicy, @@ -361,33 +360,3 @@ describe('projectImagesForTextModel', () => { ]) }) }) - -describe('durablePromptContent', () => { - it('converts text-only prompts without touching the attachment store', async () => { - const store = { saveImages: () => { throw new Error('text-only prompts must not reach the store') } } - await expect(durablePromptContent(store as unknown as AttachmentStore, [ - { type: 'text', text: 'hello' }, - ])).resolves.toEqual([{ type: 'text', text: 'hello' }]) - }) - - it('replaces image parts with admitted references in part order', async () => { - const store = { - saveImages: (inputs: readonly { data: Uint8Array }[]) => Promise.resolve(inputs.map((input, index) => ({ - attachmentId: AttachmentId(`att-${index}`), - mediaType: 'image/png' as ImageMediaType, - bytes: input.data.byteLength, - width: 1, - height: 1, - }))), - } - await expect(durablePromptContent(store as unknown as AttachmentStore, [ - { type: 'image', mediaType: 'image/png', data: 'AQ==' }, - { type: 'text', text: 'between' }, - { type: 'image', mediaType: 'image/png', data: 'Ag==' }, - ])).resolves.toEqual([ - { type: 'image', attachment: { attachmentId: 'att-0', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } }, - { type: 'text', text: 'between' }, - { type: 'image', attachment: { attachmentId: 'att-1', mediaType: 'image/png', bytes: 1, width: 1, height: 1 } }, - ]) - }) -}) diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts index aeeeca3829..83ae305084 100644 --- a/packages/subagent/subagent/src/index.ts +++ b/packages/subagent/subagent/src/index.ts @@ -30,11 +30,11 @@ */ import { Context } from '@deepseek-ai/cordis' +import { admitPromptContent } from '@deepseek-ai/dsh-attachment' import { scopeTarget } from '@deepseek-ai/dsh-scope' import type { Scoped } from '@deepseek-ai/dsh-scope' import { assertObjectJsonSchema } from '@deepseek-ai/dsh-tools' import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm' -import { durablePromptContent } from '@deepseek-ai/dsh-llm' import type { Agent } from '@deepseek-ai/dsh-agent' import type { SessionId } from '@deepseek-ai/dsh-session' import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' @@ -465,7 +465,7 @@ export class SubagentRuntime extends TypertRemoteService { } else { const attachments = this.ctx.get('attachments') if (attachments === undefined) throw new Error('subagent image prompt requires an attachment store') - content = await durablePromptContent(attachments, request.content) + content = await admitPromptContent(attachments, request.content) } return { messageId: await this.followup(parent, childSessionId, content, { source, signal }) } } catch (error: unknown) { From 145f9369461b8a38f43b5f2c141408b537079398 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 20:29:25 +0800 Subject: [PATCH 10/63] test: stabilize queued image browser snapshot --- apps/web/tests/queue-image.e2e.ts | 1 + snapshots/web/queued-image/delivered.expected.md | 15 ++++++--------- 2 files changed, 7 insertions(+), 9 deletions(-) diff --git a/apps/web/tests/queue-image.e2e.ts b/apps/web/tests/queue-image.e2e.ts index 37f30c167b..2f57a72c48 100644 --- a/apps/web/tests/queue-image.e2e.ts +++ b/apps/web/tests/queue-image.e2e.ts @@ -105,6 +105,7 @@ describe('web e2e: queued image submission', () => { await dockThumb.waitFor({ timeout: 15_000 }) await expect.poll(() => dockThumb.getAttribute('src')).toMatch(/^blob:/) await page.getByText(QUEUED_TEXT, { exact: true }).waitFor() + await page.getByRole('button', { name: 'Remove queued message' }).waitFor({ timeout: 15_000 }) const queuedSnapshot = await captureStableAria(page, '[class*="centerCol"]', scaffold.workspaceCwd) await compareOrRefreshGolden(QUEUED_EXPECTED, queuedSnapshot, MODE) diff --git a/snapshots/web/queued-image/delivered.expected.md b/snapshots/web/queued-image/delivered.expected.md index 332f611048..b2b220da72 100644 --- a/snapshots/web/queued-image/delivered.expected.md +++ b/snapshots/web/queued-image/delivered.expected.md @@ -20,10 +20,9 @@ - text: Reply with a one-sentence description of event sourcing, then stop. {{clock}} - button "Copy": - img -- button "Context injection @deepseek-ai/dsh-system-prompt": +- button "Thought for a while": + - text: Thought for a while - img - - img - - text: Context injection @deepseek-ai/dsh-system-prompt - paragraph: partial - text: Stopped - button "Copy": @@ -40,10 +39,9 @@ - text: Compare with this screenshot {{clock}} - button "Copy": - img -- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls.": +- button "Thought for a while": + - text: Thought for a while - img - - img - - text: Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls. - paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures. - button "Copy": - img @@ -56,10 +54,9 @@ - text: {{clock}} Ran for {{duration}} TTFT {{duration}} {{throughput}} tok/s Continue with the queued comparison {{clock}} - button "Copy": - img -- button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls.": +- button "Thought for a while": + - text: Thought for a while - img - - img - - text: Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls. - paragraph: Event sourcing is a pattern where all changes to an application's state are stored as an immutable, append-only sequence of events, rather than persisting only the current state, enabling full auditability, temporal queries, and event-driven architectures. - button "Copy": - img From 318bf7d2c135cad70669c9baad2d53748f622e33 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 20:44:35 +0800 Subject: [PATCH 11/63] test: account for Windows chmod coverage --- packages/context/file-reference-local/src/search.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/context/file-reference-local/src/search.ts b/packages/context/file-reference-local/src/search.ts index ba5d30c2f3..ad4571cc97 100644 --- a/packages/context/file-reference-local/src/search.ts +++ b/packages/context/file-reference-local/src/search.ts @@ -295,10 +295,12 @@ async function readDirectory(absolute: string, signal: AbortSignal) { signal.throwIfAborted() return entries.sort((left, right) => compareText(left.name, right.name)) } catch (_error: unknown) { + /* v8 ignore start -- Windows chmod cannot make the unreadable-directory fixture fail readdir; POSIX behavior covers this fallback. */ signal.throwIfAborted() // An unreadable/missing subtree contributes no candidates; other readable // branches remain useful and autocomplete is advisory. return [] + /* v8 ignore stop */ } } From 56f1a3bde6f09c23790b4bc086a953aa8badd87d Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 21:23:49 +0800 Subject: [PATCH 12/63] test: gate unreadable directory case to POSIX --- packages/context/file-reference-local/tests/search.spec.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/context/file-reference-local/tests/search.spec.ts b/packages/context/file-reference-local/tests/search.spec.ts index 7b48148bf3..3bba97f88a 100644 --- a/packages/context/file-reference-local/tests/search.spec.ts +++ b/packages/context/file-reference-local/tests/search.spec.ts @@ -199,7 +199,7 @@ describe('WorkspaceFileSearch', () => { }) }) - it('lets an unreadable subtree cost only its own candidates', async () => { + it.skipIf(process.platform === 'win32')('lets an unreadable subtree cost only its own candidates', async () => { const root = await workspace() const locked = join(root, 'locked') await mkdir(locked, { recursive: true }) From 266440c5a782a094087385278ec759d4cf834035 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 21:25:46 +0800 Subject: [PATCH 13/63] test: allow Windows merge-driver latency --- scripts/translation-pairing-merge.spec.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/translation-pairing-merge.spec.ts b/scripts/translation-pairing-merge.spec.ts index 7293989c2e..2fcc9b0729 100644 --- a/scripts/translation-pairing-merge.spec.ts +++ b/scripts/translation-pairing-merge.spec.ts @@ -30,6 +30,7 @@ const driverLauncher = fileURLToPath(new URL('./merge-translation-pairing-driver const workspaceRoot = fileURLToPath(new URL('../', import.meta.url)) const tsxLoader = import.meta.resolve('tsx/esm') const fixtures: string[] = [] +const compositionTimeoutMs = process.platform === 'win32' ? 60_000 : 15_000 interface Fixture { env: NodeJS.ProcessEnv @@ -261,7 +262,7 @@ function expectMergedPair(fixture: Fixture): void { ) } -describe('translation pairing merge composition', { timeout: 15_000 }, () => { +describe('translation pairing merge composition', { timeout: compositionTimeoutMs }, () => { it('rejects a pairing-record path outside the repository', () => { const fixture = createFixture(false) From 267bdd60aa5a676cda0e05a8071a8192d886e8c6 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 22:26:06 +0800 Subject: [PATCH 14/63] test: allow loaded Windows coverage timing --- .../tests/agent-instructions.spec.ts | 19 ++++++++++--------- scripts/install-lefthook.spec.ts | 2 +- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/packages/context/agent-instructions/tests/agent-instructions.spec.ts b/packages/context/agent-instructions/tests/agent-instructions.spec.ts index a1101a390c..9444e2e445 100644 --- a/packages/context/agent-instructions/tests/agent-instructions.spec.ts +++ b/packages/context/agent-instructions/tests/agent-instructions.spec.ts @@ -47,6 +47,7 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent const sk = (directory: string, candidateName: string): string => candidateScopeKey(directory, candidateName) const testToolSignal = new AbortController().signal +const requestTimeoutMs = process.platform === 'win32' ? 5_000 : 1_000 async function tempRepo(): Promise { return mkdtemp(join(tmpdir(), 'dsh-workspace-context-')) @@ -1348,7 +1349,7 @@ describe('workspace context request injection', () => { const original = stubAgent(root) await agentEvents(ctx, original).waterfall( 'agent/pre-step', - { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: [] }), ) const inserted = original.inbox.nextStep[0] @@ -1361,7 +1362,7 @@ describe('workspace context request injection', () => { const claimed = resumed.inbox.claim('next-step', 1) const decision = await agentEvents(ctx, resumed).waterfall( 'agent/pre-step', - { messages: claimed, turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: claimed, turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: claimed }), ) if (decision.kind !== 'enter') throw new Error('recovered baseline was rejected') @@ -1393,7 +1394,7 @@ describe('workspace context request injection', () => { const original = stubAgent(root) await agentEvents(ctx, original).waterfall( 'agent/pre-step', - { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: [] }), ) const stale = original.inbox.nextStep[0] @@ -1407,7 +1408,7 @@ describe('workspace context request injection', () => { const staleClaim = resumed.inbox.claim('next-step', 1) const staleDecision = await agentEvents(ctx, resumed).waterfall( 'agent/pre-step', - { messages: staleClaim, turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: staleClaim, turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: staleClaim }), ) @@ -1446,7 +1447,7 @@ describe('workspace context request injection', () => { const original = stubAgent(root) await agentEvents(originalCtx, original).waterfall( 'agent/pre-step', - { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: [] }), ) const stale = original.inbox.nextStep[0] @@ -1460,7 +1461,7 @@ describe('workspace context request injection', () => { const claimed = resumed.inbox.claim('next-step', 1) const decision = await agentEvents(resumedCtx, resumed).waterfall( 'agent/pre-step', - { messages: claimed, turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: claimed, turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: claimed }), ) @@ -1564,7 +1565,7 @@ describe('workspace context request injection', () => { const decision = await agentEvents(ctx, agent).waterfall( 'agent/pre-step', - { messages: [prompt], turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: [prompt], turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve(downstream), ) @@ -1621,7 +1622,7 @@ describe('workspace context request injection', () => { const decision = await agentEvents(ctx, agent).waterfall( 'agent/pre-step', - { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve(downstream), ) @@ -1732,7 +1733,7 @@ describe('workspace context request injection', () => { const decision = await agentEvents(ctx, agent).waterfall( 'agent/pre-step', - { messages: [prompt], turn: 2, step: 1, signal: AbortSignal.timeout(1000) }, + { messages: [prompt], turn: 2, step: 1, signal: AbortSignal.timeout(requestTimeoutMs) }, () => Promise.resolve({ kind: 'enter' as const, messages: [prompt] }), ) diff --git a/scripts/install-lefthook.spec.ts b/scripts/install-lefthook.spec.ts index f0c76ead6f..c7a24488f8 100644 --- a/scripts/install-lefthook.spec.ts +++ b/scripts/install-lefthook.spec.ts @@ -25,7 +25,7 @@ const tsxPackageDirectory = dirname(fileURLToPath(import.meta.resolve('tsx/packa const fixtures: string[] = [] // Multi-worktree cases spawn several Git and Node subprocesses; native Windows // coverage concurrency can delay them without changing installer behavior. -const MULTI_PROCESS_TEST_TIMEOUT_MS = 30_000 +const MULTI_PROCESS_TEST_TIMEOUT_MS = process.platform === 'win32' ? 90_000 : 30_000 interface Fixture { container: string From 6f446e196b578f0ac5437a61ff12fdea08f1f80c Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 22:29:06 +0800 Subject: [PATCH 15/63] ci: retrigger pull request workflows From 61f65ffd48d42f14c32d6ceef3b837d86c1332f4 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Thu, 27 Aug 2026 23:27:14 +0800 Subject: [PATCH 16/63] test: allow Windows title diagnostic latency --- .../test-support/session-snapshot/tests/harness.spec.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/packages/test-support/session-snapshot/tests/harness.spec.ts b/packages/test-support/session-snapshot/tests/harness.spec.ts index 647c67d662..4c88111de5 100644 --- a/packages/test-support/session-snapshot/tests/harness.spec.ts +++ b/packages/test-support/session-snapshot/tests/harness.spec.ts @@ -66,6 +66,8 @@ async function scenario(behavior: object): Promise<{ dir: string; fixtureFile: s } const boot: InputStep[] = [{ op: 'initialize' }, { op: 'newSession' }] +// A Windows coverage shard can spend more than 20ms harvesting logs before vi.waitFor records the diagnostic error. +const titleDiagnosticTimeoutMs = process.platform === 'win32' ? 5_000 : 20 it('keeps scenario-owned snapshot spill root length stable across platforms', () => { const fixtureFile = '/fixtures/scenario/session.jsonl' @@ -1057,11 +1059,11 @@ describe('runScenario', () => { steps: [ ...boot, { op: 'promptAndCancel', text: 'hang' }, - { op: 'waitForTitleAfterTurnEnd', timeoutMs: 20 }, + { op: 'waitForTitleAfterTurnEnd', timeoutMs: titleDiagnosticTimeoutMs }, ], }, { agent: AGENT, mode: 'replay', fixtureFile }, - )).rejects.toThrow(/did not persist session\/title after turn\/end within 20ms/) + )).rejects.toThrow(new RegExp(`did not persist session/title after turn/end within ${titleDiagnosticTimeoutMs}ms`)) }) it('waitForEventAfterTurnEnd holds the app for a typed post-boundary record and times out otherwise', { timeout: 20_000 }, async () => { From 7222e17dc03daf46b58eedbbdeace107a258ff0b Mon Sep 17 00:00:00 2001 From: creatixchu Date: Fri, 28 Aug 2026 15:02:04 +0800 Subject: [PATCH 17/63] fix(tool-fs): accept extension-less attachment paths in read_image --- ...e-extensionless-attachment-paths.i18n.yaml | 6 + ...ad-image-extensionless-attachment-paths.md | 27 +++ ...image-extensionless-attachment-paths.zh.md | 27 +++ docs/subsystems/attachment.i18n.yaml | 4 +- docs/subsystems/attachment.md | 2 +- docs/subsystems/attachment.zh.md | 2 +- docs/tool-catalog.i18n.yaml | 4 +- docs/tool-catalog.md | 2 +- docs/tool-catalog.zh.md | 2 +- .../attachment-local/tests/store.spec.ts | 22 ++ .../attachment/attachment/README.i18n.yaml | 4 +- packages/attachment/attachment/README.md | 3 +- packages/attachment/attachment/README.zh.md | 3 +- packages/attachment/attachment/src/index.ts | 1 + packages/attachment/attachment/src/sniff.ts | 39 ++++ .../attachment/attachment/tests/sniff.spec.ts | Bin 0 -> 1464 bytes packages/fs/tool-fs/README.i18n.yaml | 4 +- packages/fs/tool-fs/README.md | 6 +- packages/fs/tool-fs/README.zh.md | 6 +- packages/fs/tool-fs/src/read-image.ts | 52 +++-- packages/fs/tool-fs/tests/read-image.spec.ts | 190 +++++++++++++++++- .../sdk/bash-tool/tool-schemas.expected.json | 2 +- .../tool-schemas.1.expected.json | 2 +- .../tool-schemas.1.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.1.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.1.expected.json | 2 +- .../tool-schemas.1.expected.json | 2 +- .../sdk/text-turn/tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 4 +- .../both-mode-turn/system-prompt.expected.md | 2 +- .../both-mode-turn/tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 4 +- .../system-prompt.expected.md | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../lsp-definition/tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../replay.override.json | 29 +++ .../session.jsonl | 48 +++++ .../snapshot.yml | 10 + .../workspace/red.png | Bin 0 -> 69 bytes .../ptc-read-image/system-prompt.expected.md | 2 +- .../ptc-turn/system-prompt.expected.md | 2 +- .../tool-schemas.expected.json | 2 +- .../ralph-loop/tool-schemas.1.expected.json | 2 +- .../ralph-loop/tool-schemas.2.expected.json | 2 +- .../replay.override.json | 29 +++ .../read-image-attachment-path/session.jsonl | 38 ++++ .../read-image-attachment-path/snapshot.yml | 9 + .../workspace/red.png | Bin 0 -> 69 bytes .../tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../text-turn/tool-schemas.expected.json | 2 +- .../web-fetch/tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../tool-schemas.expected.json | 2 +- .../web/ptc-round/system-prompt.expected.md | 2 +- 62 files changed, 568 insertions(+), 71 deletions(-) create mode 100644 .agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml create mode 100644 .agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md create mode 100644 .agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md create mode 100644 packages/attachment/attachment/src/sniff.ts create mode 100644 packages/attachment/attachment/tests/sniff.spec.ts create mode 100644 snapshots/session/ptc-read-image-attachment-path/replay.override.json create mode 100644 snapshots/session/ptc-read-image-attachment-path/session.jsonl create mode 100644 snapshots/session/ptc-read-image-attachment-path/snapshot.yml create mode 100644 snapshots/session/ptc-read-image-attachment-path/workspace/red.png create mode 100644 snapshots/session/read-image-attachment-path/replay.override.json create mode 100644 snapshots/session/read-image-attachment-path/session.jsonl create mode 100644 snapshots/session/read-image-attachment-path/snapshot.yml create mode 100644 snapshots/session/read-image-attachment-path/workspace/red.png diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml new file mode 100644 index 0000000000..02d0e3310e --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.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-28-read-image-extensionless-attachment-paths.md +2026-08-28-read-image-extensionless-attachment-paths.md: be6acb2ca336a976bcbf0c50efda0b933fb06df6 +2026-08-28-read-image-extensionless-attachment-paths.zh.md: a4e1e677a46dd72661944e09101994358c829877 diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md new file mode 100644 index 0000000000..be6acb2ca3 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md @@ -0,0 +1,27 @@ +# Agent Note: read_image accepts extension-less attachment object paths + +Status: implemented + +English | [中文](2026-08-28-read-image-extensionless-attachment-paths.zh.md) + +## Problem + +Model-visible image descriptors name the normalized attachment's local read-only path, and normalized objects are content-addressed files without an image extension. `read_image` mapped `file_path` to a media type by extension alone and refused everything else, so passing the descriptor's own path back produced `read_image only accepts PNG/JPEG/WebP/GIF paths` for an image the store had already validated and persisted. The model's only workarounds were copying the object to a renamed file or re-uploading it. + +## Decision + +The extension stays the declared media type when it names one of the four supported formats, and every existing gate and diagnostic on that branch is unchanged. A path without an extension is no longer refused up front: the tool reads the bytes under the existing byte cap and identifies the container with `sniffImageMediaType`, a pure file-signature helper exported by the attachment Service Definition package. The sniffed type then passes through the same deployment media-type policy and `saveImage` admission, so the store's full decode remains the authority; a path whose extension names a non-image format is still refused before any I/O. + +Reading an object path re-saves its bytes rather than short-circuiting through a reverse path lookup. Normalization passes an already-normalized image through byte-identically, so the re-save deduplicates to the same content-addressed reference; a store test pins that idempotency for a re-encoded object. No reference proof is required at the tool: object paths are unguessable content digests, the published objects are already readable through the mounted filesystem (Bash included), and the session-reference gate continues to protect the remote client RPC, which is the boundary where an attachment id alone grants bytes. + +Two diagnostics are sharpened alongside: `INVALID_IMAGE` admission failures now name the offending path instead of surfacing the store's bare message, and an extension-less admission mismatch blames the file signature rather than a nonexistent extension. + +## Consequences + +The model reads a descriptor's normalized attachment path directly, in native and PTC modes, without copying, renaming, or re-uploading; recorded scenarios `read-image-attachment-path` and `ptc-read-image-attachment-path` pin both flows end to end, including deduplication to the stored reference. Ordinary extension-less image files become readable through the same content identification, while a wrong-extension path keeps its fast pre-I/O refusal and repair message. Any future consumer accepting extension-less image paths can reuse `sniffImageMediaType` instead of a second signature table. + +## Alternatives considered + +**Name objects with an extension on disk.** This changes the storage layout, dedup commit path, corrupt checks, export archive, and every committed object-path expectation, only to satisfy the tool's extension heuristic, and the heuristic itself — extension as media-type authority — stays wrong. The store already treats decoded content as the authority. + +**Instruct the model to copy the object before reading.** Prompt guidance does not stop direct calls, so the misleading refusal survives; the copy adds a filesystem write and a turn for a pure read; and the re-read commits the identical bytes to the same reference anyway, so the copy changes nothing but cost. diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md new file mode 100644 index 0000000000..a4e1e677a4 --- /dev/null +++ b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md @@ -0,0 +1,27 @@ +# Agent Note: read_image 接受无扩展名的附件对象路径 + +Status: implemented + +[English](2026-08-28-read-image-extensionless-attachment-paths.md) | 中文 + +## 问题 + +模型可见的图片描述会给出规范化附件的本地只读路径，而规范化对象是不带图片扩展名的内容寻址文件。`read_image` 仅凭扩展名把 `file_path` 映射到媒体类型并拒绝其余一切，于是把描述里的路径原样传回会得到 `read_image only accepts PNG/JPEG/WebP/GIF paths`，尽管该图片已经通过存储校验并持久保存。模型只能把对象复制成改名文件或要求重新上传。 + +## 决定 + +扩展名命名四种受支持格式之一时仍作为声明的媒体类型，该分支的所有既有检查和诊断保持不变。无扩展名的路径不再被提前拒绝：工具在既有字节上限内读取字节，用 `sniffImageMediaType` 识别容器格式，这是附件 Service Definition 包导出的纯文件签名辅助函数。识别出的类型随后经过同一套部署媒体类型政策和 `saveImage` 准入，存储实现的完整解码仍是权威；扩展名声明了非图片格式的路径依旧在任何 I/O 之前被拒绝。 + +读取对象路径会重新保存其字节，而不是通过反向路径查找走捷径。归一化让已归一化的图片字节原样通过，因此重新保存会去重到同一个内容寻址引用；一个存储测试固定了重编码对象的这一幂等性。工具处不需要会话引用证明：对象路径是不可猜测的内容摘要，已发布对象本来就能通过挂载的文件系统（包括 Bash）读到，而会话引用检查继续保护远程客户端 RPC，那才是仅凭附件 id 就能获得字节的边界。 + +顺带收紧了两处诊断：`INVALID_IMAGE` 准入失败现在会指出出错的路径而不是透传存储的裸消息，无扩展名路径的准入不匹配归因于文件签名而不是不存在的扩展名。 + +## 影响 + +模型在 native 和 PTC 两种模式下都可以直接读取描述中的规范化附件路径，无需复制、改名或重新上传；录制场景 `read-image-attachment-path` 和 `ptc-read-image-attachment-path` 端到端固定了这两条流程，包括去重到已存储引用。普通的无扩展名图片文件也通过同一套内容识别变得可读，而扩展名错误的路径保留 I/O 之前的快速拒绝和修复消息。将来任何接受无扩展名图片路径的消费方都可以复用 `sniffImageMediaType`，不必再维护一张签名表。 + +## 考虑过的替代方案 + +**在磁盘上给对象命名加扩展名。** 这会改动存储布局、去重提交路径、损坏检查、导出归档以及每一处已提交的对象路径期望，只为迁就工具的扩展名启发式，而启发式本身（以扩展名为媒体类型权威）依然是错的。存储实现一直以解码内容为权威。 + +**指示模型先复制对象再读取。** 提示词挡不住直接调用，误导性的拒绝依然存在；复制为一次纯读取平添一次文件系统写入和一轮往返；重新读取本来就会把相同字节提交到同一引用，复制除了成本什么也不改变。 diff --git a/docs/subsystems/attachment.i18n.yaml b/docs/subsystems/attachment.i18n.yaml index 8e69eaae28..9f3d160b0a 100644 --- a/docs/subsystems/attachment.i18n.yaml +++ b/docs/subsystems/attachment.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/attachment.md -attachment.md: 15daa2b8d541ba847d48f5c43a06c1c537df6d11 -attachment.zh.md: c74a18f6bec63e117afcdb141512be04f8d75f9a +attachment.md: e93e6782eae97811be2060807a867d3036931a8c +attachment.zh.md: a0167cec6d1ddd8a06bdd7501edcb3d1c6ababe5 diff --git a/docs/subsystems/attachment.md b/docs/subsystems/attachment.md index 15daa2b8d5..e93e6782ea 100644 --- a/docs/subsystems/attachment.md +++ b/docs/subsystems/attachment.md @@ -10,7 +10,7 @@ Source: [`packages/attachment/attachment/src/types.ts`](../../packages/attachmen ## Identity and verified metadata -`AttachmentId` is a branded opaque string. The local backend currently emits `sha256:`, but consumers must neither parse that representation nor derive a filesystem path from it. A consumer may ask the attachment provider for its object location through `imageHostPath()`, then must use the current execution filesystem to decide whether model tools can read that host path. +`AttachmentId` is a branded opaque string. The local backend currently emits `sha256:`, but consumers must neither parse that representation nor derive a filesystem path from it. A consumer may ask the attachment provider for its object location through `imageHostPath()`, then must use the current execution filesystem to decide whether model tools can read that host path. The model may pass such a path back to `read_image` directly: extension-less files are identified from their file signature, and re-saving a normalized object deduplicates to the same content-addressed reference. ```ts type-equiv /** Raster image formats accepted by the version-one attachment path. */ diff --git a/docs/subsystems/attachment.zh.md b/docs/subsystems/attachment.zh.md index c74a18f6be..a0167cec6d 100644 --- a/docs/subsystems/attachment.zh.md +++ b/docs/subsystems/attachment.zh.md @@ -10,7 +10,7 @@ ## 标识与经过校验的元数据 -`AttachmentId` 是带类型标记的不透明字符串。本地后端目前生成 `sha256:`，但消费方既不能解析这种表示，也不能据此派生文件系统路径。消费方可以通过 `imageHostPath()` 询问附件提供方所持对象的位置，然后必须由当前执行文件系统判断模型工具能否读取该宿主路径。 +`AttachmentId` 是带类型标记的不透明字符串。本地后端目前生成 `sha256:`，但消费方既不能解析这种表示，也不能据此派生文件系统路径。消费方可以通过 `imageHostPath()` 询问附件提供方所持对象的位置，然后必须由当前执行文件系统判断模型工具能否读取该宿主路径。模型可以把这样的路径直接传回 `read_image`：无扩展名文件按文件签名识别格式，重新保存规范化对象会去重到同一个内容寻址引用。 ```ts type-equiv /** Raster image formats accepted by the version-one attachment path. */ diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml index 392f448802..26a87fcd9d 100644 --- a/docs/tool-catalog.i18n.yaml +++ b/docs/tool-catalog.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/tool-catalog.md -tool-catalog.md: 91ff093e79cc05a2c08b5aa1130378440cd963f3 -tool-catalog.zh.md: 35daf5a7c6b1c27975721c0b9d8ddfe71eaeb803 +tool-catalog.md: f69f6e3650dccc06a5cbe243c26f0411befdc9e2 +tool-catalog.zh.md: 5ac0948c3beb50b9c361ca575029a9a2763716fa diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 91ff093e79..f69f6e3650 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -731,7 +731,7 @@ Source: [`packages/fs/tool-fs/src/index.ts`](../packages/fs/tool-fs/src/index.ts ### `read_image` -Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. +Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. ```json { diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md index 35daf5a7c6..5ac0948c3b 100644 --- a/docs/tool-catalog.zh.md +++ b/docs/tool-catalog.zh.md @@ -737,7 +737,7 @@ pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费 ### `read_image` -读取 PNG/JPEG/WebP/GIF 文件并返回图像本身。Harness 会在下一次模型请求前校验并缩小受支持的大图，因此仅为查看图片时应直接使用此工具，无需安装图片库或创建缩略图。可以用小批次并发读取彼此独立的文件。要求当前模型接受图像输入。 +读取 PNG/JPEG/WebP/GIF 文件并返回图像本身。无扩展名的路径同样被接受；格式按文件内容检测，因此规范化附件路径可以直接传入，无需复制或重命名。Harness 会在下一次模型请求前校验并缩小受支持的大图，因此仅为查看图片时应直接使用此工具，无需安装图片库或创建缩略图。可以用小批次并发读取彼此独立的文件。要求当前模型接受图像输入。 ```json { diff --git a/packages/attachment/attachment-local/tests/store.spec.ts b/packages/attachment/attachment-local/tests/store.spec.ts index 3ff58eb2da..e1c5a788d6 100644 --- a/packages/attachment/attachment-local/tests/store.spec.ts +++ b/packages/attachment/attachment-local/tests/store.spec.ts @@ -172,6 +172,28 @@ describe('local attachment store', () => { expect(String(saved.attachmentId)).toBe(`sha256:${createHash('sha256').update(read.data).digest('hex')}`) }) + it('re-saves a re-encoded normalized object byte-identically to the same reference', async () => { + const storageRoot = await root() + const oversized = new Uint8Array(await sharp({ + create: { width: 4, height: 4, channels: 3, background: { r: 9, g: 9, b: 9 } }, + }).png().toBuffer()) + const policy = { maxPixels: POLICY.maxPixels, maxDimension: 2, maxBytes: 1024 * 1024 } + const saved = await saveImageFile(storageRoot, { + data: oversized, mediaType: 'image/png', name: 'big.png', + }, { ...LIMITS, maxImagePixels: 64 }, policy) + + // Normalization passes an already-normalized object through unchanged, so + // reading the object file and saving those bytes again deduplicates: the + // read_image tool can accept object paths without minting new attachments. + const objectBytes = (await readImageFile(storageRoot, saved)).data + const resaved = await saveImageFile(storageRoot, { + data: objectBytes, mediaType: saved.mediaType, name: 'big', + }, { ...LIMITS, maxImagePixels: 64 }, policy) + expect(resaved.attachmentId).toBe(saved.attachmentId) + expect(resaved.bytes).toBe(saved.bytes) + expect(resaved.originalDimensions).toBeUndefined() + }) + it('keeps admitted history readable after deployment limits become stricter', async () => { const storageRoot = await root() const ref = await saveImageFile(storageRoot, { data: PNG, mediaType: 'image/png' }, LIMITS, POLICY) diff --git a/packages/attachment/attachment/README.i18n.yaml b/packages/attachment/attachment/README.i18n.yaml index e67d95604d..aac868951f 100644 --- a/packages/attachment/attachment/README.i18n.yaml +++ b/packages/attachment/attachment/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/attachment/attachment/README.md -README.md: 01a5d6ee143ff53175dd7327cd6d419af61938a3 -README.zh.md: 1a1d297297a6815ce5338391af0182e471f99000 +README.md: feb8b14a2a46543169820e444994ef7cb1514210 +README.zh.md: 0f088e170cde9fb27032351dc1f9861c9111b6fd diff --git a/packages/attachment/attachment/README.md b/packages/attachment/attachment/README.md index 01a5d6ee14..feb8b14a2a 100644 --- a/packages/attachment/attachment/README.md +++ b/packages/attachment/attachment/README.md @@ -67,7 +67,7 @@ This section explains the design decisions behind the seam and the service opera ### Service operations -The service family runs one admission-and-storage flow: every entry point enforces source batch limits and canonical base64, prepares provider-independent normalized attachments before publishing any member, and commits them durably in input order without partial results. `readImageRequest` derives deterministic route-sized variants whose identity includes the attachment id, transform version, pixel and byte budgets, and encoder settings. The pure `requestImageDimensions` export computes each projection's aspect-preserving dimensions from a total-pixel budget, so providers and request pricing share one geometry. `imageHostPath` exposes an implementation-owned host location only to trusted same-process consumers that need execution-world mapping. Callers compose ordered batches while the implementation owns compression concurrency, caching, and singleflight. Reads and projections preserve caller cancellation. Failures carry stable machine-readable codes, and the caller-correctable admission subset is recognizable at runtime so each protocol adapter maps its own vocabulary; the exact per-operation contracts live in [`src/index.ts`](src/index.ts) and [`src/error.ts`](src/error.ts). +The service family runs one admission-and-storage flow: every entry point enforces source batch limits and canonical base64, prepares provider-independent normalized attachments before publishing any member, and commits them durably in input order without partial results. `readImageRequest` derives deterministic route-sized variants whose identity includes the attachment id, transform version, pixel and byte budgets, and encoder settings. The pure `requestImageDimensions` export computes each projection's aspect-preserving dimensions from a total-pixel budget, so providers and request pricing share one geometry. The pure `sniffImageMediaType` export identifies a supported container from its file signature for consumers that accept extension-less image paths; persisting callers keep the store's full decode authoritative. `imageHostPath` exposes an implementation-owned host location only to trusted same-process consumers that need execution-world mapping. Callers compose ordered batches while the implementation owns compression concurrency, caching, and singleflight. Reads and projections preserve caller cancellation. Failures carry stable machine-readable codes, and the caller-correctable admission subset is recognizable at runtime so each protocol adapter maps its own vocabulary; the exact per-operation contracts live in [`src/index.ts`](src/index.ts) and [`src/error.ts`](src/error.ts). ### Source map @@ -77,6 +77,7 @@ The service family runs one admission-and-storage flow: every entry point enforc | [`src/types.ts`](src/types.ts) | Durable vocabulary: references, limits, upload and store payloads | | [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`: canonical-base64 enforcement, then `saveImages` delegation | | [`src/error.ts`](src/error.ts) | `AttachmentError` class and the `isImageAdmissionError` runtime subset | +| [`src/sniff.ts`](src/sniff.ts) | `sniffImageMediaType`: file-signature container identification | | [`src/brand.ts`](src/brand.ts) | `AttachmentId` branded opaque identifier | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; implementations enforce immutable-store checks) | diff --git a/packages/attachment/attachment/README.zh.md b/packages/attachment/attachment/README.zh.md index 1a1d297297..0f088e170c 100644 --- a/packages/attachment/attachment/README.zh.md +++ b/packages/attachment/attachment/README.zh.md @@ -67,7 +67,7 @@ kind: "package-reference" ### 服务操作 -服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。 +服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。纯函数导出 `sniffImageMediaType` 按文件签名识别受支持的图片容器，供接受无扩展名图片路径的消费方使用；持久化调用方仍以存储实现的完整解码为权威。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。 ### 源码地图 @@ -77,6 +77,7 @@ kind: "package-reference" | [`src/types.ts`](src/types.ts) | 持久词汇：引用、限额、上传与存储载荷 | | [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`：规范 base64 强制，随后委托 `saveImages` | | [`src/error.ts`](src/error.ts) | `AttachmentError` 类与 `isImageAdmissionError` 运行时子集 | +| [`src/sniff.ts`](src/sniff.ts) | `sniffImageMediaType`：按文件签名识别图片容器 | | [`src/brand.ts`](src/brand.ts) | `AttachmentId` 带类型标记的不透明标识符 | | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；实现负责强制不可变存储检查） | diff --git a/packages/attachment/attachment/src/index.ts b/packages/attachment/attachment/src/index.ts index 4ee001b86c..89df5e52c6 100644 --- a/packages/attachment/attachment/src/index.ts +++ b/packages/attachment/attachment/src/index.ts @@ -16,6 +16,7 @@ export { AttachmentError, isImageAdmissionError } from './error.ts' export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts' export { admitEncodedImages } from './admission.ts' export { requestImageDimensions } from './request-projection.ts' +export { sniffImageMediaType } from './sniff.ts' export type { AttachmentId as AttachmentIdType, EncodedImageAttachment, diff --git a/packages/attachment/attachment/src/sniff.ts b/packages/attachment/attachment/src/sniff.ts new file mode 100644 index 0000000000..9782d2ffda --- /dev/null +++ b/packages/attachment/attachment/src/sniff.ts @@ -0,0 +1,39 @@ +/** + * Leading-byte image-format identification for consumers that accept image + * files without a media-type-bearing file name, such as normalized attachment + * object paths. The result names the container the signature claims; callers + * that persist bytes keep the attachment service's full decode authoritative. + * @module @deepseek-ai/dsh-attachment/src/sniff + */ + +import type { ImageMediaType } from './types.ts' + +const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const +const JPEG_SIGNATURE = [0xff, 0xd8, 0xff] as const + +function matchesBytes(data: Uint8Array, offset: number, expected: readonly number[]): boolean { + if (data.byteLength < offset + expected.length) return false + return expected.every((byte, index) => data[offset + index] === byte) +} + +function matchesAscii(data: Uint8Array, offset: number, text: string): boolean { + if (data.byteLength < offset + text.length) return false + for (let index = 0; index < text.length; index += 1) { + if (data[offset + index] !== text.charCodeAt(index)) return false + } + return true +} + +/** + * Identify a supported image container from its file signature. + * @param data - the leading file bytes; passing the complete file is fine. + * @returns the media type the signature claims, or undefined when the bytes + * carry no complete PNG/JPEG/WebP/GIF signature. + */ +export function sniffImageMediaType(data: Uint8Array): ImageMediaType | undefined { + if (matchesBytes(data, 0, PNG_SIGNATURE)) return 'image/png' + if (matchesBytes(data, 0, JPEG_SIGNATURE)) return 'image/jpeg' + if (matchesAscii(data, 0, 'GIF87a') || matchesAscii(data, 0, 'GIF89a')) return 'image/gif' + if (matchesAscii(data, 0, 'RIFF') && matchesAscii(data, 8, 'WEBP')) return 'image/webp' + return undefined +} diff --git a/packages/attachment/attachment/tests/sniff.spec.ts b/packages/attachment/attachment/tests/sniff.spec.ts new file mode 100644 index 0000000000000000000000000000000000000000..e081abd9697521297206244cbb4369d7d0dd600c GIT binary patch literal 1464 zcmbtTU2EGg6y39b#eK6JT-k$-I)x2dNJbt8Ve7}k*n@0cIU2QWB)Lr}`R|kLINsWn ze#DrA9n6_zZZIMG!E6b!p9fLxq zPbz5)n1R8>z!V3wa>J0fLZCJjCP@&;$`il?a5ROMImUqN1`8X5w6F!C>k7g})2s5xp9QS46L*HN$yf^vd|E+*qT)SE|srR!`OL%RN)di>-Zc6jPBZe|zD>tzN{B;8})begtN;N0^;=<{WuRUCzD4Db3>+ZAfaH!kNf zSnUGKe61cgNY(1(2JdW;AeJiHpzkQe{*&cWu^^&Nbd_FKP!WR&ns lO7{soj&#W1d+5ffOjGurC3gh-l$>ABj;DEs!3E5{e*r&i-dX?v literal 0 HcmV?d00001 diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index cd2106cbbc..8913a24022 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md -README.md: 193f842aa76b7d3f4df717d1d23960ef4d3ee329 -README.zh.md: 3cbd6bec6d9a4b200d90c15b32291cacc2e41aa8 +README.md: c4c8f9270a7b9422d52e6f89567c0d7eeab1f5c6 +README.zh.md: 8bd62f68010e6363515b39e7e71d6361f746713b diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 193f842aa7..c4c8f9270a 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -44,7 +44,7 @@ The policy plugin is optional: without it the tools run against the bare provide | Tool | Arguments | Behavior | |---|---|---| | `read` | `file_path`, `offset?`, `limit?` | Line-numbered UTF-8 content with a pagination footer; `offset` is 1-based and `limit` defaults to and caps at the configured `readLimit` | -| `read_image` | `file_path` | Reads and persists a PNG/JPEG/WebP/GIF source; normalization can downscale it before the next model request, so the model need not create a thumbnail first | +| `read_image` | `file_path` | Reads and persists a PNG/JPEG/WebP/GIF source; an extension-less path (normalized attachment object paths included) is identified from its file signature; normalization can downscale it before the next model request, so the model need not create a thumbnail first | | `write` | `file_path`, `content` | Creates or fully replaces a file; with the policy plugin, overwriting requires a prior `read` at the unchanged version, creating does not | | `edit` | `file_path`, `old_string`, `new_string`, `replace_all?` | Literal replacement requiring a unique match unless `replace_all` is true; with the policy plugin, requires a prior `read` and an unchanged file | @@ -219,7 +219,7 @@ Append-only; newly visible content follows the reusable request prefix and does #### What the model sees -Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, `offset is out of range for "" ( lines)`, `cannot read "": read_image only accepts PNG/JPEG/WebP/GIF paths`, `cannot read "" as an image: model "" does not declare image input; switch to an image-capable model to read images`, and the mismatch repair `cannot read "": the extension declares , but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`. A failed 16-bit conversion reports `cannot read "": the 16-bit PNG could not be converted to the normalized 8-bit sRGB form; convert it to an 8-bit PNG/JPEG/WebP and retry`. Provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` gets `— re-read the file, then retry`, and `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved. After that reread confirms absence, `edit` reports `FS_NOT_FOUND` instead of repeating a stale remedy, while `write` uses guarded creation. +Failures are normalized as `Error: `. This package's stable validation and read messages are `file_path must be a non-empty string`, `limit must be less than or equal to `, `old_string must be a non-empty string`, `old_string and new_string must differ`, `cannot read "": not found`, `cannot read "": not a regular file`, `offset is out of range for "" ( lines)`, `cannot read "": the extension does not declare a supported image format; read_image accepts PNG/JPEG/WebP/GIF files, including extension-less files in those formats`, `cannot read "": the file content is not a supported image format; read_image accepts PNG/JPEG/WebP/GIF`, `cannot read "": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image; the file may be truncated or corrupt`, `cannot read "" as an image: model "" does not declare image input; switch to an image-capable model to read images`, and the mismatch repair `cannot read "": the extension declares , but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats` (an extension-less mismatch reports `cannot read "": the file signature claims , but the bytes decode as a different image format; the file may be corrupt`). A failed 16-bit conversion reports `cannot read "": the 16-bit PNG could not be converted to the normalized 8-bit sRGB form; convert it to an 8-bit PNG/JPEG/WebP and retry`. Provider and policy templates are quoted in their package READMEs. Guarded-mutation failures additionally carry their recovery instruction in the message, appended by this package's model-facing error wrapper: `FS_STALE_VERSION` gets `— re-read the file, then retry`, and `FS_NOT_OBSERVED` gets `— read the file, then retry`; the structured code is preserved. After that reread confirms absence, `edit` reports `FS_NOT_FOUND` instead of repeating a stale remedy, while `write` uses guarded creation. #### Token effect @@ -237,7 +237,7 @@ Append-only; newly visible content follows the reusable request prefix and does These limits define when the tool suite is a poor fit or needs special operational care. They are current package constraints, not a general filesystem comparison or a task backlog. - **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling `dsh-tool-fs-search` package supplies ripgrep-backed `glob` and `grep` rather than extending the filesystem seam. -- **`read` handles UTF-8 text files only** — images use the separate extension-routed `read_image` tool; PDF, audio, and video remain deferred. A directory target is `FS_NOT_REGULAR_FILE`. +- **`read` handles UTF-8 text files only** — images use the separate `read_image` tool; PDF, audio, and video remain deferred. A directory target is `FS_NOT_REGULAR_FILE`. - **Extension-declared media type** — the extension selects the declared type and the attachment store's magic-byte validation stays authoritative; a correctly formatted image under a wrong extension is refused with the rename remedy rather than sniffed. - **No inline image preview on the tool-result card** — UI surfaces render the image result generically (the durable reference, not pixels); inline rendering is deferred to the UI packages. - **No attachment-region tool** — an agent may crop an image through another available tool when it has a filesystem path; a pasted or dragged image without a path cannot be re-read at higher resolution. diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index 3cbd6bec6d..8bd62f6801 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -44,7 +44,7 @@ kind: "package-reference" | 工具 | 参数 | 行为 | |---|---|---| | `read` | `file_path`、`offset?`、`limit?` | 带行号的 UTF-8 内容与分页 footer；`offset` 从 1 开始，`limit` 默认为配置的 `readLimit`，上限也为该值 | -| `read_image` | `file_path` | 读取并持久保存 PNG/JPEG/WebP/GIF 源图；规范化可在下一次模型请求前缩小图片，因此模型无需先创建缩略图 | +| `read_image` | `file_path` | 读取并持久保存 PNG/JPEG/WebP/GIF 源图；无扩展名路径（包括规范化附件对象路径）按文件签名识别格式；规范化可在下一次模型请求前缩小图片，因此模型无需先创建缩略图 | | `write` | `file_path`、`content` | 创建或完整替换文件；有策略插件时，覆盖要求先在未变版本上执行 `read`，创建不需要 | | `edit` | `file_path`、`old_string`、`new_string`、`replace_all?` | 字面量替换，除非 `replace_all` 为 true 否则要求唯一匹配；有策略插件时，要求先执行 `read` 且文件未变 | @@ -219,7 +219,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces #### 模型看到的内容 -失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file`、`offset is out of range for "" ( lines)`、`cannot read "": read_image only accepts PNG/JPEG/WebP/GIF paths`、`cannot read "" as an image: model "" does not declare image input; switch to an image-capable model to read images`，以及类型不匹配的修复消息 `cannot read "": the extension declares , but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`。16-bit 转换失败会报告 `cannot read "": the 16-bit PNG could not be converted to the normalized 8-bit sRGB form; convert it to an 8-bit PNG/JPEG/WebP and retry`。提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION` 追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。该次重新读取确认缺失后，`edit` 会报告 `FS_NOT_FOUND`，而不会重复陈旧恢复指令；`write` 则使用带防护的创建。 +失败会规范化为 `Error: `。本包稳定的校验和读取消息是 `file_path must be a non-empty string`、`limit must be less than or equal to `、`old_string must be a non-empty string`、`old_string and new_string must differ`、`cannot read "": not found`、`cannot read "": not a regular file`、`offset is out of range for "" ( lines)`、`cannot read "": the extension does not declare a supported image format; read_image accepts PNG/JPEG/WebP/GIF files, including extension-less files in those formats`、`cannot read "": the file content is not a supported image format; read_image accepts PNG/JPEG/WebP/GIF`、`cannot read "": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image; the file may be truncated or corrupt`、`cannot read "" as an image: model "" does not declare image input; switch to an image-capable model to read images`，以及类型不匹配的修复消息 `cannot read "": the extension declares , but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`（无扩展名路径的不匹配报告 `cannot read "": the file signature claims , but the bytes decode as a different image format; the file may be corrupt`）。16-bit 转换失败会报告 `cannot read "": the 16-bit PNG could not be converted to the normalized 8-bit sRGB form; convert it to an 8-bit PNG/JPEG/WebP and retry`。提供方和策略模板在各自包的 README 中逐字列出。防护变更失败还会在消息中携带恢复指令，由本包面向模型的错误包装追加：`FS_STALE_VERSION` 追加 `— re-read the file, then retry`，`FS_NOT_OBSERVED` 追加 `— read the file, then retry`；结构化错误码保持不变。该次重新读取确认缺失后，`edit` 会报告 `FS_NOT_FOUND`，而不会重复陈旧恢复指令；`write` 则使用带防护的创建。 #### Token 影响 @@ -237,7 +237,7 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces 这些限制说明工具套件何时不合适，或何时需要特别的运维注意。它们是当前包约束，不是通用文件系统对比或任务积压。 - **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 `dsh-tool-fs-search` 包则提供基于 ripgrep 的 `glob` 与 `grep`，而不是扩展文件系统 seam。 -- **`read` 只处理 UTF-8 文本文件**：图像使用独立的、按扩展名路由的 `read_image` 工具；PDF、音频和视频仍延期处理。目录目标为 `FS_NOT_REGULAR_FILE`。 +- **`read` 只处理 UTF-8 文本文件**：图像使用独立的 `read_image` 工具；PDF、音频和视频仍延期处理。目录目标为 `FS_NOT_REGULAR_FILE`。 - **媒体类型按扩展名声明**：扩展名选择声明类型，附件存储的魔数校验保持权威；扩展名错误但格式正确的图像会得到改名修复提示，而不是被嗅探接受。 - **工具结果卡片没有内嵌图像预览**：UI 表面以通用形式渲染图像结果（持久引用而非像素）；内嵌渲染延后到 UI 包处理。 - **没有附件区域工具**：agent 在拥有文件系统路径时可以通过其他可用工具裁剪图片；没有路径的粘贴或拖入图片无法按更高分辨率重新读取。 diff --git a/packages/fs/tool-fs/src/read-image.ts b/packages/fs/tool-fs/src/read-image.ts index b1cbad9bb9..5941d85777 100644 --- a/packages/fs/tool-fs/src/read-image.ts +++ b/packages/fs/tool-fs/src/read-image.ts @@ -1,5 +1,8 @@ /** - * The model-facing `read_image` tool commits a PNG/JPEG/WebP/GIF file. + * The model-facing `read_image` tool commits a PNG/JPEG/WebP/GIF file. A path + * without a file extension — normalized attachment objects are named by their + * content digest alone — is accepted too: its format comes from the file + * signature, and the attachment service's full decode stays authoritative. * * The route gate is deliberately stricter than the host upload preflight. An * image-reading tool is useful only when the exact calling route can inspect @@ -10,8 +13,8 @@ import { basename, extname } from 'node:path' import type { Context } from '@deepseek-ai/cordis' -import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment' -import type { ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment' +import { AttachmentError, AttachmentId, sniffImageMediaType } from '@deepseek-ai/dsh-attachment' +import type { AttachmentStore, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import { defineTool } from '@deepseek-ai/dsh-tools' import type { GenericCallView, ToolExecution } from '@deepseek-ai/dsh-tools' @@ -98,6 +101,13 @@ export async function assertImageCapableRoute(ctx: Context, exec: ToolExecution, } } +/** Refuse a media type outside the deployment's accepted set, naming the offending path. */ +function assertDeploymentAccepts(attachments: AttachmentStore, mediaType: ImageMediaType, displayPath: string): void { + if (!attachments.imageLimits.mediaTypes.includes(mediaType)) { + throw new Error(`cannot read "${displayPath}": ${mediaType} images are not accepted by this deployment`) + } +} + /** * Re-brand a structured image outcome into the durable attachment reference an * `ImageBlock` carries. @@ -170,6 +180,7 @@ export function applyReadImageTool(ctx: Context): void { ctx.tools.register(defineTool({ name: 'read_image', description: 'Read a PNG/JPEG/WebP/GIF file and return the image itself. ' + + 'A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. ' + 'Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. ' + 'Independent files may be read concurrently in small batches. Requires the current model to accept image input.', parameters: { @@ -192,19 +203,20 @@ export function applyReadImageTool(ctx: Context): void { async execute(args, exec) { if (args.file_path.trim().length === 0) throw new Error('file_path must be a non-empty string') - // Every gate runs before any filesystem I/O so a refusal never leaks - // partial reads or attachment writes. - const mediaType = imageMediaTypeForPath(args.file_path) - if (mediaType === undefined) { - throw new Error(`cannot read "${args.file_path}": read_image only accepts PNG/JPEG/WebP/GIF paths`) + // Every pre-read gate runs before any filesystem I/O so a refusal never + // leaks partial reads or attachment writes. An extension-less path + // declares no format, so only its format and deployment media-type + // checks wait for the bytes. + const extension = extname(args.file_path).toLowerCase() + const declared = imageMediaTypeForPath(args.file_path) + if (declared === undefined && extension !== '') { + throw new Error(`cannot read "${args.file_path}": the ${extension} extension does not declare a supported image format; read_image accepts PNG/JPEG/WebP/GIF files, including extension-less files in those formats`) } const attachments = ctx.get('attachments') if (attachments === undefined) { throw new Error(`cannot read "${args.file_path}" as an image: no attachment service is mounted`) } - if (!attachments.imageLimits.mediaTypes.includes(mediaType)) { - throw new Error(`cannot read "${args.file_path}": ${mediaType} images are not accepted by this deployment`) - } + if (declared !== undefined) assertDeploymentAccepts(attachments, declared, args.file_path) await assertImageCapableRoute(ctx, exec, args.file_path) const { target, info } = await resolveRegularReadTarget(ctx, exec, args.file_path) @@ -213,6 +225,11 @@ export function applyReadImageTool(ctx: Context): void { // aggregate bound applies beside the per-image bound. const byteCap = Math.min(attachments.imageLimits.maxImageBytes, attachments.imageLimits.maxMessageImageBytes) const data = await ctx.fs.readBytes(target, exec.signal, byteCap) + const mediaType = declared ?? sniffImageMediaType(data) + if (mediaType === undefined) { + throw new Error(`cannot read "${target.displayPath}": the file content is not a supported image format; read_image accepts PNG/JPEG/WebP/GIF`) + } + if (declared === undefined) assertDeploymentAccepts(attachments, mediaType, target.displayPath) // Persist before returning: the image block must reference a durably // committed object by the time the tool/result event is appended. let ref: ImageAttachmentRef @@ -247,8 +264,19 @@ export function applyReadImageTool(ctx: Context): void { { cause: error }, ) } + if (error.code === 'INVALID_IMAGE') { + throw new Error( + `cannot read "${target.displayPath}": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image; the file may be truncated or corrupt`, + { cause: error }, + ) + } if (error.code !== 'IMAGE_TYPE_MISMATCH') throw error - const extension = extname(target.displayPath).toLowerCase() + if (declared === undefined) { + throw new Error( + `cannot read "${target.displayPath}": the file signature claims ${mediaType}, but the bytes decode as a different image format; the file may be corrupt`, + { cause: error }, + ) + } throw new Error( `cannot read "${target.displayPath}": the ${extension} extension declares ${mediaType}, but the bytes use a different image format; rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats`, { cause: error }, diff --git a/packages/fs/tool-fs/tests/read-image.spec.ts b/packages/fs/tool-fs/tests/read-image.spec.ts index 7244444245..b2aeb09256 100644 --- a/packages/fs/tool-fs/tests/read-image.spec.ts +++ b/packages/fs/tool-fs/tests/read-image.spec.ts @@ -1,8 +1,9 @@ /** * The `read_image` tool over the REAL local filesystem and attachment store: - * extension routing, the strict image-modality gate (every refusal arm), - * durable commit + image-block rendering, attachment admission failures, and - * the regression that `read` keeps its text-only contract. + * extension routing, extension-less content sniffing (attachment object paths + * included), the strict image-modality gate (every refusal arm), durable + * commit + image-block rendering, attachment admission failures, and the + * regression that `read` keeps its text-only contract. */ import { afterEach, beforeEach, describe, expect, it } from 'vitest' @@ -34,6 +35,10 @@ import { const PNG_1X1 = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC', 'base64') /** 3x3 red PNG used to trip a tiny configured pixel limit. */ const PNG_3X3 = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAEElEQVR4nGP4z8AAQQxYWACPjgj4kWPEuQAAAABJRU5ErkJggg==', 'base64') +/** 1x1 red JPEG already inside every normalization limit (byte-identical passthrough). */ +const JPEG_1X1 = Buffer.from('/9j/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAABgj/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABykX//Z', 'base64') +/** 1x1 red WebP already inside every normalization limit (byte-identical passthrough). */ +const WEBP_1X1 = Buffer.from('UklGRjwAAABXRUJQVlA4IDAAAADQAQCdASoBAAEAAUAmJaACdLoB+AADsAD+8ut//NgVzXPv9//S4P0uD9Lg/9KQAAA=', 'base64') const testToolSignal = new AbortController().signal @@ -254,6 +259,175 @@ describe('read_image happy path', () => { }) }) +/** The mounted attachment service, asserted present for direct store calls. */ +function mountedStore(ctx: Context): AttachmentStore { + const attachments = ctx.get('attachments') + if (attachments === undefined) throw new Error('expected the attachment service') + return attachments +} + +/** The host object path behind a reference, asserted present for the local store. */ +function objectPathOf(attachments: AttachmentStore, ref: ImageAttachmentRef): string { + const hostPath = attachments.imageHostPath(ref) + if (hostPath === undefined) throw new Error('expected a host-file-backed store') + return hostPath +} + +describe('extension-less paths', () => { + it('reads a normalized attachment object path directly and dedups to the stored reference', async () => { + await writeFile(join(dir, 'red.png'), PNG_1X1) + const ctx = await setup() + const first = await readImage(ctx, { file_path: 'red.png' }, agentOn('vision-model')) + expect(first.isError).toBe(false) + const ref = (first.content[1] as { attachment: ImageAttachmentRef }).attachment + const attachments = mountedStore(ctx) + const objectPath = objectPathOf(attachments, ref) + + const second = await readImage(ctx, { file_path: objectPath }, agentOn('vision-model')) + expect(second.isError).toBe(false) + const reread = (second.content[1] as { attachment: ImageAttachmentRef }).attachment + expect(reread.attachmentId).toBe(ref.attachmentId) + expect(reread.mediaType).toBe('image/png') + expect(text(second)).toContain(`${objectPath}`) + }) + + it.each([ + ['image/jpeg', JPEG_1X1], + ['image/webp', WEBP_1X1], + ] as const)('dedups a re-read %s object to its stored reference', async (mediaType, bytes) => { + const ctx = await setup() + const attachments = mountedStore(ctx) + const ref = await attachments.saveImage({ data: bytes, mediaType, name: 'source' }) + const result = await readImage(ctx, { file_path: objectPathOf(attachments, ref) }, agentOn('vision-model')) + expect(result.isError).toBe(false) + const reread = (result.content[1] as { attachment: ImageAttachmentRef }).attachment + expect(reread.attachmentId).toBe(ref.attachmentId) + expect(reread.mediaType).toBe(mediaType) + }) + + it('forwards an attachment object path read through the outer run_code context', async () => { + const ctx = await setup({ toolMode: 'ptc' }) + const attachments = mountedStore(ctx) + const ref = await attachments.saveImage({ data: PNG_1X1, mediaType: 'image/png', name: 'red.png' }) + const objectPath = objectPathOf(attachments, ref) + const runtime = ctx.codeRuntime as FakeRuntime + runtime.behavior = async (request) => { + const value = await request.bindings[0]!.functions.read_image!({ file_path: objectPath }) + return { logs: [], value } + } + + const result = await call(ctx, RUN_CODE_NAME, { + code: 'return await tools.read_image({ file_path: attachmentPath })', + description: 'Read the attachment object through PTC mode', + }, agentOn('vision-model')) + + expect(result.isError).toBe(false) + const forwarded = result.additionalContexts?.[0]?.content + expect(forwarded?.[1]).toMatchObject({ + type: 'image', + attachment: { attachmentId: ref.attachmentId, mediaType: 'image/png' }, + }) + }) + + it('reads an ordinary extension-less image file by sniffing its content', async () => { + await writeFile(join(dir, 'avatar'), PNG_1X1) + const ctx = await setup() + const result = await readImage(ctx, { file_path: 'avatar' }, agentOn('vision-model')) + expect(result.isError).toBe(false) + const image = result.content[1] as { attachment: ImageAttachmentRef } + expect(image.attachment.mediaType).toBe('image/png') + expect(image.attachment.name).toBe('avatar') + }) + + it('refuses extension-less bytes that are not a supported image', async () => { + await writeFile(join(dir, 'notes'), 'plain text, not an image') + const ctx = await setup() + const result = await readImage(ctx, { file_path: 'notes' }, agentOn('vision-model')) + expect(result.isError).toBe(true) + expect(text(result)).toContain(`cannot read "${join(dir, 'notes')}": the file content is not a supported image format`) + }) + + it('explains extension-less bytes that sniff as an image but do not decode', async () => { + await writeFile(join(dir, 'broken'), PNG_1X1.subarray(0, 16)) + const ctx = await setup() + const result = await readImage(ctx, { file_path: 'broken' }, agentOn('vision-model')) + expect(result.isError).toBe(true) + expect(text(result)).toContain('do not decode as a supported PNG/JPEG/WebP/GIF image') + }) + + it('reports a missing attachment object through the fs vocabulary', async () => { + const ctx = await setup() + const bogus = join(home, 'attachments', 'v1', 'objects', 'ab', 'ab'.repeat(32)) + const result = await readImage(ctx, { file_path: bogus }, agentOn('vision-model')) + expect(result.isError).toBe(true) + expect(text(result)).toContain('not found') + }) + + it('applies the deployment media-type policy to the sniffed format', async () => { + /** Store whose deployment accepts JPEG only; sniffed PNG bytes must refuse before any save. */ + class JpegOnlySniffStore extends AttachmentStore { + readonly imageLimits: ImageAttachmentLimits = Object.freeze({ + maxImageBytes: 1024, + maxImagesPerMessage: 1, + maxMessageImageBytes: 1024, + maxImagePixels: 100, + maxImageDimension: 2000, + mediaTypes: Object.freeze(['image/jpeg'] as const), + }) + + validateImage(_input: SaveImageAttachment): Promise { + throw new Error('unreachable: the sniffed-format policy refuses before validation') + } + + saveImage(_input: SaveImageAttachment): Promise { + throw new Error('unreachable: the sniffed-format policy refuses before save') + } + + readImage(_ref: ImageAttachmentRef): Promise { + throw new Error('unreachable in this test') + } + } + await writeFile(join(dir, 'avatar'), PNG_1X1) + const ctx = await setup({ attachments: false }) + await ctx.plugin(JpegOnlySniffStore) + const result = await readImage(ctx, { file_path: 'avatar' }, agentOn('vision-model')) + expect(result.isError).toBe(true) + expect(text(result)).toContain('image/png images are not accepted by this deployment') + }) + + it('names a signature/decoded-format disagreement on an extension-less path', async () => { + /** Store whose admission reports a media-type mismatch; the tool cannot blame an extension. */ + class MismatchStore extends AttachmentStore { + readonly imageLimits: ImageAttachmentLimits = Object.freeze({ + maxImageBytes: 1024, + maxImagesPerMessage: 1, + maxMessageImageBytes: 1024, + maxImagePixels: 100, + maxImageDimension: 2000, + mediaTypes: Object.freeze(['image/png'] as const), + }) + + validateImage(_input: SaveImageAttachment): Promise { + return Promise.resolve() + } + + saveImage(_input: SaveImageAttachment): Promise { + throw new AttachmentError('Declared image type does not match its bytes.', 'IMAGE_TYPE_MISMATCH') + } + + readImage(_ref: ImageAttachmentRef): Promise { + throw new Error('unreachable in this test') + } + } + await writeFile(join(dir, 'sniffed'), PNG_1X1) + const ctx = await setup({ attachments: false }) + await ctx.plugin(MismatchStore) + const result = await readImage(ctx, { file_path: 'sniffed' }, agentOn('vision-model')) + expect(result.isError).toBe(true) + expect(text(result)).toContain('the file signature claims image/png, but the bytes decode as a different image format') + }) +}) + describe('strict image-modality gate', () => { it('accepts an exact visual route even when the advisory model catalog omits it', async () => { await writeFile(join(dir, 'red.png'), PNG_1X1) @@ -309,7 +483,7 @@ describe('argument and service preconditions', () => { const nonImage = await readImage(ctx, { file_path: 'notes.txt' }, agentOn('vision-model')) expect(nonImage.isError).toBe(true) - expect(text(nonImage)).toContain('only accepts PNG/JPEG/WebP/GIF paths') + expect(text(nonImage)).toContain('the .txt extension does not declare a supported image format') }) it('refuses when no attachment service is mounted', async () => { @@ -373,6 +547,14 @@ describe('image admission failures', () => { expect(text(result)).toContain('rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats') }) + it('explains a named image file whose bytes do not decode', async () => { + await writeFile(join(dir, 'broken.png'), PNG_1X1.subarray(0, 16)) + const ctx = await setup() + const result = await readImage(ctx, { file_path: 'broken.png' }, agentOn('vision-model')) + expect(result.isError).toBe(true) + expect(text(result)).toContain(`cannot read "${join(dir, 'broken.png')}": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image`) + }) + it('fails with FS_TOO_LARGE before reading a file past maxImageBytes', async () => { await writeFile(join(dir, 'red.png'), PNG_1X1) const ctx = await setup({ storeConfig: { maxImageBytes: PNG_1X1.length - 1 } }) diff --git a/snapshots/sdk/bash-tool/tool-schemas.expected.json b/snapshots/sdk/bash-tool/tool-schemas.expected.json index e8fd1b5981..e8b70b6c13 100644 --- a/snapshots/sdk/bash-tool/tool-schemas.expected.json +++ b/snapshots/sdk/bash-tool/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json b/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json index a3c5b2e531..b3dee1a21b 100644 --- a/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json +++ b/snapshots/sdk/subagent-continuable-inheritance/tool-schemas.1.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json b/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json index a3c5b2e531..b3dee1a21b 100644 --- a/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json +++ b/snapshots/sdk/subagent-continuable/tool-schemas.1.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json b/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json index b3a1813e8b..a95ea12f74 100644 --- a/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json +++ b/snapshots/sdk/subagent-dsh-sdk-diagnostic/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json index fe0882fe53..5b0728889d 100644 --- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json +++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.1.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json index 3d92e885eb..3000f6cb46 100644 --- a/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json +++ b/snapshots/sdk/subagent-dsh-sdk-dynamic-route/tool-schemas.expected.json @@ -323,7 +323,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json b/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json index a3c5b2e531..b3dee1a21b 100644 --- a/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json +++ b/snapshots/sdk/subagent-list-agents/tool-schemas.1.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/subagent-report/tool-schemas.1.expected.json b/snapshots/sdk/subagent-report/tool-schemas.1.expected.json index a3c5b2e531..b3dee1a21b 100644 --- a/snapshots/sdk/subagent-report/tool-schemas.1.expected.json +++ b/snapshots/sdk/subagent-report/tool-schemas.1.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/sdk/text-turn/tool-schemas.expected.json b/snapshots/sdk/text-turn/tool-schemas.expected.json index e8fd1b5981..e8b70b6c13 100644 --- a/snapshots/sdk/text-turn/tool-schemas.expected.json +++ b/snapshots/sdk/text-turn/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/agent-instructions/tool-schemas.expected.json b/snapshots/session/agent-instructions/tool-schemas.expected.json index 36df7a0481..ebdc1383f5 100644 --- a/snapshots/session/agent-instructions/tool-schemas.expected.json +++ b/snapshots/session/agent-instructions/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { @@ -1007,7 +1007,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/both-mode-turn/system-prompt.expected.md b/snapshots/session/both-mode-turn/system-prompt.expected.md index 8511e0eff3..4ac177a40e 100644 --- a/snapshots/session/both-mode-turn/system-prompt.expected.md +++ b/snapshots/session/both-mode-turn/system-prompt.expected.md @@ -154,7 +154,7 @@ interface ToolArgsMap { /** Maximum number of lines to return. Defaults to 2000. */ limit?: number; } & Record; - /** Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ + /** Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ read_image: { /** Path to the image file, resolved by the filesystem backend. */ file_path: string; diff --git a/snapshots/session/both-mode-turn/tool-schemas.expected.json b/snapshots/session/both-mode-turn/tool-schemas.expected.json index 9893105262..c0426f9673 100644 --- a/snapshots/session/both-mode-turn/tool-schemas.expected.json +++ b/snapshots/session/both-mode-turn/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/compaction-recovery/tool-schemas.expected.json b/snapshots/session/compaction-recovery/tool-schemas.expected.json index 36df7a0481..ebdc1383f5 100644 --- a/snapshots/session/compaction-recovery/tool-schemas.expected.json +++ b/snapshots/session/compaction-recovery/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { @@ -1007,7 +1007,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md index 93ad87e990..556669a52a 100644 --- a/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md +++ b/snapshots/session/cordis-inspect-jsdoc/system-prompt.expected.md @@ -321,7 +321,7 @@ interface ToolArgsMap { /** Maximum number of lines to return. Defaults to 2000. */ limit?: number; } & Record; - /** Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ + /** Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ read_image: { /** Path to the image file, resolved by the filesystem backend. */ file_path: string; diff --git a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json index 3a0073f42a..bf0d4e5f04 100644 --- a/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json +++ b/snapshots/session/cordis-inspect-jsdoc/tool-schemas.expected.json @@ -503,7 +503,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/fs-glob-sampling/tool-schemas.expected.json b/snapshots/session/fs-glob-sampling/tool-schemas.expected.json index 47769041bd..8a61071acd 100644 --- a/snapshots/session/fs-glob-sampling/tool-schemas.expected.json +++ b/snapshots/session/fs-glob-sampling/tool-schemas.expected.json @@ -226,7 +226,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/lsp-definition/tool-schemas.expected.json b/snapshots/session/lsp-definition/tool-schemas.expected.json index 05543b4012..6c691f70fc 100644 --- a/snapshots/session/lsp-definition/tool-schemas.expected.json +++ b/snapshots/session/lsp-definition/tool-schemas.expected.json @@ -343,7 +343,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/product-subagent-both/tool-schemas.expected.json b/snapshots/session/product-subagent-both/tool-schemas.expected.json index e457070e01..22dc3e2126 100644 --- a/snapshots/session/product-subagent-both/tool-schemas.expected.json +++ b/snapshots/session/product-subagent-both/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/product-subagent-codex/tool-schemas.expected.json b/snapshots/session/product-subagent-codex/tool-schemas.expected.json index bc41f13b88..69094cb8ae 100644 --- a/snapshots/session/product-subagent-codex/tool-schemas.expected.json +++ b/snapshots/session/product-subagent-codex/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json b/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json index 2072fb3d15..29836f8c17 100644 --- a/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json +++ b/snapshots/session/product-subagent-result-diagnostic/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/ptc-read-image-attachment-path/replay.override.json b/snapshots/session/ptc-read-image-attachment-path/replay.override.json new file mode 100644 index 0000000000..c1b0ca939f --- /dev/null +++ b/snapshots/session/ptc-read-image-attachment-path/replay.override.json @@ -0,0 +1,29 @@ +[ + { + "kind": "chunks", + "chunks": [ + { "type": "block-start", "index": 0, "blockType": "tool-call" }, + { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "code-image-source", "name": "run_code", "arguments": "{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}" } }, + { "type": "usage", "usage": { "inputTokens": 3, "outputTokens": 3 } }, + { "type": "finish", "reason": { "kind": "tool-calls" } } + ] + }, + { + "kind": "chunks", + "chunks": [ + { "type": "block-start", "index": 0, "blockType": "tool-call" }, + { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "code-image-object", "name": "run_code", "arguments": "{\"code\":\"return await tools.read_image({ file_path: '{{fromRequest:(.+)/red\\.png}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}" } }, + { "type": "usage", "usage": { "inputTokens": 3, "outputTokens": 3 } }, + { "type": "finish", "reason": { "kind": "tool-calls" } } + ] + }, + { + "kind": "chunks", + "chunks": [ + { "type": "block-start", "index": 0, "blockType": "text" }, + { "type": "block-end", "index": 0, "block": { "type": "text", "text": "DONE" } }, + { "type": "usage", "usage": { "inputTokens": 3, "outputTokens": 3 } }, + { "type": "finish", "reason": { "kind": "stop" } } + ] + } +] diff --git a/snapshots/session/ptc-read-image-attachment-path/session.jsonl b/snapshots/session/ptc-read-image-attachment-path/session.jsonl new file mode 100644 index 0000000000..c03535c239 --- /dev/null +++ b/snapshots/session/ptc-read-image-attachment-path/session.jsonl @@ -0,0 +1,48 @@ +{"type":"session","version":0,"id":"{{session:1}}","createdAt":1783954000000,"cwd":"{{cwd}}","delegationDepth":0} +{"type":"permission/preset","data":{"preset":"danger-full-access"}} +{"type":"sandbox/mode","data":{"mode":"danger-full-access"}} +{"type":"approval/policy","data":{"policy":"never"}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Using run_code, call read_image on red.png, then call read_image again with the extension-less normalized attachment object path it produced, and reply with exactly the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"turn/start","data":{"turn":1}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","data":{"turn":1,"step":1}} +{"type":"user/message","data":{"content":[{"type":"text","text":"Using run_code, call read_image on red.png, then call read_image again with the extension-less normalized attachment object path it produced, and reply with exactly the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","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":"{{message:2}}"},"surfaceOp":"append"} +{"type":"session/title","data":{"title":"Using run_code, call read_image on","messageSeqs":[7],"source":{"kind":"fallback"}}} +{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[12,15]],"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":1,"callId":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}} +{"type":"tool/code-dispatch-start","data":{"rootCallId":"code-image-source","parentCallId":"code-image-source","subCallId":"code-image-source:code:1","name":"read_image","arguments":{"file_path":"red.png"}}} +{"type":"tool/code-dispatch","data":{"rootCallId":"code-image-source","parentCallId":"code-image-source","subCallId":"code-image-source:code:1","name":"read_image","arguments":{"file_path":"red.png"},"isError":false,"content":[{"type":"text","text":"{{cwd}}/red.png\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}]}} +{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"code-image-source"},"content":[{"type":"tool-result","toolCallId":"code-image-source","content":[{"type":"text","text":"{\n \"path\": \"{{cwd}}/red.png\",\n \"image\": {\n \"attachmentId\": \"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\",\n \"mediaType\": \"image/png\",\n \"bytes\": 69,\n \"width\": 1,\n \"height\": 1,\n \"name\": \"red.png\"\n }\n}"}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[17],"surfaceOp":"append"} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"{{cwd}}/red.png\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}],"source":{"kind":"plugin","plugin":"tools-code-mode"},"role":"user","id":"{{message:5}}"}]}} +{"type":"step/end","data":{"turn":1,"step":1}} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","data":{"turn":1,"step":2}} +{"type":"user/message","data":{"content":[{"type":"text","text":"{{cwd}}/red.png\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}],"source":{"kind":"plugin","plugin":"tools-code-mode"},"role":"user","id":"{{message:5}}"},"surfaceOp":"append"} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:6}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[26,29]],"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":2,"callId":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}} +{"type":"tool/code-dispatch-start","data":{"rootCallId":"code-image-object","parentCallId":"code-image-object","subCallId":"code-image-object:code:1","name":"read_image","arguments":{"file_path":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}} +{"type":"tool/code-dispatch","data":{"rootCallId":"code-image-object","parentCallId":"code-image-object","subCallId":"code-image-object:code:1","name":"read_image","arguments":{"file_path":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"},"isError":false,"content":[{"type":"text","text":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}]}} +{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"code-image-object"},"content":[{"type":"tool-result","toolCallId":"code-image-object","content":[{"type":"text","text":"{\n \"path\": \"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\",\n \"image\": {\n \"attachmentId\": \"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\",\n \"mediaType\": \"image/png\",\n \"bytes\": 69,\n \"width\": 1,\n \"height\": 1,\n \"name\": \"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"\n }\n}"}],"isError":false}],"role":"user","id":"{{message:7}}"}},"sourceEventSeqs":[31],"surfaceOp":"append"} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"inserted":[{"content":[{"type":"text","text":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}],"source":{"kind":"plugin","plugin":"tools-code-mode"},"role":"user","id":"{{message:8}}"}]}} +{"type":"step/end","data":{"turn":1,"step":2}} +{"type":"agent/inbox/spliced","data":{"target":"next-step","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","data":{"turn":1,"step":3}} +{"type":"user/message","data":{"content":[{"type":"text","text":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}],"source":{"kind":"plugin","plugin":"tools-code-mode"},"role":"user","id":"{{message:8}}"},"surfaceOp":"append"} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:9}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[40,43]],"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":3}} +{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/session/ptc-read-image-attachment-path/snapshot.yml b/snapshots/session/ptc-read-image-attachment-path/snapshot.yml new file mode 100644 index 0000000000..dc929c458a --- /dev/null +++ b/snapshots/session/ptc-read-image-attachment-path/snapshot.yml @@ -0,0 +1,10 @@ +version: 1 +scenario: ptc-read-image-attachment-path +profile: headless +composition: ptc-image +recording: authored +header: + class: ptc-image +replay: + override: true +platform: posix diff --git a/snapshots/session/ptc-read-image-attachment-path/workspace/red.png b/snapshots/session/ptc-read-image-attachment-path/workspace/red.png new file mode 100644 index 0000000000000000000000000000000000000000..62a5f8f47fec02344e5bf9061888262f677cf5d6 GIT binary patch literal 69 zcmeAS@N?(olHy`uVBq!ia0vp^j3CUx1SBVv2j2ryJf1F&Ar*6yf1E$Sz`)GN$Z+!C Rr1wB^22WQ%mvv4FO#seq5RCu; literal 0 HcmV?d00001 diff --git a/snapshots/session/ptc-read-image/system-prompt.expected.md b/snapshots/session/ptc-read-image/system-prompt.expected.md index 42106b19ac..7b20dd24e2 100644 --- a/snapshots/session/ptc-read-image/system-prompt.expected.md +++ b/snapshots/session/ptc-read-image/system-prompt.expected.md @@ -156,7 +156,7 @@ interface ToolArgsMap { /** Maximum number of lines to return. Defaults to 2000. */ limit?: number; } & Record; - /** Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ + /** Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ read_image: { /** Path to the image file, resolved by the filesystem backend. */ file_path: string; diff --git a/snapshots/session/ptc-turn/system-prompt.expected.md b/snapshots/session/ptc-turn/system-prompt.expected.md index ed2959eb01..1b5d70f27d 100644 --- a/snapshots/session/ptc-turn/system-prompt.expected.md +++ b/snapshots/session/ptc-turn/system-prompt.expected.md @@ -156,7 +156,7 @@ interface ToolArgsMap { /** Maximum number of lines to return. Defaults to 2000. */ limit?: number; } & Record; - /** Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ + /** Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ read_image: { /** Path to the image file, resolved by the filesystem backend. */ file_path: string; diff --git a/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json b/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json index 144d2309e9..41b07174f1 100644 --- a/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json +++ b/snapshots/session/pty-tools-sandbox-backend/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/ralph-loop/tool-schemas.1.expected.json b/snapshots/session/ralph-loop/tool-schemas.1.expected.json index dbcc5636e5..adf4451608 100644 --- a/snapshots/session/ralph-loop/tool-schemas.1.expected.json +++ b/snapshots/session/ralph-loop/tool-schemas.1.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/ralph-loop/tool-schemas.2.expected.json b/snapshots/session/ralph-loop/tool-schemas.2.expected.json index dbcc5636e5..adf4451608 100644 --- a/snapshots/session/ralph-loop/tool-schemas.2.expected.json +++ b/snapshots/session/ralph-loop/tool-schemas.2.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/read-image-attachment-path/replay.override.json b/snapshots/session/read-image-attachment-path/replay.override.json new file mode 100644 index 0000000000..513c2b63eb --- /dev/null +++ b/snapshots/session/read-image-attachment-path/replay.override.json @@ -0,0 +1,29 @@ +[ + { + "kind": "chunks", + "chunks": [ + { "type": "block-start", "index": 0, "blockType": "tool-call" }, + { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "read-image-source", "name": "read_image", "arguments": "{\"file_path\":\"red.png\"}" } }, + { "type": "usage", "usage": { "inputTokens": 3, "outputTokens": 3 } }, + { "type": "finish", "reason": { "kind": "tool-calls" } } + ] + }, + { + "kind": "chunks", + "chunks": [ + { "type": "block-start", "index": 0, "blockType": "tool-call" }, + { "type": "block-end", "index": 0, "block": { "type": "tool-call", "id": "read-image-object", "name": "read_image", "arguments": "{\"file_path\":\"{{fromRequest:(.+)/red\\.png}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}" } }, + { "type": "usage", "usage": { "inputTokens": 3, "outputTokens": 3 } }, + { "type": "finish", "reason": { "kind": "tool-calls" } } + ] + }, + { + "kind": "chunks", + "chunks": [ + { "type": "block-start", "index": 0, "blockType": "text" }, + { "type": "block-end", "index": 0, "block": { "type": "text", "text": "DONE" } }, + { "type": "usage", "usage": { "inputTokens": 3, "outputTokens": 3 } }, + { "type": "finish", "reason": { "kind": "stop" } } + ] + } +] diff --git a/snapshots/session/read-image-attachment-path/session.jsonl b/snapshots/session/read-image-attachment-path/session.jsonl new file mode 100644 index 0000000000..4ea43a90dc --- /dev/null +++ b/snapshots/session/read-image-attachment-path/session.jsonl @@ -0,0 +1,38 @@ +{"type":"session","version":0,"id":"{{session:1}}","createdAt":1783953000000,"cwd":"{{cwd}}","delegationDepth":0} +{"type":"permission/preset","data":{"preset":"danger-full-access"}} +{"type":"sandbox/mode","data":{"mode":"danger-full-access"}} +{"type":"approval/policy","data":{"policy":"never"}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Use read_image to look at red.png in the current directory, then call read_image again with the extension-less normalized attachment object path under .dsh, and reply with exactly the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"turn/start","data":{"turn":1}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} +{"type":"step/start","data":{"turn":1,"step":1}} +{"type":"user/message","data":{"content":[{"type":"text","text":"Use read_image to look at red.png in the current directory, then call read_image again with the extension-less normalized attachment object path under .dsh, and reply with exactly the single word DONE."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","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":"{{message:2}}"},"surfaceOp":"append"} +{"type":"session/title","data":{"title":"Use read_image to look at","messageSeqs":[7],"source":{"kind":"fallback"}}} +{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} +{"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[12,15]],"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":1,"callId":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}} +{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"read-image-source"},"content":[{"type":"tool-result","toolCallId":"read-image-source","content":[{"type":"text","text":"{{cwd}}/red.png\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[17],"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":1}} +{"type":"step/start","data":{"turn":1,"step":2}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[21,24]],"surfaceOp":"append"} +{"type":"tool/call","data":{"turn":1,"step":2,"callId":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}} +{"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"read-image-object"},"content":[{"type":"tool-result","toolCallId":"read-image-object","content":[{"type":"text","text":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[26],"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":2}} +{"type":"step/start","data":{"turn":1,"step":3}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} +{"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} +{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:7}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[30,33]],"surfaceOp":"append"} +{"type":"step/end","data":{"turn":1,"step":3}} +{"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/session/read-image-attachment-path/snapshot.yml b/snapshots/session/read-image-attachment-path/snapshot.yml new file mode 100644 index 0000000000..724699b789 --- /dev/null +++ b/snapshots/session/read-image-attachment-path/snapshot.yml @@ -0,0 +1,9 @@ +version: 1 +scenario: read-image-attachment-path +profile: headless +composition: image +recording: authored +header: + class: image +replay: + override: true diff --git a/snapshots/session/read-image-attachment-path/workspace/red.png b/snapshots/session/read-image-attachment-path/workspace/red.png new file mode 100644 index 0000000000000000000000000000000000000000..62a5f8f47fec02344e5bf9061888262f677cf5d6 GIT binary patch literal 69 zcmeAS@N?(olHy`uVBq!ia0vp^j3CUx1SBVv2j2ryJf1F&Ar*6yf1E$Sz`)GN$Z+!C Rr1wB^22WQ%mvv4FO#seq5RCu; literal 0 HcmV?d00001 diff --git a/snapshots/session/session-query-spill/tool-schemas.expected.json b/snapshots/session/session-query-spill/tool-schemas.expected.json index 3e28d4cfcb..929cd0fa8d 100644 --- a/snapshots/session/session-query-spill/tool-schemas.expected.json +++ b/snapshots/session/session-query-spill/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json b/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json index 796bac1779..ab4af3db64 100644 --- a/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json +++ b/snapshots/session/subagent-acp-diagnostic/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json b/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json index 7e4dfe696c..4b6b5b10f4 100644 --- a/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json +++ b/snapshots/session/subagent-child-question-rejection/tool-schemas.expected.json @@ -369,7 +369,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/text-turn/tool-schemas.expected.json b/snapshots/session/text-turn/tool-schemas.expected.json index c93fb6d65f..df890396ac 100644 --- a/snapshots/session/text-turn/tool-schemas.expected.json +++ b/snapshots/session/text-turn/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/session/web-fetch/tool-schemas.expected.json b/snapshots/session/web-fetch/tool-schemas.expected.json index ee18836349..5381c3bc24 100644 --- a/snapshots/session/web-fetch/tool-schemas.expected.json +++ b/snapshots/session/web-fetch/tool-schemas.expected.json @@ -306,7 +306,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/web/cordis-tool-round/tool-schemas.expected.json b/snapshots/web/cordis-tool-round/tool-schemas.expected.json index b558e1d094..4b21fbb5b5 100644 --- a/snapshots/web/cordis-tool-round/tool-schemas.expected.json +++ b/snapshots/web/cordis-tool-round/tool-schemas.expected.json @@ -566,7 +566,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/web/fresh-round-trip/tool-schemas.expected.json b/snapshots/web/fresh-round-trip/tool-schemas.expected.json index 8232bc9e23..c07e7ea3f3 100644 --- a/snapshots/web/fresh-round-trip/tool-schemas.expected.json +++ b/snapshots/web/fresh-round-trip/tool-schemas.expected.json @@ -369,7 +369,7 @@ }, { "name": "read_image", - "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", + "description": "Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input.", "parameters": { "type": "object", "properties": { diff --git a/snapshots/web/ptc-round/system-prompt.expected.md b/snapshots/web/ptc-round/system-prompt.expected.md index 6cda9dc20d..b74423d3c7 100644 --- a/snapshots/web/ptc-round/system-prompt.expected.md +++ b/snapshots/web/ptc-round/system-prompt.expected.md @@ -184,7 +184,7 @@ interface ToolArgsMap { /** Maximum number of lines to return. Defaults to 2000. */ limit?: number; } & Record; - /** Read a PNG/JPEG/WebP/GIF file and return the image itself. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ + /** Read a PNG/JPEG/WebP/GIF file and return the image itself. A path without a file extension is accepted; the format is detected from the file content, so normalized attachment paths can be passed directly without copying or renaming. Harness validates and downscales large supported images before the next model request, so use this tool directly instead of installing image libraries or creating thumbnails merely to inspect an image. Independent files may be read concurrently in small batches. Requires the current model to accept image input. */ read_image: { /** Path to the image file, resolved by the filesystem backend. */ file_path: string; From aaa692033b8c98cc69701eb52ff6600eaaea167e Mon Sep 17 00:00:00 2001 From: creatixchu Date: Fri, 28 Aug 2026 15:16:20 +0800 Subject: [PATCH 18/63] test(snapshots): project new attachment-path fixtures into packed layout --- .../session/ptc-read-image-attachment-path/session.jsonl | 6 +++--- snapshots/session/read-image-attachment-path/session.jsonl | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/snapshots/session/ptc-read-image-attachment-path/session.jsonl b/snapshots/session/ptc-read-image-attachment-path/session.jsonl index c03535c239..09da819ab9 100644 --- a/snapshots/session/ptc-read-image-attachment-path/session.jsonl +++ b/snapshots/session/ptc-read-image-attachment-path/session.jsonl @@ -15,7 +15,7 @@ {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}}}} {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[12,15]],"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[12,13,14,15],"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":1,"callId":"code-image-source","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: 'red.png' })\",\"description\":\"Read the source image\"}"}} {"type":"tool/code-dispatch-start","data":{"rootCallId":"code-image-source","parentCallId":"code-image-source","subCallId":"code-image-source:code:1","name":"read_image","arguments":{"file_path":"red.png"}}} {"type":"tool/code-dispatch","data":{"rootCallId":"code-image-source","parentCallId":"code-image-source","subCallId":"code-image-source:code:1","name":"read_image","arguments":{"file_path":"red.png"},"isError":false,"content":[{"type":"text","text":"{{cwd}}/red.png\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}]}} @@ -29,7 +29,7 @@ {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}}}} {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:6}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[26,29]],"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:6}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[26,27,28,29],"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":2,"callId":"code-image-object","name":"run_code","arguments":"{\"code\":\"return await tools.read_image({ file_path: '{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640' })\",\"description\":\"Read the normalized attachment object directly\"}"}} {"type":"tool/code-dispatch-start","data":{"rootCallId":"code-image-object","parentCallId":"code-image-object","subCallId":"code-image-object:code:1","name":"read_image","arguments":{"file_path":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}} {"type":"tool/code-dispatch","data":{"rootCallId":"code-image-object","parentCallId":"code-image-object","subCallId":"code-image-object:code:1","name":"read_image","arguments":{"file_path":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"},"isError":false,"content":[{"type":"text","text":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}]}} @@ -43,6 +43,6 @@ {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}} {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:9}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[40,43]],"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:9}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[40,41,42,43],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":3}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} diff --git a/snapshots/session/read-image-attachment-path/session.jsonl b/snapshots/session/read-image-attachment-path/session.jsonl index 4ea43a90dc..aabb815515 100644 --- a/snapshots/session/read-image-attachment-path/session.jsonl +++ b/snapshots/session/read-image-attachment-path/session.jsonl @@ -15,7 +15,7 @@ {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}}}} {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} {"type":"assistant/chunk","data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[12,15]],"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[12,13,14,15],"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":1,"callId":"read-image-source","name":"read_image","arguments":"{\"file_path\":\"red.png\"}"}} {"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"read-image-source"},"content":[{"type":"tool-result","toolCallId":"read-image-source","content":[{"type":"text","text":"{{cwd}}/red.png\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"red.png"}}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[17],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} @@ -24,7 +24,7 @@ {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}}}} {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} {"type":"assistant/chunk","data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} -{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[21,24]],"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[21,22,23,24],"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":2,"callId":"read-image-object","name":"read_image","arguments":"{\"file_path\":\"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\"}"}} {"type":"tool/result","data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"read-image-object"},"content":[{"type":"tool-result","toolCallId":"read-image-object","content":[{"type":"text","text":"{{cwd}}/.dsh/attachments/v1/objects/b1/b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640\nimage\n\nimage/png image, 1x1 px, 69 bytes\n"},{"type":"image","attachment":{"attachmentId":"sha256:b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640","mediaType":"image/png","bytes":69,"width":1,"height":1,"name":"b1ff9c8ea3a780bad09b346c423d2d0e46815926879b18e841d928376a946640"}}],"isError":false}],"role":"user","id":"{{message:6}}"}},"sourceEventSeqs":[26],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":2}} @@ -33,6 +33,6 @@ {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DONE"}}}} {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}} {"type":"assistant/chunk","data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}} -{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:7}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[[30,33]],"surfaceOp":"append"} +{"type":"assistant/message","data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"text","text":"DONE"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash-vision-exp"},"id":"{{message:7}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[30,31,32,33],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":3}} {"type":"turn/end","data":{"turn":1,"reason":{"kind":"completed"}}} From 6f08798981f64ed631794f1fd3c47808a5c167c9 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Fri, 28 Aug 2026 15:37:27 +0800 Subject: [PATCH 19/63] docs(tool-fs): sharpen extension notes and pin dotfile edge cases --- .../2026-08-10-minimal-read-image-tool.i18n.yaml | 4 ++-- .../feature/2026-08-10-minimal-read-image-tool.md | 2 +- .../2026-08-10-minimal-read-image-tool.zh.md | 2 +- ...-image-extensionless-attachment-paths.i18n.yaml | 4 ++-- ...28-read-image-extensionless-attachment-paths.md | 2 +- ...read-image-extensionless-attachment-paths.zh.md | 2 +- packages/fs/tool-fs/README.i18n.yaml | 4 ++-- packages/fs/tool-fs/README.md | 3 ++- packages/fs/tool-fs/README.zh.md | 3 ++- packages/fs/tool-fs/tests/read-image.spec.ts | 14 ++++++++++++++ 10 files changed, 28 insertions(+), 12 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.i18n.yaml index 4c276c6b0d..2853ef84aa 100644 --- a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.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-minimal-read-image-tool.md -2026-08-10-minimal-read-image-tool.md: 8880032b2648846df679ea8fa3301d182a95c06b -2026-08-10-minimal-read-image-tool.zh.md: aec34e19fc58037b031f7d4116d2fa664b2b45b5 +2026-08-10-minimal-read-image-tool.md: 0bf3e3ca79316f15727db1708b5f68ccb3d2d368 +2026-08-10-minimal-read-image-tool.zh.md: 130849991491a39200d8e2dda0e4dc9c1f166fb6 diff --git a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md index 8880032b26..0bf3e3ca79 100644 --- a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md +++ b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md @@ -22,7 +22,7 @@ Both image-reading operations live in `dsh-tool-fs` and publish ordinary logged - **PR #598's route-scoped design** used a request-ready extension point, per-route schema visibility, reversible projection, and three durable concepts. Shared LLM request projection now handles text-only routes without putting tool registration or session formats into agent-loop. - **`agent.inject()` instead of the image-bearing tool result** — routes the image around the tool result as a separate injected user message. Rejected: the image *is* the tool's result; splitting them adds a second logged message with no gain, and the tool-result path already works end to end. -- **Magic-byte sniffing instead of extension declaration** — sniffing duplicates detection the attachment store already owns (sharp-backed, authoritative). The extension is only a *declaration*; a mismatch fails closed with a rename remedy rather than being silently accepted, which also keeps the model's mental map (file name ↔ content) honest. +- **Magic-byte sniffing instead of extension declaration** — sniffing duplicates detection the attachment store already owns (sharp-backed, authoritative). The extension is only a *declaration*; a mismatch fails closed with a rename remedy rather than being silently accepted, which also keeps the model's mental map (file name ↔ content) honest. This rejection covers extension-bearing paths; [extension-less attachment object paths](2026-08-28-read-image-extensionless-attachment-paths.md) narrows it — a path that declares nothing is identified from its file signature. - **Registering unconditionally and failing on a missing store** — rejected; a deployment without an attachment store cannot ever satisfy the tool, so its schema would be a standing lie. The route gate, by contrast, is per-call state and correctly lives at the execution boundary. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md index aec34e19fc..1308499914 100644 --- a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md +++ b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md @@ -22,7 +22,7 @@ Status: implemented - **PR #598 的路由作用域设计**使用 request-ready 扩展点、按路由控制 schema 可见性、可逆投影和三个持久概念。共享 LLM 请求投影现在可以处理纯文本路由，无需把工具注册或会话格式放进 agent-loop。 - **用 `agent.inject()` 代替带图像的工具结果**——把图像绕过工具结果，作为单独注入的用户消息。拒绝：图像就是工具的结果；拆开只会多一条无收益的日志消息，而工具结果路径本就端到端可用。 -- **用魔数嗅探代替扩展名声明**——嗅探重复了附件存储已拥有的检测（基于 sharp，权威）。扩展名只是声明；不匹配时按改名修复提示失败关闭，而不是被静默接受，这也让模型对文件名与内容的对应保持诚实。 +- **用魔数嗅探代替扩展名声明**——嗅探重复了附件存储已拥有的检测（基于 sharp，权威）。扩展名只是声明；不匹配时按改名修复提示失败关闭，而不是被静默接受，这也让模型对文件名与内容的对应保持诚实。这一拒绝覆盖带扩展名的路径；[无扩展名附件对象路径](2026-08-28-read-image-extensionless-attachment-paths.zh.md)将其收窄，什么也没声明的路径按文件签名识别。 - **无条件注册、缺存储时执行报错**——拒绝；没有附件存储的部署永远无法满足该工具，其 schema 会是常态谎言。相反，路由门禁是逐调用状态，正确的位置就是执行边界。 ## 后果 diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml index 02d0e3310e..a861a2e49e 100644 --- a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.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-28-read-image-extensionless-attachment-paths.md -2026-08-28-read-image-extensionless-attachment-paths.md: be6acb2ca336a976bcbf0c50efda0b933fb06df6 -2026-08-28-read-image-extensionless-attachment-paths.zh.md: a4e1e677a46dd72661944e09101994358c829877 +2026-08-28-read-image-extensionless-attachment-paths.md: 0ca5a65ced68062612cff5494af811624188a7fb +2026-08-28-read-image-extensionless-attachment-paths.zh.md: 547c62cd9adb631744e5e79306f390bd17c8932d diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md index be6acb2ca3..0ca5a65ced 100644 --- a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md +++ b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md @@ -10,7 +10,7 @@ Model-visible image descriptors name the normalized attachment's local read-only ## Decision -The extension stays the declared media type when it names one of the four supported formats, and every existing gate and diagnostic on that branch is unchanged. A path without an extension is no longer refused up front: the tool reads the bytes under the existing byte cap and identifies the container with `sniffImageMediaType`, a pure file-signature helper exported by the attachment Service Definition package. The sniffed type then passes through the same deployment media-type policy and `saveImage` admission, so the store's full decode remains the authority; a path whose extension names a non-image format is still refused before any I/O. +The extension stays the declared media type when it names one of the four supported formats, and every existing gate and diagnostic on that branch is unchanged. For a path without an extension the tool reads the bytes under the existing byte cap and identifies the container with `sniffImageMediaType`, a pure file-signature helper exported by the attachment Service Definition package. The sniffed type then passes through the same deployment media-type policy and `saveImage` admission, so the store's full decode remains the authority; a path whose extension names a non-image format is refused before any I/O. This narrows the sniffing rejection in [the minimal read_image tool note](2026-08-10-minimal-read-image-tool.md) to extension-bearing paths: an extension is still a declaration that fails closed on mismatch, while a path that declares nothing is identified from its bytes. Reading an object path re-saves its bytes rather than short-circuiting through a reverse path lookup. Normalization passes an already-normalized image through byte-identically, so the re-save deduplicates to the same content-addressed reference; a store test pins that idempotency for a re-encoded object. No reference proof is required at the tool: object paths are unguessable content digests, the published objects are already readable through the mounted filesystem (Bash included), and the session-reference gate continues to protect the remote client RPC, which is the boundary where an attachment id alone grants bytes. diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md index a4e1e677a4..547c62cd9a 100644 --- a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md +++ b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md @@ -10,7 +10,7 @@ Status: implemented ## 决定 -扩展名命名四种受支持格式之一时仍作为声明的媒体类型，该分支的所有既有检查和诊断保持不变。无扩展名的路径不再被提前拒绝：工具在既有字节上限内读取字节，用 `sniffImageMediaType` 识别容器格式，这是附件 Service Definition 包导出的纯文件签名辅助函数。识别出的类型随后经过同一套部署媒体类型政策和 `saveImage` 准入，存储实现的完整解码仍是权威；扩展名声明了非图片格式的路径依旧在任何 I/O 之前被拒绝。 +扩展名命名四种受支持格式之一时仍作为声明的媒体类型，该分支的所有既有检查和诊断保持不变。对无扩展名的路径，工具在既有字节上限内读取字节，用 `sniffImageMediaType` 识别容器格式，这是附件 Service Definition 包导出的纯文件签名辅助函数。识别出的类型随后经过同一套部署媒体类型政策和 `saveImage` 准入，存储实现的完整解码仍是权威；扩展名声明了非图片格式的路径在任何 I/O 之前被拒绝。这把[最小 read_image 工具笔记](2026-08-10-minimal-read-image-tool.zh.md)中对嗅探的拒绝收窄到带扩展名的路径：扩展名仍是不匹配即失败的声明，而什么也没声明的路径按其字节识别。 读取对象路径会重新保存其字节，而不是通过反向路径查找走捷径。归一化让已归一化的图片字节原样通过，因此重新保存会去重到同一个内容寻址引用；一个存储测试固定了重编码对象的这一幂等性。工具处不需要会话引用证明：对象路径是不可猜测的内容摘要，已发布对象本来就能通过挂载的文件系统（包括 Bash）读到，而会话引用检查继续保护远程客户端 RPC，那才是仅凭附件 id 就能获得字节的边界。 diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index 8913a24022..b2de0de1b6 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md -README.md: c4c8f9270a7b9422d52e6f89567c0d7eeab1f5c6 -README.zh.md: 8bd62f68010e6363515b39e7e71d6361f746713b +README.md: 31e7b4c900cbd6cb232dac229eb93abde88b6042 +README.zh.md: c962f0028d56eb52e577828bf7b3e56a90b4e9d1 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index c4c8f9270a..31e7b4c900 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -238,7 +238,8 @@ These limits define when the tool suite is a poor fit or needs special operation - **No model-facing directory listing ships** — `ctx.fs.listDir` serves provider code such as skill discovery, while the sibling `dsh-tool-fs-search` package supplies ripgrep-backed `glob` and `grep` rather than extending the filesystem seam. - **`read` handles UTF-8 text files only** — images use the separate `read_image` tool; PDF, audio, and video remain deferred. A directory target is `FS_NOT_REGULAR_FILE`. -- **Extension-declared media type** — the extension selects the declared type and the attachment store's magic-byte validation stays authoritative; a correctly formatted image under a wrong extension is refused with the rename remedy rather than sniffed. +- **Extension-declared media type** — an extension selects the declared type and the attachment store's magic-byte validation stays authoritative; a correctly formatted image under a wrong extension is refused with the rename remedy rather than sniffed. Only a path with no extension is identified from its file signature. +- **Object paths re-enter source admission** — `read_image` on a normalized attachment object re-admits its bytes as a new source, so a deployment whose `maxImageBytes`/`maxMessageImageBytes` sit below the normalized-image byte budget can refuse an object path that `ctx.attachments.readImage` still serves; shipped defaults keep the normalized budget (4 MiB) far under the source caps (20 MiB). - **No inline image preview on the tool-result card** — UI surfaces render the image result generically (the durable reference, not pixels); inline rendering is deferred to the UI packages. - **No attachment-region tool** — an agent may crop an image through another available tool when it has a filesystem path; a pasted or dragged image without a path cannot be re-read at higher resolution. - **No timeout surface** — `read`/`write`/`edit` take no timeout argument and declare no timeout budget; cancellation rides `exec.signal` only ([provider rationale](../README.md)). diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index 8bd62f6801..c962f0028d 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -238,7 +238,8 @@ Use the edit tool for targeted changes to existing UTF-8 text files. It replaces - **未交付面向模型的目录列表工具**：`ctx.fs.listDir` 服务于 skill（技能）发现等提供方代码，同级 `dsh-tool-fs-search` 包则提供基于 ripgrep 的 `glob` 与 `grep`，而不是扩展文件系统 seam。 - **`read` 只处理 UTF-8 文本文件**：图像使用独立的 `read_image` 工具；PDF、音频和视频仍延期处理。目录目标为 `FS_NOT_REGULAR_FILE`。 -- **媒体类型按扩展名声明**：扩展名选择声明类型，附件存储的魔数校验保持权威；扩展名错误但格式正确的图像会得到改名修复提示，而不是被嗅探接受。 +- **媒体类型按扩展名声明**：扩展名选择声明类型，附件存储的魔数校验保持权威；扩展名错误但格式正确的图像会得到改名修复提示，而不是被嗅探接受。只有没有扩展名的路径按文件签名识别格式。 +- **对象路径重新走源准入**：对规范化附件对象调用 `read_image` 会把其字节作为新来源重新准入，因此把 `maxImageBytes`/`maxMessageImageBytes` 配置得低于规范化图片字节预算的部署可能拒绝 `ctx.attachments.readImage` 仍可读取的对象路径；默认配置下规范化预算（4 MiB）远低于源上限（20 MiB）。 - **工具结果卡片没有内嵌图像预览**：UI 表面以通用形式渲染图像结果（持久引用而非像素）；内嵌渲染延后到 UI 包处理。 - **没有附件区域工具**：agent 在拥有文件系统路径时可以通过其他可用工具裁剪图片；没有路径的粘贴或拖入图片无法按更高分辨率重新读取。 - **没有超时接口**：`read`/`write`/`edit` 不接受超时参数，也不声明超时预算；取消只通过 `exec.signal` 传递（见[提供方理由](../README.zh.md)）。 diff --git a/packages/fs/tool-fs/tests/read-image.spec.ts b/packages/fs/tool-fs/tests/read-image.spec.ts index b2aeb09256..f0f0802198 100644 --- a/packages/fs/tool-fs/tests/read-image.spec.ts +++ b/packages/fs/tool-fs/tests/read-image.spec.ts @@ -339,6 +339,20 @@ describe('extension-less paths', () => { expect(image.attachment.name).toBe('avatar') }) + it('pins the trailing-dot refusal and reads a dotfile through sniffing', async () => { + await writeFile(join(dir, '.hidden'), PNG_1X1) + const ctx = await setup() + const trailingDot = await readImage(ctx, { file_path: 'foo.' }, agentOn('vision-model')) + expect(trailingDot.isError).toBe(true) + expect(text(trailingDot)).toContain('cannot read "foo.": the . extension does not declare a supported image format') + + const dotfile = await readImage(ctx, { file_path: '.hidden' }, agentOn('vision-model')) + expect(dotfile.isError).toBe(false) + const image = dotfile.content[1] as { attachment: ImageAttachmentRef } + expect(image.attachment.mediaType).toBe('image/png') + expect(image.attachment.name).toBe('.hidden') + }) + it('refuses extension-less bytes that are not a supported image', async () => { await writeFile(join(dir, 'notes'), 'plain text, not an image') const ctx = await setup() From f3c69c2c3feffe4c033489b2dce08315051514d0 Mon Sep 17 00:00:00 2001 From: creatixchu Date: Fri, 28 Aug 2026 16:10:19 +0800 Subject: [PATCH 20/63] refactor(tool-fs): keep image sniffing tool-local --- ...-read-image-extensionless-paths.i18n.yaml} | 6 +- ...26-08-28-read-image-extensionless-paths.md | 29 ++++++ ...08-28-read-image-extensionless-paths.zh.md | 29 ++++++ ...26-08-10-minimal-read-image-tool.i18n.yaml | 4 +- .../2026-08-10-minimal-read-image-tool.md | 2 +- .../2026-08-10-minimal-read-image-tool.zh.md | 2 +- ...ad-image-extensionless-attachment-paths.md | 27 ------ ...image-extensionless-attachment-paths.zh.md | 27 ------ docs/subsystems/attachment.i18n.yaml | 4 +- docs/subsystems/attachment.md | 2 +- docs/subsystems/attachment.zh.md | 2 +- .../attachment-local/tests/store.spec.ts | 22 ----- .../attachment/attachment/README.i18n.yaml | 4 +- packages/attachment/attachment/README.md | 3 +- packages/attachment/attachment/README.zh.md | 3 +- packages/attachment/attachment/src/index.ts | 1 - packages/attachment/attachment/src/sniff.ts | 39 -------- .../attachment/attachment/tests/sniff.spec.ts | Bin 1464 -> 0 bytes packages/fs/tool-fs/README.i18n.yaml | 4 +- packages/fs/tool-fs/README.md | 2 + packages/fs/tool-fs/README.zh.md | 2 + packages/fs/tool-fs/src/read-image.ts | 39 +++++++- packages/fs/tool-fs/tests/read-image.spec.ts | 89 ++++++------------ 23 files changed, 141 insertions(+), 201 deletions(-) rename .agents/notes/implemented/{feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml => bug-fix/2026-08-28-read-image-extensionless-paths.i18n.yaml} (53%) create mode 100644 .agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.md create mode 100644 .agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.zh.md delete mode 100644 .agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md delete mode 100644 .agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md delete mode 100644 packages/attachment/attachment/src/sniff.ts delete mode 100644 packages/attachment/attachment/tests/sniff.spec.ts diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.i18n.yaml similarity index 53% rename from .agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml rename to .agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.i18n.yaml index a861a2e49e..0f9fa28a2a 100644 --- a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.i18n.yaml @@ -1,6 +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-28-read-image-extensionless-attachment-paths.md -2026-08-28-read-image-extensionless-attachment-paths.md: 0ca5a65ced68062612cff5494af811624188a7fb -2026-08-28-read-image-extensionless-attachment-paths.zh.md: 547c62cd9adb631744e5e79306f390bd17c8932d +# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.md +2026-08-28-read-image-extensionless-paths.md: cf7d82b2ed86208bcb8ef6287dfcfc7c4391ccc4 +2026-08-28-read-image-extensionless-paths.zh.md: 8d4cd15f6c414bb28307863bfe61ea3a7181ed02 diff --git a/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.md b/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.md new file mode 100644 index 0000000000..cf7d82b2ed --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.md @@ -0,0 +1,29 @@ +# Agent Note: read_image accepts extension-less image paths + +Status: implemented + +English | [中文](2026-08-28-read-image-extensionless-paths.zh.md) + +## Problem + +`read_image` mapped `file_path` to a media type by extension alone and refused a path with no extension. Valid extension-less images therefore required a renamed copy before the model could inspect them. Normalized local attachment objects exposed to the model use content digests without extensions, so their published read-only paths triggered the same refusal. + +## Decision + +`read_image` treats a file extension as a media-type declaration. PNG, JPEG, WebP, and GIF extensions select their declared types; another non-empty extension is refused before filesystem I/O, and the attachment store's full decode rejects a declaration that does not match the bytes. A path with no extension is read through `ctx.fs` under the existing `maxImageBytes` and tighter `maxMessageImageBytes` cap, then a tool-local `sniffImageMediaType` helper identifies one of the four supported file signatures. The detected type passes through the same deployment media-type policy and `saveImage` admission, whose full decode remains authoritative. This narrows the sniffing rejection in [the minimal read_image tool note](../feature/2026-08-10-minimal-read-image-tool.md) to extension-bearing paths. + +The mounted `ctx.fs` backend is the complete path-authorization authority for `read_image`. Extensions and file signatures decide only whether the tool accepts bytes that the backend returned. Any valid extension-less image readable through that backend can enter the current session, including a normalized attachment object; the tool performs no session-reference proof and the attachment service exposes no reverse path lookup. + +Admission failures name the offending path. An extension-less mismatch names the signature that supplied the declaration, while unsupported bytes report no file content. + +## Alternatives considered + +**Export signature identification from the attachment Service Definition package.** Only `read_image` needs this pre-admission declaration. Publishing the helper would make one Consumer's filename policy part of the provider-independent attachment API while the store already owns authoritative decoding. + +**Special-case normalized attachment object paths.** Resolving a path back to a Session reference would make two files readable through the same `ctx.fs` behave differently according to their origin and would leave ordinary extension-less images unsupported. Filesystem access remains the read authorization decision. + +**Add extensions to stored attachment objects.** This would change the storage layout and every object-path consumer to satisfy one tool's media-type declaration rule. + +## Consequences + +The model can read ordinary extension-less images and normalized attachment paths directly in native and PTC modes. Wrong extensions retain their pre-I/O refusal and mismatch repair. A non-image path without an extension is read up to the image byte cap before rejection, and a normalized object re-enters source admission instead of bypassing the current deployment limits. The behavior changes only `dsh-tool-fs`; the attachment Service Definition and local provider keep their existing APIs and storage behavior. diff --git a/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.zh.md b/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.zh.md new file mode 100644 index 0000000000..8d4cd15f6c --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-28-read-image-extensionless-paths.zh.md @@ -0,0 +1,29 @@ +# Agent Note: read_image 接受无扩展名图片路径 + +Status: implemented + +[English](2026-08-28-read-image-extensionless-paths.md) | 中文 + +## 问题 + +`read_image` 只按扩展名把 `file_path` 映射到媒体类型，并拒绝没有扩展名的路径。因此，模型必须先创建一份改名副本，才能查看合法的无扩展名图片。向模型公开的规范化本地附件对象以内容摘要命名，不带扩展名，所以其已发布的只读路径也会触发同一项拒绝。 + +## 决定 + +`read_image` 把文件扩展名视为媒体类型声明。PNG、JPEG、WebP 与 GIF 扩展名选择各自声明的类型；其他非空扩展名在文件系统 I/O 前被拒绝，附件存储的完整解码会拒绝与字节不匹配的声明。对于无扩展名路径，工具通过 `ctx.fs` 在既有 `maxImageBytes` 和更严格的 `maxMessageImageBytes` 上限内读取文件，再由工具内部的 `sniffImageMediaType` 辅助函数识别四种受支持的文件签名。识别结果经过同一套部署媒体类型策略和 `saveImage` 准入，后者的完整解码保持权威。这把[最小 read_image 工具 Agent Note](../feature/2026-08-10-minimal-read-image-tool.zh.md)中对嗅探的拒绝收窄到带扩展名的路径。 + +挂载的 `ctx.fs` 后端是 `read_image` 路径授权的完整依据。扩展名和文件签名只决定工具是否接受后端返回的字节。该后端可读的每个合法无扩展名图片都能进入当前会话，包括规范化附件对象；工具不证明 Session 引用，附件服务也不提供反向路径查找。 + +准入失败会指出出错路径。无扩展名路径的类型不匹配会指出提供声明的文件签名，而不受支持的字节不会出现在错误消息中。 + +## 考虑过的替代方案 + +**从附件 Service Definition 包导出文件签名识别。** 只有 `read_image` 需要这项准入前声明。公开该辅助函数会把单个消费方的文件名策略加入提供方无关的附件 API，而存储已经负责权威解码。 + +**特殊处理规范化附件对象路径。** 把路径反查为 Session 引用，会使 `ctx.fs` 以相同方式提供的两个文件根据来源产生不同读取结果，而且普通无扩展名图片仍然不受支持。文件系统访问保持读取授权决定。 + +**为存储的附件对象增加扩展名。** 这会为了满足一个工具的媒体类型声明规则而修改存储布局和每个对象路径消费方。 + +## 影响 + +模型可以在 native 和 PTC 模式下直接读取普通无扩展名图片与规范化附件路径。错误扩展名保留 I/O 前拒绝和类型不匹配修复提示。无扩展名非图片路径会在拒绝前读取到图片字节上限，规范化对象也会重新经过来源准入，而不会绕过当前部署限额。行为改动只位于 `dsh-tool-fs`；附件 Service Definition 与本地提供方保持现有 API 和存储行为。 diff --git a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.i18n.yaml b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.i18n.yaml index 2853ef84aa..d57485473f 100644 --- a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.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-minimal-read-image-tool.md -2026-08-10-minimal-read-image-tool.md: 0bf3e3ca79316f15727db1708b5f68ccb3d2d368 -2026-08-10-minimal-read-image-tool.zh.md: 130849991491a39200d8e2dda0e4dc9c1f166fb6 +2026-08-10-minimal-read-image-tool.md: be7c24965ee256e4062b5caf32ce7f8c62d9c1ae +2026-08-10-minimal-read-image-tool.zh.md: f1d09a320e0f44145e4c8681668996d66fbb4898 diff --git a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md index 0bf3e3ca79..be7c24965e 100644 --- a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md +++ b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.md @@ -22,7 +22,7 @@ Both image-reading operations live in `dsh-tool-fs` and publish ordinary logged - **PR #598's route-scoped design** used a request-ready extension point, per-route schema visibility, reversible projection, and three durable concepts. Shared LLM request projection now handles text-only routes without putting tool registration or session formats into agent-loop. - **`agent.inject()` instead of the image-bearing tool result** — routes the image around the tool result as a separate injected user message. Rejected: the image *is* the tool's result; splitting them adds a second logged message with no gain, and the tool-result path already works end to end. -- **Magic-byte sniffing instead of extension declaration** — sniffing duplicates detection the attachment store already owns (sharp-backed, authoritative). The extension is only a *declaration*; a mismatch fails closed with a rename remedy rather than being silently accepted, which also keeps the model's mental map (file name ↔ content) honest. This rejection covers extension-bearing paths; [extension-less attachment object paths](2026-08-28-read-image-extensionless-attachment-paths.md) narrows it — a path that declares nothing is identified from its file signature. +- **Magic-byte sniffing instead of extension declaration** — sniffing duplicates detection the attachment store already owns (sharp-backed, authoritative). The extension is only a *declaration*; a mismatch fails closed with a rename remedy rather than being silently accepted, which also keeps the model's mental map (file name ↔ content) honest. This rejection covers extension-bearing paths; [extension-less image paths](../bug-fix/2026-08-28-read-image-extensionless-paths.md) narrows it — a path that declares nothing is identified from its file signature. - **Registering unconditionally and failing on a missing store** — rejected; a deployment without an attachment store cannot ever satisfy the tool, so its schema would be a standing lie. The route gate, by contrast, is per-call state and correctly lives at the execution boundary. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md index 1308499914..f1d09a320e 100644 --- a/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md +++ b/.agents/notes/implemented/feature/2026-08-10-minimal-read-image-tool.zh.md @@ -22,7 +22,7 @@ Status: implemented - **PR #598 的路由作用域设计**使用 request-ready 扩展点、按路由控制 schema 可见性、可逆投影和三个持久概念。共享 LLM 请求投影现在可以处理纯文本路由，无需把工具注册或会话格式放进 agent-loop。 - **用 `agent.inject()` 代替带图像的工具结果**——把图像绕过工具结果，作为单独注入的用户消息。拒绝：图像就是工具的结果；拆开只会多一条无收益的日志消息，而工具结果路径本就端到端可用。 -- **用魔数嗅探代替扩展名声明**——嗅探重复了附件存储已拥有的检测（基于 sharp，权威）。扩展名只是声明；不匹配时按改名修复提示失败关闭，而不是被静默接受，这也让模型对文件名与内容的对应保持诚实。这一拒绝覆盖带扩展名的路径；[无扩展名附件对象路径](2026-08-28-read-image-extensionless-attachment-paths.zh.md)将其收窄，什么也没声明的路径按文件签名识别。 +- **用魔数嗅探代替扩展名声明**——嗅探重复了附件存储已拥有的检测（基于 sharp，权威）。扩展名只是声明；不匹配时按改名修复提示失败关闭，而不是被静默接受，这也让模型对文件名与内容的对应保持诚实。这一拒绝覆盖带扩展名的路径；[无扩展名图片路径](../bug-fix/2026-08-28-read-image-extensionless-paths.zh.md)将其收窄，什么也没声明的路径按文件签名识别。 - **无条件注册、缺存储时执行报错**——拒绝；没有附件存储的部署永远无法满足该工具，其 schema 会是常态谎言。相反，路由门禁是逐调用状态，正确的位置就是执行边界。 ## 后果 diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md deleted file mode 100644 index 0ca5a65ced..0000000000 --- a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.md +++ /dev/null @@ -1,27 +0,0 @@ -# Agent Note: read_image accepts extension-less attachment object paths - -Status: implemented - -English | [中文](2026-08-28-read-image-extensionless-attachment-paths.zh.md) - -## Problem - -Model-visible image descriptors name the normalized attachment's local read-only path, and normalized objects are content-addressed files without an image extension. `read_image` mapped `file_path` to a media type by extension alone and refused everything else, so passing the descriptor's own path back produced `read_image only accepts PNG/JPEG/WebP/GIF paths` for an image the store had already validated and persisted. The model's only workarounds were copying the object to a renamed file or re-uploading it. - -## Decision - -The extension stays the declared media type when it names one of the four supported formats, and every existing gate and diagnostic on that branch is unchanged. For a path without an extension the tool reads the bytes under the existing byte cap and identifies the container with `sniffImageMediaType`, a pure file-signature helper exported by the attachment Service Definition package. The sniffed type then passes through the same deployment media-type policy and `saveImage` admission, so the store's full decode remains the authority; a path whose extension names a non-image format is refused before any I/O. This narrows the sniffing rejection in [the minimal read_image tool note](2026-08-10-minimal-read-image-tool.md) to extension-bearing paths: an extension is still a declaration that fails closed on mismatch, while a path that declares nothing is identified from its bytes. - -Reading an object path re-saves its bytes rather than short-circuiting through a reverse path lookup. Normalization passes an already-normalized image through byte-identically, so the re-save deduplicates to the same content-addressed reference; a store test pins that idempotency for a re-encoded object. No reference proof is required at the tool: object paths are unguessable content digests, the published objects are already readable through the mounted filesystem (Bash included), and the session-reference gate continues to protect the remote client RPC, which is the boundary where an attachment id alone grants bytes. - -Two diagnostics are sharpened alongside: `INVALID_IMAGE` admission failures now name the offending path instead of surfacing the store's bare message, and an extension-less admission mismatch blames the file signature rather than a nonexistent extension. - -## Consequences - -The model reads a descriptor's normalized attachment path directly, in native and PTC modes, without copying, renaming, or re-uploading; recorded scenarios `read-image-attachment-path` and `ptc-read-image-attachment-path` pin both flows end to end, including deduplication to the stored reference. Ordinary extension-less image files become readable through the same content identification, while a wrong-extension path keeps its fast pre-I/O refusal and repair message. Any future consumer accepting extension-less image paths can reuse `sniffImageMediaType` instead of a second signature table. - -## Alternatives considered - -**Name objects with an extension on disk.** This changes the storage layout, dedup commit path, corrupt checks, export archive, and every committed object-path expectation, only to satisfy the tool's extension heuristic, and the heuristic itself — extension as media-type authority — stays wrong. The store already treats decoded content as the authority. - -**Instruct the model to copy the object before reading.** Prompt guidance does not stop direct calls, so the misleading refusal survives; the copy adds a filesystem write and a turn for a pure read; and the re-read commits the identical bytes to the same reference anyway, so the copy changes nothing but cost. diff --git a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md b/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md deleted file mode 100644 index 547c62cd9a..0000000000 --- a/.agents/notes/implemented/feature/2026-08-28-read-image-extensionless-attachment-paths.zh.md +++ /dev/null @@ -1,27 +0,0 @@ -# Agent Note: read_image 接受无扩展名的附件对象路径 - -Status: implemented - -[English](2026-08-28-read-image-extensionless-attachment-paths.md) | 中文 - -## 问题 - -模型可见的图片描述会给出规范化附件的本地只读路径，而规范化对象是不带图片扩展名的内容寻址文件。`read_image` 仅凭扩展名把 `file_path` 映射到媒体类型并拒绝其余一切，于是把描述里的路径原样传回会得到 `read_image only accepts PNG/JPEG/WebP/GIF paths`，尽管该图片已经通过存储校验并持久保存。模型只能把对象复制成改名文件或要求重新上传。 - -## 决定 - -扩展名命名四种受支持格式之一时仍作为声明的媒体类型，该分支的所有既有检查和诊断保持不变。对无扩展名的路径，工具在既有字节上限内读取字节，用 `sniffImageMediaType` 识别容器格式，这是附件 Service Definition 包导出的纯文件签名辅助函数。识别出的类型随后经过同一套部署媒体类型政策和 `saveImage` 准入，存储实现的完整解码仍是权威；扩展名声明了非图片格式的路径在任何 I/O 之前被拒绝。这把[最小 read_image 工具笔记](2026-08-10-minimal-read-image-tool.zh.md)中对嗅探的拒绝收窄到带扩展名的路径：扩展名仍是不匹配即失败的声明，而什么也没声明的路径按其字节识别。 - -读取对象路径会重新保存其字节，而不是通过反向路径查找走捷径。归一化让已归一化的图片字节原样通过，因此重新保存会去重到同一个内容寻址引用；一个存储测试固定了重编码对象的这一幂等性。工具处不需要会话引用证明：对象路径是不可猜测的内容摘要，已发布对象本来就能通过挂载的文件系统（包括 Bash）读到，而会话引用检查继续保护远程客户端 RPC，那才是仅凭附件 id 就能获得字节的边界。 - -顺带收紧了两处诊断：`INVALID_IMAGE` 准入失败现在会指出出错的路径而不是透传存储的裸消息，无扩展名路径的准入不匹配归因于文件签名而不是不存在的扩展名。 - -## 影响 - -模型在 native 和 PTC 两种模式下都可以直接读取描述中的规范化附件路径，无需复制、改名或重新上传；录制场景 `read-image-attachment-path` 和 `ptc-read-image-attachment-path` 端到端固定了这两条流程，包括去重到已存储引用。普通的无扩展名图片文件也通过同一套内容识别变得可读，而扩展名错误的路径保留 I/O 之前的快速拒绝和修复消息。将来任何接受无扩展名图片路径的消费方都可以复用 `sniffImageMediaType`，不必再维护一张签名表。 - -## 考虑过的替代方案 - -**在磁盘上给对象命名加扩展名。** 这会改动存储布局、去重提交路径、损坏检查、导出归档以及每一处已提交的对象路径期望，只为迁就工具的扩展名启发式，而启发式本身（以扩展名为媒体类型权威）依然是错的。存储实现一直以解码内容为权威。 - -**指示模型先复制对象再读取。** 提示词挡不住直接调用，误导性的拒绝依然存在；复制为一次纯读取平添一次文件系统写入和一轮往返；重新读取本来就会把相同字节提交到同一引用，复制除了成本什么也不改变。 diff --git a/docs/subsystems/attachment.i18n.yaml b/docs/subsystems/attachment.i18n.yaml index 9f3d160b0a..8e69eaae28 100644 --- a/docs/subsystems/attachment.i18n.yaml +++ b/docs/subsystems/attachment.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/attachment.md -attachment.md: e93e6782eae97811be2060807a867d3036931a8c -attachment.zh.md: a0167cec6d1ddd8a06bdd7501edcb3d1c6ababe5 +attachment.md: 15daa2b8d541ba847d48f5c43a06c1c537df6d11 +attachment.zh.md: c74a18f6bec63e117afcdb141512be04f8d75f9a diff --git a/docs/subsystems/attachment.md b/docs/subsystems/attachment.md index e93e6782ea..15daa2b8d5 100644 --- a/docs/subsystems/attachment.md +++ b/docs/subsystems/attachment.md @@ -10,7 +10,7 @@ Source: [`packages/attachment/attachment/src/types.ts`](../../packages/attachmen ## Identity and verified metadata -`AttachmentId` is a branded opaque string. The local backend currently emits `sha256:`, but consumers must neither parse that representation nor derive a filesystem path from it. A consumer may ask the attachment provider for its object location through `imageHostPath()`, then must use the current execution filesystem to decide whether model tools can read that host path. The model may pass such a path back to `read_image` directly: extension-less files are identified from their file signature, and re-saving a normalized object deduplicates to the same content-addressed reference. +`AttachmentId` is a branded opaque string. The local backend currently emits `sha256:`, but consumers must neither parse that representation nor derive a filesystem path from it. A consumer may ask the attachment provider for its object location through `imageHostPath()`, then must use the current execution filesystem to decide whether model tools can read that host path. ```ts type-equiv /** Raster image formats accepted by the version-one attachment path. */ diff --git a/docs/subsystems/attachment.zh.md b/docs/subsystems/attachment.zh.md index a0167cec6d..c74a18f6be 100644 --- a/docs/subsystems/attachment.zh.md +++ b/docs/subsystems/attachment.zh.md @@ -10,7 +10,7 @@ ## 标识与经过校验的元数据 -`AttachmentId` 是带类型标记的不透明字符串。本地后端目前生成 `sha256:`，但消费方既不能解析这种表示，也不能据此派生文件系统路径。消费方可以通过 `imageHostPath()` 询问附件提供方所持对象的位置，然后必须由当前执行文件系统判断模型工具能否读取该宿主路径。模型可以把这样的路径直接传回 `read_image`：无扩展名文件按文件签名识别格式，重新保存规范化对象会去重到同一个内容寻址引用。 +`AttachmentId` 是带类型标记的不透明字符串。本地后端目前生成 `sha256:`，但消费方既不能解析这种表示，也不能据此派生文件系统路径。消费方可以通过 `imageHostPath()` 询问附件提供方所持对象的位置，然后必须由当前执行文件系统判断模型工具能否读取该宿主路径。 ```ts type-equiv /** Raster image formats accepted by the version-one attachment path. */ diff --git a/packages/attachment/attachment-local/tests/store.spec.ts b/packages/attachment/attachment-local/tests/store.spec.ts index e1c5a788d6..3ff58eb2da 100644 --- a/packages/attachment/attachment-local/tests/store.spec.ts +++ b/packages/attachment/attachment-local/tests/store.spec.ts @@ -172,28 +172,6 @@ describe('local attachment store', () => { expect(String(saved.attachmentId)).toBe(`sha256:${createHash('sha256').update(read.data).digest('hex')}`) }) - it('re-saves a re-encoded normalized object byte-identically to the same reference', async () => { - const storageRoot = await root() - const oversized = new Uint8Array(await sharp({ - create: { width: 4, height: 4, channels: 3, background: { r: 9, g: 9, b: 9 } }, - }).png().toBuffer()) - const policy = { maxPixels: POLICY.maxPixels, maxDimension: 2, maxBytes: 1024 * 1024 } - const saved = await saveImageFile(storageRoot, { - data: oversized, mediaType: 'image/png', name: 'big.png', - }, { ...LIMITS, maxImagePixels: 64 }, policy) - - // Normalization passes an already-normalized object through unchanged, so - // reading the object file and saving those bytes again deduplicates: the - // read_image tool can accept object paths without minting new attachments. - const objectBytes = (await readImageFile(storageRoot, saved)).data - const resaved = await saveImageFile(storageRoot, { - data: objectBytes, mediaType: saved.mediaType, name: 'big', - }, { ...LIMITS, maxImagePixels: 64 }, policy) - expect(resaved.attachmentId).toBe(saved.attachmentId) - expect(resaved.bytes).toBe(saved.bytes) - expect(resaved.originalDimensions).toBeUndefined() - }) - it('keeps admitted history readable after deployment limits become stricter', async () => { const storageRoot = await root() const ref = await saveImageFile(storageRoot, { data: PNG, mediaType: 'image/png' }, LIMITS, POLICY) diff --git a/packages/attachment/attachment/README.i18n.yaml b/packages/attachment/attachment/README.i18n.yaml index aac868951f..e67d95604d 100644 --- a/packages/attachment/attachment/README.i18n.yaml +++ b/packages/attachment/attachment/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/attachment/attachment/README.md -README.md: feb8b14a2a46543169820e444994ef7cb1514210 -README.zh.md: 0f088e170cde9fb27032351dc1f9861c9111b6fd +README.md: 01a5d6ee143ff53175dd7327cd6d419af61938a3 +README.zh.md: 1a1d297297a6815ce5338391af0182e471f99000 diff --git a/packages/attachment/attachment/README.md b/packages/attachment/attachment/README.md index feb8b14a2a..01a5d6ee14 100644 --- a/packages/attachment/attachment/README.md +++ b/packages/attachment/attachment/README.md @@ -67,7 +67,7 @@ This section explains the design decisions behind the seam and the service opera ### Service operations -The service family runs one admission-and-storage flow: every entry point enforces source batch limits and canonical base64, prepares provider-independent normalized attachments before publishing any member, and commits them durably in input order without partial results. `readImageRequest` derives deterministic route-sized variants whose identity includes the attachment id, transform version, pixel and byte budgets, and encoder settings. The pure `requestImageDimensions` export computes each projection's aspect-preserving dimensions from a total-pixel budget, so providers and request pricing share one geometry. The pure `sniffImageMediaType` export identifies a supported container from its file signature for consumers that accept extension-less image paths; persisting callers keep the store's full decode authoritative. `imageHostPath` exposes an implementation-owned host location only to trusted same-process consumers that need execution-world mapping. Callers compose ordered batches while the implementation owns compression concurrency, caching, and singleflight. Reads and projections preserve caller cancellation. Failures carry stable machine-readable codes, and the caller-correctable admission subset is recognizable at runtime so each protocol adapter maps its own vocabulary; the exact per-operation contracts live in [`src/index.ts`](src/index.ts) and [`src/error.ts`](src/error.ts). +The service family runs one admission-and-storage flow: every entry point enforces source batch limits and canonical base64, prepares provider-independent normalized attachments before publishing any member, and commits them durably in input order without partial results. `readImageRequest` derives deterministic route-sized variants whose identity includes the attachment id, transform version, pixel and byte budgets, and encoder settings. The pure `requestImageDimensions` export computes each projection's aspect-preserving dimensions from a total-pixel budget, so providers and request pricing share one geometry. `imageHostPath` exposes an implementation-owned host location only to trusted same-process consumers that need execution-world mapping. Callers compose ordered batches while the implementation owns compression concurrency, caching, and singleflight. Reads and projections preserve caller cancellation. Failures carry stable machine-readable codes, and the caller-correctable admission subset is recognizable at runtime so each protocol adapter maps its own vocabulary; the exact per-operation contracts live in [`src/index.ts`](src/index.ts) and [`src/error.ts`](src/error.ts). ### Source map @@ -77,7 +77,6 @@ The service family runs one admission-and-storage flow: every entry point enforc | [`src/types.ts`](src/types.ts) | Durable vocabulary: references, limits, upload and store payloads | | [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`: canonical-base64 enforcement, then `saveImages` delegation | | [`src/error.ts`](src/error.ts) | `AttachmentError` class and the `isImageAdmissionError` runtime subset | -| [`src/sniff.ts`](src/sniff.ts) | `sniffImageMediaType`: file-signature container identification | | [`src/brand.ts`](src/brand.ts) | `AttachmentId` branded opaque identifier | | [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; implementations enforce immutable-store checks) | diff --git a/packages/attachment/attachment/README.zh.md b/packages/attachment/attachment/README.zh.md index 0f088e170c..1a1d297297 100644 --- a/packages/attachment/attachment/README.zh.md +++ b/packages/attachment/attachment/README.zh.md @@ -67,7 +67,7 @@ kind: "package-reference" ### 服务操作 -服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。纯函数导出 `sniffImageMediaType` 按文件签名识别受支持的图片容器，供接受无扩展名图片路径的消费方使用；持久化调用方仍以存储实现的完整解码为权威。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。 +服务族运行同一条准入与存储流程：每个入口都强制执行源批次限制与规范 base64，在发布任何成员前准备提供方无关的规范化附件，再按输入顺序持久提交而不产生部分结果。`readImageRequest` 派生确定性的路由尺寸变体，其身份包含附件 id、变换版本、像素与字节预算及编码参数。纯函数导出 `requestImageDimensions` 会按总像素预算计算每个投影保持宽高比的尺寸，使提供方与请求定价共享同一套几何计算。`imageHostPath` 只向需要执行世界映射的受信任同进程消费方暴露实现拥有的宿主位置。调用方组合有序批次，而实现拥有压缩并发、缓存与 singleflight。读取和投影保留调用方的取消语义。失败带有稳定且机器可读的错误码，运行时即可识别可由调用方修正的准入子集，让每个协议适配器映射自己的词汇；各操作的确切约定见 [`src/index.ts`](src/index.ts) 与 [`src/error.ts`](src/error.ts)。 ### 源码地图 @@ -77,7 +77,6 @@ kind: "package-reference" | [`src/types.ts`](src/types.ts) | 持久词汇：引用、限额、上传与存储载荷 | | [`src/admission.ts`](src/admission.ts) | `admitEncodedImages`：规范 base64 强制，随后委托 `saveImages` | | [`src/error.ts`](src/error.ts) | `AttachmentError` 类与 `isImageAdmissionError` 运行时子集 | -| [`src/sniff.ts`](src/sniff.ts) | `sniffImageMediaType`：按文件签名识别图片容器 | | [`src/brand.ts`](src/brand.ts) | `AttachmentId` 带类型标记的不透明标识符 | | [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；实现负责强制不可变存储检查） | diff --git a/packages/attachment/attachment/src/index.ts b/packages/attachment/attachment/src/index.ts index 89df5e52c6..4ee001b86c 100644 --- a/packages/attachment/attachment/src/index.ts +++ b/packages/attachment/attachment/src/index.ts @@ -16,7 +16,6 @@ export { AttachmentError, isImageAdmissionError } from './error.ts' export type { AttachmentErrorCode, ImageAdmissionErrorCode } from './error.ts' export { admitEncodedImages } from './admission.ts' export { requestImageDimensions } from './request-projection.ts' -export { sniffImageMediaType } from './sniff.ts' export type { AttachmentId as AttachmentIdType, EncodedImageAttachment, diff --git a/packages/attachment/attachment/src/sniff.ts b/packages/attachment/attachment/src/sniff.ts deleted file mode 100644 index 9782d2ffda..0000000000 --- a/packages/attachment/attachment/src/sniff.ts +++ /dev/null @@ -1,39 +0,0 @@ -/** - * Leading-byte image-format identification for consumers that accept image - * files without a media-type-bearing file name, such as normalized attachment - * object paths. The result names the container the signature claims; callers - * that persist bytes keep the attachment service's full decode authoritative. - * @module @deepseek-ai/dsh-attachment/src/sniff - */ - -import type { ImageMediaType } from './types.ts' - -const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const -const JPEG_SIGNATURE = [0xff, 0xd8, 0xff] as const - -function matchesBytes(data: Uint8Array, offset: number, expected: readonly number[]): boolean { - if (data.byteLength < offset + expected.length) return false - return expected.every((byte, index) => data[offset + index] === byte) -} - -function matchesAscii(data: Uint8Array, offset: number, text: string): boolean { - if (data.byteLength < offset + text.length) return false - for (let index = 0; index < text.length; index += 1) { - if (data[offset + index] !== text.charCodeAt(index)) return false - } - return true -} - -/** - * Identify a supported image container from its file signature. - * @param data - the leading file bytes; passing the complete file is fine. - * @returns the media type the signature claims, or undefined when the bytes - * carry no complete PNG/JPEG/WebP/GIF signature. - */ -export function sniffImageMediaType(data: Uint8Array): ImageMediaType | undefined { - if (matchesBytes(data, 0, PNG_SIGNATURE)) return 'image/png' - if (matchesBytes(data, 0, JPEG_SIGNATURE)) return 'image/jpeg' - if (matchesAscii(data, 0, 'GIF87a') || matchesAscii(data, 0, 'GIF89a')) return 'image/gif' - if (matchesAscii(data, 0, 'RIFF') && matchesAscii(data, 8, 'WEBP')) return 'image/webp' - return undefined -} diff --git a/packages/attachment/attachment/tests/sniff.spec.ts b/packages/attachment/attachment/tests/sniff.spec.ts deleted file mode 100644 index e081abd9697521297206244cbb4369d7d0dd600c..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1464 zcmbtTU2EGg6y39b#eK6JT-k$-I)x2dNJbt8Ve7}k*n@0cIU2QWB)Lr}`R|kLINsWn ze#DrA9n6_zZZIMG!E6b!p9fLxq zPbz5)n1R8>z!V3wa>J0fLZCJjCP@&;$`il?a5ROMImUqN1`8X5w6F!C>k7g})2s5xp9QS46L*HN$yf^vd|E+*qT)SE|srR!`OL%RN)di>-Zc6jPBZe|zD>tzN{B;8})begtN;N0^;=<{WuRUCzD4Db3>+ZAfaH!kNf zSnUGKe61cgNY(1(2JdW;AeJiHpzkQe{*&cWu^^&Nbd_FKP!WR&ns lO7{soj&#W1d+5ffOjGurC3gh-l$>ABj;DEs!3E5{e*r&i-dX?v diff --git a/packages/fs/tool-fs/README.i18n.yaml b/packages/fs/tool-fs/README.i18n.yaml index b2de0de1b6..8705144163 100644 --- a/packages/fs/tool-fs/README.i18n.yaml +++ b/packages/fs/tool-fs/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/fs/tool-fs/README.md -README.md: 31e7b4c900cbd6cb232dac229eb93abde88b6042 -README.zh.md: c962f0028d56eb52e577828bf7b3e56a90b4e9d1 +README.md: f00c96d18619e0fb59609eb66729ebfce445dbc6 +README.zh.md: 5915e5a07de10775469d0ebe301564948b357569 diff --git a/packages/fs/tool-fs/README.md b/packages/fs/tool-fs/README.md index 31e7b4c900..f00c96d186 100644 --- a/packages/fs/tool-fs/README.md +++ b/packages/fs/tool-fs/README.md @@ -65,6 +65,8 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a ### Policy and sandbox behavior +Path authorization for `read` and `read_image` belongs entirely to `ctx.fs`; media-type declarations and file signatures only decide whether `read_image` accepts the bytes returned by that backend. + With the policy plugin mounted, `write` and `edit` obtain their guard from the `fs/*` intent slots, so an unread target or a stale observation fails with `FS_NOT_OBSERVED` or `FS_STALE_VERSION` and a recovery instruction. Under a confining backend (`fs-sandbox`), `write`/`edit` additionally advertise `sandbox_permissions` and `justification`; a denied mutation returns the `[sandbox: file access denied under mode]` marker with the same-turn escalation hint, and an approved retry may stamp a strictly wider mode for that one call. ### Failures and recovery diff --git a/packages/fs/tool-fs/README.zh.md b/packages/fs/tool-fs/README.zh.md index c962f0028d..5915e5a07d 100644 --- a/packages/fs/tool-fs/README.zh.md +++ b/packages/fs/tool-fs/README.zh.md @@ -65,6 +65,8 @@ kind: "package-reference" ### 策略与沙箱行为 +`read` 与 `read_image` 的路径授权完全由 `ctx.fs` 负责；媒体类型声明和文件签名只决定 `read_image` 是否接受该后端返回的字节。 + 挂载策略插件后，`write` 与 `edit` 从 `fs/*` 意图槽位取得防护，因此未读目标或陈旧观察会以 `FS_NOT_OBSERVED` 或 `FS_STALE_VERSION` 及恢复指令失败。使用施加沙箱限制的后端（`fs-sandbox`）时，`write`/`edit` 还会公开 `sandbox_permissions` 与 `justification`；被拒绝的变更返回 `[sandbox: file access denied under mode]` 标记与同轮次升级提示，获批的重试可以在该次调用中加盖严格更宽的模式。 ### 失败与恢复 diff --git a/packages/fs/tool-fs/src/read-image.ts b/packages/fs/tool-fs/src/read-image.ts index 5941d85777..508d18de7a 100644 --- a/packages/fs/tool-fs/src/read-image.ts +++ b/packages/fs/tool-fs/src/read-image.ts @@ -1,8 +1,8 @@ /** * The model-facing `read_image` tool commits a PNG/JPEG/WebP/GIF file. A path - * without a file extension — normalized attachment objects are named by their - * content digest alone — is accepted too: its format comes from the file - * signature, and the attachment service's full decode stays authoritative. + * without a file extension is identified from its file signature, while the + * attachment service's full decode stays authoritative. The mounted `ctx.fs` + * backend owns path resolution and read access; names only declare media type. * * The route gate is deliberately stricter than the host upload preflight. An * image-reading tool is useful only when the exact calling route can inspect @@ -13,7 +13,7 @@ import { basename, extname } from 'node:path' import type { Context } from '@deepseek-ai/cordis' -import { AttachmentError, AttachmentId, sniffImageMediaType } from '@deepseek-ai/dsh-attachment' +import { AttachmentError, AttachmentId } from '@deepseek-ai/dsh-attachment' import type { AttachmentStore, ImageAttachmentRef, ImageMediaType } from '@deepseek-ai/dsh-attachment' import type { ContentBlock } from '@deepseek-ai/dsh-llm' import { defineTool } from '@deepseek-ai/dsh-tools' @@ -30,6 +30,35 @@ const IMAGE_EXTENSIONS: Readonly> = { '.gif': 'image/gif', } +const PNG_SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] as const +const JPEG_SIGNATURE = [0xff, 0xd8, 0xff] as const + +function matchesBytes(data: Uint8Array, offset: number, expected: readonly number[]): boolean { + if (data.byteLength < offset + expected.length) return false + return expected.every((byte, index) => data[offset + index] === byte) +} + +function matchesAscii(data: Uint8Array, offset: number, value: string): boolean { + if (data.byteLength < offset + value.length) return false + for (let index = 0; index < value.length; index += 1) { + if (data[offset + index] !== value.charCodeAt(index)) return false + } + return true +} + +/** + * Identify the media type declared by a supported image file signature. + * @param data - file bytes read through the current filesystem backend. + * @returns the detected supported media type, or undefined for other bytes. + */ +export function sniffImageMediaType(data: Uint8Array): ImageMediaType | undefined { + if (matchesBytes(data, 0, PNG_SIGNATURE)) return 'image/png' + if (matchesBytes(data, 0, JPEG_SIGNATURE)) return 'image/jpeg' + if (matchesAscii(data, 0, 'GIF87a') || matchesAscii(data, 0, 'GIF89a')) return 'image/gif' + if (matchesAscii(data, 0, 'RIFF') && matchesAscii(data, 8, 'WEBP')) return 'image/webp' + return undefined +} + const IMAGE_VALUE_SCHEMA = { type: 'object', additionalProperties: false, @@ -264,7 +293,7 @@ export function applyReadImageTool(ctx: Context): void { { cause: error }, ) } - if (error.code === 'INVALID_IMAGE') { + if (error.code === 'INVALID_IMAGE' && declared === undefined) { throw new Error( `cannot read "${target.displayPath}": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image; the file may be truncated or corrupt`, { cause: error }, diff --git a/packages/fs/tool-fs/tests/read-image.spec.ts b/packages/fs/tool-fs/tests/read-image.spec.ts index f0f0802198..2ac096429e 100644 --- a/packages/fs/tool-fs/tests/read-image.spec.ts +++ b/packages/fs/tool-fs/tests/read-image.spec.ts @@ -29,16 +29,13 @@ import { formatImageReadOutput, imageMediaTypeForPath, imageRefFromValue, + sniffImageMediaType, } from '../src/read-image.ts' /** 1x1 red PNG (valid signature, IHDR, IDAT). */ const PNG_1X1 = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC', 'base64') /** 3x3 red PNG used to trip a tiny configured pixel limit. */ const PNG_3X3 = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAMAAAADCAIAAADZSiLoAAAAEElEQVR4nGP4z8AAQQxYWACPjgj4kWPEuQAAAABJRU5ErkJggg==', 'base64') -/** 1x1 red JPEG already inside every normalization limit (byte-identical passthrough). */ -const JPEG_1X1 = Buffer.from('/9j/2wBDAAYEBQYFBAYGBQYHBwYIChAKCgkJChQODwwQFxQYGBcUFhYaHSUfGhsjHBYWICwgIyYnKSopGR8tMC0oMCUoKSj/2wBDAQcHBwoIChMKChMoGhYaKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj/wAARCAABAAEDASIAAhEBAxEB/8QAFQABAQAAAAAAAAAAAAAAAAAAAAf/xAAUEAEAAAAAAAAAAAAAAAAAAAAA/8QAFQEBAQAAAAAAAAAAAAAAAAAABgj/xAAUEQEAAAAAAAAAAAAAAAAAAAAA/9oADAMBAAIRAxEAPwCdABykX//Z', 'base64') -/** 1x1 red WebP already inside every normalization limit (byte-identical passthrough). */ -const WEBP_1X1 = Buffer.from('UklGRjwAAABXRUJQVlA4IDAAAADQAQCdASoBAAEAAUAmJaACdLoB+AADsAD+8ut//NgVzXPv9//S4P0uD9Lg/9KQAAA=', 'base64') const testToolSignal = new AbortController().signal @@ -170,6 +167,30 @@ describe('imageMediaTypeForPath', () => { }) }) +function ascii(value: string): Uint8Array { + return new TextEncoder().encode(value) +} + +describe('sniffImageMediaType', () => { + it('identifies each supported container from its complete signature', () => { + expect(sniffImageMediaType(Uint8Array.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00]))).toBe('image/png') + expect(sniffImageMediaType(Uint8Array.from([0xff, 0xd8, 0xff, 0xe0]))).toBe('image/jpeg') + expect(sniffImageMediaType(ascii('GIF87a...'))).toBe('image/gif') + expect(sniffImageMediaType(ascii('GIF89a...'))).toBe('image/gif') + expect(sniffImageMediaType(ascii('RIFF\0\0\0\0WEBPVP8 '))).toBe('image/webp') + }) + + it('returns undefined for other bytes, incomplete signatures, and non-WebP RIFF containers', () => { + expect(sniffImageMediaType(new Uint8Array())).toBeUndefined() + expect(sniffImageMediaType(ascii('plain text'))).toBeUndefined() + expect(sniffImageMediaType(Uint8Array.from([0x89, 0x50, 0x4e]))).toBeUndefined() + expect(sniffImageMediaType(Uint8Array.from([0xff, 0xd8]))).toBeUndefined() + expect(sniffImageMediaType(ascii('GIF90a'))).toBeUndefined() + expect(sniffImageMediaType(ascii('RIFF\0\0\0\0WAVE'))).toBeUndefined() + expect(sniffImageMediaType(ascii('RIFF\0\0\0'))).toBeUndefined() + }) +}) + describe('imageRefFromValue', () => { it('re-brands with and without the optional display name', () => { const base = { attachmentId: 'sha256:00', mediaType: 'image/png' as const, bytes: 1, width: 1, height: 1 } @@ -291,44 +312,6 @@ describe('extension-less paths', () => { expect(text(second)).toContain(`${objectPath}`) }) - it.each([ - ['image/jpeg', JPEG_1X1], - ['image/webp', WEBP_1X1], - ] as const)('dedups a re-read %s object to its stored reference', async (mediaType, bytes) => { - const ctx = await setup() - const attachments = mountedStore(ctx) - const ref = await attachments.saveImage({ data: bytes, mediaType, name: 'source' }) - const result = await readImage(ctx, { file_path: objectPathOf(attachments, ref) }, agentOn('vision-model')) - expect(result.isError).toBe(false) - const reread = (result.content[1] as { attachment: ImageAttachmentRef }).attachment - expect(reread.attachmentId).toBe(ref.attachmentId) - expect(reread.mediaType).toBe(mediaType) - }) - - it('forwards an attachment object path read through the outer run_code context', async () => { - const ctx = await setup({ toolMode: 'ptc' }) - const attachments = mountedStore(ctx) - const ref = await attachments.saveImage({ data: PNG_1X1, mediaType: 'image/png', name: 'red.png' }) - const objectPath = objectPathOf(attachments, ref) - const runtime = ctx.codeRuntime as FakeRuntime - runtime.behavior = async (request) => { - const value = await request.bindings[0]!.functions.read_image!({ file_path: objectPath }) - return { logs: [], value } - } - - const result = await call(ctx, RUN_CODE_NAME, { - code: 'return await tools.read_image({ file_path: attachmentPath })', - description: 'Read the attachment object through PTC mode', - }, agentOn('vision-model')) - - expect(result.isError).toBe(false) - const forwarded = result.additionalContexts?.[0]?.content - expect(forwarded?.[1]).toMatchObject({ - type: 'image', - attachment: { attachmentId: ref.attachmentId, mediaType: 'image/png' }, - }) - }) - it('reads an ordinary extension-less image file by sniffing its content', async () => { await writeFile(join(dir, 'avatar'), PNG_1X1) const ctx = await setup() @@ -369,14 +352,6 @@ describe('extension-less paths', () => { expect(text(result)).toContain('do not decode as a supported PNG/JPEG/WebP/GIF image') }) - it('reports a missing attachment object through the fs vocabulary', async () => { - const ctx = await setup() - const bogus = join(home, 'attachments', 'v1', 'objects', 'ab', 'ab'.repeat(32)) - const result = await readImage(ctx, { file_path: bogus }, agentOn('vision-model')) - expect(result.isError).toBe(true) - expect(text(result)).toContain('not found') - }) - it('applies the deployment media-type policy to the sniffed format', async () => { /** Store whose deployment accepts JPEG only; sniffed PNG bytes must refuse before any save. */ class JpegOnlySniffStore extends AttachmentStore { @@ -561,18 +536,10 @@ describe('image admission failures', () => { expect(text(result)).toContain('rename the file to match its actual format if it is PNG/JPEG/WebP/GIF, or convert it to one of those formats') }) - it('explains a named image file whose bytes do not decode', async () => { - await writeFile(join(dir, 'broken.png'), PNG_1X1.subarray(0, 16)) - const ctx = await setup() - const result = await readImage(ctx, { file_path: 'broken.png' }, agentOn('vision-model')) - expect(result.isError).toBe(true) - expect(text(result)).toContain(`cannot read "${join(dir, 'broken.png')}": the bytes do not decode as a supported PNG/JPEG/WebP/GIF image`) - }) - - it('fails with FS_TOO_LARGE before reading a file past maxImageBytes', async () => { - await writeFile(join(dir, 'red.png'), PNG_1X1) + it('caps an extension-less read at maxImageBytes before format detection', async () => { + await writeFile(join(dir, 'red'), PNG_1X1) const ctx = await setup({ storeConfig: { maxImageBytes: PNG_1X1.length - 1 } }) - const result = await readImage(ctx, { file_path: 'red.png' }, agentOn('vision-model')) + const result = await readImage(ctx, { file_path: 'red' }, agentOn('vision-model')) expect(result.isError).toBe(true) expect(text(result)).toContain('exceeds') }) From 51a6eabb2796209d2975ea08145ed76336a71598 Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Fri, 28 Aug 2026 17:36:55 +0800 Subject: [PATCH 21/63] perf(api): replace shift-backed stream queues --- ...-08-28-linear-stream-queue-drain.i18n.yaml | 6 + .../2026-08-28-linear-stream-queue-drain.md | 56 ++++++++++ ...2026-08-28-linear-stream-queue-drain.zh.md | 56 ++++++++++ docs/config-catalog.i18n.yaml | 4 +- docs/config-catalog.md | 3 +- docs/config-catalog.zh.md | 3 +- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 3 + docs/module-graph.zh.md | 3 + packages/api/gateway/package.json | 1 + .../api/gateway/src/client/stream-client.ts | 11 +- packages/api/gateway/src/index.ts | 7 +- packages/api/gateway/tsconfig.client.json | 3 + packages/api/gateway/tsconfig.host.json | 3 + packages/api/remotes/package.json | 1 + packages/api/remotes/src/index.ts | 11 +- packages/api/remotes/tsconfig.host.json | 3 + packages/api/session-controller/package.json | 1 + .../api/session-controller/src/control.ts | 9 +- .../api/session-controller/src/history.ts | 11 +- .../api/session-controller/tsconfig.host.json | 1 + .../api/workspace-controller/package.json | 1 + packages/api/workspace-controller/src/feed.ts | 9 +- .../workspace-controller/tsconfig.host.json | 1 + packages/client/tsdown.client.ts | 2 +- packages/util/README.i18n.yaml | 4 +- packages/util/README.md | 5 +- packages/util/README.zh.md | 5 +- packages/util/deque/README.i18n.yaml | 6 + packages/util/deque/README.md | 104 ++++++++++++++++++ packages/util/deque/README.zh.md | 104 ++++++++++++++++++ packages/util/deque/benchmarks/drain.ts | 36 ++++++ packages/util/deque/package.json | 42 +++++++ packages/util/deque/src/index.ts | 95 ++++++++++++++++ packages/util/deque/src/invariant.ts | 30 +++++ packages/util/deque/tests/deque.spec.ts | 70 ++++++++++++ packages/util/deque/tests/invariant.spec.ts | 18 +++ packages/util/deque/tsconfig.json | 15 +++ pnpm-lock.yaml | 21 ++++ scripts/client-bundle-purity.spec.ts | 3 +- scripts/doc-standard.spec.ts | 1 + .../verify-package-readme-model-experience.ts | 1 + tsconfig.base.json | 2 + tsconfig.host.json | 1 + 44 files changed, 737 insertions(+), 39 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md create mode 100644 .agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md create mode 100644 packages/util/deque/README.i18n.yaml create mode 100644 packages/util/deque/README.md create mode 100644 packages/util/deque/README.zh.md create mode 100644 packages/util/deque/benchmarks/drain.ts create mode 100644 packages/util/deque/package.json create mode 100644 packages/util/deque/src/index.ts create mode 100644 packages/util/deque/src/invariant.ts create mode 100644 packages/util/deque/tests/deque.spec.ts create mode 100644 packages/util/deque/tests/invariant.spec.ts create mode 100644 packages/util/deque/tsconfig.json diff --git a/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.i18n.yaml new file mode 100644 index 0000000000..db7441ec9f --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.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-28-linear-stream-queue-drain.md +2026-08-28-linear-stream-queue-drain.md: e92dd03ef52ead44b083f997f83746cee03af97f +2026-08-28-linear-stream-queue-drain.zh.md: 1d0ff4813b8a7e61e196cbdc63bab0c501d49e11 diff --git a/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md new file mode 100644 index 0000000000..e92dd03ef5 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md @@ -0,0 +1,56 @@ +# Agent Note: Linear drain for long-lived stream queues + +Status: implemented + +English | [中文](2026-08-28-linear-stream-queue-drain.zh.md) + +## Problem + +Long-lived stream queues can accumulate thousands of frames while their consumers are busy. Removing each frame with `Array.prototype.shift()` moves the remaining array range on the observed V8 path, so draining `N` queued frames performs quadratic reference movement and delays unrelated work on the same event loop. [Issue #3270](https://github.com/deepseek-harness/deepseek-harness/issues/3270) records the production sample that identified `ArrayShift`, `MoveRange`, and `memmove` as the dominant stack. + +The affected streams have different wake-up, failure, cancellation, and disposal behavior. Their shared requirement is storage that preserves FIFO order without making those lifecycle decisions. + +## Decision + +`@deepseek-ai/dsh-deque` owns one zero-dependency circular array for Host and browser consumers. `pushBack()`, `pushFront()`, and `popFront()` change indices instead of moving the live range. A removal clears its slot immediately. The backing array doubles when full and halves when a non-empty deque reaches one quarter of capacity, so growth and compaction copy work remains amortized constant time and vacant storage stays bounded over interleaved queue use. + +The package has no singleton state, symbols, or class identity shared between Client plugins, so the Client bundle purity rule treats it as an inline-safe library. The Gateway browser artifact carries its deque implementation without introducing a module-table entry or a Cordis service. + +The Host Remote event source, each connected Client Remote event queue, the browser Remote stream inbox, each Session history follower, each Session control stream, and each Workspace follower store frames in this deque. Their owning classes retain all wake-up, failure, cancellation, buffered-drain, and disposal behavior. Session history uses front insertion to place constructor-seed events before live events received during its opening observation. + +Queue capacity, frame coalescing, overload rejection, and global agent admission remain consumer or application policy. The deque does not infer any of them from storage pressure. + +## Verification + +The deque unit suite covers FIFO order, front insertion, array-boundary wrapping, geometric growth, quarter-full compaction after interleaved enqueue and dequeue, clearing, reuse, and `undefined` entries. Focused coverage reports 100% statements, branches, functions, and lines for `packages/util/deque/src/index.ts`. + +The API Remote, Gateway, Session control/history, and Workspace follow suites exercise the migrated lifecycle behavior. They retain their package-owned ordering, failure, cancellation, and disposal assertions. + +The command `pnpm exec tsx packages/util/deque/benchmarks/drain.ts` ran on Node v26.0.0, arm64 macOS 26.4. Five samples per size produced these median deque drain times; enqueue time is outside the measurement: + +| Entries | Median drain | Nanoseconds per entry | +|---:|---:|---:| +| 250,000 | 1.705 ms | 6.818 ns | +| 500,000 | 2.541 ms | 5.082 ns | +| 1,000,000 | 4.668 ms | 4.668 ns | +| 2,000,000 | 9.656 ms | 4.828 ns | + +The checked-in benchmark makes the measurement reproducible, but CI does not enforce a wall-clock threshold. Deterministic unit coverage owns the algorithm and compaction paths; the benchmark demonstrates approximately linear drain work on the recorded runtime. + +## Alternatives considered + +**Array head removal.** Keeping `shift()` preserves the smallest source diff but repeats the production failure mode and provides no amortized constant-time guarantee. + +**A monotonic head cursor with occasional slicing.** This can provide amortized constant-time FIFO removal, but Session history also needs front insertion before concurrently buffered entries. A circular deque provides both operations through one storage rule without a special history prefix buffer. + +**A linked deque.** Linked nodes make every end operation constant time and release removed nodes immediately, but each frame also allocates a node and pointer fields. The circular array keeps contiguous storage and amortizes the less frequent copies. + +**An external deque dependency.** The required API is small, and the retention rule includes immediate slot clearing plus a specific shrink condition that the regression suite must exercise. A local zero-dependency utility keeps that storage lifecycle inspectable in both compiler faces; an external collection would still require the same integration and retention verification. + +## Consequences + +Draining a backlog performs linear deque work instead of quadratic array-range movement. Removed frame references become collectible before backing-storage compaction, and a stream that remains active does not retain every historical slot. + +The repository owns a small generic collection implementation and its compatibility surface. Changes to its indexing, growth, or shrink rules require focused ordering and compaction coverage because every migrated stream shares the result. + +Unbounded producers can still exhaust memory or delay consumers through the volume of legitimate per-frame work. Capacity and admission policy remain separate decisions rather than hidden behavior in a generic collection. diff --git a/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md new file mode 100644 index 0000000000..1d0ff4813b --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md @@ -0,0 +1,56 @@ +# Agent Note: 长期流队列的线性排空 + +Status: implemented + +[English](2026-08-28-linear-stream-queue-drain.md) | 中文 + +## 问题 + +当消费方忙碌时，长期存在的流队列可能积累数千个帧。在观测到的 V8 路径上，使用 `Array.prototype.shift()` 移除每个帧会移动剩余数组区间，因此排空 `N` 个排队帧会执行二次方级别的引用移动，并延迟同一事件循环上的无关工作。[Issue #3270](https://github.com/deepseek-harness/deepseek-harness/issues/3270) 记录了把 `ArrayShift`、`MoveRange` 和 `memmove` 识别为主要堆栈的生产采样。 + +受影响的流具有不同的唤醒、失败、取消和 disposal 行为。它们的共同要求是保持 FIFO 顺序、同时不替它们作出这些生命周期决策的存储。 + +## 决策 + +`@deepseek-ai/dsh-deque` 为 Host 和浏览器消费方拥有一个零依赖环形数组。`pushBack()`、`pushFront()` 和 `popFront()` 改变索引，而不移动存活区间。移除会立即清空对应槽位。后备数组在满载时翻倍，在非空双端队列达到四分之一容量时减半，因此扩容和压缩的复制工作保持摊销常数时间，且交错队列使用期间的空闲存储保持有界。 + +该包没有 Client 插件之间共享的 singleton 状态、符号或类身份，因此 Client bundle purity 规则把它视为可内联库。Gateway 浏览器产物携带其双端队列实现，而不引入 module-table 条目或 Cordis 服务。 + +Host Remote 事件源、每个已连接 Client 的 Remote 事件队列、浏览器 Remote 流 inbox、每个会话历史 follower、每个会话控制流和每个 Workspace follower 都在此双端队列中存储帧。它们的所属类保留全部唤醒、失败、取消、缓冲排空和 disposal 行为。会话历史使用前插，把构造器种子事件放在打开观察期间收到的 live 事件之前。 + +队列容量、帧合并、过载拒绝和全局 agent admission 仍是消费方或应用策略。双端队列不会根据存储压力推断其中任何策略。 + +## 验证 + +双端队列单元测试覆盖 FIFO 顺序、前插、数组边界环绕、几何扩容、交错入队和出队后的四分之一满压缩、清空、复用与 `undefined` 条目。聚焦覆盖率报告显示 `packages/util/deque/src/index.ts` 的语句、分支、函数和行均为 100%。 + +API Remote、Gateway、会话控制/历史和 Workspace follow 测试覆盖迁移后的生命周期行为。它们保留所属包对顺序、失败、取消和 disposal 的断言。 + +命令 `pnpm exec tsx packages/util/deque/benchmarks/drain.ts` 在 Node v26.0.0、arm64 macOS 26.4 上运行。每个规模采样五次，得到以下双端队列排空时间中位数；测量不包含入队时间： + +| 条目数 | 排空中位数 | 每条目纳秒数 | +|---:|---:|---:| +| 250,000 | 1.705 ms | 6.818 ns | +| 500,000 | 2.541 ms | 5.082 ns | +| 1,000,000 | 4.668 ms | 4.668 ns | +| 2,000,000 | 9.656 ms | 4.828 ns | + +检入的 benchmark 使该测量可复现，但 CI 不强制墙钟时间阈值。确定性单元覆盖率负责算法和压缩路径；benchmark 在所记录运行时上证明排空工作近似线性。 + +## 考虑过的替代方案 + +**数组头部移除。** 保留 `shift()` 能得到最小源码差异，但会重复生产故障模式，也不提供摊销常数时间保证。 + +**单调头游标配合偶尔切片。** 这可以提供摊销常数时间的 FIFO 移除，但会话历史还需要在并发缓冲条目之前执行前插。环形双端队列通过一项存储规则同时提供两种操作，不需要特殊的历史前缀缓冲区。 + +**链式双端队列。** 链式节点让每个端点操作都保持常数时间，并立即释放已移除节点，但每个帧还会分配一个节点和指针字段。环形数组保持连续存储，并摊销频率较低的复制。 + +**外部双端队列依赖。** 所需 API 很小，保留规则包括立即清空槽位以及回归测试必须覆盖的特定缩容条件。本地零依赖工具让两个编译 face 都能检查该存储生命周期；外部集合仍需相同的集成和保留验证。 + +## 后果 + +排空 backlog 会执行线性双端队列工作，而不是二次方级别的数组区间移动。已移除帧的引用在后备存储压缩前即可回收，持续活动的流也不会保留每个历史槽位。 + +仓库拥有一项小型通用集合实现及其兼容性接口。对其索引、扩容或缩容规则的修改需要聚焦的顺序和压缩覆盖，因为每个已迁移流都会共享结果。 + +无界生产者仍可能通过合法逐帧工作的数量耗尽内存或延迟消费方。容量和 admission 策略仍是独立决策，而不是通用集合中的隐藏行为。 diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index e243871af1..ae563b4b35 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.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/config-catalog.md -config-catalog.md: 3c3699228bf5d4c0f49f8134d7c342f452de92c9 -config-catalog.zh.md: 0d96acf23a302d7365e6ebdb4aa3fe7cba4af400 +config-catalog.md: 4909347c5f2648962b74a7965d1e7dd18521f3b7 +config-catalog.zh.md: 98270d431a601058341eb1b5dfbb59ea4505a15e diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 3c3699228b..4909347c5f 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -290,7 +290,7 @@ export interface Config { } ``` -Source: [`packages/api/gateway/src/index.ts:117`](../packages/api/gateway/src/index.ts) +Source: [`packages/api/gateway/src/index.ts:118`](../packages/api/gateway/src/index.ts) @@ -3524,6 +3524,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them. - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)) - `@deepseek-ai/dsh-cmdline` ([`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts)) - `@deepseek-ai/dsh-code-runtime-python` ([`packages/code-runtime/code-runtime-python/src/index.ts`](../packages/code-runtime/code-runtime-python/src/index.ts)) +- `@deepseek-ai/dsh-deque` ([`packages/util/deque/src/index.ts`](../packages/util/deque/src/index.ts)) - `@deepseek-ai/dsh-experimental-agent-team-profile` ([`packages/experimental/agent-team-profile/src/index.ts`](../packages/experimental/agent-team-profile/src/index.ts)) - `@deepseek-ai/dsh-experimental-agent-team-web-profile` ([`packages/experimental/agent-team-web-profile/src/index.ts`](../packages/experimental/agent-team-web-profile/src/index.ts)) - `@deepseek-ai/dsh-experimental-webworker-packer` ([`packages/experimental/webworker-packer/src/index.ts`](../packages/experimental/webworker-packer/src/index.ts)) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 0d96acf23a..98270d431a 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -292,7 +292,7 @@ export interface Config { } ``` -来源：[`packages/api/gateway/src/index.ts:117`](../packages/api/gateway/src/index.ts) +来源：[`packages/api/gateway/src/index.ts:118`](../packages/api/gateway/src/index.ts) @@ -3525,6 +3525,7 @@ export interface Config { - `@deepseek-ai/dsh-client-web`（[`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)） - `@deepseek-ai/dsh-cmdline`（[`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts)） - `@deepseek-ai/dsh-code-runtime-python`（[`packages/code-runtime/code-runtime-python/src/index.ts`](../packages/code-runtime/code-runtime-python/src/index.ts)） +- `@deepseek-ai/dsh-deque`（[`packages/util/deque/src/index.ts`](../packages/util/deque/src/index.ts)） - `@deepseek-ai/dsh-experimental-agent-team-profile`（[`packages/experimental/agent-team-profile/src/index.ts`](../packages/experimental/agent-team-profile/src/index.ts)） - `@deepseek-ai/dsh-experimental-agent-team-web-profile`（[`packages/experimental/agent-team-web-profile/src/index.ts`](../packages/experimental/agent-team-web-profile/src/index.ts)） - `@deepseek-ai/dsh-experimental-webworker-packer`（[`packages/experimental/webworker-packer/src/index.ts`](../packages/experimental/webworker-packer/src/index.ts)） diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 41e0d5d0e8..3b9abcda71 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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/module-graph.md -module-graph.md: f9cafb86b22012c2dc1198ff810ededd988911f9 -module-graph.zh.md: ec4ac506cfef4d8ceaf3c5f83f07dad1fee66c50 +module-graph.md: 69a4ff1313710923e32e0e2bb7d702b34f169c7f +module-graph.zh.md: 2f6fd8b05e67eb8b86cd6cef376cd07456cb5c2f diff --git a/docs/module-graph.md b/docs/module-graph.md index f9cafb86b2..69a4ff1313 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -10,6 +10,7 @@ flowchart TD subgraph group_util["packages/util"] pkg_atomic_write["atomic-write"] pkg_brand["brand"] + pkg_deque["deque"] pkg_home_paths["home-paths"] pkg_launch_environment["launch-environment"] pkg_native_command["native-command"] @@ -359,6 +360,7 @@ flowchart TD end pkg_atomic_write --> pkg_invariants pkg_brand --> pkg_invariants + pkg_deque --> pkg_invariants pkg_home_paths --> pkg_invariants pkg_launch_environment --> pkg_invariants pkg_native_command --> pkg_invariants @@ -1738,6 +1740,7 @@ flowchart TD | [`invariants`](../packages/runtime-diagnostics/invariants) | `runtime-diagnostics` | — | | [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`deque`](../packages/util/deque) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`home-paths`](../packages/util/home-paths) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`launch-environment`](../packages/util/launch-environment) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`native-command`](../packages/util/native-command) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index ec4ac506cf..2f6fd8b05e 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -12,6 +12,7 @@ flowchart TD subgraph group_util["packages/util"] pkg_atomic_write["atomic-write"] pkg_brand["brand"] + pkg_deque["deque"] pkg_home_paths["home-paths"] pkg_launch_environment["launch-environment"] pkg_native_command["native-command"] @@ -361,6 +362,7 @@ flowchart TD end pkg_atomic_write --> pkg_invariants pkg_brand --> pkg_invariants + pkg_deque --> pkg_invariants pkg_home_paths --> pkg_invariants pkg_launch_environment --> pkg_invariants pkg_native_command --> pkg_invariants @@ -1740,6 +1742,7 @@ flowchart TD | [`invariants`](../packages/runtime-diagnostics/invariants) | `runtime-diagnostics` | — | | [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`deque`](../packages/util/deque) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`home-paths`](../packages/util/home-paths) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`launch-environment`](../packages/util/launch-environment) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`native-command`](../packages/util/native-command) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | diff --git a/packages/api/gateway/package.json b/packages/api/gateway/package.json index d5601ab188..aed918631c 100644 --- a/packages/api/gateway/package.json +++ b/packages/api/gateway/package.json @@ -56,6 +56,7 @@ ], "license": "MIT", "dependencies": { + "@deepseek-ai/dsh-deque": "workspace:^", "@deepseek-ai/dsh-timeout": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/schemastery": "workspace:^", diff --git a/packages/api/gateway/src/client/stream-client.ts b/packages/api/gateway/src/client/stream-client.ts index 0dd56cc72d..c62fa5f522 100644 --- a/packages/api/gateway/src/client/stream-client.ts +++ b/packages/api/gateway/src/client/stream-client.ts @@ -6,6 +6,7 @@ import { type RemoteStreamClientMessage, type RemoteStreamServerMessage, } from '../stream-protocol.ts' +import { Deque } from '@deepseek-ai/dsh-deque' import { randomUUID } from '@deepseek-ai/dsh-util-crypto' const INTERNAL_BASE = 'http://dsh.internal' @@ -311,13 +312,13 @@ function sleep(ms: number, signal: AbortSignal): Promise { } class StreamInbox { - private readonly frames: RemoteStreamServerMessage[] = [] + private readonly frames = new Deque() private wake: (() => void) | undefined private failure: Error | undefined push(frame: RemoteStreamServerMessage): void { if (this.failure !== undefined) return - this.frames.push(frame) + this.frames.pushBack(frame) this.wake?.() this.wake = undefined } @@ -325,17 +326,17 @@ class StreamInbox { fail(error: unknown): void { if (this.failure !== undefined) return this.failure = error instanceof Error ? error : new Error(String(error), { cause: error }) - this.frames.length = 0 + this.frames.clear() this.wake?.() this.wake = undefined } async next(): Promise { - while (this.frames.length === 0) { + while (this.frames.size === 0) { if (this.failure !== undefined) throw this.failure await new Promise((resolve) => { this.wake = resolve }) } - return this.frames.shift() as RemoteStreamServerMessage + return this.frames.popFront() as RemoteStreamServerMessage } } diff --git a/packages/api/gateway/src/index.ts b/packages/api/gateway/src/index.ts index 1d754b05a7..07423f9968 100644 --- a/packages/api/gateway/src/index.ts +++ b/packages/api/gateway/src/index.ts @@ -8,6 +8,7 @@ import { randomUUID } from 'node:crypto' import { Context, Service, symbols } from '@deepseek-ai/cordis' import type { ConnectionRpcHandler } from '@deepseek-ai/dsh-client-connection' +import { Deque } from '@deepseek-ai/dsh-deque' import type { WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver' import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout' import z from '@deepseek-ai/schemastery' @@ -887,13 +888,13 @@ type RemoteEventWireFrame = /** Pull-driven queue owned by one connected Client event generation. */ class RemoteEventQueue { - private readonly frames: RemoteEventWireFrame[] = [] + private readonly frames = new Deque() private waiter: (() => void) | undefined private closed = false push(frame: RemoteEventWireFrame): void { if (this.closed) return - this.frames.push(frame) + this.frames.pushBack(frame) this.waiter?.() } @@ -908,7 +909,7 @@ class RemoteEventQueue { signal.addEventListener('abort', abort, { once: true }) try { while (true) { - while (this.frames.length > 0) yield this.frames.shift() as RemoteEventWireFrame + while (this.frames.size > 0) yield this.frames.popFront() as RemoteEventWireFrame if (this.closed || signal.aborted) return await new Promise((resolve) => { this.waiter = resolve }) this.waiter = undefined diff --git a/packages/api/gateway/tsconfig.client.json b/packages/api/gateway/tsconfig.client.json index 31df1266af..aa14fb8a95 100644 --- a/packages/api/gateway/tsconfig.client.json +++ b/packages/api/gateway/tsconfig.client.json @@ -24,6 +24,9 @@ { "path": "../../typert/protocol" }, + { + "path": "../../util/deque" + }, { "path": "../../util/crypto" } diff --git a/packages/api/gateway/tsconfig.host.json b/packages/api/gateway/tsconfig.host.json index 54d5f964f3..874f7b8daf 100644 --- a/packages/api/gateway/tsconfig.host.json +++ b/packages/api/gateway/tsconfig.host.json @@ -34,6 +34,9 @@ { "path": "../../typert/protocol" }, + { + "path": "../../util/deque" + }, { "path": "../../util/timeout" } diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json index 8a271fe29a..66efeb1bd0 100644 --- a/packages/api/remotes/package.json +++ b/packages/api/remotes/package.json @@ -55,6 +55,7 @@ "lib/types/**/*.d.ts" ], "dependencies": { + "@deepseek-ai/dsh-deque": "workspace:^", "@deepseek-ai/dsh-scope": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^" }, diff --git a/packages/api/remotes/src/index.ts b/packages/api/remotes/src/index.ts index e775d3a5ae..b37136079d 100644 --- a/packages/api/remotes/src/index.ts +++ b/packages/api/remotes/src/index.ts @@ -8,6 +8,7 @@ import type { TypertRemoteEventOutcome, TypertRemoteEventSource, } from '@deepseek-ai/dsh-api-gateway' +import { Deque } from '@deepseek-ai/dsh-deque' import { carrierKeyOf } from '@deepseek-ai/dsh-scope' import { isJsonValue } from '@deepseek-ai/dsh-session' import type { JsonValue } from '@deepseek-ai/dsh-session' @@ -79,13 +80,13 @@ function remoteEventSource(ctx: Context): TypertRemoteEventSource { /** One pull-driven queue bridging synchronous Cordis listeners to an AsyncIterable. */ class RemoteEventQueue { - private readonly buffer: TypertRemoteEventDispatch[] = [] + private readonly buffer = new Deque() private waiter: (() => void) | undefined private done = false push(frame: TypertRemoteEventDispatch): boolean { if (this.done) return false - this.buffer.push(frame) + this.buffer.pushBack(frame) this.waiter?.() return true } @@ -93,8 +94,8 @@ class RemoteEventQueue { private end(reason: unknown): void { if (this.done) return this.done = true - const buffered = this.buffer.splice(0) - for (const dispatch of buffered) { + while (this.buffer.size > 0) { + const dispatch = this.buffer.popFront() as TypertRemoteEventDispatch if ('context' in dispatch) dispatch.reject(reason) } this.waiter?.() @@ -106,7 +107,7 @@ class RemoteEventQueue { try { while (true) { if (this.done || signal.aborted) return - while (this.buffer.length > 0) yield this.buffer.shift() as TypertRemoteEventDispatch + while (this.buffer.size > 0) yield this.buffer.popFront() as TypertRemoteEventDispatch await new Promise((resolve) => { this.waiter = resolve }) this.waiter = undefined } diff --git a/packages/api/remotes/tsconfig.host.json b/packages/api/remotes/tsconfig.host.json index 4dd513bdeb..d344c6be3d 100644 --- a/packages/api/remotes/tsconfig.host.json +++ b/packages/api/remotes/tsconfig.host.json @@ -42,6 +42,9 @@ { "path": "../../core/scope" }, + { + "path": "../../util/deque" + }, { "path": "../../interaction/user-approval" }, diff --git a/packages/api/session-controller/package.json b/packages/api/session-controller/package.json index 0cdd53a2a3..a8725bb649 100644 --- a/packages/api/session-controller/package.json +++ b/packages/api/session-controller/package.json @@ -73,6 +73,7 @@ ], "license": "MIT", "dependencies": { + "@deepseek-ai/dsh-deque": "workspace:^", "@deepseek-ai/schemastery": "workspace:^", "zod": "^4.4.3" }, diff --git a/packages/api/session-controller/src/control.ts b/packages/api/session-controller/src/control.ts index 81b1092d9f..db79f0a594 100644 --- a/packages/api/session-controller/src/control.ts +++ b/packages/api/session-controller/src/control.ts @@ -2,6 +2,7 @@ import type { Context } from '@deepseek-ai/cordis' import type { Agent } from '@deepseek-ai/dsh-agent' +import { Deque } from '@deepseek-ai/dsh-deque' import type { JobSnapshot } from '@deepseek-ai/dsh-jobs' import type { JsonValue, Session, SessionEvent, SessionEventMap, SessionId, UserMessage, @@ -129,13 +130,13 @@ export class SessionControlController { } class ControlQueue { - private readonly buffer: SessionControlFrame[] = [] + private readonly buffer = new Deque() private wake: (() => void) | undefined private done = false push(frame: SessionControlFrame): void { if (this.done) return - this.buffer.push(frame) + this.buffer.pushBack(frame) const wake = this.wake this.wake = undefined wake?.() @@ -154,14 +155,14 @@ class ControlQueue { signal.addEventListener('abort', onAbort, { once: true }) try { while (!this.done && !signal.aborted) { - const frame = this.buffer.shift() + const frame = this.buffer.popFront() if (frame !== undefined) { yield frame continue } await new Promise((resolve) => { this.wake = resolve }) } - while (this.buffer.length > 0 && !signal.aborted) yield this.buffer.shift() as SessionControlFrame + while (this.buffer.size > 0 && !signal.aborted) yield this.buffer.popFront() as SessionControlFrame } finally { signal.removeEventListener('abort', onAbort) this.end() diff --git a/packages/api/session-controller/src/history.ts b/packages/api/session-controller/src/history.ts index d78509e49b..99f42fe310 100644 --- a/packages/api/session-controller/src/history.ts +++ b/packages/api/session-controller/src/history.ts @@ -1,6 +1,7 @@ /** Cold Session history pagination and live-event source. */ import type { Context } from '@deepseek-ai/cordis' +import { Deque } from '@deepseek-ai/dsh-deque' import { isAppendSurfaceEvent } from '@deepseek-ai/dsh-session' import { isChunkRow, packChunkRuns, type ChunkRow } from '@deepseek-ai/dsh-session/chunk-rows' import type { SessionEvent, SessionHeader, SessionId } from '@deepseek-ai/dsh-session' @@ -88,7 +89,7 @@ export class SessionHistoryController { validateFollowRequest(request) const { address } = request const target = addressId(address) - const buffered: SessionEvent[] = [] + const buffered = new Deque() let snapshotCursor: number | undefined let wake: (() => void) | undefined const notify = (): void => { @@ -104,7 +105,7 @@ export class SessionHistoryController { this.closeFollowers.add(close) const disposeEvent = this.ctx.on('session/event', (session, event) => { if (session.id !== target) return - buffered.push(event) + buffered.pushBack(event) notify() }, { global: true }) const disposeCreated = this.ctx.on('session/created', (session) => { @@ -115,7 +116,9 @@ export class SessionHistoryController { const suffix = session.events.slice(snapshotCursor === undefined ? session.firstLiveSeq : snapshotCursor + 1) - buffered.unshift(...suffix) + for (let index = suffix.length - 1; index >= 0; index -= 1) { + buffered.pushFront(suffix[index] as SessionEvent) + } notify() }, { global: true }) const onAbort = (): void => { notify() } @@ -148,7 +151,7 @@ export class SessionHistoryController { } let nextSeq = cursor + 1 while (!follower.closed && !signal.aborted) { - const item = buffered.shift() + const item = buffered.popFront() if (item === undefined) { await new Promise((resolve) => { wake = resolve }) continue diff --git a/packages/api/session-controller/tsconfig.host.json b/packages/api/session-controller/tsconfig.host.json index bea21672b7..aba87f9107 100644 --- a/packages/api/session-controller/tsconfig.host.json +++ b/packages/api/session-controller/tsconfig.host.json @@ -32,6 +32,7 @@ { "path": "../../interaction/permission-presets" }, { "path": "../../jobs/jobs" }, { "path": "../../llm/llm" }, + { "path": "../../util/deque" }, { "path": "../../util/native-command" }, { "path": "../../preset/agent-presets" }, { "path": "../../runtime-diagnostics/invariants" }, diff --git a/packages/api/workspace-controller/package.json b/packages/api/workspace-controller/package.json index 14586d912e..c993e58cbf 100644 --- a/packages/api/workspace-controller/package.json +++ b/packages/api/workspace-controller/package.json @@ -70,6 +70,7 @@ ], "license": "MIT", "dependencies": { + "@deepseek-ai/dsh-deque": "workspace:^", "zod": "^4.4.3" }, "peerDependencies": { diff --git a/packages/api/workspace-controller/src/feed.ts b/packages/api/workspace-controller/src/feed.ts index dcb1598c59..57d38f18e5 100644 --- a/packages/api/workspace-controller/src/feed.ts +++ b/packages/api/workspace-controller/src/feed.ts @@ -1,6 +1,7 @@ /** Reconnect-safe Workspace baseline and increment producer. */ import type { Context } from '@deepseek-ai/cordis' +import { Deque } from '@deepseek-ai/dsh-deque' import type { DomainChanged } from '@deepseek-ai/dsh-storage-domain' import type { Workspace, WorkspaceRecord } from '@deepseek-ai/dsh-workspace' import { @@ -139,14 +140,14 @@ function sameStrings(left: readonly string[], right: readonly string[]): boolean } class WorkspaceFollower { - private readonly frames: WorkspaceFollowFrame[] = [] + private readonly frames = new Deque() private waiting: (() => void) | undefined private closed = false push(frame: WorkspaceFollowFrame): void { /* v8 ignore next -- closed followers are removed before later publication can reach them. */ if (this.closed) return - this.frames.push(frame) + this.frames.pushBack(frame) this.waiting?.() } @@ -158,7 +159,7 @@ class WorkspaceFollower { async *read(signal: AbortSignal): AsyncIterable { while (!this.closed && !signal.aborted) { - const frame = this.frames.shift() + const frame = this.frames.popFront() if (frame !== undefined) { yield frame continue @@ -178,7 +179,7 @@ class WorkspaceFollower { this.waiting = finish signal.addEventListener('abort', finish, { once: true }) /* v8 ignore next -- native signals and the private queue cannot change during this synchronous setup. */ - if (signal.aborted || this.closed || this.frames.length > 0) finish() + if (signal.aborted || this.closed || this.frames.size > 0) finish() }) } } diff --git a/packages/api/workspace-controller/tsconfig.host.json b/packages/api/workspace-controller/tsconfig.host.json index 4b98892781..e4a57edebe 100644 --- a/packages/api/workspace-controller/tsconfig.host.json +++ b/packages/api/workspace-controller/tsconfig.host.json @@ -20,6 +20,7 @@ { "path": "../../runtime-diagnostics/invariants" }, { "path": "../../storage/storage-domain" }, { "path": "../../typert/protocol" }, + { "path": "../../util/deque" }, { "path": "../../workspace/workspace" } ] } diff --git a/packages/client/tsdown.client.ts b/packages/client/tsdown.client.ts index 984a6a6828..3b679d3899 100644 --- a/packages/client/tsdown.client.ts +++ b/packages/client/tsdown.client.ts @@ -58,7 +58,7 @@ function styleInjectionModule( * Everything else under @deepseek-ai/* is either a module-table entry * (external) or a leak the purity gate rejects. */ -export const INLINE_SAFE = /^(?:@deepseek-ai\/dsh-(?:file-reference|session|llm|tools|brand|util-crypto|util-workspace-path)(?:\/|$)|@deepseek-ai\/dsh-token-meter\/client$)/ +export const INLINE_SAFE = /^(?:@deepseek-ai\/dsh-(?:file-reference|session|llm|tools|brand|deque|util-crypto|util-workspace-path)(?:\/|$)|@deepseek-ai\/dsh-token-meter\/client$)/ /** * Vendored framework libraries: rescoped into @deepseek-ai, so the gate below diff --git a/packages/util/README.i18n.yaml b/packages/util/README.i18n.yaml index dfba9d3271..2a5453caa5 100644 --- a/packages/util/README.i18n.yaml +++ b/packages/util/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/util/README.md -README.md: d1f48f165952a283b231e416b3391585cfee81a8 -README.zh.md: 69eb0cf9bb5845a4aeeb3880ef70fac049efbade +README.md: ea420501c4a7f454c791f69828a77e32f87a8381 +README.zh.md: 25000c76ad8702dfec14edd629d96e61abf52e4e diff --git a/packages/util/README.md b/packages/util/README.md index d1f48f1659..ea420501c4 100644 --- a/packages/util/README.md +++ b/packages/util/README.md @@ -1,5 +1,5 @@ --- -description: "Package map for the zero-dependency utility family: atomic file writes, branded ids, harness home paths, the launch environment, native commands, output retention, and timeouts." +description: "Package map for the zero-dependency utility family: atomic file writes, branded ids, deques, harness home paths, the launch environment, native commands, output retention, and timeouts." kind: "package-group" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -The `util/` group gives capability packages shared mechanical primitives instead of duplicate implementations. It covers atomic writes, branded ids, UUIDs, Harness-home paths, launch environments, native commands, output retention, and timeout handling. Every package here is a library: it registers no service or event, and the consuming capability retains the business semantics. +The `util/` group gives capability packages shared mechanical primitives instead of duplicate implementations. It covers atomic writes, branded ids, deques, UUIDs, Harness-home paths, launch environments, native commands, output retention, and timeout handling. Every package here is a library: it registers no service or event, and the consuming capability retains the business semantics. ## Table of Contents @@ -28,6 +28,7 @@ Each package provides one primitive; open a package page for how to use it. |---|---| | [`brand/`](brand/README.md) | Compile-time-only nominal brands for ids that cross package boundaries | | [`crypto/`](crypto/README.md) | Mints RFC 9562 v4 UUIDs from the cross-runtime `crypto.getRandomValues` primitive | +| [`deque/`](deque/README.md) | Provides amortized constant-time queue operations with bounded vacant storage | | [`home-paths/`](home-paths/README.md) | Resolves the single Harness home and joins shared user-data paths | | [`launch-environment/`](launch-environment/README.md) | Frozen launch environment that remembers which layer supplied each value | | [`atomic-write/`](atomic-write/README.md) | Atomic file replacement and cross-process writer locking | diff --git a/packages/util/README.zh.md b/packages/util/README.zh.md index 69eb0cf9bb..25000c76ad 100644 --- a/packages/util/README.zh.md +++ b/packages/util/README.zh.md @@ -1,5 +1,5 @@ --- -description: "零依赖工具家族的包映射：原子文件写入、品牌化 id、harness 主目录路径、启动环境、原生命令、输出保留与超时。" +description: "零依赖工具家族的包映射：原子文件写入、品牌化 id、双端队列、harness 主目录路径、启动环境、原生命令、输出保留与超时。" kind: "package-group" --- @@ -9,7 +9,7 @@ kind: "package-group" ## 概述 -`util/` 组为能力包提供共享的机制原语，避免重复实现。它涵盖原子写入、品牌化 id、UUID、Harness home 路径、启动环境、原生命令、输出保留和超时处理。这里的每个包都是库：它不注册服务或事件，业务语义仍由消费它的能力负责。 +`util/` 组为能力包提供共享的机制原语，避免重复实现。它涵盖原子写入、品牌化 id、双端队列、UUID、Harness home 路径、启动环境、原生命令、输出保留和超时处理。这里的每个包都是库：它不注册服务或事件，业务语义仍由消费它的能力负责。 ## 目录 @@ -28,6 +28,7 @@ kind: "package-group" |---|---| | [`brand/`](brand/README.zh.md) | 为跨越包边界的 id 提供仅编译期的名义品牌 | | [`crypto/`](crypto/README.zh.md) | 基于跨运行时 `crypto.getRandomValues` 原语生成 RFC 9562 v4 UUID | +| [`deque/`](deque/README.zh.md) | 提供摊销常数时间的队列操作和有界空闲存储 | | [`home-paths/`](home-paths/README.zh.md) | 解析统一的 Harness 主目录并拼接共享的用户数据路径 | | [`launch-environment/`](launch-environment/README.zh.md) | 冻结的启动环境，记住每个值来自哪一层 | | [`atomic-write/`](atomic-write/README.zh.md) | 原子文件替换与跨进程写锁 | diff --git a/packages/util/deque/README.i18n.yaml b/packages/util/deque/README.i18n.yaml new file mode 100644 index 0000000000..aa7b93e2a1 --- /dev/null +++ b/packages/util/deque/README.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 packages/util/deque/README.md +README.md: e029ecf574731bb2860dbc56383b93a9282dddfe +README.zh.md: 308f367e91c7345088eea0f5b2bccc0ad3539af7 diff --git a/packages/util/deque/README.md b/packages/util/deque/README.md new file mode 100644 index 0000000000..e029ecf574 --- /dev/null +++ b/packages/util/deque/README.md @@ -0,0 +1,104 @@ +--- +description: "Circular deque for Host and browser packages that need amortized constant-time queue operations, immediate release of removed entries, and bounded vacant storage." +kind: "package-library" +--- + +# @deepseek-ai/dsh-deque + +English | [中文](README.zh.md) + +## Summary + +`dsh-deque` lets Host and browser packages drain long-lived in-process queues without moving every remaining entry after each removal. Callers append or prepend entries and remove them from the front with amortized constant-time operations. The deque owns entry order and backing-storage release; each consumer still owns wake-up, failure, cancellation, capacity, and overload behavior. + +## Table of Contents + +- [Use this package](#use-this-package) +- [Understand the implementation](#understand-the-implementation) +- [Further Exploration](#further-exploration) +- [Model Experience](#model-experience) +- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work) +- [Dev Note](#dev-note) + +----- + + +## Use this package + +### When to use it + +Use `Deque` when entries can accumulate across asynchronous work and the consumer needs FIFO removal, optional front insertion, or explicit queue clearing. Finite local worklists can stay as arrays when their maximum size makes head removal cost irrelevant. + +### Entry point + +Import the deque, append entries at the tail, and check `size` before removing an entry whose type may include `undefined`: + +```ts +import { Deque } from '@deepseek-ai/dsh-deque' + +const frames = new Deque() +frames.pushBack('first') +frames.pushFront('before-first') + +while (frames.size > 0) { + console.log(frames.popFront()) +} +``` + +The methods do not impose a queue limit or translate consumer failures. See [`src/index.ts`](src/index.ts) for the exact TypeScript contract. + +----- + + +## Understand the implementation + +
+Implementation internals — click to expand + +The deque stores entries in a circular array. Removing an entry clears that slot immediately, while geometric growth and quarter-full shrinking keep copying work amortized constant time and prevent a head cursor from retaining indefinitely growing vacant storage. + +### Source map + +| File | Role | +|---|---| +| [`src/index.ts`](src/index.ts) | Circular deque operations and backing-storage lifecycle | +| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; ordering and storage lifecycle are exercised by unit tests) | +| [`tests/deque.spec.ts`](tests/deque.spec.ts) | FIFO, front insertion, wrapping, growth, compaction, clearing, and reuse coverage | +| [`benchmarks/drain.ts`](benchmarks/drain.ts) | Reproducible backlog-drain timing across increasing queue sizes | + +
+ +----- + + +## Further Exploration + +- [Utility package map](../README.md) — the other zero-dependency primitives shared across package groups. +- [Linear stream queue decision](../../../.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.md) — why production streams use this deque instead of array head removal. + +----- + + +## Model Experience + +None, as this in-process collection registers nothing model-facing. + +#### KV Cache effect + +Nothing here enters a model request, so provider cache reuse is unaffected. + +## Known Limitations and Deferred Work + + + +- **No capacity policy** — the deque does not bound, coalesce, or reject entries; each consumer must define overload behavior appropriate to its stream. + + +### Dev Note + +
+Working context for maintainers — click to expand + +None. + +
diff --git a/packages/util/deque/README.zh.md b/packages/util/deque/README.zh.md new file mode 100644 index 0000000000..308f367e91 --- /dev/null +++ b/packages/util/deque/README.zh.md @@ -0,0 +1,104 @@ +--- +description: "供 Host 和浏览器包使用的环形双端队列，提供摊销常数时间的队列操作、已移除条目的即时释放和有界空闲存储。" +kind: "package-library" +--- + +# @deepseek-ai/dsh-deque + +[English](README.md) | 中文 + +## 概述 + +`dsh-deque` 让 Host 和浏览器包可以排空长期存在的进程内队列，而无需在每次移除后移动所有剩余条目。调用方可以追加或前插条目，并以摊销常数时间从前端移除。双端队列负责条目顺序和后备存储释放；唤醒、失败、取消、容量和过载行为仍由各消费方负责。 + +## 目录 + +- [使用本包](#use-this-package) +- [理解实现](#understand-the-implementation) +- [进一步探索](#further-exploration) +- [模型体验](#model-experience) +- [已知限制与延期工作](#known-limitations-and-deferred-work) +- [开发备注](#dev-note) + +----- + + +## 使用本包 + +### 何时使用 + +当条目可能在异步工作期间持续积累，且消费方需要 FIFO 移除、可选前插或显式清空队列时，使用 `Deque`。如果有限本地工作列表的最大规模使头部移除成本无关紧要，它可以继续使用数组。 + +### 入口 + +导入双端队列，在尾部追加条目；当条目类型可能包含 `undefined` 时，在移除前检查 `size`： + +```ts +import { Deque } from '@deepseek-ai/dsh-deque' + +const frames = new Deque() +frames.pushBack('first') +frames.pushFront('before-first') + +while (frames.size > 0) { + console.log(frames.popFront()) +} +``` + +这些方法不施加队列限制，也不转换消费方失败。准确的 TypeScript 约定见 [`src/index.ts`](src/index.ts)。 + +----- + + +## 理解实现 + +
+实现细节——点击展开 + +双端队列把条目存入环形数组。移除条目会立即清空对应槽位；按几何级数扩容并在四分之一满时缩容，使复制工作保持摊销常数时间，并防止头游标保留持续增长的空闲存储。 + +### 源码地图 + +| 文件 | 职责 | +|---|---| +| [`src/index.ts`](src/index.ts) | 环形双端队列操作与后备存储生命周期 | +| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；顺序和存储生命周期由单元测试覆盖） | +| [`tests/deque.spec.ts`](tests/deque.spec.ts) | FIFO、前插、环绕、扩容、压缩、清空和复用覆盖 | +| [`benchmarks/drain.ts`](benchmarks/drain.ts) | 随队列规模增长的可复现 backlog 排空计时 | + +
+ +----- + + +## 进一步探索 + +- [工具包映射](../README.zh.md)——跨包组共享的其他零依赖原语。 +- [线性流队列决策](../../../.agents/notes/implemented/bug-fix/2026-08-28-linear-stream-queue-drain.zh.md)——生产流为何使用本双端队列而非数组头部移除。 + +----- + + +## 模型体验 + +无，因为这个进程内集合不注册任何面向模型的内容。 + +#### KV 缓存影响 + +这里的内容不会进入模型请求，因此不影响提供方缓存复用。 + +## 已知限制与延期工作 + + + +- **没有容量策略**——双端队列不会限制、合并或拒绝条目；每个消费方必须定义适合其流的过载行为。 + + +### 开发备注 + +
+维护者的工作上下文——点击展开 + +无。 + +
diff --git a/packages/util/deque/benchmarks/drain.ts b/packages/util/deque/benchmarks/drain.ts new file mode 100644 index 0000000000..51b067741d --- /dev/null +++ b/packages/util/deque/benchmarks/drain.ts @@ -0,0 +1,36 @@ +import { performance } from 'node:perf_hooks' +import { Deque } from '../src/index.ts' + +const sizes = [250_000, 500_000, 1_000_000, 2_000_000] +const samples = 5 + +function drain(size: number): { readonly milliseconds: number; readonly checksum: number } { + const deque = new Deque() + for (let value = 0; value < size; value += 1) deque.pushBack(value) + const started = performance.now() + let checksum = 0 + while (deque.size > 0) checksum += deque.popFront() as number + return { milliseconds: performance.now() - started, checksum } +} + +function median(values: readonly number[]): number { + const ordered = values.toSorted((left, right) => left - right) + return ordered[Math.floor(ordered.length / 2)] as number +} + +drain(sizes[0] as number) +for (const size of sizes) { + const expected = size * (size - 1) / 2 + const durations: number[] = [] + for (let sample = 0; sample < samples; sample += 1) { + const result = drain(size) + if (result.checksum !== expected) throw new Error(`invalid checksum for ${String(size)} entries`) + durations.push(result.milliseconds) + } + const milliseconds = median(durations) + console.log(JSON.stringify({ + size, + medianMilliseconds: Number(milliseconds.toFixed(3)), + nanosecondsPerEntry: Number((milliseconds * 1_000_000 / size).toFixed(3)), + })) +} diff --git a/packages/util/deque/package.json b/packages/util/deque/package.json new file mode 100644 index 0000000000..a159d0dcf9 --- /dev/null +++ b/packages/util/deque/package.json @@ -0,0 +1,42 @@ +{ + "name": "@deepseek-ai/dsh-deque", + "description": "Zero-dependency circular deque with amortized constant-time end operations and bounded vacant storage", + "version": "0.1.2-alpha.1", + "publishConfig": { + "access": "public" + }, + "repository": { + "type": "git", + "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", + "directory": "packages/util/deque" + }, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/types/**/*.d.ts" + ], + "license": "MIT", + "peerDependencies": { + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/cordis": "workspace:^" + }, + "devDependencies": { + "@deepseek-ai/dsh-invariants": "workspace:^", + "@deepseek-ai/cordis": "workspace:^" + } +} diff --git a/packages/util/deque/src/index.ts b/packages/util/deque/src/index.ts new file mode 100644 index 0000000000..8d117b7499 --- /dev/null +++ b/packages/util/deque/src/index.ts @@ -0,0 +1,95 @@ +/** + * Zero-dependency circular deque for queues that retain entries across asynchronous work. + * @module @deepseek-ai/dsh-deque + */ + +const MIN_CAPACITY = 16 + +/** + * A circular deque with amortized constant-time insertion and removal. + * Removed entries are cleared immediately, and sparse storage shrinks after + * the live entry count reaches one quarter of its capacity. + */ +export class Deque { + private buffer = new Array(MIN_CAPACITY) + private head = 0 + private count = 0 + + /** Number of entries available to remove. */ + get size(): number { + return this.count + } + + /** + * Append one entry after the current tail. + * @param value - entry to append. + */ + pushBack(value: T): void { + this.ensureCapacity() + const tail = this.head + this.count + this.buffer[tail < this.buffer.length ? tail : tail - this.buffer.length] = value + this.count += 1 + } + + /** + * Insert one entry before the current head. + * @param value - entry to prepend. + */ + pushFront(value: T): void { + this.ensureCapacity() + this.head = this.head === 0 ? this.buffer.length - 1 : this.head - 1 + this.buffer[this.head] = value + this.count += 1 + } + + /** + * Remove the current head entry and clear its retained reference. + * Callers whose element type includes `undefined` use {@link size} to + * distinguish an empty deque from an `undefined` entry. + * @returns the removed entry, or `undefined` when the deque is empty. + */ + popFront(): T | undefined { + if (this.count === 0) return undefined + const value = this.buffer[this.head] as T + this.buffer[this.head] = undefined + this.head += 1 + if (this.head === this.buffer.length) this.head = 0 + this.count -= 1 + this.compact() + return value + } + + /** Drop every entry and release the current backing storage. */ + clear(): void { + this.buffer = new Array(MIN_CAPACITY) + this.head = 0 + this.count = 0 + } + + private ensureCapacity(): void { + if (this.count < this.buffer.length) return + this.resize(this.buffer.length * 2) + } + + private compact(): void { + if (this.count === 0) { + this.head = 0 + return + } + if (this.buffer.length > MIN_CAPACITY && this.count <= this.buffer.length / 4) { + this.resize(Math.max(MIN_CAPACITY, this.buffer.length / 2)) + } + } + + private resize(capacity: number): void { + const next = new Array(capacity) + let source = this.head + for (let index = 0; index < this.count; index += 1) { + next[index] = this.buffer[source] + source += 1 + if (source === this.buffer.length) source = 0 + } + this.buffer = next + this.head = 0 + } +} diff --git a/packages/util/deque/src/invariant.ts b/packages/util/deque/src/invariant.ts new file mode 100644 index 0000000000..846a29ba4e --- /dev/null +++ b/packages/util/deque/src/invariant.ts @@ -0,0 +1,30 @@ +/** + * Package-owned invariant companion for `@deepseek-ai/dsh-deque`. + * @module @deepseek-ai/dsh-deque/invariant + */ + +/* jscpd:ignore-start */ +import type { Context } from '@deepseek-ai/cordis' +import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants' + +const PACKAGE_NAME = '@deepseek-ai/dsh-deque' + +/** Cordis companion plugin name. */ +export const name = 'deque-invariant' +/** Service required before the companion can reserve package ownership. */ +export const inject = ['invariants'] + +/** + * No runtime invariant: this pure utility owns no event stream or mutable data outside each deque; + * its ordering and storage lifecycle are exercised by unit tests. + */ +const install: InvariantInstaller = () => {} + +/** + * Register this package's invariant companion. + * @param ctx - Cordis context carrying the invariant service. + * @returns the installed registration's disposer after setup succeeds. + */ +export const apply = (ctx: Context): Promise<() => void> => + Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install)) +/* jscpd:ignore-end */ diff --git a/packages/util/deque/tests/deque.spec.ts b/packages/util/deque/tests/deque.spec.ts new file mode 100644 index 0000000000..c2a02f81c7 --- /dev/null +++ b/packages/util/deque/tests/deque.spec.ts @@ -0,0 +1,70 @@ +import { describe, expect, it } from 'vitest' +import { Deque } from '@deepseek-ai/dsh-deque' + +describe('Deque', () => { + it('removes tail-appended entries in FIFO order', () => { + const deque = new Deque() + expect(deque.size).toBe(0) + expect(deque.popFront()).toBeUndefined() + + deque.pushBack(1) + deque.pushBack(2) + + expect(deque.size).toBe(2) + expect(deque.popFront()).toBe(1) + expect(deque.popFront()).toBe(2) + expect(deque.size).toBe(0) + }) + + it('prepends entries before the existing head', () => { + const deque = new Deque() + deque.pushBack(3) + deque.pushFront(2) + deque.pushFront(1) + + expect([deque.popFront(), deque.popFront(), deque.popFront()]).toEqual([1, 2, 3]) + }) + + it('appends through the array boundary without growing', () => { + const deque = new Deque() + for (let value = 0; value < 8; value += 1) deque.pushBack(value) + for (let value = 0; value < 6; value += 1) expect(deque.popFront()).toBe(value) + for (let value = 8; value <= 16; value += 1) deque.pushBack(value) + + for (const value of [6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]) { + expect(deque.popFront()).toBe(value) + } + }) + + it('preserves order across wrapping, growth, and sparse compaction', () => { + const deque = new Deque() + for (let value = 0; value < 32; value += 1) deque.pushBack(value) + for (let value = 0; value < 24; value += 1) expect(deque.popFront()).toBe(value) + for (let value = 32; value < 128; value += 1) deque.pushBack(value) + + for (let value = 24; value < 128; value += 1) expect(deque.popFront()).toBe(value) + expect(deque.size).toBe(0) + }) + + it('drops retained storage and remains reusable after clear', () => { + const deque = new Deque() + for (let index = 0; index < 64; index += 1) deque.pushBack({ index }) + + deque.clear() + expect(deque.size).toBe(0) + expect(deque.popFront()).toBeUndefined() + + const value = {} + deque.pushBack(value) + expect(deque.popFront()).toBe(value) + }) + + it('uses size to distinguish an undefined entry from an empty deque', () => { + const deque = new Deque() + deque.pushBack(undefined) + + expect(deque.size).toBe(1) + deque.popFront() + expect(deque.size).toBe(0) + }) +}) diff --git a/packages/util/deque/tests/invariant.spec.ts b/packages/util/deque/tests/invariant.spec.ts new file mode 100644 index 0000000000..fad7278a46 --- /dev/null +++ b/packages/util/deque/tests/invariant.spec.ts @@ -0,0 +1,18 @@ +import { describe, expect, it } from 'vitest' +import { Context } from '@deepseek-ai/cordis' +import InvariantRegistry from '@deepseek-ai/dsh-invariants' +import * as DequeInvariant from '../src/invariant.ts' + +describe('deque invariant companion', () => { + it('registers its explained empty runtime invariant', async () => { + const ctx = new Context() + await ctx.plugin(InvariantRegistry) + const fiber = await ctx.plugin(DequeInvariant) + + expect(() => { + ctx.invariants.register('@deepseek-ai/dsh-deque', () => {}) + }).toThrow(/already registered/) + await fiber.dispose() + await ctx.fiber.dispose() + }) +}) diff --git a/packages/util/deque/tsconfig.json b/packages/util/deque/tsconfig.json new file mode 100644 index 0000000000..779effc3cc --- /dev/null +++ b/packages/util/deque/tsconfig.json @@ -0,0 +1,15 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../runtime-diagnostics/invariants" + } + ] +} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 9049facb91..a7a3e7be33 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -624,6 +624,9 @@ importers: packages/api/gateway: dependencies: + '@deepseek-ai/dsh-deque': + specifier: workspace:^ + version: link:../../util/deque '@deepseek-ai/dsh-timeout': specifier: workspace:^ version: link:../../util/timeout @@ -667,6 +670,9 @@ importers: packages/api/remotes: dependencies: + '@deepseek-ai/dsh-deque': + specifier: workspace:^ + version: link:../../util/deque '@deepseek-ai/dsh-scope': specifier: workspace:^ version: link:../../core/scope @@ -740,6 +746,9 @@ importers: packages/api/session-controller: dependencies: + '@deepseek-ai/dsh-deque': + specifier: workspace:^ + version: link:../../util/deque '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -880,6 +889,9 @@ importers: packages/api/workspace-controller: dependencies: + '@deepseek-ai/dsh-deque': + specifier: workspace:^ + version: link:../../util/deque zod: specifier: ^4.4.3 version: 4.4.3 @@ -9677,6 +9689,15 @@ importers: specifier: workspace:^ version: link:../../runtime-diagnostics/invariants + packages/util/deque: + devDependencies: + '@deepseek-ai/cordis': + specifier: workspace:^ + version: link:../../../vendor/cordis + '@deepseek-ai/dsh-invariants': + specifier: workspace:^ + version: link:../../runtime-diagnostics/invariants + packages/util/home-paths: devDependencies: '@deepseek-ai/cordis': diff --git a/scripts/client-bundle-purity.spec.ts b/scripts/client-bundle-purity.spec.ts index dd25b0dfcf..6d7db99497 100644 --- a/scripts/client-bundle-purity.spec.ts +++ b/scripts/client-bundle-purity.spec.ts @@ -91,9 +91,10 @@ describe('client bundle purity gate', () => { expect(() => resolveId('@deepseek-ai/dsh-client-web-react/store')).toThrow(/purity/) }) - it('lets inline-safe wire layers inline', () => { + it('lets inline-safe libraries inline', () => { expect(resolveId('@deepseek-ai/dsh-session/surface')).toBeNull() expect(resolveId('@deepseek-ai/dsh-brand')).toBeNull() + expect(resolveId('@deepseek-ai/dsh-deque')).toBeNull() expect(resolveId('@deepseek-ai/dsh-token-meter/client')).toBeNull() expect(() => resolveId('@deepseek-ai/dsh-token-meter')).toThrow(/purity/) expect(() => resolveId('@deepseek-ai/dsh-token-meter/client/internal')).toThrow(/purity/) diff --git a/scripts/doc-standard.spec.ts b/scripts/doc-standard.spec.ts index f7c5fd8c51..e4744d9514 100644 --- a/scripts/doc-standard.spec.ts +++ b/scripts/doc-standard.spec.ts @@ -78,6 +78,7 @@ const PACKAGE_LIBRARIES: Readonly> = { 'packages/util/atomic-write': 'Zero-dependency filesystem write utility.', 'packages/util/brand': 'Type-only branding primitive erased at compile time.', 'packages/util/crypto': 'Zero-dependency identifier minting utility.', + 'packages/util/deque': 'Zero-dependency circular deque utility.', 'packages/util/home-paths': 'Zero-dependency harness-home path resolver.', 'packages/util/launch-environment': 'Zero-dependency environment resolver.', 'packages/util/native-command': 'Host-side subprocess runner utility.', diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index c8f7e84d42..8f2800d88d 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -55,6 +55,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { 'packages/code-runtime/code-runtime-python': { kind: 'indirect', reason: 'The CPython subprocess backend delegates model rendering to PTC mode in dsh-tools.' }, 'packages/client/ui-agent-preset': { kind: 'indirect', reason: 'Browser-side settings row; the preset it selects owns every model-facing effect.' }, 'packages/util/crypto': { kind: 'indirect', reason: 'Pure identifier minting; the ids consumers mint with it never enter prompts as semantic content.' }, + 'packages/util/deque': { kind: 'none', reason: 'In-process collection primitive; registers nothing model-facing.' }, 'packages/core/agent-default-model': { kind: 'indirect', reason: 'The service supplies a ModelSelection; request assembly and adapters own the model-visible request.' }, 'packages/llm/deepseek-llm-api-extensions': { kind: 'indirect', reason: 'The registry contributes model-hidden provider fields; dsh-llm-deepseek owns their wire placement.' }, 'packages/preset/agent-presets': { kind: 'indirect', reason: 'The mount installs a preset\'s own plugins, which own every model-facing registration it makes visible.' }, diff --git a/tsconfig.base.json b/tsconfig.base.json index 759b985d1b..614047ccf4 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -303,6 +303,8 @@ "@deepseek-ai/dsh-credentials-local/invariant": ["./packages/credentials/credentials-local/src/invariant.ts"], "@deepseek-ai/dsh-deepseek-llm-api-extensions": ["./packages/llm/deepseek-llm-api-extensions/src"], "@deepseek-ai/dsh-deepseek-llm-api-extensions/invariant": ["./packages/llm/deepseek-llm-api-extensions/src/invariant.ts"], + "@deepseek-ai/dsh-deque": ["./packages/util/deque/src"], + "@deepseek-ai/dsh-deque/invariant": ["./packages/util/deque/src/invariant.ts"], "@deepseek-ai/dsh-e2b": ["./packages/e2b/e2b/src"], "@deepseek-ai/dsh-e2b/invariant": ["./packages/e2b/e2b/src/invariant.ts"], "@deepseek-ai/dsh-file-reference": ["./packages/context/file-reference/src"], diff --git a/tsconfig.host.json b/tsconfig.host.json index 561cee9b17..fa024a09f1 100644 --- a/tsconfig.host.json +++ b/tsconfig.host.json @@ -132,6 +132,7 @@ { "path": "./packages/util/home-paths" }, { "path": "./packages/util/timeout" }, { "path": "./packages/util/crypto" }, + { "path": "./packages/util/deque" }, { "path": "./packages/util/workspace-path" }, { "path": "./packages/util/output-retention" }, { "path": "./packages/util/atomic-write" }, From 143748bae95644cda5fc091557e778eef4aa366c Mon Sep 17 00:00:00 2001 From: Dudu-0223 Date: Fri, 28 Aug 2026 18:02:11 +0800 Subject: [PATCH 22/63] test(deque): pin storage release behavior --- packages/util/deque/tests/deque.spec.ts | 26 ++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/packages/util/deque/tests/deque.spec.ts b/packages/util/deque/tests/deque.spec.ts index c2a02f81c7..d585283461 100644 --- a/packages/util/deque/tests/deque.spec.ts +++ b/packages/util/deque/tests/deque.spec.ts @@ -1,6 +1,11 @@ import { describe, expect, it } from 'vitest' import { Deque } from '@deepseek-ai/dsh-deque' +function backingStorage(deque: Deque): readonly (T | undefined)[] { + // Storage retention is the behavior under test and has no public query API. + return (deque as unknown as { readonly buffer: readonly (T | undefined)[] }).buffer +} + describe('Deque', () => { it('removes tail-appended entries in FIFO order', () => { const deque = new Deque() @@ -40,19 +45,38 @@ describe('Deque', () => { const deque = new Deque() for (let value = 0; value < 32; value += 1) deque.pushBack(value) for (let value = 0; value < 24; value += 1) expect(deque.popFront()).toBe(value) + expect(backingStorage(deque)).toHaveLength(16) for (let value = 32; value < 128; value += 1) deque.pushBack(value) for (let value = 24; value < 128; value += 1) expect(deque.popFront()).toBe(value) expect(deque.size).toBe(0) + expect(backingStorage(deque)).toHaveLength(16) + }) + + it('releases a removed reference before sparse compaction', () => { + const deque = new Deque() + const removed = {} + deque.pushBack(removed) + deque.pushBack({}) + + expect(deque.popFront()).toBe(removed) + expect(backingStorage(deque)).not.toContain(removed) + expect(backingStorage(deque)).toHaveLength(16) }) it('drops retained storage and remains reusable after clear', () => { const deque = new Deque() - for (let index = 0; index < 64; index += 1) deque.pushBack({ index }) + const retained = {} + deque.pushBack(retained) + for (let index = 1; index < 64; index += 1) deque.pushBack({ index }) + const grownStorage = backingStorage(deque) deque.clear() expect(deque.size).toBe(0) expect(deque.popFront()).toBeUndefined() + expect(backingStorage(deque)).not.toBe(grownStorage) + expect(backingStorage(deque)).not.toContain(retained) + expect(backingStorage(deque)).toHaveLength(16) const value = {} deque.pushBack(value) From 94c714d813d5ce3a71060ef0adda78136f6032bf Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Fri, 28 Aug 2026 22:01:40 +0800 Subject: [PATCH 23/63] docs(testing): add CI test reliability skill --- ...-08-28-ci-test-reliability-skill.i18n.yaml | 6 + .../2026-08-28-ci-test-reliability-skill.md | 41 +++++++ ...2026-08-28-ci-test-reliability-skill.zh.md | 41 +++++++ ...deterministic-and-stress-testing.i18n.yaml | 4 +- ...-06-11-deterministic-and-stress-testing.md | 2 + ...-11-deterministic-and-stress-testing.zh.md | 2 + .../skills/dsh-ci-test-reliability/SKILL.md | 109 ++++++++++++++++++ .../references/ci-flake-diagnosis.md | 58 ++++++++++ .agents/skills/dsh-code-review/SKILL.md | 3 +- .agents/skills/dsh-pre-push-checks/SKILL.md | 2 + 10 files changed, 265 insertions(+), 3 deletions(-) create mode 100644 .agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml create mode 100644 .agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md create mode 100644 .agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md create mode 100644 .agents/skills/dsh-ci-test-reliability/SKILL.md create mode 100644 .agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md diff --git a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml new file mode 100644 index 0000000000..473728433a --- /dev/null +++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.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/testing/2026-08-28-ci-test-reliability-skill.md +2026-08-28-ci-test-reliability-skill.md: 5edf2aa769047cb5d4052a1338f2cc3886d9e0f9 +2026-08-28-ci-test-reliability-skill.zh.md: fd1a6d584f3c4686761f8c94ba99ee0d1c9b0233 diff --git a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md new file mode 100644 index 0000000000..5edf2aa769 --- /dev/null +++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md @@ -0,0 +1,41 @@ +# Agent Note: CI test reliability skill + +Status: implemented + +English | [中文](2026-08-28-ci-test-reliability-skill.zh.md) + +## Problem + +DeepSeek Harness runs tests across concurrent Vitest files, worker processes, repository gates, and Actions jobs. Process isolation does not isolate host ports, predictable paths, external namespaces, or inherited children, while process-global mutations and incomplete teardown can contaminate later tests. A test can select the correct tier and still pass only when it runs alone. + +The testing policy owns test tiers, defensive patterns own runtime lifecycle rules, pre-push guidance selects commands, and code review evaluates completed diffs. None of them gives an agent a focused workflow for designing resource-owning tests against the real CI topology or classifying an existing probabilistic failure before changing code. + +## Decision + +[dsh-ci-test-reliability](../../../skills/dsh-ci-test-reliability/SKILL.md) owns test isolation and CI-flake diagnosis guidance. It applies when tests or fixtures acquire host resources, mutate process-global state, depend on asynchronous readiness, own subprocesses or network listeners, or exhibit probabilistic CI failures. + +The skill requires agents to model concurrency beyond one Vitest process, allocate live resources atomically, separate stable fixture identities from ephemeral transport addresses, synchronize on observable state, restore global mutations exactly, and await teardown to quiescence. Regression evidence matches the owned risk: negative controls for guards, deterministic barriers for races, concurrent independent processes for host-resource isolation, and external observations instead of component self-reports. + +The diagnosis-only workflow lives in a separate reference so ordinary authoring does not load Actions triage procedure. It compares passing and failing evidence before classifying host collisions, incomplete lifecycle, global contamination, load-sensitive synchronization, platform or entry-path failures, product races, provider transience, or runner infrastructure. + +[dsh-pre-push-checks](../../../skills/dsh-pre-push-checks/SKILL.md) conditionally consults the reliability skill before selecting commands, while [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) applies it when reviewing risky tests. Command selection and general PR review remain with those existing skills. + +This decision partially overlaps the [deterministic and stress testing proposal](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.md). The skill ships authoring and diagnosis guidance; it does not implement that proposal's lint rule, universal replay fixture, or nightly stress job, so the proposal remains active. + +## Alternatives considered + +**Expand dsh-pre-push-checks.** Pre-push guidance runs after test design and owns evidence selection. Making it also own resource allocation, synchronization, teardown, and CI diagnosis would mix two different decisions and load reliability procedure for ordinary pushes. + +**Expand dsh-code-review.** Review guidance can detect unreliable tests after a diff exists, but it cannot guide the agent while the fixture is being designed or while a failure is being diagnosed without a PR. + +**Put the complete workflow in the standing testing policy.** The testing policy must remain the concise authority for tiers and placement. Loading detailed Actions diagnosis and resource-specific procedure for every test task would duplicate situational guidance and make that policy harder to scan. + +**Add a generic stress runner or regex gate immediately.** Repeated green runs do not prove a race is controlled, and literal ports, paths, sleeps, and URLs can be valid parser inputs or expected values. A later high-signal defect class can justify a narrow executed check without making broad textual matches policy. + +## Consequences + +Agents receive the reliability rules while designing or diagnosing the tests that need them, and pre-push and review workflows share the same criteria without duplicating the procedure. Pure deterministic tests continue to use the normal focused evidence path. + +The skill is advisory, so it cannot mechanically prevent every resource collision. A repeated, statically identifiable defect can still justify an executed repository check. The repository also retains one additional active Skill and reference whose links and statements must remain current with the actual CI topology. + +The existing deterministic-and-stress proposal remains open, and this change does not audit or rewrite the current test corpus. diff --git a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md new file mode 100644 index 0000000000..fd1a6d584f --- /dev/null +++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md @@ -0,0 +1,41 @@ +# Agent Note: CI 测试可靠性 Skill + +Status: implemented + +[English](2026-08-28-ci-test-reliability-skill.md) | 中文 + +## 问题 + +DeepSeek Harness 会在并发的 Vitest 文件、worker 进程、仓库 gate 与 Actions job 中运行测试。进程隔离不会隔离宿主机端口、可预测路径、外部命名空间或继承的子进程，而进程全局状态变更与未完成的 teardown 可能污染后续测试。即使测试选择了正确层级，也可能只在独占运行时通过。 + +测试政策负责测试层级，防御性模式负责运行时生命周期规则，pre-push 指引负责选择命令，代码 review 负责检查已完成的 diff。它们都没有为 agent 提供一个聚焦流程，用于按照真实 CI 拓扑设计会占用资源的测试，或在修改代码前对已有概率性失败进行分类。 + +## 决策 + +[dsh-ci-test-reliability](../../../skills/dsh-ci-test-reliability/SKILL.md) 负责测试隔离与 CI 概率性失败诊断指引。测试或 fixture 占用宿主机资源、修改进程全局状态、依赖异步就绪、持有子进程或网络 listener，或出现概率性 CI 失败时，使用该 Skill。 + +该 Skill 要求 agent 建模单个 Vitest 进程之外的并发，原子分配实时资源，把稳定 fixture 标识与临时传输地址分开，按可观察状态同步，精确恢复全局变更，并等待 teardown 达到静止状态。回归证据与所持有的风险匹配：guard 使用负向控制，竞态使用确定性 barrier，宿主机资源隔离使用并发独立进程，并以外部观察代替组件自述。 + +仅用于诊断的流程放在单独 reference 中，因此普通编写任务不会加载 Actions 分诊步骤。它会先比较成功与失败证据，再对宿主机冲突、未完成生命周期、全局状态污染、负载敏感同步、平台或入口路径失败、产品竞态、provider 瞬时故障或 runner 基础设施进行分类。 + +[dsh-pre-push-checks](../../../skills/dsh-pre-push-checks/SKILL.md) 在选择命令前按条件引用可靠性 Skill，[dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 则在 review 高风险测试时应用它。命令选择与通用 PR review 仍由这些现有 Skill 负责。 + +该决策与[确定性与压力测试提案](../../proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md)部分重合。该 Skill 交付测试编写与诊断指引，但没有实现提案中的 lint 规则、通用回放 fixture 或 nightly stress job，因此提案保持活跃。 + +## 考虑过的替代方案 + +**扩展 dsh-pre-push-checks。** Pre-push 指引在测试设计之后运行，负责选择证据。如果它还负责资源分配、同步、teardown 与 CI 诊断，就会混合两种不同决策，并让普通 push 也加载可靠性流程。 + +**扩展 dsh-code-review。** Review 指引可以在 diff 已存在后发现不可靠测试，但无法在 fixture 设计过程中指导 agent，也无法在没有 PR 时指导故障诊断。 + +**把完整流程放入常驻测试政策。** 测试政策需要保持为测试层级与放置规则的简洁权威来源。让每个测试任务都加载详细 Actions 诊断与资源专项流程，会重复情境性指引，也会降低政策的可扫描性。 + +**立即增加通用 stress runner 或正则 gate。** 重复运行保持绿色不能证明竞态已受控，而字面端口、路径、sleep 与 URL 可能是合法的 parser 输入或期望值。未来若出现高信号缺陷类型，可以增加窄范围的可执行检查，而不必把宽泛文本匹配当成政策。 + +## 后果 + +Agent 在设计或诊断确实需要这些规则的测试时获得可靠性指引，pre-push 与 review 流程也能共用同一套标准而不复制步骤。纯确定性测试继续采用普通的聚焦证据路径。 + +该 Skill 属于指导性规则，无法机械阻止所有资源冲突。如果某种缺陷反复出现且能被静态识别，仍可增加可执行的仓库检查。仓库也会多维护一个活跃 Skill 与 reference，其链接和陈述必须与真实 CI 拓扑保持一致。 + +现有确定性与压力测试提案继续开放，本变更也不会审计或重写当前测试语料库。 diff --git a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml index 66b0331800..ca7d2c9317 100644 --- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.i18n.yaml +++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.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/proposed/testing/2026-06-11-deterministic-and-stress-testing.md -2026-06-11-deterministic-and-stress-testing.md: d9977be835af05f9ee303b63ec6015bc9e153170 -2026-06-11-deterministic-and-stress-testing.zh.md: 263e69f85a1cd8ee47da07210e513cab272d1a44 +2026-06-11-deterministic-and-stress-testing.md: fd69611a393e36df5c5707640175bfd85c8e77ea +2026-06-11-deterministic-and-stress-testing.zh.md: 5ba8dbe4cf2a6c08bf1a3d68def9f801430b176a diff --git a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md index d9977be835..fd69611a39 100644 --- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md +++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.md @@ -4,6 +4,8 @@ Status: proposed English | [中文](2026-06-11-deterministic-and-stress-testing.zh.md) +The [CI test reliability skill](../../implemented/testing/2026-08-28-ci-test-reliability-skill.md) provides current authoring and diagnosis guidance without implementing the lint rule, universal replay fixture, or nightly stress job proposed here. Those mechanisms remain proposed. + ## Problem Several loop tests synchronize with `setTimeout(30)` sleeps — flakiness debt that wastes agent cycles on retries and can mask ordering bugs. Separately, our core architectural promise (any session log replays to identical derived history) is asserted in two tests but is cheap to assert *everywhere*. And the inbox wakeup race was verified by hand exactly once; nothing re-verifies it continuously. diff --git a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md index 263e69f85a..5ba8dbe4cf 100644 --- a/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md +++ b/.agents/notes/proposed/testing/2026-06-11-deterministic-and-stress-testing.zh.md @@ -4,6 +4,8 @@ Status: proposed [English](2026-06-11-deterministic-and-stress-testing.md) | 中文 +[CI 测试可靠性 Skill](../../implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md) 提供当前的测试编写与诊断指引，但没有实现本提案中的 lint 规则、通用回放 fixture 或 nightly stress job。这些机制仍处于提案状态。 + ## 问题 若干 agent loop（智能体循环）测试通过 `setTimeout(30)` 睡眠来同步——这是一笔不稳定性债务，浪费 agent 的重试周期，还可能掩盖时序 bug。另外，我们的核心架构承诺（任何会话日志回放后都能得到相同的派生历史）目前只在两个测试中断言，但在*所有*测试中断言的成本极低。此外，inbox 唤醒竞态只被手动验证过一次，没有任何机制持续复验。 diff --git a/.agents/skills/dsh-ci-test-reliability/SKILL.md b/.agents/skills/dsh-ci-test-reliability/SKILL.md new file mode 100644 index 0000000000..7483f13fb0 --- /dev/null +++ b/.agents/skills/dsh-ci-test-reliability/SKILL.md @@ -0,0 +1,109 @@ +--- +name: dsh-ci-test-reliability +description: Design, review, and diagnose DeepSeek Harness tests and fixtures that can fail nondeterministically under CI concurrency, shared host resources, clocks, process-global state, subprocesses, network listeners, or asynchronous teardown. Use when adding or changing tests with those risks, investigating flaky CI, or reviewing test isolation; use dsh-pre-push-checks separately to select outgoing commands. +--- + +# Reliable DSH CI tests + +Build tests that remain correct under the repository's real CI topology, not only when run alone on a quiet workstation. This skill owns isolation and reliability decisions; it does not replace the repository's test-tier policy or select every command for a push. + +## Read the owning rules + +- Use [the testing policy](../../../docs/testing.md) to select unit, coverage, expected-output, snapshot, browser, or real-API evidence. +- Use [the defensive patterns](../../../docs/defensive-patterns.md) for lifecycle, subprocess, cancellation, and teardown behavior. +- Read the active Vitest config and GitHub workflow when their worker or job topology affects the test. +- For recorded-session scenarios, also follow [the snapshot instructions](../../../snapshots/AGENTS.md). +- Use [dsh-pre-push-checks](../dsh-pre-push-checks/SKILL.md) after the test design is sound to select outgoing validation. + +## Model the execution topology + +Assume these layers can overlap unless the active configuration proves otherwise: + +1. Tests in one Vitest file. +2. Separate Vitest files or worker processes. +3. Independent Vitest or repository-gate processes in one job. +4. Different Actions jobs whose runners share one host. + +Process isolation does not isolate host ports, predictable filesystem paths, external services, databases, sockets, or inherited child processes. For every acquired resource, identify its owner, atomic allocation mechanism, observable readiness signal, registered cleanup, and quiescent completion signal. + +Do not serialize an entire suite merely because one fixture lacks isolation. Narrow the exclusive scope or change the resource allocation first. A sequential Vitest block cannot protect a host resource from another file, process, job, or runner. + +## Allocate resources atomically + +Use the resource owner's allocator instead of checking availability and claiming it later. + +- Network fixtures bind loopback with `listen(0)` and read the assigned address only after the server reports that it is listening. Never scan for a free port and bind it later. +- Create private per-test temporary roots with `mkdtemp`; do not acquire predictable shared paths. +- Give shared databases, sockets, sessions, and output locations unique per-test namespaces. +- Use exclusive creation where a path must not already exist. +- Keep stable recorded identifiers separate from ephemeral transport addresses. Translate inside the fixture instead of forcing the live resource to use the recorded value. + +Literal paths and URLs used only as parser inputs or expected values are not acquired resources. Do not rewrite them merely because they look fixed. + +## Contain process-global state + +Treat `process.env`, `cwd`, fake timers, locale and timezone, module mocks, registries, console hooks, `globalThis`, and global `fetch` interception as exclusive mutable resources. + +Prefer an injected dependency or instance-local adapter. When mutation is required: + +- capture whether the original value was absent or present; +- restore that exact state; +- register restoration immediately; +- use `try/finally` around the smallest mutation scope; +- keep an `afterEach` fallback when failure before the local `finally` is plausible; +- intercept the narrowest exact request or call that the fixture owns. + +## Synchronize on state + +A fixed sleep is not evidence that setup completed or cleanup settled. + +- Wait for an explicit readiness event, handshake, state transition, owned promise, or externally observable condition. +- Use deferred promises or barriers to place a race at a deterministic point and prove the relevant operations overlap. +- Use a timeout only to bound a wait, never as the condition that makes the assertion correct. +- Do not assert scheduler-dependent ordering unless that ordering is the product behavior under test. +- When time itself is the subject, inject or fake the clock and always restore real timers. + +## Dispose to quiescence + +Register cleanup immediately after acquisition so assertion failures also release the resource. Cleanup stops new callbacks or requests, detaches listeners, restores global hooks, terminates owned work, and awaits child exit, server close, worker termination, or the equivalent completion signal. + +Calling `abort()`, `close()`, or `kill()` without awaiting the owned completion signal is incomplete teardown. When late completion is possible, prove that disposal prevents it from mutating another test. + +## Prove the intended regression + +- Observe an ordinary regression fail before the fix when practical. +- For a new static or corpus guard, temporarily introduce the rejected case and observe the intended failure. +- For a race, use barriers to prove overlap; repeated execution alone is not a race test. +- For ports, sockets, shared paths, subprocesses, or other host resources, run independent test processes concurrently when cross-process isolation is part of the fix. +- Verify external state, events, files, logs, exits, or disposal instead of trusting the component's self-report. + +Stress runs supplement a deterministic regression; they do not replace one. + +## Reject flake-masking fixes + +Do not present these as root-cause fixes for deterministic local tests: + +- increasing a timeout without identifying the awaited state; +- adding retries; +- making all files serial; +- swallowing an error or unhandled rejection; +- weakening an assertion; +- normalizing away unstable behavior; +- adding a sleep before cleanup or assertion. + +Retries remain valid for documented transient external-provider tests under the real-API policy. Keep that exception at the external boundary. + +## Diagnose existing flakes + +For an existing probabilistic CI failure, read [the CI flake diagnosis workflow](references/ci-flake-diagnosis.md). A diagnosis-only request remains read-only: report the cause and evidence unless the user also asks for a fix. + +## Validate and report + +Run the smallest focused regression for the affected behavior. Add topology-specific evidence only when the change owns that risk: + +- global mutation needs restoration evidence; +- lifecycle or subprocess work needs quiescent teardown evidence; +- ports, sockets, or shared paths need concurrent independent-process evidence; +- a new guard needs a negative control. + +Before a push, use [dsh-pre-push-checks](../dsh-pre-push-checks/SKILL.md). Report exact commands and observed results; do not describe retries, skipped tests, or pending CI as passing. diff --git a/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md b/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md new file mode 100644 index 0000000000..101ad90cca --- /dev/null +++ b/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md @@ -0,0 +1,58 @@ +# CI flake diagnosis + +Use this workflow only when the task is to investigate an existing probabilistic test or CI failure. Preserve the requested read/write scope: diagnosis does not authorize a fix, workflow rerun, or CI configuration change. + +## Freeze the evidence + +Record the repository, workflow, job, commit SHA, runner labels, timestamps, exact failing test or command, and the first stable failure signature. Keep infrastructure messages separate from test output. + +Compare multiple failing and passing runs. Prefer runs of the same SHA; when that is impossible, verify that the relevant test and CI configuration are identical across the compared commits. One passing rerun does not prove an infrastructure fault, and one timeout does not prove a product race. + +Use Actions logs and metadata to establish whether failures overlap on one host or resource namespace. Preserve links to the supporting runs rather than pasting large logs. + +## Classify the failure + +Classify from recorded evidence, not from the eventual fix: + +- **Host-resource collision:** the same port, socket, database, predictable path, cache, or external namespace is acquired by independent processes or jobs. +- **Incomplete lifecycle:** teardown returns before children, workers, streams, servers, or callbacks reach quiescence; later output or mutations appear in another test. +- **Process-global contamination:** outcome depends on test order or leaked `process.env`, `cwd`, fake timers, globals, mocks, locale, or module state. +- **Load-sensitive synchronization:** a sleep, polling interval, or assumed event-loop turn substitutes for observable readiness or completion. +- **Platform or entry-path mismatch:** the failure consistently follows an operating system, shell, filesystem rule, source/build mode, or executable entry. +- **Product concurrency defect:** the test controls its resources, reproduces deterministically with explicit overlap, and exposes a race in shipped behavior. +- **External-provider transience:** the failure is owned by a live API or network boundary and matches its documented retry policy. +- **Runner infrastructure:** checkout, dependency download, disk, host process, or runner service fails independently of the test command. Require direct runner evidence before assigning this class. + +If evidence supports more than one independent fact, report each one. Do not collapse a timeout, signal, exit code, and assertion into a single inferred outcome. + +## Reproduce the smallest relevant topology + +Start with the owning test file or focused test name. Increase concurrency only to the first topology that reproduces the signature: + +1. one test process; +2. concurrent tests or files; +3. multiple independent Vitest processes; +4. the owning repository gate with its configured worker count; +5. separate jobs or runner processes sharing the implicated host resource. + +Match the active Vitest config, environment knobs, source/build mode, and platform. Do not lower a production timeout or add random load merely to manufacture a different failure. + +For a suspected race, replace probabilistic timing with a barrier at the contested transition. For a suspected host collision, prove simultaneous acquisition of the same identifier or prove that atomic unique allocation removes the conflict. + +## Fix at the owner + +When implementation is authorized, fix the component that allocates, publishes readiness, mutates global state, or owns teardown. Do not hide the failure in a snapshot normalizer, retry wrapper, broader timeout, global serialization setting, or weaker assertion. + +Keep stable fixture data separate from live resource allocation. A recorded URL can remain stable while the fixture maps its transport to an OS-assigned port; a stable expected path can remain an assertion without becoming a shared writable directory. + +## Close the investigation + +The evidence is complete when: + +- the original signature has a supported classification; +- the smallest relevant topology reproduces it, or the external evidence is sufficient and the reproduction limit is explicit; +- an authorized fix fails under a negative control or pre-fix state and passes under the same topology afterward; +- any concurrent-process, restoration, or quiescent-teardown proof required by the resource owner passes; +- remaining Actions checks are reported as passing, pending, skipped, or failing from their observed state. + +Do not run until a test happens to pass and call that result stable. Stop after the selected evidence establishes the conclusion, or report the missing fact that blocks classification. diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md index 510e01f3d5..a18ac20d4e 100644 --- a/.agents/skills/dsh-code-review/SKILL.md +++ b/.agents/skills/dsh-code-review/SKILL.md @@ -13,6 +13,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo — - [docs/defensive-patterns.md](../../../docs/defensive-patterns.md): subprocess, callback, async-state, and disposal bug classes. - [docs/AGENTS.md](../../../docs/AGENTS.md): documentation placement and prose discipline. - [dsh-prose-standard](../dsh-prose-standard/SKILL.md): required coverage and editorial judgment for comments, docs, prompts, and visible strings. +- [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md): isolation and regression-proof rules for resource-owning, asynchronous, or flaky tests and fixtures. - [docs/testing.md](../../../docs/testing.md) and the [quality-gates Agent Note](../../notes/implemented/process/2026-06-11-quality-gates.md): required test tiers and gates. - [Agent Notes](../../notes/README.md): design rationale. Treat disagreement with an Agent Note as a design discussion, not an automatic veto. - For bilingual changes, read [translation-rules.md](../../../docs/i18n/translation-rules.md) and [terminology.md](../../../docs/i18n/terminology.md); the extended translation skill is outside automatic review and runs only on explicit user invocation. @@ -39,7 +40,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo — - **Borrowed and derived state:** determine whether each retained value is borrowed or owned under the package contract, then trace notifications and every cache, prompt, UI echo, replay, and query view to the documented success point and authoritative source. - **Bounds cover the final operation:** locate the owner of the complete emitted or retained result, including wrappers and metadata. Probe tiny and exact limits, oversized single chunks, and multibyte text for byte limits. - **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch invalid Loader exports; a function plugin must named-export its namespace and have no default export. -- **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct. +- **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. For resource-owning, asynchronous, or flaky tests, apply [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) to the real worker/job topology, allocation, restoration, synchronization, and quiescent teardown. Coverage is necessary but not evidence that the scenario is correct. - **Invariant lifecycle and negative controls:** verify candidate observations are rejected before publication where possible, session-backed checks reconstruct durable history after late loading or HMR, and a deliberately invalid case fails through the real runner for the intended rule. - **Implemented Agent Notes match shipped reality:** when a PR implements a proposed Agent Note, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation. - **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review expected-output diffs as behavior changes, not formatting noise. diff --git a/.agents/skills/dsh-pre-push-checks/SKILL.md b/.agents/skills/dsh-pre-push-checks/SKILL.md index a9902a45d7..9a687e8f9f 100644 --- a/.agents/skills/dsh-pre-push-checks/SKILL.md +++ b/.agents/skills/dsh-pre-push-checks/SKILL.md @@ -28,6 +28,8 @@ The command never guesses or fetches a base. Supply the ref verified from curren There is no universal local baseline beyond the hooks. Every behavior change needs the narrowest available test or purpose-built check that would fail for its regression; add broader checks only for surfaces the diff actually reaches. +When the outgoing change adds or changes a resource-owning or asynchronous test, fixture, helper, or CI execution path, use [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) first to decide whether restoration, negative-control, quiescent-teardown, or concurrent-process evidence applies. This skill still selects the commands and avoids repeating evidence that already passed. + - **Package or script behavior:** run the owning Vitest file or focused test name. Add adjacent package tests when a shared contract changes; leave repository-wide coverage to CI unless the change is genuinely cross-cutting or the user requests it. - **Documentation, Agent Notes, catalogs, or doc-linked comments:** run `pnpm run doc-sync`; run full lint when the documentation workflow requires it. - **Model-, editor-, CLI-, or terminal-visible output:** run the focused keyless snapshot or real runnable-example scenario that owns the output. From 596a13d1cb73ee797efd22b19fb12d301031e00f Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 13:54:59 +0800 Subject: [PATCH 24/63] docs(testing): add platform-semantics and lane-budget rules to the skill Two failure classes the repository paid for are not covered by the isolation, synchronization, and teardown rules already in the skill. A value the operating system owns is not guaranteed to return as written. A test may write one back only where the assertion tolerates that write-back failing; where the assertion depends on it, the expected value comes from a fresh read. NTFS truncating a fractional-millisecond mtime and Windows folding environment variable name case are the two instances seen so far. A describe or case timeout overrides the runner's --testTimeout rather than yielding to it, so a value below the lane budget lowers what CI granted, while the same literal reads as a widening where the host default is smaller. The hook budget travels with the test budget, and a case asserting a timeout keeps its outer wait far larger than the timeout under test. Restoring a granted budget, or sizing a bounded retry to measured contention, is named as distinct from the masking fixes the skill rejects. The diagnosis reference gains the platform differences under its platform class, a classification path for self-hosted pools that expose no host metrics, and the stopping rule for a signature no available host can reproduce. --- ...-08-28-ci-test-reliability-skill.i18n.yaml | 4 ++-- .../2026-08-28-ci-test-reliability-skill.md | 2 ++ ...2026-08-28-ci-test-reliability-skill.zh.md | 2 ++ .../skills/dsh-ci-test-reliability/SKILL.md | 22 +++++++++++++++++++ .../references/ci-flake-diagnosis.md | 6 +++-- 5 files changed, 32 insertions(+), 4 deletions(-) diff --git a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml index 473728433a..6d33252c51 100644 --- a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.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/testing/2026-08-28-ci-test-reliability-skill.md -2026-08-28-ci-test-reliability-skill.md: 5edf2aa769047cb5d4052a1338f2cc3886d9e0f9 -2026-08-28-ci-test-reliability-skill.zh.md: fd1a6d584f3c4686761f8c94ba99ee0d1c9b0233 +2026-08-28-ci-test-reliability-skill.md: 1c8e0389dfa6e3eb3a6e04e994e6400d19a673ac +2026-08-28-ci-test-reliability-skill.zh.md: ef36eab497bee874cd117488ddf4895c7edd0ed1 diff --git a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md index 5edf2aa769..1c8e0389df 100644 --- a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md +++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.md @@ -16,6 +16,8 @@ The testing policy owns test tiers, defensive patterns own runtime lifecycle rul The skill requires agents to model concurrency beyond one Vitest process, allocate live resources atomically, separate stable fixture identities from ephemeral transport addresses, synchronize on observable state, restore global mutations exactly, and await teardown to quiescence. Regression evidence matches the owned risk: negative controls for guards, deterministic barriers for races, concurrent independent processes for host-resource isolation, and external observations instead of component self-reports. +Two rules cover the failures the repository has actually paid for. A value the operating system owns is not guaranteed to return as written, so a test may write one back only where the assertion tolerates that write-back failing; where the assertion depends on it, the expected value comes from a fresh read. And a suite timeout overrides the runner flag rather than yielding to it, so a suite bound by process creation takes the lane budget, raises the hook budget with it, and keeps an outer wait far larger than any timeout under test. Restoring a granted budget or sizing a bounded retry to measured contention is therefore not a masking fix. + The diagnosis-only workflow lives in a separate reference so ordinary authoring does not load Actions triage procedure. It compares passing and failing evidence before classifying host collisions, incomplete lifecycle, global contamination, load-sensitive synchronization, platform or entry-path failures, product races, provider transience, or runner infrastructure. [dsh-pre-push-checks](../../../skills/dsh-pre-push-checks/SKILL.md) conditionally consults the reliability skill before selecting commands, while [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) applies it when reviewing risky tests. Command selection and general PR review remain with those existing skills. diff --git a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md index fd1a6d584f..ef36eab497 100644 --- a/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md +++ b/.agents/notes/implemented/testing/2026-08-28-ci-test-reliability-skill.zh.md @@ -16,6 +16,8 @@ DeepSeek Harness 会在并发的 Vitest 文件、worker 进程、仓库 gate 与 该 Skill 要求 agent 建模单个 Vitest 进程之外的并发，原子分配实时资源，把稳定 fixture 标识与临时传输地址分开，按可观察状态同步，精确恢复全局变更，并等待 teardown 达到静止状态。回归证据与所持有的风险匹配：guard 使用负向控制，竞态使用确定性 barrier，宿主机资源隔离使用并发独立进程，并以外部观察代替组件自述。 +另有两条规则覆盖仓库已经付出过代价的失败。操作系统拥有的值不保证按写入的样子返回，因此只有在断言容忍写回失败时，测试才可以把它写回去；断言依赖写回成功时，期望值取自重新读取。以及套件级 timeout 覆盖而不是让位于 runner 的 flag，因此受进程创建约束的套件取 lane 预算、连同 hook 预算一起抬高，并让外层等待远大于任何被测超时。据此，恢复已被授予的预算、或按实测争抢标定一个有界重试，都不属于掩盖式修复。 + 仅用于诊断的流程放在单独 reference 中，因此普通编写任务不会加载 Actions 分诊步骤。它会先比较成功与失败证据，再对宿主机冲突、未完成生命周期、全局状态污染、负载敏感同步、平台或入口路径失败、产品竞态、provider 瞬时故障或 runner 基础设施进行分类。 [dsh-pre-push-checks](../../../skills/dsh-pre-push-checks/SKILL.md) 在选择命令前按条件引用可靠性 Skill，[dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 则在 review 高风险测试时应用它。命令选择与通用 PR review 仍由这些现有 Skill 负责。 diff --git a/.agents/skills/dsh-ci-test-reliability/SKILL.md b/.agents/skills/dsh-ci-test-reliability/SKILL.md index 7483f13fb0..d9fd0f1700 100644 --- a/.agents/skills/dsh-ci-test-reliability/SKILL.md +++ b/.agents/skills/dsh-ci-test-reliability/SKILL.md @@ -53,6 +53,25 @@ Prefer an injected dependency or instance-local adapter. When mutation is requir - keep an `afterEach` fallback when failure before the local `finally` is plausible; - intercept the narrowest exact request or call that the fixture owns. +## Respect platform-owned semantics + +CI runs the same suite on Windows and on POSIX hosts, and a value the operating system owns does not always come back the way a test wrote it. + +- Writing a value back is safe only when the assertion tolerates the write-back failing. Restoring a file's `mtime` to prove that a fingerprint invalidates anyway holds everywhere; restoring it to prove that a record stays valid assumes a lossless round trip, which NTFS's 100-nanosecond ticks do not give a fractional millisecond. When the assertion depends on the restoration, take the expected value from a fresh read rather than from the remembered one. +- Windows matches environment variable names case-insensitively, so a fixture seeding `http_proxy` and `HTTP_PROXY` as separate keys holds one entry there. +- Windows releases file handles asynchronously, so a rename or removal that completes at once on a POSIX host needs a bounded retry sized to the observed contention. +- Windows has no POSIX permission or signal semantics. A case that depends on them takes an explicit platform skip naming the reason, rather than an assertion weakened everywhere. + +Prefer an observation that holds on every platform. When a case genuinely cannot, exclude it on that platform explicitly. + +## Budget timeouts against the lane + +A `describe` or case timeout overrides the runner's `--testTimeout` instead of yielding to it, so a value below the lane's budget lowers what CI already granted — and the same literal reads as a widening on a host whose default is smaller. A suite bound by process creation takes the lane budget; a tighter value carries the reason it is tighter. + +Raise the hook budget with the test budget. Setup and teardown pay the same contention, so lifting only the case budget moves a contended failure into `afterEach`. + +Where a timeout is the subject, keep the outer wait far larger than the timeout under test. A case proving that a 20 ms deadline fires must not race the harness's own wait, or load decides which deadline reports first. + ## Synchronize on state A fixed sleep is not evidence that setup completed or cleanup settled. @@ -75,6 +94,7 @@ Calling `abort()`, `close()`, or `kill()` without awaiting the owned completion - For a new static or corpus guard, temporarily introduce the rejected case and observe the intended failure. - For a race, use barriers to prove overlap; repeated execution alone is not a race test. - For ports, sockets, shared paths, subprocesses, or other host resources, run independent test processes concurrently when cross-process isolation is part of the fix. +- Where a fixture spawns with its own deadline, assert that no signal or timeout ended the child before asserting its exit status, so a killed child reports as a timeout instead of as a status mismatch. - Verify external state, events, files, logs, exits, or disposal instead of trusting the component's self-report. Stress runs supplement a deterministic regression; they do not replace one. @@ -93,6 +113,8 @@ Do not present these as root-cause fixes for deterministic local tests: Retries remain valid for documented transient external-provider tests under the real-API policy. Keep that exception at the external boundary. +Restoring a budget is not masking. Raising a suite to the lane budget it already had, or sizing a bounded retry to the contention actually measured on the runner, names the awaited work and returns what the lane granted; neither invents headroom around an unexamined wait. + ## Diagnose existing flakes For an existing probabilistic CI failure, read [the CI flake diagnosis workflow](references/ci-flake-diagnosis.md). A diagnosis-only request remains read-only: report the cause and evidence unless the user also asks for a fix. diff --git a/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md b/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md index 101ad90cca..9cdfb61972 100644 --- a/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md +++ b/.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md @@ -18,10 +18,10 @@ Classify from recorded evidence, not from the eventual fix: - **Incomplete lifecycle:** teardown returns before children, workers, streams, servers, or callbacks reach quiescence; later output or mutations appear in another test. - **Process-global contamination:** outcome depends on test order or leaked `process.env`, `cwd`, fake timers, globals, mocks, locale, or module state. - **Load-sensitive synchronization:** a sleep, polling interval, or assumed event-loop turn substitutes for observable readiness or completion. -- **Platform or entry-path mismatch:** the failure consistently follows an operating system, shell, filesystem rule, source/build mode, or executable entry. +- **Platform or entry-path mismatch:** the failure consistently follows an operating system, shell, filesystem rule, source/build mode, or executable entry. Timestamp precision, environment variable name case, handle-release timing, and permission semantics all differ between Windows and POSIX hosts, so a case passing on macOS says nothing about the Windows lane. - **Product concurrency defect:** the test controls its resources, reproduces deterministically with explicit overlap, and exposes a race in shipped behavior. - **External-provider transience:** the failure is owned by a live API or network boundary and matches its documented retry policy. -- **Runner infrastructure:** checkout, dependency download, disk, host process, or runner service fails independently of the test command. Require direct runner evidence before assigning this class. +- **Runner infrastructure:** checkout, dependency download, disk, host process, or runner service fails independently of the test command. Require direct runner evidence before assigning this class. Where a self-hosted pool exposes no host metrics, say so and classify from what the logs do carry: one signature repeating across unrelated branches on one pool is evidence of shared-host contention even when the host cannot be inspected. If evidence supports more than one independent fact, report each one. Do not collapse a timeout, signal, exit code, and assertion into a single inferred outcome. @@ -37,6 +37,8 @@ Start with the owning test file or focused test name. Increase concurrency only Match the active Vitest config, environment knobs, source/build mode, and platform. Do not lower a production timeout or add random load merely to manufacture a different failure. +Where the signature belongs to a platform the available host cannot run, the ladder stops at the last reachable rung. Record that limit rather than substituting a passing run on another platform, then use CI as the reproduction, changing one suspected owner per run so the result stays attributable. + For a suspected race, replace probabilistic timing with a barrier at the contested transition. For a suspected host collision, prove simultaneous acquisition of the same identifier or prove that atomic unique allocation removes the conflict. ## Fix at the owner From de256e8bc134a9063b61a4b9930909b407ba4eb4 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 26 Aug 2026 15:49:42 +0800 Subject: [PATCH 25/63] feat: enforce published dependency policy --- package.json | 3 + .../benchmark-next-package-dependency.spec.ts | 114 +++++ scripts/benchmark-next-package-dependency.ts | 271 ++++++++++ scripts/benchmark-npm-resolution.spec.ts | 84 +++ scripts/benchmark-npm-resolution.ts | 417 +++++++++++++++ scripts/package-dependency-policy.ts | 52 ++ scripts/package-invariants.spec.ts | 62 ++- scripts/package-invariants.ts | 23 +- scripts/run-gates.spec.ts | 11 +- scripts/run-gates.ts | 2 + scripts/verify-client-packages.spec.ts | 162 +----- scripts/verify-client-packages.ts | 314 +----------- scripts/verify-package-dependencies.spec.ts | 260 ++++++++++ scripts/verify-package-dependencies.ts | 479 ++++++++++++++++++ 14 files changed, 1804 insertions(+), 450 deletions(-) create mode 100644 scripts/benchmark-next-package-dependency.spec.ts create mode 100644 scripts/benchmark-next-package-dependency.ts create mode 100644 scripts/benchmark-npm-resolution.spec.ts create mode 100644 scripts/benchmark-npm-resolution.ts create mode 100644 scripts/package-dependency-policy.ts create mode 100644 scripts/verify-package-dependencies.spec.ts create mode 100644 scripts/verify-package-dependencies.ts diff --git a/package.json b/package.json index 9587f220d0..2ec0a09049 100644 --- a/package.json +++ b/package.json @@ -50,6 +50,8 @@ "test:web:perf": "npm run build && npm run test:web:perf:built", "test:web:perf:built": "DSH_SNAPSHOT=replay vitest run --config vitest.web.perf.config.ts", "test:web:stress": "npm run build && vitest run --config vitest.web-stress.config.ts", + "benchmark:npm-resolution": "tsx scripts/benchmark-npm-resolution.ts", + "benchmark:npm-resolution:next": "tsx scripts/benchmark-next-package-dependency.ts", "test:gui": "vitest run packages/client packages/host", "check:all": "tsx scripts/run-gates.ts check-all", "check:ci": "tsx scripts/run-gates.ts ci-primary", @@ -104,6 +106,7 @@ "verify-optional-dependency-imports": "tsx scripts/verify-optional-dependency-imports.ts", "verify-runtime-closure": "tsx scripts/verify-runtime-closure.ts", "verify-application-entrypoints": "tsx scripts/verify-application-entrypoints.ts", + "verify-package-dependencies": "tsx scripts/verify-package-dependencies.ts", "verify-client-packages": "tsx scripts/verify-client-packages.ts", "verify-client-ui-i18n": "tsx scripts/verify-client-ui-i18n.ts", "verify-vendored-links": "tsx scripts/verify-vendored-links.ts", diff --git a/scripts/benchmark-next-package-dependency.spec.ts b/scripts/benchmark-next-package-dependency.spec.ts new file mode 100644 index 0000000000..9248a3288e --- /dev/null +++ b/scripts/benchmark-next-package-dependency.spec.ts @@ -0,0 +1,114 @@ +import { describe, expect, it } from 'vitest' +import { + applyFactsToRegistry, + discoverBenchmarkCandidates, + parseNextPackageBenchmarkOptions, + type MutableRegistryManifest, +} from './benchmark-next-package-dependency.ts' +import type { + PackageDependencyFacts, + PackageDependencyManifest, + WorkspacePackageManifest, +} from './verify-package-dependencies.ts' +import type { RegistryIndex } from './benchmark-npm-resolution.ts' + +describe('next package benchmark options', () => { + it('parses candidate and repetition controls', () => { + expect(parseNextPackageBenchmarkOptions([ + '--', + '--candidates=@f/a,@f/b', + '--runs=2', + '--finalist-runs=4', + '--finalists=3', + '--jobs=6', + '--timeout-ms=9000', + ])).toEqual({ + candidates: ['@f/a', '@f/b'], + coarseRuns: 2, + finalistRuns: 4, + finalists: 3, + jobs: 6, + timeoutMs: 9000, + }) + }) + + it('rejects invalid positive integers', () => { + expect(() => parseNextPackageBenchmarkOptions(['--jobs=0'])).toThrow('--jobs must be a positive integer') + }) +}) + +describe('next package benchmark graph', () => { + it('applies a source-derived candidate without changing the filesystem', () => { + const manifest: PackageDependencyManifest & { version: string } = { + name: '@f/probe', + version: '1.0.0', + peerDependencies: { + '@deepseek-ai/cordis': 'workspace:^', + '@f/runtime': 'workspace:^', + '@f/types': 'workspace:^', + }, + devDependencies: { + '@deepseek-ai/cordis': 'workspace:^', + '@f/runtime': 'workspace:^', + '@f/types': 'workspace:^', + }, + } + const facts: PackageDependencyFacts = { + manifestPath: 'packages/g/probe/package.json', + role: 'configured-host', + manifest, + workspaceNames: new Set(['@deepseek-ai/cordis', '@f/probe', '@f/runtime', '@f/types']), + allSourceUses: new Map([ + ['@f/runtime', ['packages/g/probe/src/index.ts']], + ['@f/types', ['packages/g/probe/src/types.ts']], + ]), + hostRuntimeSourceUses: new Map([['@f/runtime', ['packages/g/probe/src/index.ts']]]), + clientInject: new Set(), + } + const index = new Map>([ + ['@f/probe', new Map([['1.0.0', structuredClone(manifest) as MutableRegistryManifest]])], + ]) + applyFactsToRegistry(index, facts, new Map([ + ['@deepseek-ai/cordis', '4.0.1'], + ['@f/probe', '1.0.0'], + ['@f/runtime', '2.0.0'], + ['@f/types', '3.0.0'], + ])) + + expect(index.get('@f/probe')?.get('1.0.0')).toMatchObject({ + dependencies: { '@f/runtime': '^2.0.0' }, + peerDependencies: { '@deepseek-ai/cordis': '^4.0.1' }, + }) + expect(index.get('@f/probe')?.get('1.0.0')?.dependencies).not.toHaveProperty('@f/types') + }) + + it('finds reachable unconfigured packages with non-Cordis peers', () => { + const index = new Map([ + ['@deepseek-ai/dsh', new Map([['1.0.0', { + name: '@deepseek-ai/dsh', version: '1.0.0', dependencies: { '@f/a': '^1.0.0', '@f/b': '^1.0.0' }, + }]])], + ['@f/a', new Map([['1.0.0', { + name: '@f/a', version: '1.0.0', peerDependencies: { '@f/runtime': '^1.0.0' }, + }]])], + ['@f/b', new Map([['1.0.0', { + name: '@f/b', version: '1.0.0', peerDependencies: { '@deepseek-ai/cordis': '^4.0.0' }, + }]])], + ['@f/runtime', new Map([['1.0.0', { name: '@f/runtime', version: '1.0.0' }]])], + ]) as RegistryIndex + const release = new Map([ + ['@f/a', { + name: '@f/a', dir: 'packages/g/a', manifestPath: 'packages/g/a/package.json', manifest: { name: '@f/a' }, + }], + ['@f/b', { + name: '@f/b', dir: 'packages/g/b', manifestPath: 'packages/g/b/package.json', manifest: { name: '@f/b' }, + }], + ]) + + expect(discoverBenchmarkCandidates( + index, + new Map([['@deepseek-ai/dsh', '1.0.0'], ['@f/a', '1.0.0'], ['@f/b', '1.0.0']]), + release, + new Set(), + )).toEqual(['@f/a']) + }) +}) diff --git a/scripts/benchmark-next-package-dependency.ts b/scripts/benchmark-next-package-dependency.ts new file mode 100644 index 0000000000..545045de6f --- /dev/null +++ b/scripts/benchmark-next-package-dependency.ts @@ -0,0 +1,271 @@ +/** Benchmark which additional Host package most reduces npm peer resolution. */ + +import { availableParallelism } from 'node:os' +import { resolve } from 'node:path' +import { parseArgs } from 'node:util' +import { + benchmarkNpmResolution, + buildRegistryIndex, + parsePositiveIntegerOption, + publishWorkspaceRange, + type RegistryIndex, +} from './benchmark-npm-resolution.ts' +import { + readPackageDependencyFacts, + readPackageDependencyState, + readWorkspacePackageManifests, + repairPackageDependencyManifest, + type PackageDependencyFacts, + type WorkspacePackageManifest, +} from './verify-package-dependencies.ts' + +const TARGET_PACKAGE = '@deepseek-ai/dsh' +const CORDIS = '@deepseek-ai/cordis' + +interface Options { + readonly candidates?: readonly string[] + readonly coarseRuns: number + readonly finalistRuns: number + readonly finalists: number + readonly jobs: number + readonly timeoutMs: number +} + +export interface MutableRegistryManifest { + name: string + version: string + dependencies?: Record + optionalDependencies?: Record + peerDependencies?: Record + peerDependenciesMeta?: Record +} + +interface Measurement { + readonly package: string + readonly seconds: readonly number[] + readonly medianSeconds: number +} + +/** Parse benchmark selection and repetition options. */ +export function parseNextPackageBenchmarkOptions(args: readonly string[]): Options { + const normalized = args[0] === '--' ? args.slice(1) : args + const { values } = parseArgs({ + args: [...normalized], + options: { + candidates: { type: 'string' }, + runs: { type: 'string' }, + 'finalist-runs': { type: 'string' }, + finalists: { type: 'string' }, + jobs: { type: 'string' }, + 'timeout-ms': { type: 'string' }, + }, + allowPositionals: false, + }) + return { + ...(values.candidates === undefined + ? {} + : { candidates: values.candidates.split(',').filter(Boolean) }), + coarseRuns: parsePositiveIntegerOption(values.runs, 1, '--runs'), + finalistRuns: parsePositiveIntegerOption(values['finalist-runs'], 3, '--finalist-runs'), + finalists: parsePositiveIntegerOption(values.finalists, 5, '--finalists'), + jobs: parsePositiveIntegerOption(values.jobs, Math.min(8, availableParallelism()), '--jobs'), + timeoutMs: parsePositiveIntegerOption(values['timeout-ms'], 120_000, '--timeout-ms'), + } +} + +function median(values: readonly number[]): number { + const sorted = [...values].sort((left, right) => left - right) + const middle = Math.floor(sorted.length / 2) + return sorted.length % 2 === 0 + ? ((sorted[middle - 1] ?? 0) + (sorted[middle] ?? 0)) / 2 + : sorted[middle] ?? 0 +} + +function cloneIndex(index: RegistryIndex): Map> { + return new Map([...index].map(([name, versions]) => [ + name, + new Map([...versions].map(([version, manifest]) => [ + version, + structuredClone(manifest) as MutableRegistryManifest, + ])), + ])) +} + +function publishedSection( + values: Readonly> | undefined, + workspaceVersions: ReadonlyMap, +): Record | undefined { + if (values === undefined) return undefined + return Object.fromEntries(Object.entries(values).map(([name, range]) => { + const version = workspaceVersions.get(name) + return [name, version === undefined ? range : publishWorkspaceRange(range, version)] + })) +} + +/** Apply one source-derived policy result to an in-memory registry manifest. */ +export function applyFactsToRegistry( + index: Map>, + facts: PackageDependencyFacts, + workspaceVersions: ReadonlyMap, +): void { + const source = structuredClone(facts.manifest) + repairPackageDependencyManifest({ ...facts, manifest: source }) + const version = workspaceVersions.get(source.name ?? '') + const target = version === undefined ? undefined : index.get(source.name ?? '')?.get(version) + if (target === undefined) throw new Error(`local registry has no ${source.name ?? 'unnamed package'}@${version ?? 'unknown'}`) + for (const field of ['dependencies', 'optionalDependencies', 'peerDependencies'] as const) { + const values = publishedSection(source[field], workspaceVersions) + if (values !== undefined) target[field] = values + else if (field === 'dependencies') delete target.dependencies + else if (field === 'optionalDependencies') delete target.optionalDependencies + else delete target.peerDependencies + } + if (source.peerDependenciesMeta === undefined) delete target.peerDependenciesMeta + else target.peerDependenciesMeta = structuredClone(source.peerDependenciesMeta) as Record +} + +function currentVersion(pkg: WorkspacePackageManifest): string { + const version = pkg.manifest.version + if (typeof version !== 'string') throw new Error(`${pkg.manifestPath}: missing package version`) + return version +} + +/** Find reachable Host candidates whose published manifests still carry non-Cordis peers. */ +export function discoverBenchmarkCandidates( + index: RegistryIndex, + workspaceVersions: ReadonlyMap, + releasePackages: ReadonlyMap, + policyPackages: ReadonlySet, +): string[] { + const reached = new Set() + const queue = [TARGET_PACKAGE] + for (let cursor = 0; cursor < queue.length; cursor += 1) { + const name = queue[cursor] + if (name === undefined || reached.has(name)) continue + const version = workspaceVersions.get(name) + const manifest = version === undefined ? undefined : index.get(name)?.get(version) + if (manifest === undefined) continue + reached.add(name) + const installed = { + ...manifest.dependencies, + ...manifest.optionalDependencies, + ...Object.fromEntries(Object.entries(manifest.peerDependencies ?? {}) + .filter(([peer]) => (manifest.peerDependenciesMeta?.[peer] as { optional?: boolean } | undefined)?.optional !== true)), + } + for (const dependency of Object.keys(installed).sort()) { + if (!reached.has(dependency)) queue.push(dependency) + } + } + return [...reached].filter((name) => { + if (policyPackages.has(name) || !releasePackages.has(name)) return false + const version = workspaceVersions.get(name) + const manifest = version === undefined ? undefined : index.get(name)?.get(version) + return Object.keys(manifest?.peerDependencies ?? {}).some(peer => peer !== CORDIS) + }).sort() +} + +async function measure( + index: RegistryIndex, + targetVersion: string, + runs: number, + timeoutMs: number, +): Promise { + const seconds: number[] = [] + for (let run = 0; run < runs; run += 1) { + const result = await benchmarkNpmResolution(index, targetVersion, timeoutMs) + if (result.archiveRequests > 0) throw new Error('metadata-only benchmark requested package archives') + seconds.push(Number((result.durationMs / 1000).toFixed(2))) + } + return seconds +} + +async function mapConcurrent( + values: readonly T[], + jobs: number, + operation: (value: T) => Promise, +): Promise { + const results: R[] = [] + let next = 0 + await Promise.all(Array.from({ length: Math.min(jobs, values.length) }, async () => { + while (next < values.length) { + const index = next + next += 1 + const value = values[index] + if (value === undefined) return + results[index] = await operation(value) + } + })) + return results +} + +async function main(): Promise { + const options = parseNextPackageBenchmarkOptions(process.argv.slice(2)) + const root = resolve(import.meta.dirname, '..') + const packages = readWorkspacePackageManifests(root) + const workspaceVersions = new Map(packages.all.map(pkg => [pkg.name, currentVersion(pkg)])) + const releaseByName = new Map(packages.release.map(pkg => [pkg.name, pkg])) + const state = readPackageDependencyState(root) + if (state.policyViolations.length > 0) throw new Error(state.policyViolations.join('\n')) + const base = cloneIndex(buildRegistryIndex(root)) + for (const facts of state.facts) applyFactsToRegistry(base, facts, workspaceVersions) + const targetVersion = workspaceVersions.get(TARGET_PACKAGE) + if (targetVersion === undefined) throw new Error(`workspace has no ${TARGET_PACKAGE}`) + const policyNames = new Set(state.facts.map(facts => facts.manifest.name).filter(name => name !== undefined)) + const discovered = discoverBenchmarkCandidates(base, workspaceVersions, releaseByName, policyNames) + const candidates = options.candidates ?? discovered + for (const name of candidates) { + if (!discovered.includes(name)) throw new Error(`${name} is not a reachable unconfigured Host candidate`) + } + const candidateFacts = new Map(candidates.map((name) => { + const pkg = releaseByName.get(name) + if (pkg === undefined) throw new Error(`release set has no ${name}`) + return [name, readPackageDependencyFacts(root, pkg, 'configured-host', state.workspaceNames)] + })) + + const baselineSeconds = await measure(base, targetVersion, options.finalistRuns, options.timeoutMs) + const baseline = median(baselineSeconds) + console.log(JSON.stringify({ type: 'baseline', seconds: baselineSeconds, medianSeconds: baseline })) + + const coarse = await mapConcurrent(candidates, options.jobs, async (name): Promise => { + const index = cloneIndex(base) + const facts = candidateFacts.get(name) + if (facts === undefined) throw new Error(`missing source facts for ${name}`) + applyFactsToRegistry(index, facts, workspaceVersions) + const seconds = await measure(index, targetVersion, options.coarseRuns, options.timeoutMs) + const result = { package: name, seconds, medianSeconds: median(seconds) } + console.log(JSON.stringify({ type: 'coarse', ...result })) + return result + }) + const finalists = coarse.sort((left, right) => left.medianSeconds - right.medianSeconds) + .slice(0, options.finalists) + const measured: Measurement[] = [] + for (const finalist of finalists) { + const index = cloneIndex(base) + const facts = candidateFacts.get(finalist.package) + if (facts === undefined) throw new Error(`missing source facts for ${finalist.package}`) + applyFactsToRegistry(index, facts, workspaceVersions) + const seconds = await measure(index, targetVersion, options.finalistRuns, options.timeoutMs) + measured.push({ package: finalist.package, seconds, medianSeconds: median(seconds) }) + } + const ranking = measured.sort((left, right) => left.medianSeconds - right.medianSeconds) + .map(result => ({ + ...result, + gainSeconds: Number((baseline - result.medianSeconds).toFixed(2)), + })) + console.log(JSON.stringify({ + type: 'result', + baselineSeconds, + baselineMedianSeconds: baseline, + candidateCount: candidates.length, + ranking, + }, null, 2)) +} + +if (import.meta.main) { + try { + await main() + } catch (error) { + console.error(`benchmark-next-package-dependency: ${error instanceof Error ? error.message : String(error)}`) + process.exitCode = 1 + } +} diff --git a/scripts/benchmark-npm-resolution.spec.ts b/scripts/benchmark-npm-resolution.spec.ts new file mode 100644 index 0000000000..92a6bdbfcb --- /dev/null +++ b/scripts/benchmark-npm-resolution.spec.ts @@ -0,0 +1,84 @@ +import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { dirname, join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { + benchmarkNpmResolution, + buildRegistryIndex, + parseBenchmarkOptions, + publishWorkspaceRange, + type RegistryIndex, +} from './benchmark-npm-resolution.ts' + +const roots: string[] = [] + +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) +}) + +function writeJson(root: string, path: string, value: unknown): void { + const absolute = join(root, path) + mkdirSync(dirname(absolute), { recursive: true }) + writeFileSync(absolute, `${JSON.stringify(value, null, 2)}\n`) +} + +describe('npm resolution benchmark', () => { + it('parses repeat, timeout, threshold, and ref options', () => { + expect(parseBenchmarkOptions([])).toEqual({ runs: 1, timeoutMs: 300_000 }) + expect(parseBenchmarkOptions([ + '--runs', '3', '--timeout-ms', '45000', '--max-ms', '20000', '--ref', 'master', + ])).toEqual({ runs: 3, timeoutMs: 45_000, maxMs: 20_000, ref: 'master' }) + expect(parseBenchmarkOptions(['--', '--runs', '2'])).toEqual({ runs: 2, timeoutMs: 300_000 }) + expect(() => parseBenchmarkOptions(['--runs', '0'])).toThrow('--runs must be a positive integer') + }) + + it('projects workspace protocols to published ranges', () => { + expect(publishWorkspaceRange('workspace:^', '1.2.3')).toBe('^1.2.3') + expect(publishWorkspaceRange('workspace:~', '1.2.3')).toBe('~1.2.3') + expect(publishWorkspaceRange('workspace:*', '1.2.3')).toBe('1.2.3') + expect(publishWorkspaceRange('^4.0.0', '1.2.3')).toBe('^4.0.0') + }) + + it('combines installed metadata with current publishable workspace fields', () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-npm-registry-index-')) + roots.push(root) + writeJson(root, 'node_modules/.pnpm/external@2.0.0/node_modules/external/package.json', { + name: 'external', + version: '2.0.0', + dependencies: { child: '^1.0.0' }, + devDependencies: { ignored: '^1.0.0' }, + }) + writeJson(root, 'apps/cli/package.json', { + name: '@deepseek-ai/dsh', + version: '0.1.0', + dependencies: { '@deepseek-ai/dsh-child': 'workspace:^', external: '^2.0.0' }, + devDependencies: { ignored: 'workspace:^' }, + }) + writeJson(root, 'packages/core/child/package.json', { + name: '@deepseek-ai/dsh-child', + version: '0.1.0', + }) + + const index = buildRegistryIndex(root) + + expect(index.get('external')?.get('2.0.0')).toMatchObject({ dependencies: { child: '^1.0.0' } }) + expect(index.get('@deepseek-ai/dsh')?.get('0.1.0')).toEqual({ + name: '@deepseek-ai/dsh', + version: '0.1.0', + dependencies: { '@deepseek-ai/dsh-child': '^0.1.0', external: '^2.0.0' }, + }) + }) + + it('runs npm against the local registry without requesting an archive', async () => { + const index: RegistryIndex = new Map([[ + '@deepseek-ai/dsh', + new Map([['0.1.0', { name: '@deepseek-ai/dsh', version: '0.1.0' }]]), + ]]) + const result = await benchmarkNpmResolution(index, '0.1.0', 10_000) + + expect(result.durationMs).toBeGreaterThan(0) + expect(result.registryRequests).toBeGreaterThan(0) + expect(result.archiveRequests).toBe(0) + expect(result.unknownPackages).toEqual([]) + }) +}) diff --git a/scripts/benchmark-npm-resolution.ts b/scripts/benchmark-npm-resolution.ts new file mode 100644 index 0000000000..57834d4f09 --- /dev/null +++ b/scripts/benchmark-npm-resolution.ts @@ -0,0 +1,417 @@ +/** Benchmark npm's dependency-tree resolution against an all-local registry. */ + +import { execFileSync, spawn } from 'node:child_process' +import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { createServer, type Server } from 'node:http' +import { tmpdir } from 'node:os' +import { join, resolve } from 'node:path' +import { performance } from 'node:perf_hooks' +import { parseArgs } from 'node:util' + +const TARGET_PACKAGE = '@deepseek-ai/dsh' +const DEFAULT_TIMEOUT_MS = 300_000 +const WORKSPACE_MANIFEST_GLOBS = [ + 'apps/*/package.json', + 'packages/*/*/package.json', + 'vendor/*/package.json', + 'native/landlock-run/package.json', + 'native/landlock-run/packages/*/package.json', +] +const INSTALLED_MANIFEST_GLOBS = [ + 'node_modules/.pnpm/*/node_modules/*/package.json', + 'node_modules/.pnpm/*/node_modules/@*/*/package.json', +] +const PUBLISHED_FIELDS = [ + 'dependencies', + 'optionalDependencies', + 'peerDependencies', + 'peerDependenciesMeta', + 'engines', + 'os', + 'cpu', + 'bin', +] as const + +interface PackageManifest { + readonly name?: unknown + readonly version?: unknown + readonly dependencies?: Record + readonly optionalDependencies?: Record + readonly peerDependencies?: Record + readonly peerDependenciesMeta?: Record + readonly engines?: unknown + readonly os?: unknown + readonly cpu?: unknown + readonly bin?: unknown +} + +interface RegistryVersion extends PackageManifest { + readonly name: string + readonly version: string +} + +/** Package versions served by the local benchmark registry. */ +export type RegistryIndex = ReadonlyMap> + +/** Parsed command-line options for one benchmark invocation. */ +export interface BenchmarkOptions { + readonly ref?: string + readonly runs: number + readonly timeoutMs: number + readonly maxMs?: number +} + +/** One measured npm resolution. */ +export interface BenchmarkRun { + readonly durationMs: number + readonly registryRequests: number + readonly archiveRequests: number + readonly unknownPackages: readonly string[] +} + +/** Parse one positive-integer command-line option or use its default. */ +export function parsePositiveIntegerOption(raw: string | undefined, fallback: number, name: string): number { + if (raw === undefined) return fallback + const value = Number.parseInt(raw, 10) + if (!Number.isSafeInteger(value) || value < 1 || String(value) !== raw) { + throw new Error(`${name} must be a positive integer, got ${JSON.stringify(raw)}`) + } + return value +} + +/** + * Parse supported benchmark arguments. + * @param args - Command-line arguments after the script path. + * @returns Validated benchmark options. + */ +export function parseBenchmarkOptions(args: readonly string[]): BenchmarkOptions { + const normalized = args[0] === '--' ? args.slice(1) : args + const { values } = parseArgs({ + args: [...normalized], + options: { + ref: { type: 'string' }, + runs: { type: 'string' }, + 'timeout-ms': { type: 'string' }, + 'max-ms': { type: 'string' }, + }, + allowPositionals: false, + }) + const maxMs = values['max-ms'] === undefined + ? undefined + : parsePositiveIntegerOption(values['max-ms'], 0, '--max-ms') + return { + runs: parsePositiveIntegerOption(values.runs, 1, '--runs'), + timeoutMs: parsePositiveIntegerOption(values['timeout-ms'], DEFAULT_TIMEOUT_MS, '--timeout-ms'), + ...(values.ref === undefined ? {} : { ref: values.ref }), + ...(maxMs === undefined ? {} : { maxMs }), + } +} + +function workspaceManifestPath(path: string): boolean { + return /^(?:apps\/[^/]+|packages\/[^/]+\/[^/]+|vendor\/[^/]+|native\/landlock-run(?:\/packages\/[^/]+)?)\/package\.json$/.test(path) +} + +function workspaceManifestPaths(root: string, ref: string | undefined): string[] { + if (ref === undefined) return globSync(WORKSPACE_MANIFEST_GLOBS, { cwd: root }).sort() + return execFileSync('git', ['ls-tree', '-r', '--name-only', ref, '--', 'apps', 'packages', 'vendor', 'native'], { + cwd: root, + encoding: 'utf8', + }).split('\n').filter(workspaceManifestPath).sort() +} + +function readGitFiles(root: string, ref: string, paths: readonly string[]): ReadonlyMap { + const output = execFileSync('git', ['cat-file', '--batch'], { + cwd: root, + input: paths.map(path => `${ref}:${path}\n`).join(''), + maxBuffer: 64 * 1024 * 1024, + }) + const contents = new Map() + let offset = 0 + for (const path of paths) { + const headerEnd = output.indexOf(0x0a, offset) + if (headerEnd < 0) throw new Error(`git cat-file returned no header for ${ref}:${path}`) + const header = output.subarray(offset, headerEnd).toString('utf8') + if (header.endsWith(' missing')) throw new Error(`git ref ${ref} has no ${path}`) + const size = Number.parseInt(header.split(' ')[2] ?? '', 10) + if (!Number.isSafeInteger(size) || size < 0) { + throw new Error(`git cat-file returned an invalid size for ${ref}:${path}`) + } + const contentStart = headerEnd + 1 + const contentEnd = contentStart + size + if (output[contentEnd] !== 0x0a) throw new Error(`git cat-file truncated ${ref}:${path}`) + contents.set(path, output.subarray(contentStart, contentEnd).toString('utf8')) + offset = contentEnd + 1 + } + return contents +} + +/** + * Convert a workspace protocol range to the range published by pnpm pack. + * @param range - Dependency range from a workspace manifest. + * @param targetVersion - Current version of the referenced workspace package. + * @returns The registry-facing semver range. + */ +export function publishWorkspaceRange(range: string, targetVersion: string): string { + if (range === 'workspace:*') return targetVersion + if (range === 'workspace:^') return `^${targetVersion}` + if (range === 'workspace:~') return `~${targetVersion}` + if (range.startsWith('workspace:')) return range.slice('workspace:'.length) + return range +} + +function copyPublishedManifest( + source: PackageManifest, + workspaceVersions: ReadonlyMap, +): RegistryVersion | undefined { + if (typeof source.name !== 'string' || typeof source.version !== 'string') return undefined + const output: Record = { name: source.name, version: source.version } + for (const field of PUBLISHED_FIELDS) { + const value = source[field] + if (value === undefined) continue + if (field === 'dependencies' || field === 'optionalDependencies' || field === 'peerDependencies') { + output[field] = Object.fromEntries(Object.entries(value as Record).map(([name, range]) => { + const targetVersion = workspaceVersions.get(name) + return [name, targetVersion === undefined ? range : publishWorkspaceRange(range, targetVersion)] + })) + } else { + output[field] = structuredClone(value) + } + } + return output as unknown as RegistryVersion +} + +function addManifest(index: Map>, manifest: RegistryVersion): void { + const versions = index.get(manifest.name) ?? new Map() + versions.set(manifest.version, manifest) + index.set(manifest.name, versions) +} + +/** + * Build registry metadata from installed external packages and workspace manifests. + * @param root - Repository root containing the pnpm virtual store. + * @param ref - Optional Git ref used instead of working-tree workspace manifests. + * @returns Package metadata served by the benchmark registry. + */ +export function buildRegistryIndex(root: string, ref?: string): RegistryIndex { + const index = new Map>() + for (const path of globSync(INSTALLED_MANIFEST_GLOBS, { cwd: root }).sort()) { + const manifest = JSON.parse(readFileSync(resolve(root, path), 'utf8')) as PackageManifest + const copied = copyPublishedManifest(manifest, new Map()) + if (copied !== undefined) addManifest(index, copied) + } + + const paths = workspaceManifestPaths(root, ref) + const refContents = ref === undefined ? undefined : readGitFiles(root, ref, paths) + const workspace = paths.map(path => + JSON.parse(refContents?.get(path) ?? readFileSync(resolve(root, path), 'utf8')) as PackageManifest) + const workspaceVersions = new Map(workspace.flatMap(manifest => + typeof manifest.name === 'string' && typeof manifest.version === 'string' + ? [[manifest.name, manifest.version] as const] + : [])) + for (const manifest of workspace) { + const copied = copyPublishedManifest(manifest, workspaceVersions) + if (copied !== undefined) addManifest(index, copied) + } + return index +} + +function latestVersion(versions: ReadonlyMap): string { + const sorted = [...versions.keys()].sort((left, right) => left.localeCompare(right, 'en', { numeric: true })) + const latest = sorted.at(-1) + if (latest === undefined) throw new Error('local registry package has no versions') + return latest +} + +function listen(server: Server): Promise { + return new Promise((resolveListen, reject) => { + server.once('error', reject) + server.listen(0, '127.0.0.1', () => { + server.off('error', reject) + const address = server.address() + if (address === null || typeof address === 'string') { + reject(new Error('local registry did not expose a TCP port')) + return + } + resolveListen(address.port) + }) + }) +} + +function close(server: Server): Promise { + return new Promise((resolveClose, reject) => { + server.close((error) => { + if (error === undefined) resolveClose() + else reject(error) + }) + }) +} + +function npmExecutable(): string { + return process.platform === 'win32' ? 'npm.cmd' : 'npm' +} + +async function runNpm( + cwd: string, + registry: string, + timeoutMs: number, +): Promise<{ durationMs: number; output: string; timedOut: boolean }> { + const started = performance.now() + const child = spawn(npmExecutable(), [ + 'install', + '--package-lock-only', + '--ignore-scripts', + '--no-audit', + '--no-fund', + '--loglevel=error', + `--registry=${registry}`, + ], { + cwd, + // Windows resolves npm through a .cmd shim, which spawn() refuses + // without a shell since the CVE-2024-27980 hardening. + shell: process.platform === 'win32', + env: { + ...process.env, + npm_config_cache: join(cwd, '.npm-cache'), + npm_config_update_notifier: 'false', + }, + stdio: ['ignore', 'pipe', 'pipe'], + }) + let output = '' + child.stdout.setEncoding('utf8') + child.stderr.setEncoding('utf8') + child.stdout.on('data', (chunk) => { output += String(chunk) }) + child.stderr.on('data', (chunk) => { output += String(chunk) }) + const outcome = await new Promise<{ status: number | null; timedOut: boolean }>((resolveExit, reject) => { + let timeoutReached = false + const timer = setTimeout(() => { + timeoutReached = true + child.kill('SIGTERM') + }, timeoutMs) + child.once('error', reject) + child.once('exit', (status) => { + clearTimeout(timer) + resolveExit({ status, timedOut: timeoutReached }) + }) + }) + const durationMs = performance.now() - started + if (outcome.timedOut) return { durationMs, output, timedOut: true } + if (outcome.status !== 0) { + throw new Error(`npm install exited ${String(outcome.status)} after ${durationMs.toFixed(0)} ms\n${output.trim()}`) + } + return { durationMs, output, timedOut: false } +} + +/** + * Resolve the CLI install graph once without downloading package archives. + * @param index - Package metadata exposed through the local registry. + * @param targetVersion - Version of `@deepseek-ai/dsh` to install. + * @param timeoutMs - Hard wall-clock limit for the npm child process. + * @returns Timing and registry-request observations. + */ +export async function benchmarkNpmResolution( + index: RegistryIndex, + targetVersion: string, + timeoutMs: number, +): Promise { + let registryRequests = 0 + let archiveRequests = 0 + const unknownPackages = new Set() + let registry = '' + const server = createServer((request, response) => { + registryRequests++ + const pathname = new URL(request.url ?? '/', registry).pathname + if (pathname.startsWith('/tarballs/')) { + archiveRequests++ + response.writeHead(500, { 'content-type': 'application/json' }) + response.end(JSON.stringify({ error: 'package-lock-only benchmark requested an archive' })) + return + } + const name = decodeURIComponent(pathname.slice(1)) + const versions = index.get(name) + if (versions === undefined) { + unknownPackages.add(name) + response.writeHead(404, { 'content-type': 'application/json' }) + response.end(JSON.stringify({ error: 'not_found' })) + return + } + const materialized = Object.fromEntries([...versions].map(([version, manifest]) => [version, { + ...manifest, + dist: { tarball: `${registry}tarballs/${encodeURIComponent(name)}-${version}.tgz` }, + }])) + const body = JSON.stringify({ + name, + 'dist-tags': { latest: latestVersion(versions) }, + versions: materialized, + }) + response.writeHead(200, { + 'content-type': 'application/json', + 'content-length': Buffer.byteLength(body), + }) + response.end(body) + }) + const port = await listen(server) + registry = `http://127.0.0.1:${String(port)}/` + const consumer = mkdtempSync(join(tmpdir(), 'dsh-npm-resolution-')) + try { + writeFileSync(join(consumer, 'package.json'), `${JSON.stringify({ + name: 'dsh-npm-resolution-benchmark', + version: '0.0.0', + private: true, + dependencies: { [TARGET_PACKAGE]: targetVersion }, + }, null, 2)}\n`) + const result = await runNpm(consumer, registry, timeoutMs) + if (result.timedOut) throw new Error(`npm resolution exceeded ${String(timeoutMs)} ms`) + return { + durationMs: result.durationMs, + registryRequests, + archiveRequests, + unknownPackages: [...unknownPackages].sort(), + } + } finally { + await close(server) + rmSync(consumer, { recursive: true, force: true }) + } +} + +async function main(): Promise { + const options = parseBenchmarkOptions(process.argv.slice(2)) + const root = resolve(import.meta.dirname, '..') + const started = performance.now() + const index = buildRegistryIndex(root, options.ref) + const targetVersions = index.get(TARGET_PACKAGE) + if (targetVersions === undefined) throw new Error(`local registry contains no ${TARGET_PACKAGE}`) + const targetVersion = latestVersion(targetVersions) + const npmVersion = execFileSync(npmExecutable(), ['--version'], { encoding: 'utf8' }).trim() + console.log( + `benchmark-npm-resolution: npm ${npmVersion}, ${options.ref === undefined ? 'working tree' : options.ref}, ` + + `${String(index.size)} package name(s), setup ${(performance.now() - started).toFixed(0)} ms.`, + ) + const durations: number[] = [] + for (let run = 1; run <= options.runs; run++) { + const result = await benchmarkNpmResolution(index, targetVersion, options.timeoutMs) + durations.push(result.durationMs) + console.log( + `benchmark-npm-resolution: run ${String(run)}/${String(options.runs)} resolved ${TARGET_PACKAGE}@${targetVersion}` + + ` in ${(result.durationMs / 1000).toFixed(2)} s with ${String(result.registryRequests)} metadata request(s)` + + ` and ${String(result.unknownPackages.length)} local 404 package name(s).`, + ) + if (result.archiveRequests > 0) throw new Error('npm requested package archives during the metadata-only benchmark') + } + const minimum = Math.min(...durations) + const maximum = Math.max(...durations) + console.log( + `benchmark-npm-resolution: ${String(options.runs)} run(s), min ${(minimum / 1000).toFixed(2)} s, max ${(maximum / 1000).toFixed(2)} s.`, + ) + if (options.maxMs !== undefined && maximum > options.maxMs) { + throw new Error(`npm resolution exceeded --max-ms=${String(options.maxMs)} (max ${maximum.toFixed(0)} ms)`) + } +} + +if (import.meta.main) { + try { + await main() + } catch (error) { + console.error(`benchmark-npm-resolution: ${error instanceof Error ? error.message : String(error)}`) + process.exitCode = 1 + } +} diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts new file mode 100644 index 0000000000..1a172daafc --- /dev/null +++ b/scripts/package-dependency-policy.ts @@ -0,0 +1,52 @@ +/** Explicit exceptions and Host packages for the published dependency policy. */ + +/** Packages treated as Client/Host packages without declaring `dsh.client`. */ +const CLIENT_FACE_INCLUDE: readonly string[] = [] + +/** Packages exempted from automatic Client/Host treatment despite declaring `dsh.client`. */ +const CLIENT_FACE_EXCLUDE: readonly string[] = [ + '@deepseek-ai/dsh-api-session-controller', +] + +/** Host-only packages whose peer relays are deliberately flattened. */ +const HOST_DEPENDENCY_PACKAGES: readonly string[] = [ + '@deepseek-ai/dsh-llm', + '@deepseek-ai/dsh-session', +] + +/** Complete configurable input to package dependency classification. */ +export interface PackageDependencyPolicy { + readonly clientFaceInclude: readonly string[] + readonly clientFaceExclude: readonly string[] + readonly hostPackages: readonly string[] +} + +/** Repository dependency policy consumed by verification and benchmarking. */ +export const PACKAGE_DEPENDENCY_POLICY: PackageDependencyPolicy = { + clientFaceInclude: CLIENT_FACE_INCLUDE, + clientFaceExclude: CLIENT_FACE_EXCLUDE, + hostPackages: HOST_DEPENDENCY_PACKAGES, +} + +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +/** Whether a package manifest declares a dynamically loaded Client entry. */ +export function hasClientDeclaration(dshField: unknown): boolean { + return isRecord(dshField) && Object.hasOwn(dshField, 'client') +} + +/** Whether the repository policy flattens one package's non-Cordis peers. */ +export function usesFlattenedPackageDependencies( + manifestPath: string, + packageName: string, + dshField: unknown, + policy: PackageDependencyPolicy = PACKAGE_DEPENDENCY_POLICY, +): boolean { + if (!manifestPath.startsWith('packages/') || manifestPath.startsWith('packages/experimental/')) return false + if (policy.hostPackages.includes(packageName)) return true + if (manifestPath.startsWith('packages/client/')) return true + const included = hasClientDeclaration(dshField) || policy.clientFaceInclude.includes(packageName) + return included && !policy.clientFaceExclude.includes(packageName) +} diff --git a/scripts/package-invariants.spec.ts b/scripts/package-invariants.spec.ts index 626aa59bce..d972e36816 100644 --- a/scripts/package-invariants.spec.ts +++ b/scripts/package-invariants.spec.ts @@ -5,6 +5,7 @@ import { afterEach, describe, expect, it } from 'vitest' import { collectPackageInvariantViolations, } from './package-invariants.ts' +import { usesFlattenedPackageDependencies } from './package-dependency-policy.ts' const roots: string[] = [] @@ -28,7 +29,10 @@ export const apply = (ctx: { invariants: { register(name: string, install: typeo function fixture(options: { packageName?: string + packageDirectory?: string source?: string + clientDeclaration?: boolean + clientExport?: boolean invariantExport?: boolean invariantDependency?: boolean invariantReference?: boolean @@ -36,19 +40,34 @@ function fixture(options: { } = {}): string { const root = mkdtempSync(join(tmpdir(), 'dsh-package-invariants-')) roots.push(root) - const dir = join(root, 'packages/core/probe') + const packageDirectory = options.packageDirectory ?? 'packages/core/probe' + const dir = join(root, packageDirectory) mkdirSync(join(dir, 'src'), { recursive: true }) const packageName = options.packageName ?? '@deepseek-ai/dsh-probe' + const exports = options.invariantExport === false ? {} : { + './invariant': { + types: './lib/types/invariant.d.ts', + default: './lib/invariant.js', + }, + ...(options.clientExport === true ? { + './client': { + types: './lib/types/client/index.d.ts', + default: './lib/client.js', + }, + } : {}), + } + const dsh = options.clientDeclaration === true ? { client: {} } : undefined + const developmentOnlyInvariant = usesFlattenedPackageDependencies( + `${packageDirectory}/package.json`, + packageName, + dsh, + ) const manifest = { name: packageName, - exports: options.invariantExport === false ? {} : { - './invariant': { - types: './lib/types/invariant.d.ts', - default: './lib/invariant.js', - }, - }, + ...(dsh === undefined ? {} : { dsh }), + exports, files: ['lib/index.js', 'lib/invariant.js'], - peerDependencies: options.invariantDependency === false ? {} : { + peerDependencies: options.invariantDependency === false || developmentOnlyInvariant ? {} : { '@deepseek-ai/dsh-invariants': 'workspace:^', }, devDependencies: options.invariantDependency === false ? {} : { @@ -72,6 +91,33 @@ describe('package invariant gate', () => { expect(collectPackageInvariantViolations(fixture())).toEqual([]) }) + it('accepts development-only invariants for configured Host dependencies', () => { + expect(collectPackageInvariantViolations(fixture({ packageName: '@deepseek-ai/dsh-llm' }))).toEqual([]) + }) + + it('accepts development-only invariants for client packages', () => { + expect(collectPackageInvariantViolations(fixture({ + packageName: '@deepseek-ai/dsh-client-probe', + packageDirectory: 'packages/client/probe', + }))).toEqual([]) + }) + + it('accepts development-only invariants for packages with a dsh.client entry', () => { + expect(collectPackageInvariantViolations(fixture({ clientDeclaration: true, clientExport: true }))).toEqual([]) + }) + + it('keeps invariant peers for packages that only export a Client API', () => { + expect(collectPackageInvariantViolations(fixture({ clientExport: true }))).toEqual([]) + }) + + it('keeps invariant peers for experimental packages with a dsh.client entry', () => { + expect(collectPackageInvariantViolations(fixture({ + packageDirectory: 'packages/experimental/probe', + clientDeclaration: true, + clientExport: true, + }))).toEqual([]) + }) + it('accepts an invariant reference owned by a package-local leaf project', () => { const root = fixture({ invariantReference: false }) const dir = join(root, 'packages/core/probe') diff --git a/scripts/package-invariants.ts b/scripts/package-invariants.ts index 3e4e5ac757..eeafd0e9fb 100644 --- a/scripts/package-invariants.ts +++ b/scripts/package-invariants.ts @@ -7,12 +7,14 @@ import { existsSync, globSync, readFileSync } from 'node:fs' import { dirname, relative, resolve, sep } from 'node:path' import ts from 'typescript' +import { usesFlattenedPackageDependencies } from './package-dependency-policy.ts' /** Required explanation marker for an intentionally empty installer. */ const NO_RUNTIME_INVARIANT_MARKER = 'No runtime invariant:' interface PackageManifest { name?: string + dsh?: unknown exports?: Record files?: string[] peerDependencies?: Record @@ -96,18 +98,23 @@ function checkManifest( addViolation(violations, owner.manifestPath, 'files must publish lib/invariant.js') } if (owner.packageName === '@deepseek-ai/dsh-invariants') return - if (manifest.peerDependencies?.['@deepseek-ai/dsh-invariants'] !== 'workspace:^') { - addViolation( - violations, - owner.manifestPath, - '@deepseek-ai/dsh-invariants must be a workspace:^ peerDependency', - ) + const developmentOnlyInvariant = usesFlattenedPackageDependencies( + owner.manifestPath, + owner.packageName, + manifest.dsh, + ) + const expectedRange = 'workspace:^' + const peerRange = manifest.peerDependencies?.['@deepseek-ai/dsh-invariants'] + if (developmentOnlyInvariant ? peerRange !== undefined : peerRange !== expectedRange) { + addViolation(violations, owner.manifestPath, developmentOnlyInvariant + ? '@deepseek-ai/dsh-invariants must not be a peerDependency under this package dependency policy' + : '@deepseek-ai/dsh-invariants must be a workspace:^ peerDependency') } - if (manifest.devDependencies?.['@deepseek-ai/dsh-invariants'] !== 'workspace:^') { + if (manifest.devDependencies?.['@deepseek-ai/dsh-invariants'] !== expectedRange) { addViolation( violations, owner.manifestPath, - '@deepseek-ai/dsh-invariants must also be a workspace:^ devDependency', + `@deepseek-ai/dsh-invariants must be a ${expectedRange} devDependency`, ) } } diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts index 0033a55958..f30dc4adca 100644 --- a/scripts/run-gates.spec.ts +++ b/scripts/run-gates.spec.ts @@ -102,7 +102,7 @@ describe('gate graph validation', () => { const ids = withPnpmEntrypoint(() => gatesForMode('hygiene').map(subject => subject.id)) expect(ids).toEqual([ - 'rescope-vendor', 'publint', 'constraints', 'application-entrypoints', + 'rescope-vendor', 'publint', 'constraints', 'package-dependencies', 'application-entrypoints', 'dsh-package-licenses', 'package-invariants', 'built-package-invariants', 'node-next-types', 'optional-dependency-imports', 'client-packages', 'client-ui-i18n', 'cordis-config', 'runtime-closure', 'vendored-links', @@ -141,6 +141,15 @@ describe('gate graph validation', () => { }, ) + it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)( + 'keeps package dependency enforcement in %s', + (mode) => { + const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id)) + + expect(ids).toContain('package-dependencies') + }, + ) + it.each(['ci-primary', 'ci-static', 'check-all'] as const)( 'keeps the client dependency policy in %s', (mode) => { diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index f3052d6c25..9a71f1876e 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -278,6 +278,7 @@ function ciSharedStaticGates(): Gate[] { pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }), pnpmScript('application-entrypoints', 'verify-application-entrypoints', { label: 'application entrypoints' }), pnpmScript('constraints', 'constraints'), + pnpmScript('package-dependencies', 'verify-package-dependencies', { label: 'package dependencies' }), pnpmScript('dsh-package-licenses', 'verify-dsh-package-licenses', { label: 'DSH package licenses' }), pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }), pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }), @@ -667,6 +668,7 @@ function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] { pnpmScript('rescope-vendor', 'rescope-vendor:check', { label: 'vendor rescope' }), pnpmScript('publint', 'publint', artifactOptions), pnpmScript('constraints', 'constraints'), + pnpmScript('package-dependencies', 'verify-package-dependencies', { label: 'package dependencies' }), pnpmScript('application-entrypoints', 'verify-application-entrypoints', { label: 'application entrypoints' }), pnpmScript('dsh-package-licenses', 'verify-dsh-package-licenses', { label: 'DSH package licenses' }), pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }), diff --git a/scripts/verify-client-packages.spec.ts b/scripts/verify-client-packages.spec.ts index aa39b84316..05a4acf031 100644 --- a/scripts/verify-client-packages.spec.ts +++ b/scripts/verify-client-packages.spec.ts @@ -1,4 +1,4 @@ -/** Tests for client package modes, dependency sections, and module requests. */ +/** Tests for client package modes and module requests. */ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' @@ -6,6 +6,7 @@ import { dirname, join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' import { collectClientPackageViolations, + collectLocalSourceSpecifiers, collectRuntimeSourcePackageUses, collectRuntimeSourceSpecifiers, collectSourcePackageUses, @@ -106,6 +107,19 @@ describe('source package uses', () => { '@deepseek-ai/dsh-b/remote', 'react', ]) + expect([...collectLocalSourceSpecifiers('feature.ts', [ + "import type { A } from './types.ts'", + "export { value } from './value.ts'", + "const load = () => import('./lazy.ts')", + "const legacy = require('./legacy.ts')", + "declare module './augmentation.ts' {}", + "import '@deepseek-ai/dsh-a'", + ].join('\n'))].sort()).toEqual([ + './lazy.ts', + './legacy.ts', + './types.ts', + './value.ts', + ]) }) }) @@ -152,109 +166,6 @@ describe('package modes', () => { }) }) -describe('dependency sections', () => { - it('accepts dynamic peer plus dev relationships, static dev inputs, and private dependencies', () => { - const slots = pkg('ui-slots', { dynamic: false, staticLinked: true }) - const conversation = pkg('conversation', { - inject: ['@deepseek-ai/dsh-client-feature'], - sourceUses: { - '@deepseek-ai/dsh-agent': ['packages/client/conversation/src/index.ts'], - '@deepseek-ai/dsh-client-ui-slots': ['packages/client/conversation/src/client/slots.ts'], - react: ['packages/client/conversation/src/client/view.tsx'], - }, - dependencies: { immer: '^10.1.1' }, - peerDependencies: { - [CORDIS]: 'workspace:^', - '@deepseek-ai/dsh-agent': 'workspace:^', - '@deepseek-ai/dsh-client-feature': 'workspace:^', - }, - devDependencies: { - [CORDIS]: 'workspace:^', - '@deepseek-ai/dsh-agent': 'workspace:^', - '@deepseek-ai/dsh-client-feature': 'workspace:^', - '@deepseek-ai/dsh-client-ui-slots': 'workspace:^', - react: '^18.2.0', - }, - }) - expect(collectClientPackageViolations(facts([slots, conversation], { - platformModules: ['react', slots.name], - }))).toEqual([]) - }) - - it('rejects internal dependencies, static peers, and mismatched peer development ranges', () => { - const slots = pkg('ui-slots', { dynamic: false, staticLinked: true }) - const subject = pkg('feature', { - sourceUses: { - '@deepseek-ai/dsh-agent': ['packages/client/feature/src/index.ts'], - [slots.name]: ['packages/client/feature/src/view.tsx'], - }, - dependencies: { '@deepseek-ai/dsh-agent': 'workspace:^' }, - peerDependencies: { [CORDIS]: 'workspace:^', [slots.name]: 'workspace:^' }, - devDependencies: { [CORDIS]: 'workspace:^', [slots.name]: 'workspace:*' }, - }) - const found = collectClientPackageViolations(facts([slots, subject])) - expect(found).toHaveLength(2) - expect(found.join('\n')).toContain('peer-installed DSH relationship') - expect(found.join('\n')).toContain('static client input') - }) - - it('requires every peer to have the same development range', () => { - const subject = pkg('feature', { - peerDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/cordis-plugin-loader': 'workspace:^' }, - }) - expect(collectClientPackageViolations(facts([subject]))).toEqual([ - 'packages/client/feature/package.json: peerDependencies.@deepseek-ai/cordis-plugin-loader' - + ' is workspace:^, so devDependencies.@deepseek-ai/cordis-plugin-loader must use the same range;' - + ' found no declaration', - ]) - }) - - it('requires statically linked third-party runtime imports in dependencies', () => { - const primitives = pkg('ui-primitives', { - dynamic: false, - staticLinked: true, - runtimeSourceUses: { shiki: ['packages/client/ui-primitives/src/highlight.ts'] }, - devDependencies: { [CORDIS]: 'workspace:^', shiki: '^4.3.1' }, - }) - const found = collectClientPackageViolations(facts([primitives])) - expect(found).toHaveLength(1) - expect(found[0]).toContain('runtime import retained by a statically linked artifact') - expect(found[0]).toContain('declare it only in dependencies') - - const valid = { ...primitives, dependencies: { shiki: '^4.3.1' }, devDependencies: { [CORDIS]: 'workspace:^' } } - expect(collectClientPackageViolations(facts([valid]))).toEqual([]) - }) - - it('keeps the web shell runtime inputs development-only', () => { - const web = pkg('web', { - dynamic: false, - staticLinked: true, - runtimeSourceUses: { - '@deepseek-ai/cordis-plugin-loader': ['packages/client/web/src/boot.ts'], - react: ['packages/client/web/src/seed.ts'], - }, - devDependencies: { - [CORDIS]: 'workspace:^', - '@deepseek-ai/cordis-plugin-loader': 'workspace:^', - react: '^18.2.0', - }, - }) - expect(collectClientPackageViolations(facts([web]))).toEqual([]) - }) - - it('allows npm dependency cycles', () => { - const a = pkg('a', { - peerDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-client-b': 'workspace:^' }, - devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-client-b': 'workspace:^' }, - }) - const b = pkg('b', { - peerDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-client-a': 'workspace:^' }, - devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-client-a': 'workspace:^' }, - }) - expect(collectClientPackageViolations(facts([a, b]))).toEqual([]) - }) -}) - describe('module requests', () => { it('rejects runtime requests from one client feature package to another dynamic row', () => { const ui = declaration('ui', { @@ -378,7 +289,7 @@ describe('manifest declarations', () => { ]) }) - it('fixes unambiguous dependency sections and declaration entries', () => { + it('fixes malformed declaration entries without changing dependency sections', () => { const root = mkdtempSync(join(tmpdir(), 'client-packages-fix-')) roots.push(root) const subject = pkg('feature', { @@ -426,43 +337,8 @@ describe('manifest declarations', () => { external: ['@deepseek-ai/dsh-missing'], inject: ['@deepseek-ai/dsh-agent'], }) - expect(fixed.dependencies).toBeUndefined() - expect(fixed.peerDependencies).toEqual({ - '@deepseek-ai/cordis-plugin-loader': 'workspace:^', - [CORDIS]: 'workspace:^', - '@deepseek-ai/dsh-agent': 'workspace:*', - }) - expect(fixed.devDependencies).toEqual({ - '@deepseek-ai/dsh-client-ui-slots': 'workspace:^', - [CORDIS]: 'workspace:^', - '@deepseek-ai/dsh-agent': 'workspace:*', - '@deepseek-ai/cordis-plugin-loader': 'workspace:^', - }) - }) - - it('fixes a statically linked runtime import into dependencies', () => { - const root = mkdtempSync(join(tmpdir(), 'client-packages-static-fix-')) - roots.push(root) - const subject = pkg('ui-primitives', { - dynamic: false, - staticLinked: true, - runtimeSourceUses: { shiki: ['packages/client/ui-primitives/src/highlight.ts'] }, - devDependencies: { [CORDIS]: 'workspace:^', shiki: '^4.3.1' }, - }) - mkdirSync(dirname(join(root, subject.manifest)), { recursive: true }) - writeFileSync(join(root, subject.manifest), JSON.stringify({ - name: subject.name, - peerDependencies: subject.peerDependencies, - devDependencies: subject.devDependencies, - })) - writeFileSync(join(root, 'package.json'), JSON.stringify({ private: true })) - - expect(fixClientPackageManifests(root, facts([subject]))).toEqual([subject.manifest]) - const fixed = JSON.parse(readFileSync(join(root, subject.manifest), 'utf8')) as { - dependencies: Record - devDependencies: Record - } - expect(fixed.dependencies).toEqual({ shiki: '^4.3.1' }) - expect(fixed.devDependencies).toEqual({ [CORDIS]: 'workspace:^' }) + expect(fixed.dependencies).toEqual(subject.dependencies) + expect(fixed.peerDependencies).toEqual(subject.peerDependencies) + expect(fixed.devDependencies).toEqual(subject.devDependencies) }) }) diff --git a/scripts/verify-client-packages.ts b/scripts/verify-client-packages.ts index 294cba6328..94e70497ae 100644 --- a/scripts/verify-client-packages.ts +++ b/scripts/verify-client-packages.ts @@ -1,6 +1,5 @@ /** - * Verify client package modes, npm dependency sections, and the synchronous - * browser module-request graph. + * Verify client package modes and the synchronous browser module-request graph. */ import { globSync, readFileSync, writeFileSync } from 'node:fs' @@ -17,8 +16,6 @@ const PLATFORM_SOURCE = 'packages/client/web/src/platform.ts' const PARSER_PRELOAD_SOURCE = 'packages/client/modules/src/index.ts' const STATIC_PRESET_SOURCE = 'packages/client/tsdown.client.ts' const CORDIS = '@deepseek-ai/cordis' -const DSH_PREFIX = '@deepseek-ai/dsh-' -const CLIENT_WEB = '@deepseek-ai/dsh-client-web' /** One workspace package's browser-module declaration. */ export interface ClientDeclaration { @@ -92,6 +89,17 @@ export function collectRuntimeSourceSpecifiers(path: string, source: string): Se return collectSourceFileUses(sourceFile, true, 'specifier') } +/** + * Collect relative module specifiers used to follow one source entry's local closure. + * @param path - File path used to select TypeScript's parser mode. + * @param source - Source text to inspect. + * @returns Relative imports, exports, requires, and import types. + */ +export function collectLocalSourceSpecifiers(path: string, source: string): Set { + const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true) + return collectSourceFileUses(sourceFile, false, 'local') +} + function importCarriesRuntimeValue(node: ts.ImportDeclaration): boolean { const clause = node.importClause if (clause === undefined) return true @@ -114,12 +122,17 @@ function exportCarriesRuntimeValue(node: ts.ExportDeclaration): boolean { function collectSourceFileUses( sourceFile: ts.SourceFile, runtimeOnly: boolean, - key: 'package' | 'specifier', + key: 'local' | 'package' | 'specifier', ): Set { const uses = new Set() const add = (specifier: ts.Expression | undefined): void => { - if (specifier === undefined || !ts.isStringLiteral(specifier) || !isBareSpecifier(specifier.text)) return + if (specifier === undefined || !ts.isStringLiteralLike(specifier)) return + if (key === 'local') { + if (specifier.text.startsWith('.')) uses.add(specifier.text) + return + } + if (!isBareSpecifier(specifier.text)) return uses.add(key === 'package' ? packageNameOf(specifier.text) : specifier.text) } const visit = (node: ts.Node): void => { @@ -135,9 +148,10 @@ function collectSourceFileUses( && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === 'require')) { add(node.arguments[0]) - } else if (!runtimeOnly && ts.isModuleDeclaration(node) && ts.isStringLiteral(node.name)) { + } else if (!runtimeOnly && key !== 'local' && ts.isModuleDeclaration(node) && ts.isStringLiteral(node.name)) { add(node.name) - } else if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) { + } else if (key !== 'local' + && (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node))) { uses.add('react') } ts.forEachChild(node, visit) @@ -170,7 +184,6 @@ export function collectClientPackageViolations(facts: ClientPackageFacts): strin return [ ...facts.malformed, ...collectModeViolations(facts), - ...collectDependencyViolations(facts), ...collectModuleViolations(facts), ].sort((left, right) => left.localeCompare(right)) } @@ -181,10 +194,8 @@ interface ManifestDocument { changed: boolean } -type DependencySection = 'dependencies' | 'peerDependencies' | 'devDependencies' - /** - * Repair manifest declarations whose intended result follows uniquely from the policy. + * Repair malformed or redundant `dsh.client` declaration entries. * @param root - Absolute repository root. * @param facts - Facts used by the verification pass. * @returns Repository-relative manifests written by the fixer. @@ -217,53 +228,6 @@ export function fixClientPackageManifests(root: string, facts: ClientPackageFact ) || target.changed } - const staticInputs = new Set([ - ...facts.staticLinkedPackages, - ...facts.platformModules.map(packageNameOf), - ]) - staticInputs.delete(CORDIS) - const inferredRanges = dependencyRangeCandidates(root) - for (const pkg of facts.packages) { - const target = document(pkg.manifest) - const expected = expectedSections(pkg, staticInputs) - for (const [name, rule] of expected) { - const range = preferredRange(target.manifest, name, rule.kind, inferredRanges) - if (range === undefined) continue - target.changed = rule.kind === 'dependency' - ? ensureDependencyOnly(target.manifest, name, range) || target.changed - : rule.kind === 'dev' - ? ensureDevOnly(target.manifest, name, range) || target.changed - : ensurePeerDev(target.manifest, name, range) || target.changed - } - - if (pkg.dynamic) { - const productionNames = new Set([ - ...Object.keys(section(target.manifest, 'dependencies')), - ...Object.keys(section(target.manifest, 'peerDependencies')), - ]) - for (const name of productionNames) { - if (expected.has(name)) continue - const range = preferredRange( - target.manifest, - name, - staticInputs.has(name) ? 'dev' : 'peer-dev', - inferredRanges, - ) - if (range === undefined) continue - if (staticInputs.has(name)) { - target.changed = ensureDevOnly(target.manifest, name, range) || target.changed - } else if (section(target.manifest, 'dependencies')[name] !== undefined && isInternalDsh(name)) { - target.changed = ensurePeerDev(target.manifest, name, range) || target.changed - } - } - } - - for (const [name, range] of Object.entries(section(target.manifest, 'peerDependencies'))) { - target.changed = setDependency(target.manifest, 'devDependencies', name, range) || target.changed - } - target.changed = deleteEmptySections(target.manifest) || target.changed - } - const changed = [...documents.values()].filter(target => target.changed).sort((left, right) => left.path.localeCompare(right.path)) for (const target of changed) { @@ -295,102 +259,6 @@ function normalizeClientArray( return true } -function ensureDevOnly(manifest: Manifest, name: string, range: string): boolean { - let changed = deleteDependency(manifest, 'dependencies', name) - changed = deleteDependency(manifest, 'peerDependencies', name) || changed - return setDependency(manifest, 'devDependencies', name, range) || changed -} - -function ensureDependencyOnly(manifest: Manifest, name: string, range: string): boolean { - let changed = deleteDependency(manifest, 'peerDependencies', name) - changed = deleteDependency(manifest, 'devDependencies', name) || changed - return setDependency(manifest, 'dependencies', name, range) || changed -} - -function ensurePeerDev(manifest: Manifest, name: string, range: string): boolean { - let changed = deleteDependency(manifest, 'dependencies', name) - changed = setDependency(manifest, 'peerDependencies', name, range) || changed - return setDependency(manifest, 'devDependencies', name, range) || changed -} - -function setDependency(manifest: Manifest, field: DependencySection, name: string, range: string): boolean { - const dependencies = mutableSection(manifest, field) - if (dependencies[name] === range) return false - dependencies[name] = range - return true -} - -function deleteDependency(manifest: Manifest, field: DependencySection, name: string): boolean { - const dependencies = section(manifest, field) - if (dependencies[name] === undefined) return false - manifest[field] = Object.fromEntries(Object.entries(dependencies).filter(([key]) => key !== name)) - return true -} - -function deleteEmptySections(manifest: Manifest): boolean { - let changed = false - for (const field of ['dependencies', 'peerDependencies', 'devDependencies'] as const) { - if (manifest[field] === undefined || Object.keys(section(manifest, field)).length > 0) continue - if (field === 'dependencies') delete manifest.dependencies - else if (field === 'peerDependencies') delete manifest.peerDependencies - else delete manifest.devDependencies - changed = true - } - return changed -} - -function preferredRange( - manifest: Manifest, - name: string, - kind: ExpectedRule['kind'], - inferred: ReadonlyMap>, -): string | undefined { - const order: readonly DependencySection[] = kind === 'dependency' - ? ['dependencies', 'devDependencies', 'peerDependencies'] - : kind === 'dev' - ? ['devDependencies', 'peerDependencies', 'dependencies'] - : ['peerDependencies', 'devDependencies', 'dependencies'] - for (const field of order) { - const range = section(manifest, field)[name] - if (range !== undefined) return range - } - if (isInternalDsh(name)) return 'workspace:^' - const candidates = inferred.get(name) - return candidates?.size === 1 ? [...candidates][0] : undefined -} - -function dependencyRangeCandidates(root: string): Map> { - const candidates = new Map>() - const paths = globSync([ - 'package.json', - ...MANIFEST_GLOBS, - 'website/package.json', - ], { cwd: root }).map(normalizePath) - for (const path of new Set(paths)) { - const manifest = JSON.parse(readFileSync(resolve(root, path), 'utf8')) as Manifest - for (const field of ['dependencies', 'peerDependencies', 'devDependencies'] as const) { - for (const [name, range] of Object.entries(section(manifest, field))) { - const ranges = candidates.get(name) ?? new Set() - ranges.add(range) - candidates.set(name, ranges) - } - } - } - return candidates -} - -function section(manifest: Manifest, field: DependencySection): Record { - return manifest[field] ?? {} -} - -function mutableSection(manifest: Manifest, field: DependencySection): Record { - const value = manifest[field] - if (value !== undefined) return value - const created: Record = {} - manifest[field] = created - return created -} - function collectModeViolations(facts: ClientPackageFacts): string[] { const violations: string[] = [] for (const pkg of facts.packages) { @@ -435,114 +303,6 @@ function collectModeViolations(facts: ClientPackageFacts): string[] { return violations } -interface ExpectedRule { - readonly kind: 'dependency' | 'dev' | 'peer-dev' - readonly origins: Set -} - -function collectDependencyViolations(facts: ClientPackageFacts): string[] { - const violations: string[] = [] - const staticInputs = new Set([ - ...facts.staticLinkedPackages, - ...facts.platformModules.map(packageNameOf), - ]) - staticInputs.delete(CORDIS) - - for (const pkg of [...facts.packages].sort((left, right) => left.manifest.localeCompare(right.manifest))) { - const expected = expectedSections(pkg, staticInputs) - for (const [name, rule] of [...expected].sort(([left], [right]) => left.localeCompare(right))) { - const actual = declaredSections(pkg, name) - if (rule.kind === 'dependency') { - if (actual.length === 1 && actual[0] === 'dependencies') continue - violations.push( - pkg.manifest + ': ' + name + ' (' + describeOrigins(rule.origins) + ') is a runtime import' - + ' retained by a statically linked artifact; declare it only in dependencies, found ' - + describeSections(actual), - ) - continue - } - if (rule.kind === 'dev') { - if (actual.length === 1 && actual[0] === 'devDependencies') continue - violations.push( - pkg.manifest + ': ' + name + ' (' + describeOrigins(rule.origins) + ') is a static client input;' - + ' declare it only in devDependencies, found ' + describeSections(actual), - ) - continue - } - - const peerRange = pkg.peerDependencies[name] - const devRange = pkg.devDependencies[name] - if (actual.length === 2 - && actual.includes('peerDependencies') - && actual.includes('devDependencies') - && peerRange === devRange) continue - violations.push( - pkg.manifest + ': ' + name + ' (' + describeOrigins(rule.origins) + ')' - + ' is a peer-installed DSH relationship; declare it in peerDependencies and devDependencies' - + ' with matching ranges, not dependencies; found ' + describeSections(actual) - + describeRangeMismatch(peerRange, devRange), - ) - } - - for (const [name, peerRange] of Object.entries(pkg.peerDependencies).sort(([left], [right]) => left.localeCompare(right))) { - if (expected.has(name)) continue - const devRange = pkg.devDependencies[name] - if (devRange === peerRange) continue - violations.push( - pkg.manifest + ': peerDependencies.' + name + ' is ' + peerRange + ', so devDependencies.' + name - + ' must use the same range; found ' + (devRange ?? 'no declaration'), - ) - } - - if (!pkg.dynamic) continue - for (const section of ['dependencies', 'peerDependencies'] as const) { - for (const name of Object.keys(pkg[section]).sort()) { - if (expected.has(name)) continue - if (staticInputs.has(name)) { - violations.push( - pkg.manifest + ': dynamic package declares static input ' + name + ' in ' + section + ';' - + ' move it to devDependencies or delete the stale declaration', - ) - } else if (section === 'dependencies' && isInternalDsh(name)) { - violations.push( - pkg.manifest + ': dynamic package declares ' + name + ' in dependencies;' - + ' dynamic DSH relationships are peer plus dev, and static client inputs are dev-only', - ) - } - } - } - } - return violations -} - -function expectedSections(pkg: ClientPackage, staticInputs: ReadonlySet): Map { - const expected = new Map([ - [CORDIS, { kind: 'peer-dev', origins: new Set(['client package baseline']) }], - ]) - if (!pkg.dynamic) { - if (pkg.name === CLIENT_WEB) return expected - for (const [name, locations] of Object.entries(pkg.runtimeSourceUses)) { - if (name === pkg.name || name === CORDIS || isInternalDsh(name)) continue - expected.set(name, { kind: 'dependency', origins: new Set(locations) }) - } - return expected - } - - const add = (name: string, origin: string): void => { - if (name === pkg.name) return - const kind = staticInputs.has(name) ? 'dev' : isInternalDsh(name) ? 'peer-dev' : undefined - if (kind === undefined) return - const current = expected.get(name) - if (current !== undefined) current.origins.add(origin) - else expected.set(name, { kind, origins: new Set([origin]) }) - } - for (const [name, locations] of Object.entries(pkg.sourceUses)) { - for (const location of locations) add(name, location) - } - for (const name of pkg.inject) add(name, 'dsh.client.inject') - return expected -} - interface ModuleEdge { readonly from: string readonly to: string @@ -895,32 +655,6 @@ function rowPackageOf(specifier: string, rows: ReadonlySet): string | un return rows.has(stripped) ? stripped : undefined } -function declaredSections(pkg: ClientPackage, name: string): string[] { - return (['dependencies', 'peerDependencies', 'devDependencies'] as const) - .filter(section => pkg[section][name] !== undefined) -} - -function describeSections(sections: readonly string[]): string { - return sections.length === 0 ? 'no dependency declaration' : sections.join(' + ') -} - -function describeRangeMismatch(peer: string | undefined, dev: string | undefined): string { - if (peer === undefined || dev === undefined || peer === dev) return '' - return ' (peer ' + peer + ', dev ' + dev + ')' -} - -function describeOrigins(origins: ReadonlySet): string { - const sorted = [...origins].sort() - const [first, second, ...rest] = sorted - if (first === undefined) return 'production use' - if (second === undefined) return first - return rest.length === 0 ? first + ', ' + second : first + ', ' + second + ', and ' + String(rest.length) + ' more' -} - -function isInternalDsh(name: string): boolean { - return name === CORDIS || name.startsWith(DSH_PREFIX) -} - function isBareSpecifier(specifier: string): boolean { return !specifier.startsWith('.') && !specifier.startsWith('/') && !specifier.startsWith('#') } @@ -956,7 +690,7 @@ async function main(): Promise { const requests = facts.declarations.reduce((total, pkg) => total + pkg.external.length, 0) console.log( GATE + ': ' + String(facts.packages.length) + ' client packages (' + String(dynamic) + ' dynamic, ' - + String(facts.packages.length - dynamic) + ' statically linked) satisfy dependency and module-request rules; ' + + String(facts.packages.length - dynamic) + ' statically linked) satisfy package-mode and module-request rules; ' + String(requests) + ' explicit external request(s).', ) } diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts new file mode 100644 index 0000000000..253a5ea7c3 --- /dev/null +++ b/scripts/verify-package-dependencies.spec.ts @@ -0,0 +1,260 @@ +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' +import { tmpdir } from 'node:os' +import { dirname, join } from 'node:path' +import { afterEach, describe, expect, it } from 'vitest' +import { + PACKAGE_DEPENDENCY_POLICY, + type PackageDependencyPolicy, +} from './package-dependency-policy.ts' +import { + collectPackageDependencyViolations, + discoverPackageDependencyScope, + fixPackageDependencies, + formatManagedRuntimeDependencies, + readPackageDependencyFacts, + repairPackageDependencyManifest, + type PackageDependencyFacts, + type PackageDependencyManifest, + type WorkspacePackageManifest, +} from './verify-package-dependencies.ts' + +const CORDIS = '@deepseek-ai/cordis' +const roots: string[] = [] + +afterEach(() => { + for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) +}) + +function pkg( + name: string, + manifestPath: string, + manifest: Partial = {}, +): WorkspacePackageManifest { + return { + name, + manifestPath, + dir: dirname(manifestPath), + manifest: { name, ...manifest }, + } +} + +function policy(fields: Partial = {}): PackageDependencyPolicy { + return { + clientFaceInclude: [], + clientFaceExclude: [], + hostPackages: [], + ...fields, + } +} + +function facts(manifest: PackageDependencyManifest): PackageDependencyFacts { + return { + manifestPath: 'packages/core/probe/package.json', + role: 'configured-host', + manifest, + workspaceNames: new Set([ + CORDIS, + '@deepseek-ai/dsh-runtime', + '@deepseek-ai/dsh-types', + '@deepseek-ai/dsh-stale', + '@deepseek-ai/schemastery', + ]), + allSourceUses: new Map([ + ['@deepseek-ai/dsh-runtime', ['packages/core/probe/src/index.ts']], + ['@deepseek-ai/dsh-types', ['packages/core/probe/src/types.ts']], + ]), + hostRuntimeSourceUses: new Map([ + ['@deepseek-ai/dsh-runtime', ['packages/core/probe/src/index.ts']], + ]), + clientInject: new Set(), + } +} + +describe('package dependency scope', () => { + it('keeps the measured Host relay roster explicit', () => { + expect(PACKAGE_DEPENDENCY_POLICY.clientFaceExclude).toEqual([ + '@deepseek-ai/dsh-api-session-controller', + ]) + expect(PACKAGE_DEPENDENCY_POLICY.hostPackages).toEqual([ + '@deepseek-ai/dsh-llm', + '@deepseek-ai/dsh-session', + ]) + }) + + it('discovers the Client directory, dsh.client declarations, and configured Host packages', () => { + const packages = [ + pkg('@f/static', 'packages/client/static/package.json'), + pkg('@f/dynamic-client', 'packages/client/dynamic/package.json', { dsh: { client: {} } }), + pkg('@f/dual', 'packages/api/dual/package.json', { dsh: { client: {} } }), + pkg('@f/export-only', 'packages/api/export-only/package.json', { exports: { './client': './lib/client.js' } }), + pkg('@f/forced-client', 'packages/api/forced/package.json'), + pkg('@f/excluded', 'packages/api/excluded/package.json', { dsh: { client: {} } }), + pkg('@f/host', 'packages/core/host/package.json'), + ] + + const found = discoverPackageDependencyScope(packages, policy({ + clientFaceInclude: ['@f/forced-client'], + clientFaceExclude: ['@f/excluded'], + hostPackages: ['@f/host'], + })) + + expect(found.violations).toEqual([]) + expect(found.selected.map(item => [item.name, item.role])).toEqual([ + ['@f/dual', 'client-host'], + ['@f/forced-client', 'client-host'], + ['@f/dynamic-client', 'client-host'], + ['@f/static', 'client-host'], + ['@f/host', 'configured-host'], + ]) + }) + + it('rejects stale, redundant, overlapping, and unknown configuration', () => { + const packages = [ + pkg('@f/client', 'packages/client/client/package.json'), + pkg('@f/dual', 'packages/api/dual/package.json', { dsh: { client: {} } }), + pkg('@f/host', 'packages/core/host/package.json'), + ] + const found = discoverPackageDependencyScope(packages, policy({ + clientFaceInclude: ['@f/dual', '@f/missing', '@f/host'], + clientFaceExclude: ['@f/client', '@f/host', '@f/missing'], + hostPackages: ['@f/dual'], + })) + + expect(found.violations).toEqual(expect.arrayContaining([ + expect.stringContaining('clientFaceInclude redundantly names automatically discovered package @f/dual'), + expect.stringContaining('@f/host appears in both clientFaceInclude and clientFaceExclude'), + expect.stringContaining('clientFaceExclude cannot exempt packages/client package @f/client'), + expect.stringContaining('clientFaceExclude names @f/host, which declares no dsh.client entry'), + expect.stringContaining('hostPackages redundantly names Client-faced package @f/dual'), + expect.stringContaining('unknown release package @f/missing'), + ])) + }) +}) + +describe('face-aware source classification', () => { + it('counts Host values as dependencies and Client values as development inputs', () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-package-faces-')) + roots.push(root) + const subject = pkg('@f/dual', 'packages/g/dual/package.json', { + dsh: { client: { inject: ['@f/injected'] } }, + }) + const files = { + 'packages/g/dual/src/index.ts': [ + "import { value } from '@f/runtime'", + "import type { Shared } from '@f/types'", + "export { nested } from './nested.ts'", + ].join('\n'), + 'packages/g/dual/src/nested.ts': "export { nested } from '@f/nested'", + 'packages/g/dual/src/client/index.ts': "import { browser } from '@f/browser'", + } + for (const [path, source] of Object.entries(files)) { + mkdirSync(dirname(join(root, path)), { recursive: true }) + writeFileSync(join(root, path), source) + } + + const found = readPackageDependencyFacts(root, subject, 'client-host', new Set([ + CORDIS, '@f/runtime', '@f/types', '@f/nested', '@f/browser', '@f/injected', + ])) + + expect([...found.hostRuntimeSourceUses.keys()].sort()).toEqual(['@f/nested', '@f/runtime']) + expect([...found.allSourceUses.keys()].sort()).toEqual(['@f/browser', '@f/nested', '@f/runtime', '@f/types']) + }) +}) + +describe('dependency sections', () => { + it('accepts Host dependencies, development-only inputs, and shared Cordis', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + dependencies: { + '@deepseek-ai/dsh-runtime': 'workspace:^', + '@deepseek-ai/schemastery': 'workspace:^', + external: '^1.0.0', + }, + devDependencies: { + '@deepseek-ai/dsh-types': 'workspace:^', + [CORDIS]: 'workspace:^', + }, + peerDependencies: { [CORDIS]: 'workspace:^' }, + } + expect(collectPackageDependencyViolations({ + facts: [facts(manifest)], packages: [], policyViolations: [], workspaceNames: facts(manifest).workspaceNames, + })).toEqual([]) + }) + + it('lists managed Host runtime dependencies for fix review', () => { + const subject = facts({ name: '@deepseek-ai/dsh-probe' }) + expect(formatManagedRuntimeDependencies({ + facts: [subject], packages: [], policyViolations: [], workspaceNames: subject.workspaceNames, + })).toEqual([ + 'verify-package-dependencies: 1 managed Host runtime dependency edge(s) remain in dependencies across 1 package(s):', + ' @deepseek-ai/dsh-probe: @deepseek-ai/dsh-runtime', + ]) + }) + + it('reports wrong sections, workspace ranges, and stale peer metadata', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + dependencies: { '@deepseek-ai/dsh-types': 'workspace:*' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-runtime': 'workspace:^' }, + peerDependencies: { [CORDIS]: 'workspace:*', '@deepseek-ai/dsh-runtime': 'workspace:^' }, + peerDependenciesMeta: { '@deepseek-ai/dsh-missing': { optional: true } }, + } + const state = { + facts: [facts(manifest)], packages: [], policyViolations: [], workspaceNames: facts(manifest).workspaceNames, + } + const violations = collectPackageDependencyViolations(state) + expect(violations).toEqual(expect.arrayContaining([ + expect.stringContaining('@deepseek-ai/dsh-runtime'), + expect.stringContaining('@deepseek-ai/dsh-types'), + expect.stringContaining(`${CORDIS} must be matching peerDependencies + devDependencies`), + expect.stringContaining('dependencies.@deepseek-ai/dsh-types must use workspace:^'), + expect.stringContaining('peerDependenciesMeta.@deepseek-ai/dsh-missing has no matching'), + ])) + }) + + it('repairs owned relationships without changing unrelated dependencies', () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-package-dependencies-')) + roots.push(root) + const manifestPath = 'package.json' + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + dependencies: { '@deepseek-ai/schemastery': 'workspace:*', external: '^1.0.0' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-runtime': 'workspace:^' }, + peerDependencies: { + [CORDIS]: 'workspace:^', + '@deepseek-ai/dsh-runtime': 'workspace:^', + '@deepseek-ai/dsh-stale': 'workspace:^', + }, + peerDependenciesMeta: { '@deepseek-ai/dsh-stale': { optional: true } }, + } + writeFileSync(join(root, manifestPath), `${JSON.stringify(manifest, null, 2)}\n`) + const subject = { ...facts(manifest), manifestPath } + const state = { facts: [subject], packages: [], policyViolations: [], workspaceNames: subject.workspaceNames } + + expect(fixPackageDependencies(root, state)).toEqual([manifestPath]) + const fixed = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as PackageDependencyManifest + expect(fixed.dependencies).toEqual({ + '@deepseek-ai/schemastery': 'workspace:^', + external: '^1.0.0', + '@deepseek-ai/dsh-runtime': 'workspace:^', + }) + expect(fixed.devDependencies).toEqual({ + [CORDIS]: 'workspace:^', + '@deepseek-ai/dsh-types': 'workspace:^', + '@deepseek-ai/dsh-stale': 'workspace:^', + }) + expect(fixed.peerDependencies).toEqual({ [CORDIS]: 'workspace:^' }) + expect(fixed.peerDependenciesMeta).toBeUndefined() + }) + + it('repairs an in-memory manifest for benchmark simulation', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + peerDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-runtime': 'workspace:^' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-runtime': 'workspace:^' }, + } + repairPackageDependencyManifest(facts(manifest)) + expect(manifest.dependencies).toEqual({ '@deepseek-ai/dsh-runtime': 'workspace:^' }) + expect(manifest.peerDependencies).toEqual({ [CORDIS]: 'workspace:^' }) + }) +}) diff --git a/scripts/verify-package-dependencies.ts b/scripts/verify-package-dependencies.ts new file mode 100644 index 0000000000..fda6184864 --- /dev/null +++ b/scripts/verify-package-dependencies.ts @@ -0,0 +1,479 @@ +/** Verify and repair npm dependency sections from published Client and Host faces. */ + +import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs' +import { dirname, extname, join, normalize, relative, resolve, sep } from 'node:path' +import { + hasClientDeclaration, + PACKAGE_DEPENDENCY_POLICY, + type PackageDependencyPolicy, +} from './package-dependency-policy.ts' +import { + collectLocalSourceSpecifiers, + collectRuntimeSourcePackageUses, + collectSourcePackageUses, +} from './verify-client-packages.ts' + +const GATE = 'verify-package-dependencies' +const CORDIS = '@deepseek-ai/cordis' +const WORKSPACE_RANGE = 'workspace:^' +const RELEASE_MANIFEST_GLOB = 'packages/!(experimental)/*/package.json' +const WORKSPACE_MANIFEST_GLOBS = [ + 'apps/*/package.json', + 'packages/*/*/package.json', + 'vendor/*/package.json', +] + +type DependencySection = 'dependencies' | 'devDependencies' | 'optionalDependencies' | 'peerDependencies' +export type PackageDependencyRole = 'client-host' | 'configured-host' + +/** Manifest fields read and repaired by the package dependency policy. */ +export interface PackageDependencyManifest { + name?: string + version?: string + exports?: unknown + dependencies?: Record + devDependencies?: Record + optionalDependencies?: Record + peerDependencies?: Record + peerDependenciesMeta?: Record + dsh?: { client?: { inject?: string[] } } +} + +/** One workspace package and its source location. */ +export interface WorkspacePackageManifest { + readonly dir: string + readonly manifestPath: string + readonly manifest: PackageDependencyManifest + readonly name: string +} + +/** Source and manifest facts for one package covered by the policy. */ +export interface PackageDependencyFacts { + readonly manifestPath: string + readonly role: PackageDependencyRole + readonly manifest: PackageDependencyManifest + readonly workspaceNames: ReadonlySet + readonly allSourceUses: ReadonlyMap + readonly hostRuntimeSourceUses: ReadonlyMap + readonly clientInject: ReadonlySet +} + +/** Complete policy input read from the repository. */ +export interface PackageDependencyState { + readonly facts: readonly PackageDependencyFacts[] + readonly packages: readonly WorkspacePackageManifest[] + readonly policyViolations: readonly string[] + readonly workspaceNames: ReadonlySet +} + +export interface ExpectedPackageDependency { + readonly section: 'dependencies' | 'devDependencies' | 'peer-dev' + readonly origins: readonly string[] +} + +function normalizePath(path: string): string { + return path.split(sep).join('/') +} + +function packageNameOf(specifier: string): string | undefined { + if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('#') || specifier.includes(':')) { + return undefined + } + const parts = specifier.split('/') + return specifier.startsWith('@') ? parts.length >= 2 ? `${parts[0]}/${parts[1]}` : undefined : parts[0] +} + +/** Read package manifests used for scope discovery and workspace-name checks. */ +export function readWorkspacePackageManifests(root: string): { + all: WorkspacePackageManifest[] + release: WorkspacePackageManifest[] +} { + const read = (manifestPath: string): WorkspacePackageManifest => { + const manifest = JSON.parse(readFileSync(resolve(root, manifestPath), 'utf8')) as PackageDependencyManifest + if (typeof manifest.name !== 'string') throw new Error(`${manifestPath}: missing package name`) + return { + dir: dirname(manifestPath), + manifestPath, + manifest, + name: manifest.name, + } + } + const all = globSync(WORKSPACE_MANIFEST_GLOBS, { cwd: root }).map(normalizePath).sort().map(read) + const releasePaths = new Set(globSync(RELEASE_MANIFEST_GLOB, { cwd: root }).map(normalizePath)) + return { all, release: all.filter(pkg => releasePaths.has(pkg.manifestPath)) } +} + +function duplicates(values: readonly string[]): string[] { + const seen = new Set() + const duplicated = new Set() + for (const value of values) { + if (seen.has(value)) duplicated.add(value) + seen.add(value) + } + return [...duplicated].sort() +} + +/** Discover Client faces and configured Host packages, validating explicit overrides. */ +export function discoverPackageDependencyScope( + packages: readonly WorkspacePackageManifest[], + policy: PackageDependencyPolicy, +): { selected: Array; violations: string[] } { + const violations: string[] = [] + const byName = new Map(packages.map(pkg => [pkg.name, pkg])) + const include = new Set(policy.clientFaceInclude) + const exclude = new Set(policy.clientFaceExclude) + const host = new Set(policy.hostPackages) + + for (const [field, values] of [ + ['clientFaceInclude', policy.clientFaceInclude], + ['clientFaceExclude', policy.clientFaceExclude], + ['hostPackages', policy.hostPackages], + ] as const) { + for (const name of duplicates(values)) violations.push(`${field} lists ${name} more than once`) + for (const name of values) { + if (!byName.has(name)) violations.push(`${field} names unknown release package ${name}`) + } + } + for (const name of include) { + if (exclude.has(name)) violations.push(`${name} appears in both clientFaceInclude and clientFaceExclude`) + const pkg = byName.get(name) + if (pkg !== undefined + && (pkg.manifestPath.startsWith('packages/client/') || hasClientDeclaration(pkg.manifest.dsh))) { + violations.push(`clientFaceInclude redundantly names automatically discovered package ${name}`) + } + } + for (const name of exclude) { + const pkg = byName.get(name) + if (pkg !== undefined && pkg.manifestPath.startsWith('packages/client/')) { + violations.push(`clientFaceExclude cannot exempt packages/client package ${name}`) + } else if (pkg !== undefined && !hasClientDeclaration(pkg.manifest.dsh)) { + violations.push(`clientFaceExclude names ${name}, which declares no dsh.client entry`) + } + } + + const selected: Array = [] + for (const pkg of packages) { + const clientDirectory = pkg.manifestPath.startsWith('packages/client/') + const clientHost = clientDirectory + || ((hasClientDeclaration(pkg.manifest.dsh) || include.has(pkg.name)) && !exclude.has(pkg.name)) + const configuredHost = host.has(pkg.name) + if (configuredHost && clientHost) { + violations.push(`hostPackages redundantly names Client-faced package ${pkg.name}`) + } + const role = clientHost ? 'client-host' : configuredHost ? 'configured-host' : undefined + if (role !== undefined) selected.push({ ...pkg, role }) + } + return { + selected: selected.sort((left, right) => left.manifestPath.localeCompare(right.manifestPath)), + violations: [...new Set(violations)].sort(), + } +} + +function addUse(target: Map, name: string, path: string): void { + const paths = target.get(name) ?? [] + if (!paths.includes(path)) paths.push(path) + target.set(name, paths) +} + +function resolveLocal(importer: string, specifier: string): string | undefined { + const raw = resolve(dirname(importer), specifier) + const candidates = extname(raw) === '' + ? [`${raw}.ts`, `${raw}.tsx`, `${raw}.mts`, `${raw}.cts`, join(raw, 'index.ts'), join(raw, 'index.tsx')] + : [raw, raw.replace(/\.js$/, '.ts'), raw.replace(/\.jsx$/, '.tsx'), raw.replace(/\.mjs$/, '.mts'), raw.replace(/\.cjs$/, '.cts')] + return candidates.find(candidate => existsSync(candidate)) +} + +function readHostRuntimeUses(root: string, pkg: WorkspacePackageManifest): Map { + const uses = new Map() + const seen = new Set() + const visit = (path: string): void => { + const normalized = normalize(path) + if (seen.has(normalized) || !existsSync(normalized)) return + seen.add(normalized) + const source = readFileSync(normalized, 'utf8') + const displayPath = normalizePath(relative(root, normalized)) + for (const name of collectRuntimeSourcePackageUses(normalized, source)) addUse(uses, name, displayPath) + for (const specifier of collectLocalSourceSpecifiers(normalized, source)) { + const target = resolveLocal(normalized, specifier) + if (target !== undefined) visit(target) + } + } + visit(resolve(root, pkg.dir, 'src/index.ts')) + return uses +} + +function readAllSourceUses(root: string, pkg: WorkspacePackageManifest): Map { + const uses = new Map() + for (const sourcePath of globSync('src/**/*.{ts,tsx,mts,cts}', { cwd: resolve(root, pkg.dir) }).sort()) { + const source = readFileSync(resolve(root, pkg.dir, sourcePath), 'utf8') + const displayPath = `${pkg.dir}/${normalizePath(sourcePath)}` + for (const name of collectSourcePackageUses(sourcePath, source)) addUse(uses, name, displayPath) + } + return uses +} + +/** Read source usage for one already-classified package. */ +export function readPackageDependencyFacts( + root: string, + pkg: WorkspacePackageManifest, + role: PackageDependencyRole, + workspaceNames: ReadonlySet, +): PackageDependencyFacts { + const inject = pkg.manifest.dsh?.client?.inject ?? [] + return { + manifestPath: pkg.manifestPath, + role, + manifest: pkg.manifest, + workspaceNames, + allSourceUses: readAllSourceUses(root, pkg), + hostRuntimeSourceUses: readHostRuntimeUses(root, pkg), + clientInject: new Set(inject.map(packageNameOf).filter(name => name !== undefined)), + } +} + +/** Read every package covered by the current dependency policy. */ +export function readPackageDependencyState( + root: string, + policy: PackageDependencyPolicy = PACKAGE_DEPENDENCY_POLICY, +): PackageDependencyState { + const packages = readWorkspacePackageManifests(root) + const workspaceNames = new Set(packages.all.map(pkg => pkg.name)) + const discovered = discoverPackageDependencyScope(packages.release, policy) + return { + facts: discovered.selected.map(pkg => readPackageDependencyFacts(root, pkg, pkg.role, workspaceNames)), + packages: packages.release, + policyViolations: discovered.violations, + workspaceNames, + } +} + +/** Derive the required npm section for each relationship owned by the policy. */ +export function expectedPackageDependencies( + facts: PackageDependencyFacts, +): ReadonlyMap { + const expected = new Map }>() + const add = (name: string, sectionName: ExpectedPackageDependency['section'], origin: string): void => { + if (name === facts.manifest.name || name === CORDIS) return + const current = expected.get(name) + const section = current?.section === 'dependencies' || sectionName === 'dependencies' + ? 'dependencies' + : 'devDependencies' + expected.set(name, { section, origins: new Set([...(current?.origins ?? []), origin]) }) + } + + expected.set(CORDIS, { section: 'peer-dev', origins: new Set(['shared Cordis runtime']) }) + for (const [name, paths] of facts.allSourceUses) { + if (!facts.workspaceNames.has(name)) continue + for (const path of paths) add(name, 'devDependencies', path) + } + for (const name of facts.clientInject) { + if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'dsh.client.inject') + } + for (const name of Object.keys(facts.manifest.peerDependencies ?? {})) { + if (name !== CORDIS) add(name, 'devDependencies', 'existing non-Cordis peer') + } + for (const [name, paths] of facts.hostRuntimeSourceUses) { + if (!facts.workspaceNames.has(name) && facts.manifest.peerDependencies?.[name] === undefined) continue + for (const path of paths) add(name, 'dependencies', path) + } + return new Map([...expected].map(([name, rule]) => [name, { + section: rule.section, + origins: [...rule.origins].sort(), + }])) +} + +/** Format the managed Host runtime edges that remain ordinary dependencies. */ +export function formatManagedRuntimeDependencies(state: PackageDependencyState): string[] { + const rows = state.facts.flatMap((facts) => { + const dependencies = [...expectedPackageDependencies(facts)] + .filter(([, rule]) => rule.section === 'dependencies') + .map(([name]) => name) + .sort() + if (dependencies.length === 0) return [] + return [{ + name: facts.manifest.name ?? facts.manifestPath, + dependencies, + }] + }).sort((left, right) => left.name.localeCompare(right.name)) + const edges = rows.reduce((total, row) => total + row.dependencies.length, 0) + return [ + `${GATE}: ${String(edges)} managed Host runtime dependency edge(s) remain in dependencies across ${String(rows.length)} package(s):`, + ...rows.map(row => ` ${row.name}: ${row.dependencies.join(', ')}`), + ] +} + +function section(manifest: PackageDependencyManifest, name: DependencySection): Record { + return manifest[name] ?? {} +} + +function mutableSection(manifest: PackageDependencyManifest, name: DependencySection): Record { + manifest[name] ??= {} + return manifest[name] +} + +function declaredSections(manifest: PackageDependencyManifest, name: string): DependencySection[] { + return (['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const) + .filter(sectionName => section(manifest, sectionName)[name] !== undefined) +} + +function describeSections(sections: readonly DependencySection[]): string { + return sections.length === 0 ? 'no dependency section' : sections.join(' + ') +} + +/** Return all manifest and policy violations in stable order. */ +export function collectPackageDependencyViolations(state: PackageDependencyState): string[] { + const violations = [...state.policyViolations] + for (const facts of state.facts) { + for (const [name, rule] of expectedPackageDependencies(facts)) { + const actual = declaredSections(facts.manifest, name) + if (rule.section === 'peer-dev') { + if (actual.length === 2 + && actual.includes('peerDependencies') + && actual.includes('devDependencies') + && section(facts.manifest, 'peerDependencies')[name] === WORKSPACE_RANGE + && section(facts.manifest, 'devDependencies')[name] === WORKSPACE_RANGE + && facts.manifest.peerDependenciesMeta?.[name] === undefined) continue + violations.push( + `${facts.manifestPath}: ${name} must be matching peerDependencies + devDependencies at ${WORKSPACE_RANGE}; found ${describeSections(actual)}`, + ) + continue + } + const expectedSection = rule.section + const range = section(facts.manifest, expectedSection)[name] + if (actual.length === 1 + && actual[0] === expectedSection + && (!facts.workspaceNames.has(name) || range === WORKSPACE_RANGE)) continue + violations.push( + `${facts.manifestPath}: ${name} (${rule.origins.join(', ')}) must be ${expectedSection}-only` + + (facts.workspaceNames.has(name) ? ` at ${WORKSPACE_RANGE}` : '') + + `; found ${describeSections(actual)}`, + ) + } + for (const sectionName of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const) { + for (const [name, range] of Object.entries(section(facts.manifest, sectionName))) { + if (!facts.workspaceNames.has(name) || range === WORKSPACE_RANGE) continue + violations.push(`${facts.manifestPath}: ${sectionName}.${name} must use ${WORKSPACE_RANGE}, found ${range}`) + } + } + for (const name of Object.keys(facts.manifest.peerDependenciesMeta ?? {})) { + if (facts.manifest.peerDependencies?.[name] === undefined) { + violations.push(`${facts.manifestPath}: peerDependenciesMeta.${name} has no matching peerDependencies entry`) + } + } + } + return [...new Set(violations)].sort() +} + +function deleteDependency( + manifest: PackageDependencyManifest, + sectionName: DependencySection, + name: string, +): void { + const dependencies = manifest[sectionName] + if (dependencies?.[name] === undefined) return + const retained = Object.fromEntries(Object.entries(dependencies).filter(([key]) => key !== name)) + if (Object.keys(retained).length > 0) { + manifest[sectionName] = retained + return + } + switch (sectionName) { + case 'dependencies': delete manifest.dependencies; break + case 'devDependencies': delete manifest.devDependencies; break + case 'optionalDependencies': delete manifest.optionalDependencies; break + case 'peerDependencies': delete manifest.peerDependencies; break + } +} + +function deletePeerMeta(manifest: PackageDependencyManifest, name: string): void { + if (manifest.peerDependenciesMeta?.[name] === undefined) return + const retained = Object.fromEntries(Object.entries(manifest.peerDependenciesMeta) + .filter(([key]) => key !== name)) + if (Object.keys(retained).length > 0) manifest.peerDependenciesMeta = retained + else delete manifest.peerDependenciesMeta +} + +function preferredRange( + facts: PackageDependencyFacts, + name: string, + target: ExpectedPackageDependency['section'], +): string | undefined { + if (facts.workspaceNames.has(name)) return WORKSPACE_RANGE + const order: readonly DependencySection[] = target === 'dependencies' + ? ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] + : ['devDependencies', 'peerDependencies', 'dependencies', 'optionalDependencies'] + return order.map(sectionName => section(facts.manifest, sectionName)[name]).find(value => value !== undefined) +} + +/** Apply the dependency policy to one in-memory manifest. */ +export function repairPackageDependencyManifest(facts: PackageDependencyFacts): void { + for (const [name, rule] of expectedPackageDependencies(facts)) { + if (rule.section === 'peer-dev') { + for (const sectionName of ['dependencies', 'optionalDependencies'] as const) { + deleteDependency(facts.manifest, sectionName, name) + } + mutableSection(facts.manifest, 'peerDependencies')[name] = WORKSPACE_RANGE + mutableSection(facts.manifest, 'devDependencies')[name] = WORKSPACE_RANGE + deletePeerMeta(facts.manifest, name) + continue + } + const range = preferredRange(facts, name, rule.section) + if (range === undefined) continue + for (const sectionName of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const) { + if (sectionName !== rule.section) deleteDependency(facts.manifest, sectionName, name) + } + mutableSection(facts.manifest, rule.section)[name] = range + deletePeerMeta(facts.manifest, name) + } + for (const name of Object.keys(facts.manifest.peerDependenciesMeta ?? {})) { + if (facts.manifest.peerDependencies?.[name] === undefined) deletePeerMeta(facts.manifest, name) + } + for (const sectionName of ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'] as const) { + for (const name of Object.keys(section(facts.manifest, sectionName))) { + if (facts.workspaceNames.has(name)) mutableSection(facts.manifest, sectionName)[name] = WORKSPACE_RANGE + } + } +} + +/** Repair every covered manifest and return repository-relative changed paths. */ +export function fixPackageDependencies(root: string, state: PackageDependencyState): string[] { + if (state.policyViolations.length > 0) return [] + const changed: string[] = [] + for (const facts of state.facts) { + const before = `${JSON.stringify(facts.manifest, null, 2)}\n` + repairPackageDependencyManifest(facts) + const after = `${JSON.stringify(facts.manifest, null, 2)}\n` + if (after === before) continue + writeFileSync(resolve(root, facts.manifestPath), after) + changed.push(facts.manifestPath) + } + return changed.sort() +} + +function main(): void { + const root = resolve(import.meta.dirname, '..') + let state = readPackageDependencyState(root) + const fix = process.argv.includes('--fix') + if (fix) { + const changed = fixPackageDependencies(root, state) + console.log(`${GATE}: fixed ${String(changed.length)} manifest(s).`) + state = readPackageDependencyState(root) + } + const violations = collectPackageDependencyViolations(state) + if (violations.length > 0) { + console.error(`${GATE}: ${String(violations.length)} violation(s):`) + for (const violation of violations) console.error(` ${violation}`) + process.exitCode = 1 + return + } + const roles = Object.groupBy(state.facts, fact => fact.role) + console.log( + `${GATE}: ${String(state.facts.length)} package(s) match the published dependency policy` + + ` (${String(roles['client-host']?.length ?? 0)} Client/Host,` + + ` ${String(roles['configured-host']?.length ?? 0)} configured Host).`, + ) + if (fix) { + for (const line of formatManagedRuntimeDependencies(state)) console.log(line) + } +} + +if (import.meta.main) main() From e4406344560c78e8210246430163de40056259dd Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 26 Aug 2026 15:49:56 +0800 Subject: [PATCH 26/63] docs: define published dependency faces --- ...ient-shells-and-dynamic-packages.i18n.yaml | 4 +- ...8-15-client-shells-and-dynamic-packages.md | 6 +- ...5-client-shells-and-dynamic-packages.zh.md | 6 +- ...2026-08-10-npm-release-sequences.i18n.yaml | 4 +- .../2026-08-10-npm-release-sequences.md | 6 ++ .../2026-08-10-npm-release-sequences.zh.md | 6 ++ ...08-26-published-dependency-faces.i18n.yaml | 6 ++ .../2026-08-26-published-dependency-faces.md | 55 +++++++++++++++++++ ...026-08-26-published-dependency-faces.zh.md | 55 +++++++++++++++++++ packages/client/AGENTS.md | 12 ++-- 10 files changed, 144 insertions(+), 16 deletions(-) create mode 100644 .agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml create mode 100644 .agents/notes/implemented/process/2026-08-26-published-dependency-faces.md create mode 100644 .agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md diff --git a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.i18n.yaml index 3baf886df0..9898d344d1 100644 --- a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.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-08-15-client-shells-and-dynamic-packages.md -2026-08-15-client-shells-and-dynamic-packages.md: 016314d10f55e0b590e98944ca417bae658ab56a -2026-08-15-client-shells-and-dynamic-packages.zh.md: 4e0277d1becab8467521dc21d0e5b7509d1ee993 +2026-08-15-client-shells-and-dynamic-packages.md: 1d67c778b6a06849324dd6095a98d57dc41b94f9 +2026-08-15-client-shells-and-dynamic-packages.zh.md: db1e4e7e7b319c283ae39a94535d88d4dc71d60a diff --git a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md index 016314d10f..1d67c778b6 100644 --- a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md +++ b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.md @@ -57,11 +57,11 @@ After the `immediately` tier has registered its factories, the kernel creates al ### Dependency declarations -Every client package keeps Cordis in matching `peerDependencies` and `devDependencies`. A dynamic package that imports, re-exports, augments, or names an internal dynamic package in `dsh.client.inject` keeps that package as matching peer and development dependencies. Static client inputs and React modules are development-only inputs for a dynamic package because the shell supplies their runtime identities. +Every Client package keeps Cordis in matching `peerDependencies` and `devDependencies`; Cordis is its only peer. Browser imports, type references, module augmentations, and `dsh.client.inject` are development inputs because the Client build and shipped profile supply their runtime identities. A package that also publishes a Host entry keeps that entry's runtime value imports in `dependencies`. [Published dependency faces](../process/2026-08-26-published-dependency-faces.md) owns package discovery, exceptions, and the explicit Host roster. Ordinary installed libraries remain `dependencies`: a dynamic build may bundle a private implementation, while a `staticLinked` library retains its bare import for the final host. Each build face decides externality independently from npm sections. Published file lists cover every runtime entry, relative asset, and declaration file reached by the artifact. -`verify-client-packages` enforces these classifications, dependency sections, build forms, parser-preload alignment, shared-module requests, and module-graph acyclicity. The repository publint pass enforces publication closure. The verifier's `--fix` mode repairs only unambiguous manifest drift. +`verify-package-dependencies` enforces and repairs dependency sections. `verify-client-packages` enforces build forms, parser-preload alignment, shared-module requests, and module-graph acyclicity. The repository publint pass enforces publication closure. ## Alternatives considered @@ -77,7 +77,7 @@ Ordinary installed libraries remain `dependencies`: a dynamic build may bundle a ## Consequences -Bundle contents stay stable when an npm dependency moves between peer and development sections, because each build face declares externality directly. Static libraries remain host-assembled, while dynamic packages retain uniform artifacts and lifecycle governance. +Bundle contents stay stable when an internal DSH relationship is development-only, because each build face declares externality directly. Static libraries remain host-assembled, while dynamic packages retain uniform artifacts and lifecycle governance. The shipped profile owns the complete Client package roster, so individual Client packages do not ask npm to solve the same graph again through peer placement. The startup protocol depends on the modules package id, and modules must remain self-contained at runtime. Combo generation preserves its ordinary package artifact and gives every other row one shared initial transport; HMR uses the same route with that row as its sole resource. A missing bootstrap registration fails before Cordis starts; later plugin import, apply, and service-wait failures remain visible through the boot page's ACTIVE scan. diff --git a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md index 4e0277d1be..db1e4e7e7b 100644 --- a/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-15-client-shells-and-dynamic-packages.zh.md @@ -57,11 +57,11 @@ Bootstrap combo 当前只登记 modules factory。启动内核把原始图与外 ### 依赖声明 -每个 client 包都把 Cordis 保持为 matching `peerDependencies` 和 `devDependencies`。动态包若 import、re-export、augment 内部动态包，或在 `dsh.client.inject` 中命名它，就把该包保持为 matching peer 与开发依赖。静态 client 输入和 React 模块对动态包只是开发依赖，因为外壳提供其运行期身份。 +每个 Client 包都把 Cordis 保持为范围一致的 `peerDependencies` 和 `devDependencies`；Cordis 是唯一的 peer。Browser import、类型引用、模块扩充与 `dsh.client.inject` 都是开发输入，因为 Client 构建与发布 profile 会提供其运行期身份。同时发布 Host 入口的包把该入口的运行期 value import 放在 `dependencies`。[发布依赖门面](../process/2026-08-26-published-dependency-faces.zh.md)负责包发现、例外与显式 Host 名册。 普通安装库仍放在 `dependencies`：动态构建可以内联私有实现，而 `staticLinked` 库会保留 bare import 交给最终宿主。各构建 face 独立决定 external，不由 npm 区段推导。发布文件列表覆盖产物实际可达的每个运行期入口、相对资产和声明文件。 -`verify-client-packages` 会检查这些分类、依赖区段、构建形态、parser preload 对齐、共享模块请求和模块图无环性。仓库 publint pass 负责检查发布闭包。该验证器的 `--fix` 模式只修复无歧义的 manifest 漂移。 +`verify-package-dependencies` 检查并修复依赖区段。`verify-client-packages` 检查构建形态、parser preload 对齐、共享模块请求和模块图无环性。仓库 publint pass 负责检查发布闭包。 ## Alternatives considered @@ -77,7 +77,7 @@ Bootstrap combo 当前只登记 modules factory。启动内核把原始图与外 ## Consequences -Npm 依赖在 peer 与开发区段间移动时，bundle 内容保持稳定，因为每个构建 face 都直接声明 external。静态库继续由宿主装配，动态包则保留统一产物与生命周期治理。 +内部 DSH 关系仅放在开发区段时，bundle 内容仍保持稳定，因为每个构建 face 都直接声明 external。静态库继续由宿主装配，动态包则保留统一产物与生命周期治理。发布 profile 拥有完整 Client 包名册，因此各 Client 包不再要求 npm 通过 peer placement 重复求解同一张图。 启动协议依赖 modules 的 package id，modules 还必须保持运行期自包含。Combo 生成保留其普通 package 产物，并为其他全部 row 提供一条共享初始传输；HMR 使用同一条路由，并只把该 row 作为资源。缺少 bootstrap registration 会在 Cordis 启动前失败；后续插件 import、apply 与 service 等待失败仍由启动页的 ACTIVE 扫描呈现。 diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml index da8882e163..1cbf4b3a85 100644 --- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.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-10-npm-release-sequences.md -2026-08-10-npm-release-sequences.md: 014bfe3abb2548a369cbfc6a5f11263303e0656a -2026-08-10-npm-release-sequences.zh.md: a67311afd93d3f4f9f0a396237c9ce0b04db0a06 +2026-08-10-npm-release-sequences.md: f83bce914bae4cfc5a047bf975b623579dc9156f +2026-08-10-npm-release-sequences.zh.md: c24e5c0a29af2f875136d439ce3fe06577c061b1 diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md index 014bfe3abb..f83bce914b 100644 --- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md +++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md @@ -80,6 +80,12 @@ Every reference to a workspace member uses `workspace:^`, so `pnpm pack` substit `scripts/check-workspace-constraints.ts` requires the protocol, so a new package cannot reintroduce a hand-written range; the invariant-companion rule requires `workspace:^` for `@deepseek-ai/dsh-invariants` for the same reason. +### Published dependency faces use an explicit policy + +[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) classifies workspace relationships by their published Client and Host use, keeps only Cordis as a peer in covered packages, and applies a small explicit Host roster. [Published dependency faces and bounded peer relays](2026-08-26-published-dependency-faces.md) owns the selection rules and rationale. + +`pnpm run benchmark:npm-resolution` measures this graph manually with the installed npm executable. `pnpm run benchmark:npm-resolution:next` additionally tries each reachable unconfigured Host package and serially remeasures the leading candidates. Both commands use a loopback metadata registry and reject archive requests, so their duration excludes package downloads. Neither command is an aggregate gate because scheduler load and metadata completion order make wall-clock thresholds nondeterministic. + ### An optional dependency is never loaded at module scope A dependency in `optionalDependencies`, or a peer carrying `peerDependenciesMeta..optional`, may be absent from an installed tree — that absence is the whole promise of "optional". A static import is evaluated when the importing module loads, so one absent package stops being "this capability is unavailable" and becomes a load failure for everything that reaches the importing module. The failure appears only in an installed tree missing that package, and no test here constructs one: a workspace install always has every package, so the unit tests, the snapshots, and the packed-install probe all pass while the published package is broken for the consumer who declined the optional peer. diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md index a67311afd9..c24e5c0a29 100644 --- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md +++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md @@ -80,6 +80,12 @@ registry 的两个行为决定了「怎么尝试一次发布」。写入之间 `scripts/check-workspace-constraints.ts` 要求这个协议，所以新包无法再引入硬写的范围；同理，invariant companion 规则要求 `@deepseek-ai/dsh-invariants` 用 `workspace:^`。 +### 发布依赖门面使用显式策略 + +[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) 按已发布的 Client 与 Host 用法分类 workspace 关系，让受管包只保留 Cordis peer，并应用一份较小的显式 Host 名册。[发布依赖门面与有限 peer 中继](2026-08-26-published-dependency-faces.zh.md)记录选包规则与理由。 + +`pnpm run benchmark:npm-resolution` 使用当前安装的 npm 手动测量该依赖图。`pnpm run benchmark:npm-resolution:next` 还会逐个尝试每个可达且未配置的 Host 包，再串行复测领先候选。两个命令都使用回环 metadata registry 并拒绝包归档请求，因此耗时不包含包下载。调度器负载与 metadata 完成顺序会使墙钟阈值失去确定性，所以两个命令都不进入聚合门禁。 + ### optional 依赖绝不在模块作用域被加载 `optionalDependencies` 里的依赖，或带 `peerDependenciesMeta..optional` 的 peer，在安装出来的树里可以不存在——这份「可以不存在」正是 optional 的全部承诺。而静态 import 在引入方模块加载时就求值，于是一个缺失的包不再表现为「这个能力不可用」，而是变成所有能走到该模块的代码的加载失败。这种失败只在「缺了该包的安装树」里出现，而本仓没有任何测试构造这种树：workspace 安装总是把每个包都装上，所以单测、快照、打包安装探针全都会过，而那个拒绝了这个 optional peer 的消费者拿到的却是坏的包。 diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml new file mode 100644 index 0000000000..2056e59e6e --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.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/process/2026-08-26-published-dependency-faces.md +2026-08-26-published-dependency-faces.md: 437044a0dca9c5c2b2b509d62de3983a38f396b1 +2026-08-26-published-dependency-faces.zh.md: b8398a9168889871f451bdaeeb225d850eebeb98 diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md new file mode 100644 index 0000000000..437044a0dc --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md @@ -0,0 +1,55 @@ +# Agent Note: Published dependency faces and bounded peer relays + +Status: implemented + +English | [中文](2026-08-26-published-dependency-faces.zh.md) + +## Problem + +A package may contain a browser bundle, a Host entry, shared TypeScript declarations, and Cordis injection metadata. Encoding all of those relationships as required npm peers made the published CLI expensive to install: npm installs peers automatically and repeatedly evaluates placement through deep, converging peer paths. Changing ranges or making the peers optional did not remove that traversal. + +The package that chooses a Client build input is the shipped profile, while a Host value import is loaded by Node from the importing package. Those relationships need different npm sections. Applying one rule to every Host package would reduce the graph but would also create a large migration with no corresponding installation benefit. + +## Decision + +### Package selection + +[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) owns dependency-section policy. It always covers packages under `packages/client/` and every non-experimental package that declares `dsh.client`. The directory includes static Client inputs without a dynamic row, while `dsh.client` identifies dynamically loaded packages outside it; a `"./client"` export alone is an API and does not select npm dependency policy. Every selected package's Host entry is scanned, including entries under `packages/client/`. + +[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) provides explicit Client-face include and exclude lists. An include handles an exceptional package without `dsh.client`, while an exclude removes an automatically discovered dual-face package outside `packages/client/`. The verifier rejects unknown, stale, redundant, duplicate, overlapping, and ineffective entries. The include list is empty; the exclude list contains `@deepseek-ai/dsh-api-session-controller`, because adding it back would migrate nine more Host edges while its five-run candidate retest improved median resolution by only 0.15 seconds. + +Host-only packages join the same policy through a separate explicit list. The list contains `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-session`; source imports do not expand it. + +### Dependency sections + +Every covered package keeps `@deepseek-ai/cordis` in matching `peerDependencies` and `devDependencies`. Cordis is the shared plugin runtime whose identity the application controls. + +A workspace package reached by a runtime value import from the Host entry closure belongs only in `dependencies`. Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Existing third-party dependencies outside these managed relationships keep their declared section. Workspace references use `workspace:^`. + +The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. Its `--fix` mode performs only the section and range changes implied by this classification and removes stale peer metadata. + +### Performance verification + +[`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) applies the current policy to an in-memory local registry, measures the current CLI graph, and tries every reachable unconfigured Host package one at a time. Concurrent runs provide a coarse shortlist; finalists run serially because npm's peer-placement search can take different paths when metadata request completion order changes. + +The benchmark is manual rather than a CI gate. It performs metadata-only installs in fresh consumers, so its relative results identify peer relays without measuring registry latency or archive downloads. + +## Alternatives considered + +**Keep internal relationships as peers.** npm must place and validate each required peer along converging ancestry paths, which recreates the reported install-time failure even when all internal versions are compatible. + +**Use the `"./client"` export as the Client-face roster.** A package may publish Client-facing types or a browser API without contributing a dynamically loaded row. Selecting that package broadens the migration to unrelated Host packages such as Goal, Session Title, and Todo. `dsh.client` identifies dynamic rows, while the `packages/client/` directory independently covers static Client inputs. + +**Flatten every Host package.** This removes more peer work but expands the migration to packages whose individual benchmark result is negligible. The explicit Host list preserves the remaining peer contracts until measurement justifies another entry. + +**Move every Client-related declaration to development-only.** A dual-face package's Host value imports remain real Node loads. Omitting them from the published dependency graph makes the package depend on accidental hoisting by a profile. + +**Enforce a wall-clock threshold in CI.** Resolver time varies with machine load and metadata completion order. Deterministic manifest classification belongs in CI; timing remains a maintainer benchmark. + +## Consequences + +The published dependency graph follows artifact ownership instead of source-directory coupling. Client bundles and shipped profiles provide browser identities, Host modules install the values they load, and only Cordis remains a repository-wide peer for covered packages. + +Moving a public type-only relationship to `devDependencies` means a standalone TypeScript consumer must install the referenced type package when it consumes that declaration. The shipped profiles install the complete supported package family; supporting independently assembled TypeScript consumers would require a different policy. + +The explicit overrides and Host list are reviewable decisions. Adding an exception changes the installed graph and requires the focused verifier tests plus a fresh next-package benchmark. The metadata-only benchmark is diagnostic evidence, not a release-time performance promise. diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md new file mode 100644 index 0000000000..b8398a9168 --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md @@ -0,0 +1,55 @@ +# Agent Note: 发布依赖门面与有限 peer 中继 + +Status: implemented + +[English](2026-08-26-published-dependency-faces.md) | 中文 + +## 问题 + +一个包可能同时包含浏览器 bundle、Host 入口、共享 TypeScript 声明和 Cordis 注入元数据。把这些关系全部编码成必需 npm peer 会使已发布 CLI 的安装代价过高：npm 会自动安装 peer，并沿深层、反复汇合的 peer 路径重复执行放置检查。修改版本范围或把 peer 标成 optional 都不会消除这类遍历。 + +Client 构建输入由发布 profile 选择，而 Host value import 由导入它的包通过 Node 加载；两者需要不同的 npm 区段。把规则应用到每个 Host 包虽然也能缩小依赖图，却会制造一个没有对应安装收益的大范围迁移。 + +## 决策 + +### 包选择 + +[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) 统一负责依赖区段策略。它始终覆盖 `packages/client/` 下的包，以及声明 `dsh.client` 的每个非实验包。该目录包含没有动态 row 的静态 Client 输入，而 `dsh.client` 标识目录外的动态装载包；仅有 `"./client"` export 只是 API，不参与 npm 依赖策略选包。每个选中包的 Host 入口都会接受扫描，包括 `packages/client/` 下的入口。 + +[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 提供显式 Client 门面 include 与 exclude 列表。include 用于没有 `dsh.client` 的例外包，exclude 用于移除 `packages/client/` 之外自动发现的双面包。验证器拒绝未知、失效、冗余、重复、相互重叠和无法生效的配置项。include 列表为空；exclude 列表包含 `@deepseek-ai/dsh-api-session-controller`，因为把它加回会多迁移九条 Host 边，而五次候选复测的 resolver 中位数仅改善 0.15 秒。 + +Host-only 包通过另一份显式列表加入同一策略。该列表包含 `@deepseek-ai/dsh-llm` 和 `@deepseek-ai/dsh-session`；源码 import 不会自动扩大列表。 + +### 依赖区段 + +每个受管包都把 `@deepseek-ai/cordis` 保持在范围一致的 `peerDependencies` 和 `devDependencies` 中。Cordis 是由应用控制身份的共享插件运行时。 + +Host 入口闭包中的运行期 value import 所到达的 workspace 包只属于 `dependencies`。Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。不属于这些受管关系的现有第三方 dependency 保持原区段。Workspace 引用使用 `workspace:^`。 + +验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。其 `--fix` 模式只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 + +### 性能验证 + +[`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) 把当前策略应用到内存中的本地 registry，测量当前 CLI 依赖图，并逐个尝试每个可达且未配置的 Host 包。并发运行用于得到粗筛名单；由于 metadata 请求的完成顺序会让 npm 的 peer 放置搜索走不同路径，最终候选会串行复测。 + +Benchmark 是手动诊断工具而非 CI 门禁。它在全新 consumer 中执行仅 metadata 的安装，因此相对结果可以定位 peer 中继，但不测量 registry 延迟或包归档下载。 + +## 考虑过的替代方案 + +**把内部关系继续保留为 peer。** npm 必须沿汇合的祖先路径放置并验证每个必需 peer；即使内部版本全部兼容，也会重新产生已报告的安装耗时问题。 + +**用 `"./client"` export 作为 Client 门面名册。** 包可能发布 Client 类型或浏览器 API，却不贡献动态装载 row。选中这类包会把迁移扩大到 Goal、Session Title 和 Todo 等无关 Host 包。`dsh.client` 标识动态 row，而 `packages/client/` 目录独立覆盖静态 Client 输入。 + +**拍平全部 Host 包。** 这会移除更多 peer 工作，却把迁移扩大到单包 benchmark 收益可忽略的包。显式 Host 列表会保留其余 peer 约束，直到测量结果证明应增加新成员。 + +**把所有 Client 相关声明都改为仅开发依赖。** 双面包的 Host value import 仍是实际的 Node 加载；从发布依赖图中删掉它们，会让包依赖 profile 的偶然提升。 + +**在 CI 中强制墙钟阈值。** Resolver 耗时会随机器负载和 metadata 完成顺序变化。确定性的 manifest 分类进入 CI，耗时测量保留为维护者 benchmark。 + +## 结果 + +发布依赖图按产物归属而不是源码目录耦合分类。Client bundle 与发布 profile 提供浏览器运行时身份，Host 模块安装自己加载的实体，而 Cordis 是受管包中唯一的全仓 peer。 + +把公开纯类型关系放进 `devDependencies`，意味着独立 TypeScript 消费者在使用该声明时必须自行安装被引用的类型包。发布 profile 会安装完整的受支持包族；若要支持独立组装的 TypeScript 消费者，需要另一套策略。 + +显式 override 与 Host 列表都是需要评审的决策。增加例外会改变安装图，因此需要运行聚焦 verifier 测试并重新执行 next-package benchmark。仅 metadata benchmark 是诊断证据，不是发布时安装耗时承诺。 diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md index 29a111effe..cf7964203b 100644 --- a/packages/client/AGENTS.md +++ b/packages/client/AGENTS.md @@ -56,13 +56,13 @@ Non-negotiables across the layers: ## Dependency declaration -Npm sections describe installation and development relationships; each build face independently decides what its artifact contains. [`verify-client-packages`](../../scripts/verify-client-packages.ts) checks the client-specific rules and can repair unambiguous manifest drift with `--fix`. +Npm sections describe installation and development relationships; each build face independently decides what its artifact contains. [`verify-package-dependencies`](../../scripts/verify-package-dependencies.ts) checks and repairs these rules; [`verify-client-packages`](../../scripts/verify-client-packages.ts) owns Client loading and module requests. 1. **Every client package keeps Cordis in matching `peerDependencies` and `devDependencies`.** This includes the static packages because their Node face participates in the same Cordis plugin contract. -2. **A dynamic package declares internal dynamic relationships as peer plus dev.** Production source imports, re-exports, module augmentations, and type-only references to an `@deepseek-ai/dsh-*` package count, as does a package named by `dsh.client.inject`. A test-only internal dependency stays dev-only. -3. **Static client inputs are dev-only for a dynamic consumer.** A package without `dsh.client`, plus the React modules seeded by the web shell, belongs only in the consumer's `devDependencies`; it never belongs in that dynamic package's `dependencies` or `peerDependencies`. `packages/client/web` likewise keeps Loader, modules, and static UI inputs as development inputs; Cordis remains peer plus dev. -4. **Ordinary installed libraries stay in `dependencies`.** This includes private implementation libraries bundled into `lib/client.js` and bare imports left in a statically linked `lib/index.js`; the final Vite host, not the library build, merges and splits the latter. A dynamic package never puts an `@deepseek-ai/dsh-*` package in `dependencies`. -5. **Every peer has a matching development range.** npm dependency and peer cycles are allowed; only the synchronous module-request graph has the separate acyclicity rule below. +2. **A package under `packages/client/` is always covered; `dsh.client` marks a Client/Host package outside that directory.** Explicit include/exclude entries handle exceptions. Every covered package's Host entry is scanned, while a `./client` export alone does not select dependency policy. +3. **Browser and type relationships are development-only.** Client imports, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and metadata-only peers belong only in `devDependencies`. +4. **Host value imports are ordinary dependencies.** A workspace value reached from the package's Host entry belongs only in `dependencies`; it is not a peer merely because another package may also install it. +5. **Ordinary installed libraries stay in `dependencies`.** This includes private implementation libraries bundled into `lib/client.js` and bare imports left in a statically linked `lib/index.js`; the final Vite host, not the library build, merges and splits the latter. 6. **Browser and Node build faces declare externality independently.** A dynamic browser half uses the baseline plus `dsh.client.external`; a statically linked face externalizes every bare specifier; a Node face externalizes its production dependencies ([`tsdown.client.ts`](tsdown.client.ts)). Moving a name between npm sections must not silently change bundle contents. 7. **Keep the published payload closed.** Every relative runtime import and emitted asset must be covered by `files`; the repository publint pass checks the exact publication view. @@ -140,7 +140,7 @@ Bringing up a new `packages/client/` plugin package (ui-workspace is a com 3. **dsh.client manifest semantics**: `platform: 'web'` always, and the declaration requires a `./client` export (the scan throws without one); `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is Cordis fiber inject waiting on *services*, nothing else. A non-baseline `external` request sequences its dynamic supplier ahead of the consumer — see [shared modules](#shared-modules-and-the-module-graph). 4. **Registering into another package's slot**: apply order is unconstrained, and a business service is not a declaration barrier. Use `ctx.slots.inject(name, () => ctx.slots.register(...))`; it waits on the actual declaration, removes the contribution when that declaration collapses, reruns after redeclaration, and leaves with the caller's plugin fiber. Return a generator yielding each registration when several contributions must install and roll back atomically. A bare `slots.register` into an undeclared slot remains an error; keep service edges only for services the contribution actually reads. 5. Rebuild the bundle (`pnpm --filter bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources. -6. **Declaration decisions**, each settled by [dependency declaration](#dependency-declaration) and [shared modules](#shared-modules-and-the-module-graph): does the package ship a `./client` export; which non-baseline value imports require `dsh.client.external`; which dynamic value dependencies are peer plus dev; which static compile inputs are dev-only; and whether `files` covers every relative runtime import and emitted asset. +6. **Declaration decisions**, each settled by [dependency declaration](#dependency-declaration) and [shared modules](#shared-modules-and-the-module-graph): does the package ship a `./client` export; which non-baseline value imports require `dsh.client.external`; which Host value imports are ordinary dependencies; which Browser and type inputs are dev-only; and whether `files` covers every relative runtime import and emitted asset. ## New component checklist From c55beac34adfe8696bf949704fa2327202ecff7e Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:06:46 +0800 Subject: [PATCH 27/63] feat: verify Host dependency export identity --- ...08-26-published-dependency-faces.i18n.yaml | 4 +- .../2026-08-26-published-dependency-faces.md | 14 +- ...026-08-26-published-dependency-faces.zh.md | 14 +- packages/client/AGENTS.md | 2 +- .../benchmark-next-package-dependency.spec.ts | 10 + scripts/verify-client-packages.ts | 11 + scripts/verify-package-dependencies.spec.ts | 195 +++++++++++- scripts/verify-package-dependencies.ts | 298 +++++++++++++++--- 8 files changed, 490 insertions(+), 58 deletions(-) diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml index 2056e59e6e..433b12fa8c 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.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-26-published-dependency-faces.md -2026-08-26-published-dependency-faces.md: 437044a0dca9c5c2b2b509d62de3983a38f396b1 -2026-08-26-published-dependency-faces.zh.md: b8398a9168889871f451bdaeeb225d850eebeb98 +2026-08-26-published-dependency-faces.md: 04b02afe372b2f3d90729f17e837b40ff1e0e6fa +2026-08-26-published-dependency-faces.zh.md: 468fb443e2e94bf23f8c61201f43c2a82f7f509b diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md index 437044a0dc..04b02afe37 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md @@ -14,9 +14,9 @@ The package that chooses a Client build input is the shipped profile, while a Ho ### Package selection -[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) owns dependency-section policy. It always covers packages under `packages/client/` and every non-experimental package that declares `dsh.client`. The directory includes static Client inputs without a dynamic row, while `dsh.client` identifies dynamically loaded packages outside it; a `"./client"` export alone is an API and does not select npm dependency policy. Every selected package's Host entry is scanned, including entries under `packages/client/`. +[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) owns dependency-section policy. It always covers packages under `packages/client/` and every non-experimental package that declares `dsh.client`. Inside the directory, `dsh.client` marks a Client/Host package whose Host entry is scanned; a package without that declaration is a Client-only static build input. Outside the directory, `dsh.client` selects the same Client/Host scan. A `"./client"` export alone is an API and does not select npm dependency policy. -[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) provides explicit Client-face include and exclude lists. An include handles an exceptional package without `dsh.client`, while an exclude removes an automatically discovered dual-face package outside `packages/client/`. The verifier rejects unknown, stale, redundant, duplicate, overlapping, and ineffective entries. The include list is empty; the exclude list contains `@deepseek-ai/dsh-api-session-controller`, because adding it back would migrate nine more Host edges while its five-run candidate retest improved median resolution by only 0.15 seconds. +[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) provides explicit Client-face include and exclude lists. An include handles an exceptional package without `dsh.client`, while an exclude removes an automatically discovered dual-face package outside `packages/client/`. The verifier rejects unknown, stale, redundant, duplicate, overlapping, and ineffective entries. The include list is empty; the exclude list contains `@deepseek-ai/dsh-api-session-controller` and `@deepseek-ai/dsh-api-workspace-controller`. Adding Session Controller back would migrate nine more Host edges while its five-run candidate retest improved median resolution by only 0.15 seconds. Host-only packages join the same policy through a separate explicit list. The list contains `@deepseek-ai/dsh-llm` and `@deepseek-ai/dsh-session`; source imports do not expand it. @@ -24,9 +24,11 @@ Host-only packages join the same policy through a separate explicit list. The li Every covered package keeps `@deepseek-ai/cordis` in matching `peerDependencies` and `devDependencies`. Cordis is the shared plugin runtime whose identity the application controls. -A workspace package reached by a runtime value import from the Host entry closure belongs only in `dependencies`. Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Existing third-party dependencies outside these managed relationships keep their declared section. Workspace references use `workspace:^`. +A workspace package reached by a runtime value import from the Host entry closure belongs only in `dependencies` when every imported runtime export appears in the policy's `safeHostDependencyExports` table. An export whose constructor identity or module state must be shared appears in `peerRequiredHostExports`; importing one such export keeps the whole package edge in matching `peerDependencies` and `devDependencies`. Each table key is an exact module specifier and each value is a reviewed export set. The verifier follows runtime local imports from the Host entry, records named and default imports and re-exports, and rejects exports present in neither table; namespace, dynamic, and side-effect imports remain unbounded and cannot enter either table. -The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. Its `--fix` mode performs only the section and range changes implied by this classification and removes stale peer metadata. +Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Existing third-party dependencies outside these managed relationships keep their declared section. Workspace references use `workspace:^`. + +The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. An unclassified Host runtime export is a policy violation that blocks all `--fix` writes; a maintainer must review the export and classify it, change the source relationship, or change the package selection. Once source safety passes, `--fix` performs only the section and range changes implied by the classification and removes stale peer metadata. ### Performance verification @@ -48,8 +50,8 @@ The benchmark is manual rather than a CI gate. It performs metadata-only install ## Consequences -The published dependency graph follows artifact ownership instead of source-directory coupling. Client bundles and shipped profiles provide browser identities, Host modules install the values they load, and only Cordis remains a repository-wide peer for covered packages. +The published dependency graph follows artifact ownership instead of source-directory coupling. Client bundles and shipped profiles provide browser identities, Host modules install duplicate-safe values they load, and Cordis plus explicitly peer-required Host exports retain shared package instances. Moving a public type-only relationship to `devDependencies` means a standalone TypeScript consumer must install the referenced type package when it consumes that declaration. The shipped profiles install the complete supported package family; supporting independently assembled TypeScript consumers would require a different policy. -The explicit overrides and Host list are reviewable decisions. Adding an exception changes the installed graph and requires the focused verifier tests plus a fresh next-package benchmark. The metadata-only benchmark is diagnostic evidence, not a release-time performance promise. +The explicit overrides, Host list, and export classifications are reviewable decisions. Class constructors used by `instanceof`, symbols, and accessors for module-private registries require peers when their identity or state crosses package boundaries; being a value import alone does not make an export duplicate-safe. Changing a classification changes the installed graph and requires the focused verifier tests plus a fresh next-package benchmark. The metadata-only benchmark is diagnostic evidence, not a release-time performance promise. diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md index b8398a9168..468fb443e2 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md @@ -14,9 +14,9 @@ Client 构建输入由发布 profile 选择，而 Host value import 由导入它 ### 包选择 -[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) 统一负责依赖区段策略。它始终覆盖 `packages/client/` 下的包，以及声明 `dsh.client` 的每个非实验包。该目录包含没有动态 row 的静态 Client 输入，而 `dsh.client` 标识目录外的动态装载包；仅有 `"./client"` export 只是 API，不参与 npm 依赖策略选包。每个选中包的 Host 入口都会接受扫描，包括 `packages/client/` 下的入口。 +[`verify-package-dependencies`](../../../../scripts/verify-package-dependencies.ts) 统一负责依赖区段策略。它始终覆盖 `packages/client/` 下的包，以及声明 `dsh.client` 的每个非实验包。在该目录内，`dsh.client` 标记需要扫描 Host 入口的 Client/Host 包；没有该声明的包是仅供 Client 编译的静态输入。在目录外，`dsh.client` 选择相同的 Client/Host 扫描。仅有 `"./client"` export 只是 API，不参与 npm 依赖策略选包。 -[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 提供显式 Client 门面 include 与 exclude 列表。include 用于没有 `dsh.client` 的例外包，exclude 用于移除 `packages/client/` 之外自动发现的双面包。验证器拒绝未知、失效、冗余、重复、相互重叠和无法生效的配置项。include 列表为空；exclude 列表包含 `@deepseek-ai/dsh-api-session-controller`，因为把它加回会多迁移九条 Host 边，而五次候选复测的 resolver 中位数仅改善 0.15 秒。 +[`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 提供显式 Client 门面 include 与 exclude 列表。include 用于没有 `dsh.client` 的例外包，exclude 用于移除 `packages/client/` 之外自动发现的双面包。验证器拒绝未知、失效、冗余、重复、相互重叠和无法生效的配置项。include 列表为空；exclude 列表包含 `@deepseek-ai/dsh-api-session-controller` 和 `@deepseek-ai/dsh-api-workspace-controller`。把 Session Controller 加回会多迁移九条 Host 边，而五次候选复测的 resolver 中位数仅改善 0.15 秒。 Host-only 包通过另一份显式列表加入同一策略。该列表包含 `@deepseek-ai/dsh-llm` 和 `@deepseek-ai/dsh-session`；源码 import 不会自动扩大列表。 @@ -24,9 +24,11 @@ Host-only 包通过另一份显式列表加入同一策略。该列表包含 `@d 每个受管包都把 `@deepseek-ai/cordis` 保持在范围一致的 `peerDependencies` 和 `devDependencies` 中。Cordis 是由应用控制身份的共享插件运行时。 -Host 入口闭包中的运行期 value import 所到达的 workspace 包只属于 `dependencies`。Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。不属于这些受管关系的现有第三方 dependency 保持原区段。Workspace 引用使用 `workspace:^`。 +Host 入口闭包中的运行期 value import 所到达的 workspace 包，只有在每个运行期导出都列入策略的 `safeHostDependencyExports` 表时才只属于 `dependencies`。constructor 身份或模块状态必须共享的导出列入 `peerRequiredHostExports`；一旦使用这类导出，整条包依赖边就保留在范围一致的 `peerDependencies` 与 `devDependencies` 中。表的每个 key 都是精确 module specifier，每个 value 都是经审查的导出集合。验证器从 Host 入口沿运行期本地 import 扫描，记录具名与默认 import 和 re-export，并拒绝两个表都未收录的导出；namespace、dynamic 和 side-effect import 无法限定导出范围，因此不能进入任一表。 -验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。其 `--fix` 模式只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 +Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。不属于这些受管关系的现有第三方 dependency 保持原区段。Workspace 引用使用 `workspace:^`。 + +验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。未分类的 Host 运行期导出属于策略违规，会阻止 `--fix` 的全部写入；维护者必须审查该导出，并选择分类该导出、修改源码关系或修改选包范围。源码安全检查通过后，`--fix` 只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 ### 性能验证 @@ -48,8 +50,8 @@ Benchmark 是手动诊断工具而非 CI 门禁。它在全新 consumer 中执 ## 结果 -发布依赖图按产物归属而不是源码目录耦合分类。Client bundle 与发布 profile 提供浏览器运行时身份，Host 模块安装自己加载的实体，而 Cordis 是受管包中唯一的全仓 peer。 +发布依赖图按产物归属而不是源码目录耦合分类。Client bundle 与发布 profile 提供浏览器运行时身份，Host 模块安装自己加载的可重复实体，而 Cordis 和显式标为 peer-required 的 Host 导出继续共享包实例。 把公开纯类型关系放进 `devDependencies`，意味着独立 TypeScript 消费者在使用该声明时必须自行安装被引用的类型包。发布 profile 会安装完整的受支持包族；若要支持独立组装的 TypeScript 消费者，需要另一套策略。 -显式 override 与 Host 列表都是需要评审的决策。增加例外会改变安装图，因此需要运行聚焦 verifier 测试并重新执行 next-package benchmark。仅 metadata benchmark 是诊断证据，不是发布时安装耗时承诺。 +显式 override、Host 列表与导出分类都是需要评审的决策。当 class constructor、symbol 和访问模块私有 registry 的函数跨包传递身份或状态时，它们要求 peer；仅仅属于 value import 并不能证明导出可重复安装。修改分类会改变安装图，因此需要运行聚焦 verifier 测试并重新执行 next-package benchmark。仅 metadata benchmark 是诊断证据，不是发布时安装耗时承诺。 diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md index cf7964203b..6ef0c5e42c 100644 --- a/packages/client/AGENTS.md +++ b/packages/client/AGENTS.md @@ -61,7 +61,7 @@ Npm sections describe installation and development relationships; each build fac 1. **Every client package keeps Cordis in matching `peerDependencies` and `devDependencies`.** This includes the static packages because their Node face participates in the same Cordis plugin contract. 2. **A package under `packages/client/` is always covered; `dsh.client` marks a Client/Host package outside that directory.** Explicit include/exclude entries handle exceptions. Every covered package's Host entry is scanned, while a `./client` export alone does not select dependency policy. 3. **Browser and type relationships are development-only.** Client imports, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and metadata-only peers belong only in `devDependencies`. -4. **Host value imports are ordinary dependencies.** A workspace value reached from the package's Host entry belongs only in `dependencies`; it is not a peer merely because another package may also install it. +4. **Host value imports require classified exports.** A workspace value reached from the package's Host entry belongs only in `dependencies` when its exact module specifier and runtime export appear in `safeHostDependencyExports`. Exports whose identity or module state must be shared appear in `peerRequiredHostExports` and keep the whole package edge in matching `peerDependencies` and `devDependencies`. The verifier rejects unclassified exports before `--fix` writes manifests. 5. **Ordinary installed libraries stay in `dependencies`.** This includes private implementation libraries bundled into `lib/client.js` and bare imports left in a statically linked `lib/index.js`; the final Vite host, not the library build, merges and splits the latter. 6. **Browser and Node build faces declare externality independently.** A dynamic browser half uses the baseline plus `dsh.client.external`; a statically linked face externalizes every bare specifier; a Node face externalizes its production dependencies ([`tsdown.client.ts`](tsdown.client.ts)). Moving a name between npm sections must not silently change bundle contents. 7. **Keep the published payload closed.** Every relative runtime import and emitted asset must be covered by `files`; the repository publint pass checks the exact publication view. diff --git a/scripts/benchmark-next-package-dependency.spec.ts b/scripts/benchmark-next-package-dependency.spec.ts index 9248a3288e..2a0ee10189 100644 --- a/scripts/benchmark-next-package-dependency.spec.ts +++ b/scripts/benchmark-next-package-dependency.spec.ts @@ -63,6 +63,16 @@ describe('next package benchmark graph', () => { ['@f/types', ['packages/g/probe/src/types.ts']], ]), hostRuntimeSourceUses: new Map([['@f/runtime', ['packages/g/probe/src/index.ts']]]), + hostRuntimeExportUses: [{ + packageName: '@f/runtime', + specifier: '@f/runtime', + exportName: 'runtimeValue', + sourcePath: 'packages/g/probe/src/index.ts', + line: 1, + column: 10, + sourceLine: "import { runtimeValue } from '@f/runtime'", + }], + peerRequiredHostDependencies: new Set(), clientInject: new Set(), } const index = new Map>([ diff --git a/scripts/verify-client-packages.ts b/scripts/verify-client-packages.ts index 94e70497ae..9dfb1599cb 100644 --- a/scripts/verify-client-packages.ts +++ b/scripts/verify-client-packages.ts @@ -100,6 +100,17 @@ export function collectLocalSourceSpecifiers(path: string, source: string): Set< return collectSourceFileUses(sourceFile, false, 'local') } +/** + * Collect relative module specifiers retained by one production source file. + * @param path - File path used to select TypeScript's parser mode. + * @param source - Source text to inspect. + * @returns Relative imports, exports, and requires that survive compilation. + */ +export function collectRuntimeLocalSourceSpecifiers(path: string, source: string): Set { + const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true) + return collectSourceFileUses(sourceFile, true, 'local') +} + function importCarriesRuntimeValue(node: ts.ImportDeclaration): boolean { const clause = node.importClause if (clause === undefined) return true diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts index 253a5ea7c3..23c1bbca69 100644 --- a/scripts/verify-package-dependencies.spec.ts +++ b/scripts/verify-package-dependencies.spec.ts @@ -7,10 +7,13 @@ import { type PackageDependencyPolicy, } from './package-dependency-policy.ts' import { + collectHostDependencyExportPolicyViolations, collectPackageDependencyViolations, + collectRuntimeSourceExportUses, discoverPackageDependencyScope, fixPackageDependencies, formatManagedRuntimeDependencies, + formatPeerRequiredRuntimeDependencies, readPackageDependencyFacts, repairPackageDependencyManifest, type PackageDependencyFacts, @@ -43,6 +46,8 @@ function policy(fields: Partial = {}): PackageDependenc clientFaceInclude: [], clientFaceExclude: [], hostPackages: [], + safeHostDependencyExports: {}, + peerRequiredHostExports: {}, ...fields, } } @@ -66,6 +71,16 @@ function facts(manifest: PackageDependencyManifest): PackageDependencyFacts { hostRuntimeSourceUses: new Map([ ['@deepseek-ai/dsh-runtime', ['packages/core/probe/src/index.ts']], ]), + hostRuntimeExportUses: [{ + packageName: '@deepseek-ai/dsh-runtime', + specifier: '@deepseek-ai/dsh-runtime', + exportName: 'runtimeValue', + sourcePath: 'packages/core/probe/src/index.ts', + line: 1, + column: 10, + sourceLine: "import { runtimeValue } from '@deepseek-ai/dsh-runtime'", + }], + peerRequiredHostDependencies: new Set(), clientInject: new Set(), } } @@ -74,11 +89,19 @@ describe('package dependency scope', () => { it('keeps the measured Host relay roster explicit', () => { expect(PACKAGE_DEPENDENCY_POLICY.clientFaceExclude).toEqual([ '@deepseek-ai/dsh-api-session-controller', + '@deepseek-ai/dsh-api-workspace-controller', ]) expect(PACKAGE_DEPENDENCY_POLICY.hostPackages).toEqual([ '@deepseek-ai/dsh-llm', '@deepseek-ai/dsh-session', ]) + expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/schemastery']).toEqual(['default']) + expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-scope']).toEqual([ + 'carrierKeyOf', 'scopeOf', 'scopeTarget', + ]) + expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-typert-protocol']).toEqual([ + 'TypertLookupFailure', 'TypertRemoteFailure', 'remoteMethods', + ]) }) it('discovers the Client directory, dsh.client declarations, and configured Host packages', () => { @@ -103,7 +126,7 @@ describe('package dependency scope', () => { ['@f/dual', 'client-host'], ['@f/forced-client', 'client-host'], ['@f/dynamic-client', 'client-host'], - ['@f/static', 'client-host'], + ['@f/static', 'client-only'], ['@f/host', 'configured-host'], ]) }) @@ -129,6 +152,49 @@ describe('package dependency scope', () => { expect.stringContaining('unknown release package @f/missing'), ])) }) + + it('rejects stale, duplicate, and unbounded safe Host export entries', () => { + const consumer = pkg('@f/consumer', 'packages/core/consumer/package.json') + const provider = pkg('@f/provider', 'packages/core/provider/package.json') + const workspaceNames = new Set([CORDIS, consumer.name, provider.name]) + const consumerFacts: PackageDependencyFacts = { + manifestPath: consumer.manifestPath, + role: 'configured-host', + manifest: consumer.manifest, + workspaceNames, + allSourceUses: new Map(), + hostRuntimeSourceUses: new Map([[provider.name, ['packages/core/consumer/src/index.ts']]]), + hostRuntimeExportUses: [{ + packageName: provider.name, + specifier: `${provider.name}/api`, + exportName: 'safeValue', + sourcePath: 'packages/core/consumer/src/index.ts', + line: 1, + column: 10, + sourceLine: "import { safeValue } from '@f/provider/api'", + }], + peerRequiredHostDependencies: new Set(), + clientInject: new Set(), + } + + expect(collectHostDependencyExportPolicyViolations( + [consumerFacts], + workspaceNames, + { + safeHostDependencyExports: { + [`${provider.name}/api`]: ['safeValue', 'safeValue', '*', 'staleValue'], + }, + peerRequiredHostExports: { + [`${provider.name}/api`]: ['safeValue'], + }, + }, + )).toEqual(expect.arrayContaining([ + expect.stringContaining('export safeValue more than once'), + expect.stringContaining('cannot classify unbounded'), + expect.stringContaining('unused @f/provider/api export staleValue'), + expect.stringContaining('appears in both Host export classifications'), + ])) + }) }) describe('face-aware source classification', () => { @@ -142,9 +208,11 @@ describe('face-aware source classification', () => { 'packages/g/dual/src/index.ts': [ "import { value } from '@f/runtime'", "import type { Shared } from '@f/types'", + "import type { Hidden } from './types.ts'", "export { nested } from './nested.ts'", ].join('\n'), 'packages/g/dual/src/nested.ts': "export { nested } from '@f/nested'", + 'packages/g/dual/src/types.ts': "import { hidden } from '@f/hidden'; export type Hidden = typeof hidden", 'packages/g/dual/src/client/index.ts': "import { browser } from '@f/browser'", } for (const [path, source] of Object.entries(files)) { @@ -153,11 +221,63 @@ describe('face-aware source classification', () => { } const found = readPackageDependencyFacts(root, subject, 'client-host', new Set([ - CORDIS, '@f/runtime', '@f/types', '@f/nested', '@f/browser', '@f/injected', + CORDIS, '@f/runtime', '@f/types', '@f/nested', '@f/hidden', '@f/browser', '@f/injected', ])) expect([...found.hostRuntimeSourceUses.keys()].sort()).toEqual(['@f/nested', '@f/runtime']) - expect([...found.allSourceUses.keys()].sort()).toEqual(['@f/browser', '@f/nested', '@f/runtime', '@f/types']) + expect(found.hostRuntimeExportUses).toEqual([ + { + packageName: '@f/nested', + specifier: '@f/nested', + exportName: 'nested', + sourcePath: 'packages/g/dual/src/nested.ts', + line: 1, + column: 10, + sourceLine: "export { nested } from '@f/nested'", + }, + { + packageName: '@f/runtime', + specifier: '@f/runtime', + exportName: 'value', + sourcePath: 'packages/g/dual/src/index.ts', + line: 1, + column: 10, + sourceLine: "import { value } from '@f/runtime'", + }, + ]) + expect([...found.allSourceUses.keys()].sort()).toEqual([ + '@f/browser', '@f/hidden', '@f/nested', '@f/runtime', '@f/types', + ]) + }) + + it('identifies exact runtime exports without treating type imports as values', () => { + const source = [ + "import defaultValue, { value as local, type Kind } from '@f/root'", + "import * as namespace from '@f/namespace'", + "import '@f/effect'", + "import type { TypeOnly } from '@f/types'", + "export { source as renamed, type SourceType } from '@f/reexport'", + "export * from '@f/star'", + "void import('@f/dynamic')", + "void require('@f/required')", + 'void defaultValue; void local; void namespace', + ].join('\n') + const uses = collectRuntimeSourceExportUses('probe.ts', source) + expect(uses.map(({ specifier, exportName }) => ({ specifier, exportName }))).toEqual([ + { specifier: '@f/dynamic', exportName: '*' }, + { specifier: '@f/effect', exportName: '(side effect)' }, + { specifier: '@f/namespace', exportName: '*' }, + { specifier: '@f/reexport', exportName: 'source' }, + { specifier: '@f/required', exportName: '*' }, + { specifier: '@f/root', exportName: 'default' }, + { specifier: '@f/root', exportName: 'value' }, + { specifier: '@f/star', exportName: '*' }, + ]) + expect(uses.find(use => use.specifier === '@f/root' && use.exportName === 'value')).toMatchObject({ + line: 1, + column: 24, + sourceLine: "import defaultValue, { value as local, type Kind } from '@f/root'", + }) }) }) @@ -186,8 +306,73 @@ describe('dependency sections', () => { expect(formatManagedRuntimeDependencies({ facts: [subject], packages: [], policyViolations: [], workspaceNames: subject.workspaceNames, })).toEqual([ - 'verify-package-dependencies: 1 managed Host runtime dependency edge(s) remain in dependencies across 1 package(s):', - ' @deepseek-ai/dsh-probe: @deepseek-ai/dsh-runtime', + 'verify-package-dependencies: 1 managed Host runtime edge(s) remain in dependencies across 1 package(s):', + ' @deepseek-ai/dsh-probe -> @deepseek-ai/dsh-runtime: @deepseek-ai/dsh-runtime#runtimeValue', + ]) + }) + + it('reports an unapproved Host runtime export without rewriting its dependency section', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + dependencies: { '@deepseek-ai/dsh-runtime': 'workspace:^' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-types': 'workspace:^' }, + peerDependencies: { [CORDIS]: 'workspace:^' }, + } + const subject = facts(manifest) + const safetyViolations = collectHostDependencyExportPolicyViolations( + [subject], + subject.workspaceNames, + { safeHostDependencyExports: {}, peerRequiredHostExports: {} }, + ) + const state = { + facts: [subject], packages: [], policyViolations: safetyViolations, workspaceNames: subject.workspaceNames, + } + + expect(safetyViolations).toEqual([ + 'packages/core/probe/src/index.ts:1:10: @deepseek-ai/dsh-runtime#runtimeValue is not classified as ' + + 'safe or peer-required — import { runtimeValue } from \'@deepseek-ai/dsh-runtime\'', + ]) + expect(fixPackageDependencies('/unused', state)).toEqual([]) + expect(manifest.dependencies).toEqual({ '@deepseek-ai/dsh-runtime': 'workspace:^' }) + }) + + it('keeps an edge as a peer when one imported export requires shared identity', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + dependencies: { '@deepseek-ai/dsh-runtime': 'workspace:^' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-types': 'workspace:^' }, + peerDependencies: { [CORDIS]: 'workspace:^' }, + } + const subject: PackageDependencyFacts = { + ...facts(manifest), + peerRequiredHostDependencies: new Set(['@deepseek-ai/dsh-runtime']), + } + expect(collectHostDependencyExportPolicyViolations( + [subject], + subject.workspaceNames, + { + safeHostDependencyExports: {}, + peerRequiredHostExports: { + '@deepseek-ai/dsh-runtime': ['runtimeValue'], + }, + }, + )).toEqual([]) + + repairPackageDependencyManifest(subject) + expect(manifest.dependencies).toBeUndefined() + expect(manifest.peerDependencies).toMatchObject({ + [CORDIS]: 'workspace:^', + '@deepseek-ai/dsh-runtime': 'workspace:^', + }) + expect(manifest.devDependencies).toMatchObject({ + [CORDIS]: 'workspace:^', + '@deepseek-ai/dsh-runtime': 'workspace:^', + }) + expect(formatPeerRequiredRuntimeDependencies({ + facts: [subject], packages: [], policyViolations: [], workspaceNames: subject.workspaceNames, + })).toEqual([ + 'verify-package-dependencies: 1 Host runtime edge(s) remain in peerDependencies because their exports require shared identity across 1 package(s):', + ' @deepseek-ai/dsh-probe -> @deepseek-ai/dsh-runtime: @deepseek-ai/dsh-runtime#runtimeValue', ]) }) diff --git a/scripts/verify-package-dependencies.ts b/scripts/verify-package-dependencies.ts index fda6184864..f8ac1cf3dd 100644 --- a/scripts/verify-package-dependencies.ts +++ b/scripts/verify-package-dependencies.ts @@ -2,14 +2,14 @@ import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs' import { dirname, extname, join, normalize, relative, resolve, sep } from 'node:path' +import ts from 'typescript' import { hasClientDeclaration, PACKAGE_DEPENDENCY_POLICY, type PackageDependencyPolicy, } from './package-dependency-policy.ts' import { - collectLocalSourceSpecifiers, - collectRuntimeSourcePackageUses, + collectRuntimeLocalSourceSpecifiers, collectSourcePackageUses, } from './verify-client-packages.ts' @@ -24,7 +24,7 @@ const WORKSPACE_MANIFEST_GLOBS = [ ] type DependencySection = 'dependencies' | 'devDependencies' | 'optionalDependencies' | 'peerDependencies' -export type PackageDependencyRole = 'client-host' | 'configured-host' +export type PackageDependencyRole = 'client-only' | 'client-host' | 'configured-host' /** Manifest fields read and repaired by the package dependency policy. */ export interface PackageDependencyManifest { @@ -55,9 +55,22 @@ export interface PackageDependencyFacts { readonly workspaceNames: ReadonlySet readonly allSourceUses: ReadonlyMap readonly hostRuntimeSourceUses: ReadonlyMap + readonly hostRuntimeExportUses: readonly HostRuntimeExportUse[] + readonly peerRequiredHostDependencies: ReadonlySet readonly clientInject: ReadonlySet } +/** One runtime export reached from a package's Host source closure. */ +export interface HostRuntimeExportUse { + readonly packageName: string + readonly specifier: string + readonly exportName: string + readonly sourcePath: string + readonly line: number + readonly column: number + readonly sourceLine: string +} + /** Complete policy input read from the repository. */ export interface PackageDependencyState { readonly facts: readonly PackageDependencyFacts[] @@ -154,13 +167,13 @@ export function discoverPackageDependencyScope( const selected: Array = [] for (const pkg of packages) { const clientDirectory = pkg.manifestPath.startsWith('packages/client/') - const clientHost = clientDirectory - || ((hasClientDeclaration(pkg.manifest.dsh) || include.has(pkg.name)) && !exclude.has(pkg.name)) + const clientHost = (hasClientDeclaration(pkg.manifest.dsh) || include.has(pkg.name)) && !exclude.has(pkg.name) + const clientOnly = clientDirectory && !clientHost const configuredHost = host.has(pkg.name) - if (configuredHost && clientHost) { + if (configuredHost && (clientHost || clientOnly)) { violations.push(`hostPackages redundantly names Client-faced package ${pkg.name}`) } - const role = clientHost ? 'client-host' : configuredHost ? 'configured-host' : undefined + const role = clientHost ? 'client-host' : clientOnly ? 'client-only' : configuredHost ? 'configured-host' : undefined if (role !== undefined) selected.push({ ...pkg, role }) } return { @@ -175,6 +188,95 @@ function addUse(target: Map, name: string, path: string): void target.set(name, paths) } +const NAMESPACE_RUNTIME_EXPORT = '*' +const SIDE_EFFECT_RUNTIME_EXPORT = '(side effect)' + +interface RuntimeSourceExportUse { + readonly specifier: string + readonly exportName: string + readonly line: number + readonly column: number + readonly sourceLine: string +} + +/** Collect exact runtime exports imported or re-exported by one source file. */ +export function collectRuntimeSourceExportUses(path: string, source: string): RuntimeSourceExportUse[] { + const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true) + const uses = new Map() + const sourceLines = source.split(/\r?\n/u) + const record = (specifier: string, exportName: string, locationNode: ts.Node): void => { + const key = `${specifier}\0${exportName}` + if (uses.has(key)) return + const position = sourceFile.getLineAndCharacterOfPosition(locationNode.getStart(sourceFile)) + uses.set(key, { + specifier, + exportName, + line: position.line + 1, + column: position.character + 1, + sourceLine: sourceLines[position.line]?.trim() ?? '', + }) + } + const add = ( + specifierNode: ts.Expression | undefined, + exportName: string, + locationNode: ts.Node = specifierNode ?? sourceFile, + ): void => { + if (specifierNode === undefined || !ts.isStringLiteralLike(specifierNode)) return + if (packageNameOf(specifierNode.text) === undefined) return + record(specifierNode.text, exportName, locationNode) + } + const visit = (node: ts.Node): void => { + if (ts.isImportDeclaration(node)) { + const clause = node.importClause + if (clause === undefined) { + add(node.moduleSpecifier, SIDE_EFFECT_RUNTIME_EXPORT) + } else if (clause.phaseModifier !== ts.SyntaxKind.TypeKeyword) { + if (clause.name !== undefined) add(node.moduleSpecifier, 'default', clause.name) + const bindings = clause.namedBindings + if (bindings !== undefined && ts.isNamespaceImport(bindings)) { + add(node.moduleSpecifier, NAMESPACE_RUNTIME_EXPORT, bindings.name) + } else if (bindings !== undefined && bindings.elements.length === 0) { + add(node.moduleSpecifier, SIDE_EFFECT_RUNTIME_EXPORT) + } else if (bindings !== undefined) { + for (const element of bindings.elements) { + const imported = element.propertyName ?? element.name + if (!element.isTypeOnly) add(node.moduleSpecifier, imported.text, imported) + } + } + } + } else if (ts.isExportDeclaration(node) && !node.isTypeOnly) { + const clause = node.exportClause + if (clause === undefined || ts.isNamespaceExport(clause)) { + add(node.moduleSpecifier, NAMESPACE_RUNTIME_EXPORT) + } else if (clause.elements.length === 0) { + add(node.moduleSpecifier, SIDE_EFFECT_RUNTIME_EXPORT) + } else { + for (const element of clause.elements) { + const imported = element.propertyName ?? element.name + if (!element.isTypeOnly) add(node.moduleSpecifier, imported.text, imported) + } + } + } else if (ts.isImportEqualsDeclaration(node) + && !node.isTypeOnly + && ts.isExternalModuleReference(node.moduleReference)) { + add(node.moduleReference.expression, NAMESPACE_RUNTIME_EXPORT, node.name) + } else if (ts.isCallExpression(node) + && (node.expression.kind === ts.SyntaxKind.ImportKeyword + || ts.isIdentifier(node.expression) && node.expression.text === 'require')) { + add(node.arguments[0], NAMESPACE_RUNTIME_EXPORT) + } else if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) { + record('react/jsx-runtime', NAMESPACE_RUNTIME_EXPORT, node) + } + ts.forEachChild(node, visit) + } + visit(sourceFile) + return [...uses.values()].sort((left, right) => + left.specifier.localeCompare(right.specifier) + || left.exportName.localeCompare(right.exportName) + || left.line - right.line + || left.column - right.column) +} + function resolveLocal(importer: string, specifier: string): string | undefined { const raw = resolve(dirname(importer), specifier) const candidates = extname(raw) === '' @@ -183,8 +285,12 @@ function resolveLocal(importer: string, specifier: string): string | undefined { return candidates.find(candidate => existsSync(candidate)) } -function readHostRuntimeUses(root: string, pkg: WorkspacePackageManifest): Map { - const uses = new Map() +function readHostRuntimeUses(root: string, pkg: WorkspacePackageManifest): { + packageUses: Map + exportUses: HostRuntimeExportUse[] +} { + const packageUses = new Map() + const exportUses = new Map() const seen = new Set() const visit = (path: string): void => { const normalized = normalize(path) @@ -192,14 +298,29 @@ function readHostRuntimeUses(root: string, pkg: WorkspacePackageManifest): Map + left.packageName.localeCompare(right.packageName) + || left.specifier.localeCompare(right.specifier) + || left.exportName.localeCompare(right.exportName) + || left.sourcePath.localeCompare(right.sourcePath) + || left.line - right.line + || left.column - right.column), + } } function readAllSourceUses(root: string, pkg: WorkspacePackageManifest): Map { @@ -218,19 +339,82 @@ export function readPackageDependencyFacts( pkg: WorkspacePackageManifest, role: PackageDependencyRole, workspaceNames: ReadonlySet, + policy: PackageDependencyPolicy = PACKAGE_DEPENDENCY_POLICY, ): PackageDependencyFacts { const inject = pkg.manifest.dsh?.client?.inject ?? [] + const hostRuntime = role === 'client-only' + ? { packageUses: new Map(), exportUses: [] } + : readHostRuntimeUses(root, pkg) return { manifestPath: pkg.manifestPath, role, manifest: pkg.manifest, workspaceNames, allSourceUses: readAllSourceUses(root, pkg), - hostRuntimeSourceUses: readHostRuntimeUses(root, pkg), + hostRuntimeSourceUses: hostRuntime.packageUses, + hostRuntimeExportUses: hostRuntime.exportUses, + peerRequiredHostDependencies: new Set(hostRuntime.exportUses + .filter(use => policy.peerRequiredHostExports[use.specifier]?.includes(use.exportName) === true) + .map(use => use.packageName)), clientInject: new Set(inject.map(packageNameOf).filter(name => name !== undefined)), } } +/** Validate reviewed Host export classifications against current source facts. */ +export function collectHostDependencyExportPolicyViolations( + facts: readonly PackageDependencyFacts[], + workspaceNames: ReadonlySet, + policy: Pick, +): string[] { + const violations: string[] = [] + const allRuntimeUses = facts.flatMap(fact => fact.hostRuntimeExportUses) + const classifications = [ + ['safeHostDependencyExports', policy.safeHostDependencyExports], + ['peerRequiredHostExports', policy.peerRequiredHostExports], + ] as const + for (const [field, entries] of classifications) { + for (const [specifier, exportNames] of Object.entries(entries)) { + const provider = packageNameOf(specifier) + if (provider === undefined || !workspaceNames.has(provider)) { + violations.push(`${field} specifier ${specifier} is not a workspace package`) + } + if (exportNames.length === 0) { + violations.push(`${field} lists no exports for ${specifier}`) + } + for (const exportName of duplicates(exportNames)) { + violations.push(`${field} lists ${specifier} export ${exportName} more than once`) + } + for (const exportName of exportNames) { + if (exportName === '' || exportName === NAMESPACE_RUNTIME_EXPORT || exportName === SIDE_EFFECT_RUNTIME_EXPORT) { + violations.push(`${field} cannot classify unbounded ${specifier} export ${exportName}`) + continue + } + if (!allRuntimeUses.some(use => use.specifier === specifier && use.exportName === exportName)) { + violations.push(`${field} lists unused ${specifier} export ${exportName}`) + } + if (field === 'safeHostDependencyExports' + && policy.peerRequiredHostExports[specifier]?.includes(exportName) === true) { + violations.push(`${specifier} export ${exportName} appears in both Host export classifications`) + } + } + } + } + + for (const fact of facts) { + for (const use of fact.hostRuntimeExportUses) { + if (use.packageName === fact.manifest.name || use.packageName === CORDIS) continue + if (!workspaceNames.has(use.packageName) && fact.manifest.peerDependencies?.[use.packageName] === undefined) continue + if (policy.safeHostDependencyExports[use.specifier]?.includes(use.exportName) === true) continue + if (policy.peerRequiredHostExports[use.specifier]?.includes(use.exportName) === true) continue + violations.push( + `${use.sourcePath}:${String(use.line)}:${String(use.column)}: ` + + `${use.specifier}#${use.exportName} is not classified as safe or peer-required — ${use.sourceLine}`, + ) + } + } + return violations.sort() +} + /** Read every package covered by the current dependency policy. */ export function readPackageDependencyState( root: string, @@ -239,10 +423,15 @@ export function readPackageDependencyState( const packages = readWorkspacePackageManifests(root) const workspaceNames = new Set(packages.all.map(pkg => pkg.name)) const discovered = discoverPackageDependencyScope(packages.release, policy) + const facts = discovered.selected.map(pkg => + readPackageDependencyFacts(root, pkg, pkg.role, workspaceNames, policy)) return { - facts: discovered.selected.map(pkg => readPackageDependencyFacts(root, pkg, pkg.role, workspaceNames)), + facts, packages: packages.release, - policyViolations: discovered.violations, + policyViolations: [ + ...discovered.violations, + ...collectHostDependencyExportPolicyViolations(facts, workspaceNames, policy), + ].sort(), workspaceNames, } } @@ -255,9 +444,11 @@ export function expectedPackageDependencies( const add = (name: string, sectionName: ExpectedPackageDependency['section'], origin: string): void => { if (name === facts.manifest.name || name === CORDIS) return const current = expected.get(name) - const section = current?.section === 'dependencies' || sectionName === 'dependencies' - ? 'dependencies' - : 'devDependencies' + const section = current?.section === 'peer-dev' || sectionName === 'peer-dev' + ? 'peer-dev' + : current?.section === 'dependencies' || sectionName === 'dependencies' + ? 'dependencies' + : 'devDependencies' expected.set(name, { section, origins: new Set([...(current?.origins ?? []), origin]) }) } @@ -274,7 +465,8 @@ export function expectedPackageDependencies( } for (const [name, paths] of facts.hostRuntimeSourceUses) { if (!facts.workspaceNames.has(name) && facts.manifest.peerDependencies?.[name] === undefined) continue - for (const path of paths) add(name, 'dependencies', path) + const expectedSection = facts.peerRequiredHostDependencies.has(name) ? 'peer-dev' : 'dependencies' + for (const path of paths) add(name, expectedSection, path) } return new Map([...expected].map(([name, rule]) => [name, { section: rule.section, @@ -282,23 +474,46 @@ export function expectedPackageDependencies( }])) } -/** Format the managed Host runtime edges that remain ordinary dependencies. */ +interface ManagedRuntimeEdge { + readonly consumer: string + readonly dependency: string + readonly exports: readonly string[] +} + +function managedRuntimeEdges( + state: PackageDependencyState, + expectedSection: 'dependencies' | 'peer-dev', +): ManagedRuntimeEdge[] { + return state.facts.flatMap(facts => [...expectedPackageDependencies(facts)] + .filter(([name, rule]) => name !== CORDIS && rule.section === expectedSection) + .map(([dependency]) => ({ + consumer: facts.manifest.name ?? facts.manifestPath, + dependency, + exports: [...new Set(facts.hostRuntimeExportUses + .filter(use => use.packageName === dependency) + .map(use => `${use.specifier}#${use.exportName}`))].sort(), + }))) + .sort((left, right) => + left.consumer.localeCompare(right.consumer) || left.dependency.localeCompare(right.dependency)) +} + +/** Format Host runtime edges whose reviewed exports permit ordinary dependencies. */ export function formatManagedRuntimeDependencies(state: PackageDependencyState): string[] { - const rows = state.facts.flatMap((facts) => { - const dependencies = [...expectedPackageDependencies(facts)] - .filter(([, rule]) => rule.section === 'dependencies') - .map(([name]) => name) - .sort() - if (dependencies.length === 0) return [] - return [{ - name: facts.manifest.name ?? facts.manifestPath, - dependencies, - }] - }).sort((left, right) => left.name.localeCompare(right.name)) - const edges = rows.reduce((total, row) => total + row.dependencies.length, 0) + const rows = managedRuntimeEdges(state, 'dependencies') + const packages = new Set(rows.map(row => row.consumer)).size return [ - `${GATE}: ${String(edges)} managed Host runtime dependency edge(s) remain in dependencies across ${String(rows.length)} package(s):`, - ...rows.map(row => ` ${row.name}: ${row.dependencies.join(', ')}`), + `${GATE}: ${String(rows.length)} managed Host runtime edge(s) remain in dependencies across ${String(packages)} package(s):`, + ...rows.map(row => ` ${row.consumer} -> ${row.dependency}: ${row.exports.join(', ')}`), + ] +} + +/** Format Host runtime edges retained as peers by their imported export classification. */ +export function formatPeerRequiredRuntimeDependencies(state: PackageDependencyState): string[] { + const rows = managedRuntimeEdges(state, 'peer-dev') + const packages = new Set(rows.map(row => row.consumer)).size + return [ + `${GATE}: ${String(rows.length)} Host runtime edge(s) remain in peerDependencies because their exports require shared identity across ${String(packages)} package(s):`, + ...rows.map(row => ` ${row.consumer} -> ${row.dependency}: ${row.exports.join(', ')}`), ] } @@ -323,6 +538,7 @@ function describeSections(sections: readonly DependencySection[]): string { /** Return all manifest and policy violations in stable order. */ export function collectPackageDependencyViolations(state: PackageDependencyState): string[] { const violations = [...state.policyViolations] + if (violations.length > 0) return [...new Set(violations)].sort() for (const facts of state.facts) { for (const [name, rule] of expectedPackageDependencies(facts)) { const actual = declaredSections(facts.manifest, name) @@ -454,9 +670,13 @@ function main(): void { let state = readPackageDependencyState(root) const fix = process.argv.includes('--fix') if (fix) { - const changed = fixPackageDependencies(root, state) - console.log(`${GATE}: fixed ${String(changed.length)} manifest(s).`) - state = readPackageDependencyState(root) + if (state.policyViolations.length > 0) { + console.error(`${GATE}: --fix skipped because dependency policy review failed.`) + } else { + const changed = fixPackageDependencies(root, state) + console.log(`${GATE}: fixed ${String(changed.length)} manifest(s).`) + state = readPackageDependencyState(root) + } } const violations = collectPackageDependencyViolations(state) if (violations.length > 0) { @@ -468,11 +688,13 @@ function main(): void { const roles = Object.groupBy(state.facts, fact => fact.role) console.log( `${GATE}: ${String(state.facts.length)} package(s) match the published dependency policy` - + ` (${String(roles['client-host']?.length ?? 0)} Client/Host,` + + ` (${String(roles['client-only']?.length ?? 0)} Client-only,` + + ` ${String(roles['client-host']?.length ?? 0)} Client/Host,` + ` ${String(roles['configured-host']?.length ?? 0)} configured Host).`, ) if (fix) { for (const line of formatManagedRuntimeDependencies(state)) console.log(line) + for (const line of formatPeerRequiredRuntimeDependencies(state)) console.log(line) } } From 943a544899f8870b21c91d278cfe00bc9f9ce19f Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 26 Aug 2026 19:11:24 +0800 Subject: [PATCH 28/63] feat: classify Host dependency exports --- ...08-26-published-dependency-faces.i18n.yaml | 4 +-- .../2026-08-26-published-dependency-faces.md | 35 +++++++++++++++++-- ...026-08-26-published-dependency-faces.zh.md | 35 +++++++++++++++++-- scripts/package-dependency-policy.ts | 32 +++++++++++++++++ 4 files changed, 98 insertions(+), 8 deletions(-) diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml index 433b12fa8c..7f3153a5b2 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.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-26-published-dependency-faces.md -2026-08-26-published-dependency-faces.md: 04b02afe372b2f3d90729f17e837b40ff1e0e6fa -2026-08-26-published-dependency-faces.zh.md: 468fb443e2e94bf23f8c61201f43c2a82f7f509b +2026-08-26-published-dependency-faces.md: a4c745e8bc811027791317b334d285274f24dd20 +2026-08-26-published-dependency-faces.zh.md: 73b8dd28f40a63ea2a13544be535be7832138ba2 diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md index 04b02afe37..a4c745e8bc 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md @@ -30,11 +30,40 @@ Workspace imports used by the Client bundle, type-only imports, module augmentat The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. An unclassified Host runtime export is a policy violation that blocks all `--fix` writes; a maintainer must review the export and classify it, change the source relationship, or change the package selection. Once source safety passes, `--fix` performs only the section and range changes implied by the classification and removes stale peer metadata. +### Maintainer workflow + +Run the verifier without `--fix` for a read-only check of package selection, export classifications, dependency sections, workspace ranges, and peer metadata. An unclassified runtime import reports one clickable `path:line:column` diagnostic per imported export. + +```sh +pnpm run verify-package-dependencies +``` + +Classify each new Host runtime export in [`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) before generating manifests. `safeHostDependencyExports` permits an ordinary dependency; `peerRequiredHostExports` keeps the whole provider package edge in matching peer and development sections. An export may appear in exactly one table. After refactoring a peer-required export so duplicate package copies are safe, move that exact specifier and export to the safe table; an edge becomes an ordinary dependency only after none of its imported exports remain peer-required. + +Generate managed manifest sections, refresh the lockfile separately, and review both results. `--fix` writes nothing while a policy violation exists; after success it prints the ordinary-dependency and peer-required edge lists, but does not update the lockfile. + +```sh +pnpm run verify-package-dependencies -- --fix +pnpm install --lockfile-only +git diff -- packages pnpm-lock.yaml +``` + +Measure the working-tree graph and a Git ref through the local metadata-only registry. Each run creates a fresh consumer and npm cache, executes `npm install --package-lock-only`, rejects archive downloads, and leaves the repository unchanged. `--runs` controls repetitions, `--timeout-ms` bounds each run, and optional `--max-ms` makes the command fail when the slowest run exceeds a threshold. + +```sh +pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000 +pnpm run benchmark:npm-resolution -- --ref=origin/master --runs=5 --timeout-ms=300000 +``` + +Rank the next Host package by applying the current policy in memory, measuring a baseline, trying each reachable unconfigured package, and serially retesting the fastest coarse candidates. Positive `gainSeconds` is `baseline median - candidate median`; `--candidates` limits the roster, `--jobs` controls coarse concurrency, and neither phase writes manifests. A selected candidate still requires export classification before it joins `hostPackages`. + +```sh +pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists=5 --jobs=8 --timeout-ms=120000 +``` + ### Performance verification -[`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) applies the current policy to an in-memory local registry, measures the current CLI graph, and tries every reachable unconfigured Host package one at a time. Concurrent runs provide a coarse shortlist; finalists run serially because npm's peer-placement search can take different paths when metadata request completion order changes. - -The benchmark is manual rather than a CI gate. It performs metadata-only installs in fresh consumers, so its relative results identify peer relays without measuring registry latency or archive downloads. +[`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) and [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) remain manual rather than CI gates because resolver time varies with machine load and metadata completion order. Their fresh-consumer, metadata-only runs isolate npm's dependency-tree calculation from registry latency and archive downloads, so relative results identify peer relays without creating a release-time performance promise. ## Alternatives considered diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md index 468fb443e2..73b8dd28f4 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md @@ -30,11 +30,40 @@ Client bundle 使用的 workspace import、纯类型 import、模块扩充、`ds 验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。未分类的 Host 运行期导出属于策略违规，会阻止 `--fix` 的全部写入；维护者必须审查该导出，并选择分类该导出、修改源码关系或修改选包范围。源码安全检查通过后，`--fix` 只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 +### 维护流程 + +不带 `--fix` 运行验证器，会以只读方式检查选包范围、导出分类、依赖区段、workspace range 与 peer metadata。未分类的运行期 import 会按每个导出分别报告可点击的 `path:line:column` 诊断。 + +```sh +pnpm run verify-package-dependencies +``` + +生成 manifest 前，在 [`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 中分类每个新增 Host 运行期导出。`safeHostDependencyExports` 允许普通 dependency；`peerRequiredHostExports` 让整个提供包依赖边保留在范围一致的 peer 与开发区段。一个导出只能出现在一个表中。把 peer-required 导出重构到重复安装安全后，将该精确 specifier 与导出移入 safe 表；只有当一条依赖边的所有 import 都不再使用 peer-required 导出时，它才会成为普通 dependency。 + +生成受管 manifest 区段后，单独刷新 lockfile，并审查两部分结果。存在策略违规时，`--fix` 不写任何文件；成功后，它会分别打印普通 dependency 与 peer-required 依赖边，但不会更新 lockfile。 + +```sh +pnpm run verify-package-dependencies -- --fix +pnpm install --lockfile-only +git diff -- packages pnpm-lock.yaml +``` + +通过仅 metadata 的本地 registry 测量工作树依赖图与 Git ref。每轮都会创建全新 consumer 与 npm cache，执行 `npm install --package-lock-only`，拒绝下载包归档，并保持仓库不变。`--runs` 控制重复次数，`--timeout-ms` 限制单轮耗时，可选 `--max-ms` 会在最慢一轮超过阈值时让命令失败。 + +```sh +pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000 +pnpm run benchmark:npm-resolution -- --ref=origin/master --runs=5 --timeout-ms=300000 +``` + +计算下一项 Host 包时，命令会在内存中应用当前策略、测量 baseline、逐个尝试可达且未配置的包，并串行复测粗筛中最快的候选。正数 `gainSeconds` 等于 `baseline median - candidate median`；`--candidates` 限定名册，`--jobs` 控制粗筛并发度，两个阶段都不写 manifest。选中的候选仍需先完成导出分类，才能加入 `hostPackages`。 + +```sh +pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists=5 --jobs=8 --timeout-ms=120000 +``` + ### 性能验证 -[`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) 把当前策略应用到内存中的本地 registry，测量当前 CLI 依赖图，并逐个尝试每个可达且未配置的 Host 包。并发运行用于得到粗筛名单；由于 metadata 请求的完成顺序会让 npm 的 peer 放置搜索走不同路径，最终候选会串行复测。 - -Benchmark 是手动诊断工具而非 CI 门禁。它在全新 consumer 中执行仅 metadata 的安装，因此相对结果可以定位 peer 中继，但不测量 registry 延迟或包归档下载。 +[`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) 与 [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) 保持为手动工具而非 CI 门禁，因为 resolver 耗时会随机器负载和 metadata 完成顺序变化。它们通过全新 consumer 和仅 metadata 的运行，把 npm 依赖树计算与 registry 延迟、包归档下载分离，因此相对结果可以定位 peer 中继，但不构成发布时性能承诺。 ## 考虑过的替代方案 diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts index 1a172daafc..4160acd422 100644 --- a/scripts/package-dependency-policy.ts +++ b/scripts/package-dependency-policy.ts @@ -6,6 +6,7 @@ const CLIENT_FACE_INCLUDE: readonly string[] = [] /** Packages exempted from automatic Client/Host treatment despite declaring `dsh.client`. */ const CLIENT_FACE_EXCLUDE: readonly string[] = [ '@deepseek-ai/dsh-api-session-controller', + '@deepseek-ai/dsh-api-workspace-controller', ] /** Host-only packages whose peer relays are deliberately flattened. */ @@ -14,11 +15,40 @@ const HOST_DEPENDENCY_PACKAGES: readonly string[] = [ '@deepseek-ai/dsh-session', ] +/** + * Runtime exports whose values remain valid when npm installs another package copy. + */ +const SAFE_HOST_DEPENDENCY_EXPORTS = { + '@deepseek-ai/dsh-api-session-controller/remote-events': ['SESSION_CONTROLLER_REMOTE_EVENTS'], + '@deepseek-ai/dsh-credentials': ['credentialKey'], + '@deepseek-ai/dsh-host-apiproxy': ['toFetchHandler'], + '@deepseek-ai/dsh-host-apiproxy/api': ['RpcId', 'clientRequestSchema'], + '@deepseek-ai/dsh-llm': ['MessageId', 'callConfigEquals', 'deepFreeze', 'freezeMessage'], + '@deepseek-ai/dsh-llm/brand': ['ToolCallId'], + '@deepseek-ai/dsh-session': ['isJsonValue'], + '@deepseek-ai/dsh-settings': ['settingsNamespace'], + '@deepseek-ai/dsh-system-prompt': ['FIRST_PARTY_SECTION_ORDER'], + '@deepseek-ai/dsh-timeout': ['MAX_TIMER_DELAY_MS'], + '@deepseek-ai/dsh-util-crypto': ['randomUUID'], + '@deepseek-ai/schemastery': ['default'], +} as const satisfies HostDependencyExports + +/** Runtime exports that require every consumer to resolve the provider's shared peer instance. */ +const PEER_REQUIRED_HOST_EXPORTS = { + '@deepseek-ai/dsh-scope': ['carrierKeyOf', 'scopeOf', 'scopeTarget'], + '@deepseek-ai/dsh-typert-protocol': ['TypertLookupFailure', 'TypertRemoteFailure', 'remoteMethods'], +} as const satisfies HostDependencyExports + +/** Exact import specifier to reviewed runtime exports. */ +type HostDependencyExports = Readonly> + /** Complete configurable input to package dependency classification. */ export interface PackageDependencyPolicy { readonly clientFaceInclude: readonly string[] readonly clientFaceExclude: readonly string[] readonly hostPackages: readonly string[] + readonly safeHostDependencyExports: HostDependencyExports + readonly peerRequiredHostExports: HostDependencyExports } /** Repository dependency policy consumed by verification and benchmarking. */ @@ -26,6 +56,8 @@ export const PACKAGE_DEPENDENCY_POLICY: PackageDependencyPolicy = { clientFaceInclude: CLIENT_FACE_INCLUDE, clientFaceExclude: CLIENT_FACE_EXCLUDE, hostPackages: HOST_DEPENDENCY_PACKAGES, + safeHostDependencyExports: SAFE_HOST_DEPENDENCY_EXPORTS, + peerRequiredHostExports: PEER_REQUIRED_HOST_EXPORTS, } function isRecord(value: unknown): value is Record { From 91b5a0198061e2fb4f076a2370d4aa96130a683b Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 26 Aug 2026 23:52:19 +0800 Subject: [PATCH 29/63] fix: complete dependency policy generation --- ...08-26-published-dependency-faces.i18n.yaml | 4 +- .../2026-08-26-published-dependency-faces.md | 7 +- ...026-08-26-published-dependency-faces.zh.md | 7 +- packages/client/AGENTS.md | 2 +- scripts/gen-module-graph.ts | 154 ++++++++++++------ scripts/package-dependency-policy.ts | 16 ++ scripts/package-graph.spec.ts | 21 +++ scripts/verify-package-dependencies.spec.ts | 14 +- scripts/verify-package-dependencies.ts | 24 +++ 9 files changed, 191 insertions(+), 58 deletions(-) diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml index 7f3153a5b2..689c45dea9 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.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-26-published-dependency-faces.md -2026-08-26-published-dependency-faces.md: a4c745e8bc811027791317b334d285274f24dd20 -2026-08-26-published-dependency-faces.zh.md: 73b8dd28f40a63ea2a13544be535be7832138ba2 +2026-08-26-published-dependency-faces.md: 6174e2a46482362c0ff54b5dec261440ce4f6131 +2026-08-26-published-dependency-faces.zh.md: 090031e9cde07d75aae79a87207d879fe220257d diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md index a4c745e8bc..6174e2a464 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md @@ -28,6 +28,8 @@ A workspace package reached by a runtime value import from the Host entry closur Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Existing third-party dependencies outside these managed relationships keep their declared section. Workspace references use `workspace:^`. +Some development relationships exist only in `dsh.client.inject` or TypeScript project references. The policy's `configurationOnlyDevDependencies` table names only those reviewed edges and keeps them in `devDependencies`. + The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. An unclassified Host runtime export is a policy violation that blocks all `--fix` writes; a maintainer must review the export and classify it, change the source relationship, or change the package selection. Once source safety passes, `--fix` performs only the section and range changes implied by the classification and removes stale peer metadata. ### Maintainer workflow @@ -40,12 +42,11 @@ pnpm run verify-package-dependencies Classify each new Host runtime export in [`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) before generating manifests. `safeHostDependencyExports` permits an ordinary dependency; `peerRequiredHostExports` keeps the whole provider package edge in matching peer and development sections. An export may appear in exactly one table. After refactoring a peer-required export so duplicate package copies are safe, move that exact specifier and export to the safe table; an edge becomes an ordinary dependency only after none of its imported exports remain peer-required. -Generate managed manifest sections, refresh the lockfile separately, and review both results. `--fix` writes nothing while a policy violation exists; after success it prints the ordinary-dependency and peer-required edge lists, but does not update the lockfile. +Generate the managed manifests and every directly derived artifact with one command. `--fix` writes nothing while a policy violation exists; after success it refreshes `pnpm-lock.yaml`, regenerates both module-graph languages and their pairing record, and prints the ordinary-dependency and peer-required edge lists. ```sh pnpm run verify-package-dependencies -- --fix -pnpm install --lockfile-only -git diff -- packages pnpm-lock.yaml +git diff -- packages pnpm-lock.yaml docs/module-graph.md docs/module-graph.zh.md docs/module-graph.i18n.yaml ``` Measure the working-tree graph and a Git ref through the local metadata-only registry. Each run creates a fresh consumer and npm cache, executes `npm install --package-lock-only`, rejects archive downloads, and leaves the repository unchanged. `--runs` controls repetitions, `--timeout-ms` bounds each run, and optional `--max-ms` makes the command fail when the slowest run exceeds a threshold. diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md index 73b8dd28f4..090031e9cd 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md @@ -28,6 +28,8 @@ Host 入口闭包中的运行期 value import 所到达的 workspace 包，只 Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。不属于这些受管关系的现有第三方 dependency 保持原区段。Workspace 引用使用 `workspace:^`。 +部分开发期关系只存在于 `dsh.client.inject` 或 TypeScript project reference 中。策略的 `configurationOnlyDevDependencies` 表只列出这些已评审的依赖边，并将它们保留在 `devDependencies` 中。 + 验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。未分类的 Host 运行期导出属于策略违规，会阻止 `--fix` 的全部写入；维护者必须审查该导出，并选择分类该导出、修改源码关系或修改选包范围。源码安全检查通过后，`--fix` 只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 ### 维护流程 @@ -40,12 +42,11 @@ pnpm run verify-package-dependencies 生成 manifest 前，在 [`package-dependency-policy.ts`](../../../../scripts/package-dependency-policy.ts) 中分类每个新增 Host 运行期导出。`safeHostDependencyExports` 允许普通 dependency；`peerRequiredHostExports` 让整个提供包依赖边保留在范围一致的 peer 与开发区段。一个导出只能出现在一个表中。把 peer-required 导出重构到重复安装安全后，将该精确 specifier 与导出移入 safe 表；只有当一条依赖边的所有 import 都不再使用 peer-required 导出时，它才会成为普通 dependency。 -生成受管 manifest 区段后，单独刷新 lockfile，并审查两部分结果。存在策略违规时，`--fix` 不写任何文件；成功后，它会分别打印普通 dependency 与 peer-required 依赖边，但不会更新 lockfile。 +用一条命令生成受管 manifest 和所有直接派生产物。存在策略违规时，`--fix` 不写任何文件；成功后，它会刷新 `pnpm-lock.yaml`、重新生成中英文 module graph 及其配对记录，并打印普通 dependency 与 peer-required 依赖边。 ```sh pnpm run verify-package-dependencies -- --fix -pnpm install --lockfile-only -git diff -- packages pnpm-lock.yaml +git diff -- packages pnpm-lock.yaml docs/module-graph.md docs/module-graph.zh.md docs/module-graph.i18n.yaml ``` 通过仅 metadata 的本地 registry 测量工作树依赖图与 Git ref。每轮都会创建全新 consumer 与 npm cache，执行 `npm install --package-lock-only`，拒绝下载包归档，并保持仓库不变。`--runs` 控制重复次数，`--timeout-ms` 限制单轮耗时，可选 `--max-ms` 会在最慢一轮超过阈值时让命令失败。 diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md index 6ef0c5e42c..1b33de5039 100644 --- a/packages/client/AGENTS.md +++ b/packages/client/AGENTS.md @@ -60,7 +60,7 @@ Npm sections describe installation and development relationships; each build fac 1. **Every client package keeps Cordis in matching `peerDependencies` and `devDependencies`.** This includes the static packages because their Node face participates in the same Cordis plugin contract. 2. **A package under `packages/client/` is always covered; `dsh.client` marks a Client/Host package outside that directory.** Explicit include/exclude entries handle exceptions. Every covered package's Host entry is scanned, while a `./client` export alone does not select dependency policy. -3. **Browser and type relationships are development-only.** Client imports, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and metadata-only peers belong only in `devDependencies`. +3. **Browser and type relationships are development-only.** Client imports, type-only imports, module augmentations, TypeScript project references, `dsh.client.inject`, invariant companions, and metadata-only peers belong only in `devDependencies`. Configuration-only entries that Knip cannot infer from imports are listed in the dependency policy and projected into `knip.json` by `--fix`. 4. **Host value imports require classified exports.** A workspace value reached from the package's Host entry belongs only in `dependencies` when its exact module specifier and runtime export appear in `safeHostDependencyExports`. Exports whose identity or module state must be shared appear in `peerRequiredHostExports` and keep the whole package edge in matching `peerDependencies` and `devDependencies`. The verifier rejects unclassified exports before `--fix` writes manifests. 5. **Ordinary installed libraries stay in `dependencies`.** This includes private implementation libraries bundled into `lib/client.js` and bare imports left in a statically linked `lib/index.js`; the final Vite host, not the library build, merges and splits the latter. 6. **Browser and Node build faces declare externality independently.** A dynamic browser half uses the baseline plus `dsh.client.external`; a statically linked face externalizes every bare specifier; a Node face externalizes its production dependencies ([`tsdown.client.ts`](tsdown.client.ts)). Moving a name between npm sections must not silently change bundle contents. diff --git a/scripts/gen-module-graph.ts b/scripts/gen-module-graph.ts index 0d1b16588f..d095c1afed 100644 --- a/scripts/gen-module-graph.ts +++ b/scripts/gen-module-graph.ts @@ -1,21 +1,21 @@ -/** - * Generate `docs/module-graph.md` from in-repo `peerDependencies`, the canonical - * runtime edges. The deterministic output groups packages by directory and - * renders both Mermaid and a dependency table; `--check` verifies freshness. - */ +/** Generate the paired shared-instance package graph from workspace peer dependencies. */ +import { existsSync, readFileSync, writeFileSync } from 'node:fs' import { resolve } from 'node:path' -import { readFileSync, writeFileSync } from 'node:fs' import { collectPackageGraph, escapeMermaidLabel as escLabel, graphNodeId as nodeId, type PackageGraphNode, } from './package-graph.ts' +import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts' +import { renderTranslationPairingRecord, translationPairPaths } from './translation-pairing-record.ts' const root = resolve(import.meta.dirname, '..') -const OUT = 'docs/module-graph.md' +const SOURCE = 'docs/module-graph.md' +const PATHS = translationPairPaths(SOURCE) type Pkg = PackageGraphNode +type Locale = 'en' | 'zh' const GROUP_ORDER = [ 'util', @@ -46,42 +46,55 @@ function packageLink(pkg: Pkg): string { return `[\`${pkg.short}\`](../${pkg.rel})` } -/** Render the full docs/module-graph.md content (pure, deterministic). */ -function render(pkgs: Pkg[]): string { +/** + * Render one locale of the complete deterministic package graph. + * @param pkgs - Dependency-first package nodes. + * @param locale - Output document language. + * @returns Complete generated Markdown. + */ +export function renderModuleGraph(pkgs: readonly Pkg[], locale: Locale): string { const edges: string[] = [] - for (const p of pkgs) { - for (const d of p.deps) edges.push(` ${nodeId('pkg', p.short)} --> ${nodeId('pkg', d)}`) + for (const pkg of pkgs) { + for (const dependency of pkg.deps) edges.push(` ${nodeId('pkg', pkg.short)} --> ${nodeId('pkg', dependency)}`) } const byShort = new Map(pkgs.map(pkg => [pkg.short, pkg])) - const groups = [...new Set(pkgs.map(pkg => pkg.group))].sort((a, b) => { - const ia = GROUP_ORDER.indexOf(a) - const ib = GROUP_ORDER.indexOf(b) - const na = ia === -1 ? Number.MAX_SAFE_INTEGER : ia - const nb = ib === -1 ? Number.MAX_SAFE_INTEGER : ib - return na - nb || a.localeCompare(b) + const groups = [...new Set(pkgs.map(pkg => pkg.group))].sort((left, right) => { + const leftIndex = GROUP_ORDER.indexOf(left) + const rightIndex = GROUP_ORDER.indexOf(right) + const normalizedLeft = leftIndex === -1 ? Number.MAX_SAFE_INTEGER : leftIndex + const normalizedRight = rightIndex === -1 ? Number.MAX_SAFE_INTEGER : rightIndex + return normalizedLeft - normalizedRight || left.localeCompare(right) }) const groupBlocks: string[] = [] for (const group of groups) { groupBlocks.push(` subgraph ${nodeId('group', group)}["packages/${escLabel(group)}"]`) - for (const pkg of pkgs.filter(p => p.group === group).sort((a, b) => a.short.localeCompare(b.short))) { + for (const pkg of pkgs.filter(candidate => candidate.group === group) + .sort((left, right) => left.short.localeCompare(right.short))) { groupBlocks.push(` ${nodeId('pkg', pkg.short)}["${escLabel(pkg.short)}"]`) } groupBlocks.push(' end') } - const rows = pkgs.map((p) => { - const deps = p.deps.length ? p.deps.map((d) => { - const dep = byShort.get(d) - return dep ? packageLink(dep) : `\`${d}\`` - }).join(', ') : '—' - return `| ${packageLink(p)} | \`${p.group}\` | ${deps} |` + const rows = pkgs.map((pkg) => { + const dependencies = pkg.deps.length > 0 + ? pkg.deps.map((dependency) => { + const target = byShort.get(dependency) + return target ? packageLink(target) : `\`${dependency}\`` + }).join(', ') + : '—' + return `| ${packageLink(pkg)} | \`${pkg.group}\` | ${dependencies} |` }) + const chinese = locale === 'zh' return [ - '', + chinese + ? '' + : '', '', - '# Module dependency graph', + chinese ? '# 共享实例依赖关系图' : '# Shared-instance dependency graph', '', - 'Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package\'s `peerDependencies` (the canonical runtime-dependency signal) and grouped by the `packages//` hierarchy. An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped.', + ...(chinese ? ['[English](module-graph.md) | 中文', ''] : []), + chinese + ? '`@deepseek-ai/dsh-*` harness 包之间的 peer 依赖关系。peer 表示消费端需要提供共享实例，不包括普通运行时 dependency 或仅开发期关系。该图按 `packages//` 层级分组；边 `a --> b` 表示包 `a` peer 依赖包 `b`。名称中的 `@deepseek-ai/dsh-` 前缀已移除。' + : 'Peer dependencies among the `@deepseek-ai/dsh-*` harness packages. A peer means the consumer requires a shared instance; ordinary runtime dependencies and development-only relationships are not shown. The graph is grouped by the `packages//` hierarchy. An edge `a --> b` means package `a` has package `b` as a peer. Names omit the `@deepseek-ai/dsh-` prefix.', '', '```mermaid', 'flowchart TD', @@ -89,31 +102,76 @@ function render(pkgs: Pkg[]): string { ...edges, '```', '', - '| Package | Group | Depends on |', + chinese ? '| 包 | 分组 | Peer 依赖 |' : '| Package | Group | Peer dependencies |', '| --- | --- | --- |', ...rows, '', ].join('\n') } -const content = render(collectPackageGraph(root, GROUP_ORDER, 'gen-module-graph')) - -if (process.argv.includes('--check')) { - let committed: string | null = null - try { - committed = readFileSync(resolve(root, OUT), 'utf8') - } catch { - // A missing artifact is the expected read failure. Any read failure has the - // same remedy here—regenerate—so it is reported as stale below. - committed = null - } - if (committed === content) { - console.log(`gen-module-graph: ${OUT} is up to date.`) - process.exit(0) - } - console.error(`gen-module-graph: ${OUT} is stale. Run \`pnpm run gen-module-graph\` and commit ${OUT}.`) - process.exit(1) +/** + * Compute both localized graph documents from the current workspace manifests. + * @param scanRoot - Repository root containing packages and documentation. + * @returns Repository-relative output paths and exact generated content. + */ +export function computeModuleGraphOutputs(scanRoot: string = root): ReadonlyMap { + const packages = collectPackageGraph(scanRoot, GROUP_ORDER, 'gen-module-graph') + return new Map([ + [PATHS.source, renderModuleGraph(packages, 'en')], + [PATHS.zh, renderModuleGraph(packages, 'zh')], + ]) } -writeFileSync(resolve(root, OUT), content) -console.log(`gen-module-graph: wrote ${OUT}.`) +/** + * Write both graph documents and their recovery record. + * @param scanRoot - Repository root containing packages and documentation. + * @returns Repository-relative paths whose content changed. + */ +export function writeModuleGraph(scanRoot: string = root): string[] { + const outputs = computeModuleGraphOutputs(scanRoot) + const changed: string[] = [] + for (const [path, content] of outputs) { + const destination = resolve(scanRoot, path) + if (existsSync(destination) && readFileSync(destination, 'utf8') === content) continue + writeFileSync(destination, content) + changed.push(path) + } + const source = Buffer.from(outputs.get(PATHS.source) ?? '') + const zh = Buffer.from(outputs.get(PATHS.zh) ?? '') + const record = renderTranslationPairingRecord(PATHS, { + sourceHash: storeGitBlob(scanRoot, source), + zhHash: storeGitBlob(scanRoot, zh), + }) + const recordPath = resolve(scanRoot, PATHS.meta) + if (!existsSync(recordPath) || readFileSync(recordPath, 'utf8') !== record) { + writeFileSync(recordPath, record) + changed.push(PATHS.meta) + } + return changed.sort() +} + +/** CLI entry: regenerate by default, or verify all paired outputs with `--check`. @returns Nothing. */ +export function main(): void { + const outputs = computeModuleGraphOutputs(root) + const record = renderTranslationPairingRecord(PATHS, { + sourceHash: gitBlobHash(Buffer.from(outputs.get(PATHS.source) ?? '')), + zhHash: gitBlobHash(Buffer.from(outputs.get(PATHS.zh) ?? '')), + }) + const expected = new Map([...outputs, [PATHS.meta, record]]) + if (process.argv.includes('--check')) { + const stale = [...expected].filter(([path, content]) => ( + !existsSync(resolve(root, path)) || readFileSync(resolve(root, path), 'utf8') !== content + )).map(([path]) => path) + if (stale.length === 0) { + console.log(`gen-module-graph: ${expected.size} artifact(s) are up to date.`) + return + } + console.error(`gen-module-graph: stale — ${stale.join(', ')}. Run \`pnpm run gen-module-graph\` and commit the result.`) + process.exitCode = 1 + return + } + const changed = writeModuleGraph(root) + console.log(`gen-module-graph: ${expected.size} artifact(s) computed, ${String(changed.length)} written.`) +} + +if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) main() diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts index 4160acd422..2d8f7eb56c 100644 --- a/scripts/package-dependency-policy.ts +++ b/scripts/package-dependency-policy.ts @@ -15,6 +15,20 @@ const HOST_DEPENDENCY_PACKAGES: readonly string[] = [ '@deepseek-ai/dsh-session', ] +/** Development-only package relationships not represented by source imports. */ +const CONFIGURATION_ONLY_DEV_DEPENDENCIES = { + '@deepseek-ai/dsh-client-locale': ['@deepseek-ai/dsh-api-remotes'], + '@deepseek-ai/dsh-client-ui-conversation': [ + '@deepseek-ai/dsh-api-remotes', + '@deepseek-ai/dsh-client-ui-workspace', + ], + '@deepseek-ai/dsh-client-ui-model-selection': ['@deepseek-ai/dsh-client-ui-input-trigger'], + '@deepseek-ai/dsh-client-ui-sidebar': ['@deepseek-ai/dsh-client-ui-workspace'], + '@deepseek-ai/dsh-client-ui-subagent': ['@deepseek-ai/dsh-client-ui-input-trigger'], + '@deepseek-ai/dsh-client-ui-theme': ['@deepseek-ai/dsh-api-remotes'], + '@deepseek-ai/dsh-client-ui-tool': ['@deepseek-ai/dsh-api-remotes'], +} as const satisfies Readonly> + /** * Runtime exports whose values remain valid when npm installs another package copy. */ @@ -47,6 +61,7 @@ export interface PackageDependencyPolicy { readonly clientFaceInclude: readonly string[] readonly clientFaceExclude: readonly string[] readonly hostPackages: readonly string[] + readonly configurationOnlyDevDependencies: Readonly> readonly safeHostDependencyExports: HostDependencyExports readonly peerRequiredHostExports: HostDependencyExports } @@ -56,6 +71,7 @@ export const PACKAGE_DEPENDENCY_POLICY: PackageDependencyPolicy = { clientFaceInclude: CLIENT_FACE_INCLUDE, clientFaceExclude: CLIENT_FACE_EXCLUDE, hostPackages: HOST_DEPENDENCY_PACKAGES, + configurationOnlyDevDependencies: CONFIGURATION_ONLY_DEV_DEPENDENCIES, safeHostDependencyExports: SAFE_HOST_DEPENDENCY_EXPORTS, peerRequiredHostExports: PEER_REQUIRED_HOST_EXPORTS, } diff --git a/scripts/package-graph.spec.ts b/scripts/package-graph.spec.ts index fecbccedfe..99b3c3b9f1 100644 --- a/scripts/package-graph.spec.ts +++ b/scripts/package-graph.spec.ts @@ -2,6 +2,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs' import { tmpdir } from 'node:os' import { join } from 'node:path' import { afterEach, describe, expect, it } from 'vitest' +import { renderModuleGraph } from './gen-module-graph.ts' import { collectPackageGraph } from './package-graph.ts' const roots: string[] = [] @@ -49,3 +50,23 @@ describe('collectPackageGraph', () => { .toThrow('fixture: @deepseek-ai/dsh-consumer references missing in-repo peer @deepseek-ai/dsh-missing') }) }) + +describe('renderModuleGraph', () => { + it('renders the same peer edge in both generated languages', () => { + const packages = [ + { short: 'provider', name: '@deepseek-ai/dsh-provider', group: 'core', rel: 'packages/core/provider', deps: [] }, + { short: 'consumer', name: '@deepseek-ai/dsh-consumer', group: 'core', rel: 'packages/core/consumer', deps: ['provider'] }, + ] + + const english = renderModuleGraph(packages, 'en') + const chinese = renderModuleGraph(packages, 'zh') + + expect(english).toContain('# Shared-instance dependency graph') + expect(chinese).toContain('# 共享实例依赖关系图') + expect(chinese).toContain('[English](module-graph.md) | 中文') + for (const output of [english, chinese]) { + expect(output).toContain('pkg_consumer --> pkg_provider') + expect(output).toContain('| [`consumer`](../packages/core/consumer) | `core` | [`provider`](../packages/core/provider) |') + } + }) +}) diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts index 23c1bbca69..ad4752f9a7 100644 --- a/scripts/verify-package-dependencies.spec.ts +++ b/scripts/verify-package-dependencies.spec.ts @@ -46,6 +46,7 @@ function policy(fields: Partial = {}): PackageDependenc clientFaceInclude: [], clientFaceExclude: [], hostPackages: [], + configurationOnlyDevDependencies: {}, safeHostDependencyExports: {}, peerRequiredHostExports: {}, ...fields, @@ -95,6 +96,18 @@ describe('package dependency scope', () => { '@deepseek-ai/dsh-llm', '@deepseek-ai/dsh-session', ]) + expect(PACKAGE_DEPENDENCY_POLICY.configurationOnlyDevDependencies).toEqual({ + '@deepseek-ai/dsh-client-locale': ['@deepseek-ai/dsh-api-remotes'], + '@deepseek-ai/dsh-client-ui-conversation': [ + '@deepseek-ai/dsh-api-remotes', + '@deepseek-ai/dsh-client-ui-workspace', + ], + '@deepseek-ai/dsh-client-ui-model-selection': ['@deepseek-ai/dsh-client-ui-input-trigger'], + '@deepseek-ai/dsh-client-ui-sidebar': ['@deepseek-ai/dsh-client-ui-workspace'], + '@deepseek-ai/dsh-client-ui-subagent': ['@deepseek-ai/dsh-client-ui-input-trigger'], + '@deepseek-ai/dsh-client-ui-theme': ['@deepseek-ai/dsh-api-remotes'], + '@deepseek-ai/dsh-client-ui-tool': ['@deepseek-ai/dsh-api-remotes'], + }) expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/schemastery']).toEqual(['default']) expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-scope']).toEqual([ 'carrierKeyOf', 'scopeOf', 'scopeTarget', @@ -219,7 +232,6 @@ describe('face-aware source classification', () => { mkdirSync(dirname(join(root, path)), { recursive: true }) writeFileSync(join(root, path), source) } - const found = readPackageDependencyFacts(root, subject, 'client-host', new Set([ CORDIS, '@f/runtime', '@f/types', '@f/nested', '@f/hidden', '@f/browser', '@f/injected', ])) diff --git a/scripts/verify-package-dependencies.ts b/scripts/verify-package-dependencies.ts index f8ac1cf3dd..3782d61309 100644 --- a/scripts/verify-package-dependencies.ts +++ b/scripts/verify-package-dependencies.ts @@ -1,8 +1,10 @@ /** Verify and repair npm dependency sections from published Client and Host faces. */ +import { spawnSync } from 'node:child_process' import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs' import { dirname, extname, join, normalize, relative, resolve, sep } from 'node:path' import ts from 'typescript' +import { writeModuleGraph } from './gen-module-graph.ts' import { hasClientDeclaration, PACKAGE_DEPENDENCY_POLICY, @@ -439,6 +441,7 @@ export function readPackageDependencyState( /** Derive the required npm section for each relationship owned by the policy. */ export function expectedPackageDependencies( facts: PackageDependencyFacts, + policy: PackageDependencyPolicy = PACKAGE_DEPENDENCY_POLICY, ): ReadonlyMap { const expected = new Map }>() const add = (name: string, sectionName: ExpectedPackageDependency['section'], origin: string): void => { @@ -460,6 +463,12 @@ export function expectedPackageDependencies( for (const name of facts.clientInject) { if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'dsh.client.inject') } + for (const name of PACKAGE_DEPENDENCY_POLICY.configurationOnlyDevDependencies[facts.manifest.name ?? ''] ?? []) { + if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'configured development-only relationship') + } + for (const name of policy.configurationOnlyDevDependencies[facts.manifest.name ?? ''] ?? []) { + if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'configured development-only relationship') + } for (const name of Object.keys(facts.manifest.peerDependencies ?? {})) { if (name !== CORDIS) add(name, 'devDependencies', 'existing non-Cordis peer') } @@ -665,6 +674,16 @@ export function fixPackageDependencies(root: string, state: PackageDependencySta return changed.sort() } +function refreshPnpmLockfile(root: string): void { + const result = spawnSync( + 'pnpm', + ['install', '--lockfile-only', '--ignore-scripts', '--no-frozen-lockfile'], + { cwd: root, shell: process.platform === 'win32', stdio: 'inherit' }, + ) + if (result.error !== undefined) throw new Error(`could not refresh pnpm-lock.yaml: ${result.error.message}`) + if (result.status !== 0) throw new Error(`pnpm lockfile refresh exited with status ${String(result.status)}`) +} + function main(): void { const root = resolve(import.meta.dirname, '..') let state = readPackageDependencyState(root) @@ -675,6 +694,11 @@ function main(): void { } else { const changed = fixPackageDependencies(root, state) console.log(`${GATE}: fixed ${String(changed.length)} manifest(s).`) + refreshPnpmLockfile(root) + const graphChanges = writeModuleGraph(root) + console.log( + `${GATE}: refreshed pnpm-lock.yaml and wrote ${String(graphChanges.length)} module-graph artifact(s).`, + ) state = readPackageDependencyState(root) } } From b46d36d3bf4ba352df62cc86b6329c038c4209cf Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 27 Aug 2026 01:23:01 +0800 Subject: [PATCH 30/63] test(release): verify dual-version npm layout --- ...08-26-published-dependency-faces.i18n.yaml | 4 +- .../2026-08-26-published-dependency-faces.md | 10 +- ...026-08-26-published-dependency-faces.zh.md | 10 +- .github/workflows/release.yml | 46 +++- package.json | 1 + scripts/benchmark-npm-resolution.spec.ts | 23 ++ scripts/benchmark-npm-resolution.ts | 70 +++++- scripts/ci-workflow.spec.ts | 16 +- scripts/verify-npm-install-layout.spec.ts | 102 ++++++++ scripts/verify-npm-install-layout.ts | 217 ++++++++++++++++++ 10 files changed, 482 insertions(+), 17 deletions(-) create mode 100644 scripts/verify-npm-install-layout.spec.ts create mode 100644 scripts/verify-npm-install-layout.ts diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml index 689c45dea9..e09edf4f86 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.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-26-published-dependency-faces.md -2026-08-26-published-dependency-faces.md: 6174e2a46482362c0ff54b5dec261440ce4f6131 -2026-08-26-published-dependency-faces.zh.md: 090031e9cde07d75aae79a87207d879fe220257d +2026-08-26-published-dependency-faces.md: aa7714e5c83aaf1c68ef300bdb10006e534bf88d +2026-08-26-published-dependency-faces.zh.md: e0ba33ff25651d1adf378af87fd6065ed9e54d03 diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md index 6174e2a464..aa7714e5c8 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md @@ -56,6 +56,12 @@ pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000 pnpm run benchmark:npm-resolution -- --ref=origin/master --runs=5 --timeout-ms=300000 ``` +Verify package placement through two incompatible synthetic DSH releases. The verifier copies every current DSH manifest into `0.1.0` and `0.2.0`, asks npm for a package lock only, and rejects cross-release DSH resolution, unexpected DSH locations, unequal release inventories, multiple Cordis installations, and package archive requests. The local index contains only installed current-platform metadata, so npm-accepted probes for unavailable optional packages are reported without failing the check. + +```sh +pnpm run verify-npm-install-layout +``` + Rank the next Host package by applying the current policy in memory, measuring a baseline, trying each reachable unconfigured package, and serially retesting the fastest coarse candidates. Positive `gainSeconds` is `baseline median - candidate median`; `--candidates` limits the roster, `--jobs` controls coarse concurrency, and neither phase writes manifests. A selected candidate still requires export classification before it joins `hostPackages`. ```sh @@ -64,7 +70,7 @@ pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists ### Performance verification -[`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) and [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) remain manual rather than CI gates because resolver time varies with machine load and metadata completion order. Their fresh-consumer, metadata-only runs isolate npm's dependency-tree calculation from registry latency and archive downloads, so relative results identify peer relays without creating a release-time performance promise. +[`verify-npm-install-layout`](../../../../scripts/verify-npm-install-layout.ts) is a deterministic package-path and version check in the `Release (dsh)` workflow on every pull request and master push; it does not enforce resolver duration. [`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) and [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) remain manual because resolver time varies with machine load and metadata completion order. Their fresh-consumer, metadata-only runs isolate npm's dependency-tree calculation from registry latency and archive downloads, so relative results identify peer relays without creating a release-time performance promise. ## Alternatives considered @@ -84,4 +90,4 @@ The published dependency graph follows artifact ownership instead of source-dire Moving a public type-only relationship to `devDependencies` means a standalone TypeScript consumer must install the referenced type package when it consumes that declaration. The shipped profiles install the complete supported package family; supporting independently assembled TypeScript consumers would require a different policy. -The explicit overrides, Host list, and export classifications are reviewable decisions. Class constructors used by `instanceof`, symbols, and accessors for module-private registries require peers when their identity or state crosses package boundaries; being a value import alone does not make an export duplicate-safe. Changing a classification changes the installed graph and requires the focused verifier tests plus a fresh next-package benchmark. The metadata-only benchmark is diagnostic evidence, not a release-time performance promise. +The explicit overrides, Host list, and export classifications are reviewable decisions. Class constructors used by `instanceof`, symbols, and accessors for module-private registries require peers when their identity or state crosses package boundaries; being a value import alone does not make an export duplicate-safe. Changing a classification changes the installed graph and requires the focused verifier tests, the two-release layout check, and a fresh next-package benchmark. The metadata-only benchmark is diagnostic evidence, not a release-time performance promise. diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md index 090031e9cd..e0ba33ff25 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md @@ -56,6 +56,12 @@ pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000 pnpm run benchmark:npm-resolution -- --ref=origin/master --runs=5 --timeout-ms=300000 ``` +通过两个互不兼容的 DSH 合成版本验证包落位。验证器把每份当前 DSH manifest 分别复制为 `0.1.0` 和 `0.2.0`，只要求 npm 生成 package lock，并拒绝跨版本 DSH 解析、非预期 DSH 路径、两套版本清单不一致、多个 Cordis 实例以及包归档请求。本地索引只包含当前平台已安装的 metadata，因此只报告而不拒绝 npm 已接受的不可用可选包探测。 + +```sh +pnpm run verify-npm-install-layout +``` + 计算下一项 Host 包时，命令会在内存中应用当前策略、测量 baseline、逐个尝试可达且未配置的包，并串行复测粗筛中最快的候选。正数 `gainSeconds` 等于 `baseline median - candidate median`；`--candidates` 限定名册，`--jobs` 控制粗筛并发度，两个阶段都不写 manifest。选中的候选仍需先完成导出分类，才能加入 `hostPackages`。 ```sh @@ -64,7 +70,7 @@ pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists ### 性能验证 -[`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) 与 [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) 保持为手动工具而非 CI 门禁，因为 resolver 耗时会随机器负载和 metadata 完成顺序变化。它们通过全新 consumer 和仅 metadata 的运行，把 npm 依赖树计算与 registry 延迟、包归档下载分离，因此相对结果可以定位 peer 中继，但不构成发布时性能承诺。 +[`verify-npm-install-layout`](../../../../scripts/verify-npm-install-layout.ts) 是 `Release (dsh)` workflow 在每个 pull request 和 master push 上运行的确定性包路径与版本检查；它不限制 resolver 耗时。[`benchmark-npm-resolution`](../../../../scripts/benchmark-npm-resolution.ts) 与 [`benchmark-next-package-dependency`](../../../../scripts/benchmark-next-package-dependency.ts) 保持为手动工具，因为 resolver 耗时会随机器负载和 metadata 完成顺序变化。它们通过全新 consumer 和仅 metadata 的运行，把 npm 依赖树计算与 registry 延迟、包归档下载分离，因此相对结果可以定位 peer 中继，但不构成发布时性能承诺。 ## 考虑过的替代方案 @@ -84,4 +90,4 @@ pnpm run benchmark:npm-resolution:next -- --runs=1 --finalist-runs=5 --finalists 把公开纯类型关系放进 `devDependencies`，意味着独立 TypeScript 消费者在使用该声明时必须自行安装被引用的类型包。发布 profile 会安装完整的受支持包族；若要支持独立组装的 TypeScript 消费者，需要另一套策略。 -显式 override、Host 列表与导出分类都是需要评审的决策。当 class constructor、symbol 和访问模块私有 registry 的函数跨包传递身份或状态时，它们要求 peer；仅仅属于 value import 并不能证明导出可重复安装。修改分类会改变安装图，因此需要运行聚焦 verifier 测试并重新执行 next-package benchmark。仅 metadata benchmark 是诊断证据，不是发布时安装耗时承诺。 +显式 override、Host 列表与导出分类都是需要评审的决策。当 class constructor、symbol 和访问模块私有 registry 的函数跨包传递身份或状态时，它们要求 peer；仅仅属于 value import 并不能证明导出可重复安装。修改分类会改变安装图，因此需要运行聚焦 verifier 测试、双版本布局检查并重新执行 next-package benchmark。仅 metadata benchmark 是诊断证据，不是发布时安装耗时承诺。 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 4ae1940c0c..ad6c64ae67 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,9 +2,9 @@ # entries, all on one version. The vendored framework and the native packages are # separate sequences with their own workflows and version lines. # -# Pack runs without credentials on every pull request and master push, so a -# pull request proves the whole publish set still packs. Publication is a manual -# workflow_dispatch of release-publish.yml from a dsh-v* tag. +# Pack and dependency-layout verification run without credentials on every pull +# request and master push. Publication is a manual workflow_dispatch of +# release-publish.yml from a dsh-v* tag. name: Release (dsh) on: @@ -26,6 +26,46 @@ env: DSH_TELEMETRY_DISABLED: '1' jobs: + dependencies: + name: Dependency layout + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@v6 + with: + persist-credentials: false + + - uses: pnpm/action-setup@v4 + with: + dest: ${{ runner.temp }}/setup-pnpm + + - uses: actions/setup-node@v6 + with: + node-version: ${{ env.PRIMARY_NODE_VERSION }} + + - name: Configure pnpm store path + id: pnpm-store + run: | + store_root="$HOME/.local/share/pnpm/store" + echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV" + store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent) + echo "path=$store_path" >> "$GITHUB_OUTPUT" + + - uses: actions/cache/restore@v4 + with: + path: ${{ steps.pnpm-store.outputs.path }} + key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }} + restore-keys: | + ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm- + + - name: Install (immutable) + run: pnpm install --frozen-lockfile + + - name: Verify dependency policy + run: pnpm run verify-package-dependencies + + - name: Verify npm install layout + run: pnpm run verify-npm-install-layout + pack: name: Pack npm tarballs runs-on: ubuntu-24.04 diff --git a/package.json b/package.json index 2ec0a09049..f88f78a491 100644 --- a/package.json +++ b/package.json @@ -107,6 +107,7 @@ "verify-runtime-closure": "tsx scripts/verify-runtime-closure.ts", "verify-application-entrypoints": "tsx scripts/verify-application-entrypoints.ts", "verify-package-dependencies": "tsx scripts/verify-package-dependencies.ts", + "verify-npm-install-layout": "tsx scripts/verify-npm-install-layout.ts", "verify-client-packages": "tsx scripts/verify-client-packages.ts", "verify-client-ui-i18n": "tsx scripts/verify-client-ui-i18n.ts", "verify-vendored-links": "tsx scripts/verify-vendored-links.ts", diff --git a/scripts/benchmark-npm-resolution.spec.ts b/scripts/benchmark-npm-resolution.spec.ts index 92a6bdbfcb..e450614a44 100644 --- a/scripts/benchmark-npm-resolution.spec.ts +++ b/scripts/benchmark-npm-resolution.spec.ts @@ -7,6 +7,7 @@ import { buildRegistryIndex, parseBenchmarkOptions, publishWorkspaceRange, + resolveNpmPackageLock, type RegistryIndex, } from './benchmark-npm-resolution.ts' @@ -81,4 +82,26 @@ describe('npm resolution benchmark', () => { expect(result.archiveRequests).toBe(0) expect(result.unknownPackages).toEqual([]) }) + + it('returns npm placement for two aliased package versions without requesting archives', async () => { + const index: RegistryIndex = new Map([[ + '@deepseek-ai/dsh', + new Map([ + ['0.1.0', { name: '@deepseek-ai/dsh', version: '0.1.0' }], + ['0.2.0', { name: '@deepseek-ai/dsh', version: '0.2.0' }], + ]), + ]]) + + const result = await resolveNpmPackageLock(index, { + '@deepseek-ai/dsh': '0.2.0', + 'dsh-previous': 'npm:@deepseek-ai/dsh@0.1.0', + }, 10_000) + + expect(result.archiveRequests).toBe(0) + expect(result.packageLock.packages['node_modules/@deepseek-ai/dsh']?.version).toBe('0.2.0') + expect(result.packageLock.packages['node_modules/dsh-previous']).toMatchObject({ + name: '@deepseek-ai/dsh', + version: '0.1.0', + }) + }) }) diff --git a/scripts/benchmark-npm-resolution.ts b/scripts/benchmark-npm-resolution.ts index 57834d4f09..2e7ff71732 100644 --- a/scripts/benchmark-npm-resolution.ts +++ b/scripts/benchmark-npm-resolution.ts @@ -69,6 +69,27 @@ export interface BenchmarkRun { readonly unknownPackages: readonly string[] } +/** Published-package fields retained in npm's package-lock layout. */ +export interface NpmLockPackage { + readonly name?: string + readonly version?: string + readonly dependencies?: Readonly> + readonly optionalDependencies?: Readonly> + readonly peerDependencies?: Readonly> + readonly peerDependenciesMeta?: Readonly> +} + +/** The installed paths selected by npm without materializing package archives. */ +export interface NpmPackageLock { + readonly lockfileVersion: number + readonly packages: Readonly> +} + +/** npm resolution observations together with its computed install layout. */ +export interface NpmPackageLockResolution extends BenchmarkRun { + readonly packageLock: NpmPackageLock +} + /** Parse one positive-integer command-line option or use its default. */ export function parsePositiveIntegerOption(raw: string | undefined, fallback: number, name: string): number { if (raw === undefined) return fallback @@ -250,6 +271,19 @@ function npmExecutable(): string { return process.platform === 'win32' ? 'npm.cmd' : 'npm' } +function readNpmPackageLock(path: string): NpmPackageLock { + const parsed: unknown = JSON.parse(readFileSync(path, 'utf8')) + if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) { + throw new Error('npm produced an invalid package-lock.json') + } + const { lockfileVersion, packages } = parsed as Record + if (!Number.isSafeInteger(lockfileVersion) || packages === null + || typeof packages !== 'object' || Array.isArray(packages)) { + throw new Error('npm produced an invalid package-lock.json') + } + return parsed as NpmPackageLock +} + async function runNpm( cwd: string, registry: string, @@ -302,17 +336,17 @@ async function runNpm( } /** - * Resolve the CLI install graph once without downloading package archives. + * Ask npm to compute an install layout without downloading package archives. * @param index - Package metadata exposed through the local registry. - * @param targetVersion - Version of `@deepseek-ai/dsh` to install. + * @param dependencies - Root dependencies whose install layout npm computes. * @param timeoutMs - Hard wall-clock limit for the npm child process. - * @returns Timing and registry-request observations. + * @returns The package lock plus timing and registry-request observations. */ -export async function benchmarkNpmResolution( +export async function resolveNpmPackageLock( index: RegistryIndex, - targetVersion: string, + dependencies: Readonly>, timeoutMs: number, -): Promise { +): Promise { let registryRequests = 0 let archiveRequests = 0 const unknownPackages = new Set() @@ -357,7 +391,7 @@ export async function benchmarkNpmResolution( name: 'dsh-npm-resolution-benchmark', version: '0.0.0', private: true, - dependencies: { [TARGET_PACKAGE]: targetVersion }, + dependencies, }, null, 2)}\n`) const result = await runNpm(consumer, registry, timeoutMs) if (result.timedOut) throw new Error(`npm resolution exceeded ${String(timeoutMs)} ms`) @@ -366,6 +400,7 @@ export async function benchmarkNpmResolution( registryRequests, archiveRequests, unknownPackages: [...unknownPackages].sort(), + packageLock: readNpmPackageLock(join(consumer, 'package-lock.json')), } } finally { await close(server) @@ -373,6 +408,27 @@ export async function benchmarkNpmResolution( } } +/** + * Resolve the CLI install graph once without downloading package archives. + * @param index - Package metadata exposed through the local registry. + * @param targetVersion - Version of `@deepseek-ai/dsh` to install. + * @param timeoutMs - Hard wall-clock limit for the npm child process. + * @returns Timing and registry-request observations. + */ +export async function benchmarkNpmResolution( + index: RegistryIndex, + targetVersion: string, + timeoutMs: number, +): Promise { + const result = await resolveNpmPackageLock(index, { [TARGET_PACKAGE]: targetVersion }, timeoutMs) + return { + durationMs: result.durationMs, + registryRequests: result.registryRequests, + archiveRequests: result.archiveRequests, + unknownPackages: result.unknownPackages, + } +} + async function main(): Promise { const options = parseBenchmarkOptions(process.argv.slice(2)) const root = resolve(import.meta.dirname, '..') diff --git a/scripts/ci-workflow.spec.ts b/scripts/ci-workflow.spec.ts index 0a59f36ae7..fa9fc052f5 100644 --- a/scripts/ci-workflow.spec.ts +++ b/scripts/ci-workflow.spec.ts @@ -603,7 +603,7 @@ describe('npm release workflows', () => { for (const file of ['release.yml', 'release-vendor.yml']) { const workflow = loadWorkflow(`.github/workflows/${file}`) if (!isRecord(workflow.jobs)) throw new TypeError(`${file} must define jobs`) - expect(Object.keys(workflow.jobs).sort()).toEqual(['pack']) + expect(Object.keys(workflow.jobs).sort()).toEqual(file === 'release.yml' ? ['dependencies', 'pack'] : ['pack']) } // publication is workflow_dispatch-only (never a PR check) and keeps the @@ -618,6 +618,20 @@ describe('npm release workflows', () => { expect(publish.concurrency).toMatchObject({ group: 'Release-publish' }) } }) + + it('runs dependency policy and npm layout checks in the DSH release workflow', () => { + const workflow = loadWorkflow('.github/workflows/release.yml') + const dependencies = workflowJob(workflow, 'dependencies') + if (!isRecord(workflow.on) || !Array.isArray(dependencies.steps)) { + throw new TypeError('DSH release workflow must define triggers and dependency steps') + } + const commands = dependencies.steps.flatMap(step => + isRecord(step) && typeof step.run === 'string' ? [step.run] : []) + + expect(Object.keys(workflow.on).sort()).toEqual(['pull_request', 'push', 'workflow_dispatch']) + expect(commands).toContain('pnpm run verify-package-dependencies') + expect(commands).toContain('pnpm run verify-npm-install-layout') + }) }) describe('Documentation site publication', () => { diff --git a/scripts/verify-npm-install-layout.spec.ts b/scripts/verify-npm-install-layout.spec.ts new file mode 100644 index 0000000000..3c36c9bdd7 --- /dev/null +++ b/scripts/verify-npm-install-layout.spec.ts @@ -0,0 +1,102 @@ +import { describe, expect, it } from 'vitest' +import type { NpmPackageLock, RegistryIndex } from './benchmark-npm-resolution.ts' +import { + assertDualDshInstallLayout, + buildDualDshRegistry, +} from './verify-npm-install-layout.ts' + +function validLayout(): NpmPackageLock { + return { + lockfileVersion: 3, + packages: { + '': { dependencies: { '@deepseek-ai/dsh': '0.2.0', 'dsh-previous': 'npm:@deepseek-ai/dsh@0.1.0' } }, + 'node_modules/@deepseek-ai/cordis': { version: '4.0.1' }, + 'node_modules/@deepseek-ai/dsh': { + version: '0.2.0', + dependencies: { '@deepseek-ai/dsh-child': '^0.2.0' }, + peerDependencies: { '@deepseek-ai/cordis': '^4.0.1' }, + }, + 'node_modules/@deepseek-ai/dsh-child': { + version: '0.2.0', + dependencies: { '@deepseek-ai/dsh-leaf': '^0.2.0' }, + }, + 'node_modules/@deepseek-ai/dsh-leaf': { version: '0.2.0' }, + 'node_modules/dsh-previous': { + name: '@deepseek-ai/dsh', + version: '0.1.0', + dependencies: { '@deepseek-ai/dsh-child': '^0.1.0' }, + peerDependencies: { '@deepseek-ai/cordis': '^4.0.1' }, + }, + 'node_modules/dsh-previous/node_modules/@deepseek-ai/dsh-child': { + version: '0.1.0', + dependencies: { '@deepseek-ai/dsh-leaf': '^0.1.0' }, + }, + 'node_modules/dsh-previous/node_modules/@deepseek-ai/dsh-leaf': { version: '0.1.0' }, + }, + } +} + +describe('npm install layout verifier', () => { + it('creates two incompatible versions of every DSH package', () => { + const index: RegistryIndex = new Map([ + ['@deepseek-ai/dsh', new Map([['0.1.1-rc.2', { + name: '@deepseek-ai/dsh', + version: '0.1.1-rc.2', + dependencies: { '@deepseek-ai/dsh-child': '^0.1.1-rc.2' }, + peerDependencies: { '@deepseek-ai/cordis': '^4.0.1' }, + }]])], + ['@deepseek-ai/dsh-child', new Map([['0.1.1-rc.2', { + name: '@deepseek-ai/dsh-child', + version: '0.1.1-rc.2', + }]])], + ['@deepseek-ai/cordis', new Map([['4.0.1', { + name: '@deepseek-ai/cordis', + version: '4.0.1', + }]])], + ]) + + const dual = buildDualDshRegistry(index, '0.1.1-rc.2') + + expect([...dual.get('@deepseek-ai/dsh')?.keys() ?? []]).toEqual(['0.1.0', '0.2.0']) + expect(dual.get('@deepseek-ai/dsh')?.get('0.1.0')).toMatchObject({ + version: '0.1.0', + dependencies: { '@deepseek-ai/dsh-child': '^0.1.0' }, + peerDependencies: { '@deepseek-ai/cordis': '^4.0.1' }, + }) + expect(dual.get('@deepseek-ai/dsh')?.get('0.2.0')).toMatchObject({ + version: '0.2.0', + dependencies: { '@deepseek-ai/dsh-child': '^0.2.0' }, + }) + expect(dual.get('@deepseek-ai/cordis')).toBe(index.get('@deepseek-ai/cordis')) + }) + + it('accepts isolated DSH releases with one shared Cordis installation', () => { + expect(assertDualDshInstallLayout(validLayout())).toEqual({ + dshPackagesPerVersion: 3, + checkedDshEdges: 4, + }) + }) + + it('rejects an internal edge that crosses release versions', () => { + const layout = validLayout() + const packages = { ...layout.packages } + Reflect.deleteProperty(packages, 'node_modules/dsh-previous/node_modules/@deepseek-ai/dsh-leaf') + + expect(() => assertDualDshInstallLayout({ ...layout, packages })).toThrow( + 'node_modules/dsh-previous/node_modules/@deepseek-ai/dsh-child: dependencies ' + + '@deepseek-ai/dsh-leaf resolves to node_modules/@deepseek-ai/dsh-leaf@0.2.0, expected 0.1.0', + ) + }) + + it('rejects a second Cordis installation', () => { + const layout = validLayout() + const packages = { + ...layout.packages, + 'node_modules/dsh-previous/node_modules/@deepseek-ai/cordis': { version: '4.0.1' }, + } + + expect(() => assertDualDshInstallLayout({ ...layout, packages })).toThrow( + 'expected one shared @deepseek-ai/cordis', + ) + }) +}) diff --git a/scripts/verify-npm-install-layout.ts b/scripts/verify-npm-install-layout.ts new file mode 100644 index 0000000000..9a125ea864 --- /dev/null +++ b/scripts/verify-npm-install-layout.ts @@ -0,0 +1,217 @@ +/** Verify npm's physical package placement for two incompatible DSH releases. */ + +import { readFileSync } from 'node:fs' +import { posix, resolve } from 'node:path' +import { + buildRegistryIndex, + resolveNpmPackageLock, + type NpmLockPackage, + type NpmPackageLock, + type RegistryIndex, +} from './benchmark-npm-resolution.ts' + +const DSH_PACKAGE = '@deepseek-ai/dsh' +const CORDIS_PACKAGE = '@deepseek-ai/cordis' +const NESTED_DSH_ALIAS = 'dsh-previous' +const NESTED_DSH_PATH = `node_modules/${NESTED_DSH_ALIAS}` +const DEPENDENCY_FIELDS = ['dependencies', 'optionalDependencies', 'peerDependencies'] as const +const TIMEOUT_MS = 300_000 + +/** Synthetic incompatible versions used to expose cross-release placement errors. */ +export const SYNTHETIC_DSH_VERSIONS = ['0.1.0', '0.2.0'] as const + +interface MutableRegistryManifest { + name: string + version: string + dependencies?: Record + optionalDependencies?: Record + peerDependencies?: Record + [key: string]: unknown +} + +/** Summary of a verified two-release npm layout. */ +export interface DshInstallLayoutSummary { + readonly dshPackagesPerVersion: number + readonly checkedDshEdges: number +} + +function isDshPackage(name: string): boolean { + return name === DSH_PACKAGE || name.startsWith(`${DSH_PACKAGE}-`) +} + +function cloneForVersion(manifest: object, version: string): MutableRegistryManifest { + const cloned = structuredClone(manifest) as MutableRegistryManifest + cloned.version = version + for (const field of DEPENDENCY_FIELDS) { + const dependencies = cloned[field] + if (dependencies === undefined) continue + for (const name of Object.keys(dependencies)) { + if (isDshPackage(name)) dependencies[name] = `^${version}` + } + } + return cloned +} + +/** + * Replace the working release with two incompatible, internally consistent DSH releases. + * @param index - Registry metadata containing the working release. + * @param sourceVersion - Workspace version copied into each synthetic release. + * @returns Registry metadata containing both synthetic DSH releases and unchanged external packages. + */ +export function buildDualDshRegistry(index: RegistryIndex, sourceVersion: string): RegistryIndex { + const output = new Map(index) + let dshPackages = 0 + for (const [name, versions] of index) { + if (!isDshPackage(name)) { + output.set(name, versions) + continue + } + const source = versions.get(sourceVersion) + if (source === undefined) throw new Error(`${name} has no workspace version ${sourceVersion}`) + dshPackages++ + output.set(name, new Map(SYNTHETIC_DSH_VERSIONS.map(version => [ + version, + cloneForVersion(source, version), + ]))) + } + if (dshPackages === 0) throw new Error('registry contains no DSH packages') + return output +} + +function packageNameAtPath(path: string, manifest: NpmLockPackage): string | undefined { + if (manifest.name !== undefined) return manifest.name + const marker = 'node_modules/' + const markerIndex = path.lastIndexOf(marker) + if (markerIndex < 0) return undefined + const segments = path.slice(markerIndex + marker.length).split('/') + if (segments[0]?.startsWith('@')) { + return segments[1] === undefined ? undefined : `${segments[0]}/${segments[1]}` + } + return segments[0] +} + +function resolvePackagePath( + packages: Readonly>, + sourcePath: string, + dependency: string, +): string | undefined { + let directory = sourcePath + while (directory !== '.') { + const candidate = posix.join(directory, 'node_modules', dependency) + if (packages[candidate] !== undefined) return candidate + directory = posix.dirname(directory) + } + const rootCandidate = posix.join('node_modules', dependency) + return packages[rootCandidate] === undefined ? undefined : rootCandidate +} + +function setDifference(left: ReadonlySet, right: ReadonlySet): string[] { + return [...left].filter(value => !right.has(value)).sort() +} + +/** + * Assert that npm isolates both DSH releases while sharing the Cordis runtime. + * @param packageLock - Metadata-only package lock produced by npm. + * @returns Counts for the verified DSH packages and dependency edges. + */ +export function assertDualDshInstallLayout(packageLock: NpmPackageLock): DshInstallLayoutSummary { + const [nestedVersion, rootVersion] = SYNTHETIC_DSH_VERSIONS + const errors: string[] = [] + const namesByVersion = new Map>([ + [nestedVersion, new Set()], + [rootVersion, new Set()], + ]) + const installed = Object.entries(packageLock.packages) + let checkedDshEdges = 0 + + for (const [path, manifest] of installed) { + const name = packageNameAtPath(path, manifest) + if (name === undefined || !isDshPackage(name)) continue + const version = manifest.version + if (version !== nestedVersion && version !== rootVersion) { + errors.push(`${path}: expected DSH version ${nestedVersion} or ${rootVersion}, got ${String(version)}`) + continue + } + namesByVersion.get(version)?.add(name) + const expectedPath = version === rootVersion + ? `node_modules/${name}` + : name === DSH_PACKAGE + ? NESTED_DSH_PATH + : `${NESTED_DSH_PATH}/node_modules/${name}` + if (path !== expectedPath) { + errors.push(`${path}: expected ${name}@${version} at ${expectedPath}`) + } + + for (const field of DEPENDENCY_FIELDS) { + for (const dependency of Object.keys(manifest[field] ?? {})) { + if (!isDshPackage(dependency)) continue + const targetPath = resolvePackagePath(packageLock.packages, path, dependency) + const optionalPeer = field === 'peerDependencies' + && manifest.peerDependenciesMeta?.[dependency]?.optional === true + if (targetPath === undefined) { + if (field === 'optionalDependencies' || optionalPeer) continue + errors.push(`${path}: ${field} ${dependency} does not resolve`) + continue + } + checkedDshEdges++ + const targetVersion = packageLock.packages[targetPath]?.version + if (targetVersion !== version) { + errors.push( + `${path}: ${field} ${dependency} resolves to ${targetPath}@${String(targetVersion)}, expected ${version}`, + ) + } + } + } + } + + const nestedNames = namesByVersion.get(nestedVersion) ?? new Set() + const rootNames = namesByVersion.get(rootVersion) ?? new Set() + if (!nestedNames.has(DSH_PACKAGE)) errors.push(`${NESTED_DSH_PATH}: missing ${DSH_PACKAGE}@${nestedVersion}`) + if (!rootNames.has(DSH_PACKAGE)) errors.push(`node_modules/${DSH_PACKAGE}: missing ${DSH_PACKAGE}@${rootVersion}`) + const onlyNested = setDifference(nestedNames, rootNames) + const onlyRoot = setDifference(rootNames, nestedNames) + if (onlyNested.length > 0) errors.push(`only ${nestedVersion} contains: ${onlyNested.join(', ')}`) + if (onlyRoot.length > 0) errors.push(`only ${rootVersion} contains: ${onlyRoot.join(', ')}`) + + const cordisPaths = installed.flatMap(([path, manifest]) => + packageNameAtPath(path, manifest) === CORDIS_PACKAGE ? [path] : []) + if (cordisPaths.length !== 1 || cordisPaths[0] !== `node_modules/${CORDIS_PACKAGE}`) { + errors.push(`expected one shared ${CORDIS_PACKAGE} at node_modules/${CORDIS_PACKAGE}, got ${cordisPaths.join(', ')}`) + } + + if (errors.length > 0) throw new Error(`invalid npm install layout:\n${errors.map(error => ` - ${error}`).join('\n')}`) + return { dshPackagesPerVersion: rootNames.size, checkedDshEdges } +} + +function workspaceVersion(root: string): string { + const manifest = JSON.parse(readFileSync(resolve(root, 'apps/cli/package.json'), 'utf8')) as { version?: unknown } + if (typeof manifest.version !== 'string') throw new Error('apps/cli/package.json has no string version') + return manifest.version +} + +async function main(): Promise { + const root = resolve(import.meta.dirname, '..') + const index = buildDualDshRegistry(buildRegistryIndex(root), workspaceVersion(root)) + const [nestedVersion, rootVersion] = SYNTHETIC_DSH_VERSIONS + const result = await resolveNpmPackageLock(index, { + [DSH_PACKAGE]: rootVersion, + [NESTED_DSH_ALIAS]: `npm:${DSH_PACKAGE}@${nestedVersion}`, + }, TIMEOUT_MS) + if (result.archiveRequests !== 0) throw new Error(`npm requested ${String(result.archiveRequests)} package archive(s)`) + const summary = assertDualDshInstallLayout(result.packageLock) + console.log( + `verify-npm-install-layout: ${String(summary.dshPackagesPerVersion)} DSH package(s) per release and ` + + `${String(summary.checkedDshEdges)} internal edge(s) verified in ${(result.durationMs / 1000).toFixed(2)} s; ` + + `both releases share one Cordis installation; ${String(result.unknownPackages.length)} unavailable optional ` + + 'package name(s) ignored by npm.', + ) +} + +if (import.meta.main) { + try { + await main() + } catch (error) { + console.error(`verify-npm-install-layout: ${error instanceof Error ? error.message : String(error)}`) + process.exitCode = 1 + } +} From 9162bc69bd9c1e681ef4266a394e133ef31c78ae Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 27 Aug 2026 02:03:00 +0800 Subject: [PATCH 31/63] fix(release): harden dependency verification --- ...08-26-published-dependency-faces.i18n.yaml | 4 +- .../2026-08-26-published-dependency-faces.md | 6 +- ...026-08-26-published-dependency-faces.zh.md | 6 +- .../benchmark-next-package-dependency.spec.ts | 1 + scripts/benchmark-npm-resolution.spec.ts | 75 ++++++++++ scripts/benchmark-npm-resolution.ts | 138 ++++++++++++++---- scripts/package-dependency-policy.ts | 6 +- scripts/verify-package-dependencies.spec.ts | 75 +++++++++- scripts/verify-package-dependencies.ts | 29 ++-- 9 files changed, 287 insertions(+), 53 deletions(-) diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml index e09edf4f86..3604d6fe6a 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.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-26-published-dependency-faces.md -2026-08-26-published-dependency-faces.md: aa7714e5c83aaf1c68ef300bdb10006e534bf88d -2026-08-26-published-dependency-faces.zh.md: e0ba33ff25651d1adf378af87fd6065ed9e54d03 +2026-08-26-published-dependency-faces.md: 668d4c721446a87388ae50951156d1b24f91138c +2026-08-26-published-dependency-faces.zh.md: b10a285a81490f8eb66d70d3e73c2f676ad1b35c diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md index aa7714e5c8..668d4c7214 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.md @@ -26,11 +26,11 @@ Every covered package keeps `@deepseek-ai/cordis` in matching `peerDependencies` A workspace package reached by a runtime value import from the Host entry closure belongs only in `dependencies` when every imported runtime export appears in the policy's `safeHostDependencyExports` table. An export whose constructor identity or module state must be shared appears in `peerRequiredHostExports`; importing one such export keeps the whole package edge in matching `peerDependencies` and `devDependencies`. Each table key is an exact module specifier and each value is a reviewed export set. The verifier follows runtime local imports from the Host entry, records named and default imports and re-exports, and rejects exports present in neither table; namespace, dynamic, and side-effect imports remain unbounded and cannot enter either table. -Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Existing third-party dependencies outside these managed relationships keep their declared section. Workspace references use `workspace:^`. +Workspace imports used by the Client bundle, type-only imports, module augmentations, `dsh.client.inject`, invariant companions, and existing metadata-only peers belong only in `devDependencies`. Ordinary third-party packages imported by the Host runtime belong in `dependencies`; other third-party relationships keep their declared section. Workspace references use `workspace:^`. Some development relationships exist only in `dsh.client.inject` or TypeScript project references. The policy's `configurationOnlyDevDependencies` table names only those reviewed edges and keeps them in `devDependencies`. -The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. An unclassified Host runtime export is a policy violation that blocks all `--fix` writes; a maintainer must review the export and classify it, change the source relationship, or change the package selection. Once source safety passes, `--fix` performs only the section and range changes implied by the classification and removes stale peer metadata. +The verifier reads source manifests and source files, so it runs on a clean tree without built `lib/`. Every selected Host face must have `src/index.ts`. An unclassified Host runtime export is a policy violation that blocks all `--fix` writes; a maintainer must review the export and classify it, change the source relationship, or change the package selection. Once source safety passes, `--fix` performs only the section and range changes implied by the classification and removes stale peer metadata. ### Maintainer workflow @@ -49,7 +49,7 @@ pnpm run verify-package-dependencies -- --fix git diff -- packages pnpm-lock.yaml docs/module-graph.md docs/module-graph.zh.md docs/module-graph.i18n.yaml ``` -Measure the working-tree graph and a Git ref through the local metadata-only registry. Each run creates a fresh consumer and npm cache, executes `npm install --package-lock-only`, rejects archive downloads, and leaves the repository unchanged. `--runs` controls repetitions, `--timeout-ms` bounds each run, and optional `--max-ms` makes the command fail when the slowest run exceeds a threshold. +Measure the working-tree graph and a Git ref through the local metadata-only registry. Each run creates a fresh consumer and npm cache, replaces inherited npm configuration with explicit peer, hoisting, and registry settings, executes `npm install --package-lock-only`, rejects archive downloads, and leaves the repository unchanged. `--runs` controls repetitions, `--timeout-ms` terminates the npm process tree after its deadline, and optional `--max-ms` makes the command fail when the slowest run exceeds a threshold. ```sh pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000 diff --git a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md index e0ba33ff25..b10a285a81 100644 --- a/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md +++ b/.agents/notes/implemented/process/2026-08-26-published-dependency-faces.zh.md @@ -26,11 +26,11 @@ Host-only 包通过另一份显式列表加入同一策略。该列表包含 `@d Host 入口闭包中的运行期 value import 所到达的 workspace 包，只有在每个运行期导出都列入策略的 `safeHostDependencyExports` 表时才只属于 `dependencies`。constructor 身份或模块状态必须共享的导出列入 `peerRequiredHostExports`；一旦使用这类导出，整条包依赖边就保留在范围一致的 `peerDependencies` 与 `devDependencies` 中。表的每个 key 都是精确 module specifier，每个 value 都是经审查的导出集合。验证器从 Host 入口沿运行期本地 import 扫描，记录具名与默认 import 和 re-export，并拒绝两个表都未收录的导出；namespace、dynamic 和 side-effect import 无法限定导出范围，因此不能进入任一表。 -Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。不属于这些受管关系的现有第三方 dependency 保持原区段。Workspace 引用使用 `workspace:^`。 +Client bundle 使用的 workspace import、纯类型 import、模块扩充、`dsh.client.inject`、invariant companion 和仅有元数据的现存 peer 只属于 `devDependencies`。Host 运行时导入的普通第三方包属于 `dependencies`；其他第三方关系保持原区段。Workspace 引用使用 `workspace:^`。 部分开发期关系只存在于 `dsh.client.inject` 或 TypeScript project reference 中。策略的 `configurationOnlyDevDependencies` 表只列出这些已评审的依赖边，并将它们保留在 `devDependencies` 中。 -验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。未分类的 Host 运行期导出属于策略违规，会阻止 `--fix` 的全部写入；维护者必须审查该导出，并选择分类该导出、修改源码关系或修改选包范围。源码安全检查通过后，`--fix` 只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 +验证器读取源码 manifest 和源码文件，因此可以在没有已构建 `lib/` 的干净工作树上运行。每个被选中的 Host face 都必须存在 `src/index.ts`。未分类的 Host 运行期导出属于策略违规，会阻止 `--fix` 的全部写入；维护者必须审查该导出，并选择分类该导出、修改源码关系或修改选包范围。源码安全检查通过后，`--fix` 只执行分类所确定的区段与范围变更，并删除失效的 peer 元数据。 ### 维护流程 @@ -49,7 +49,7 @@ pnpm run verify-package-dependencies -- --fix git diff -- packages pnpm-lock.yaml docs/module-graph.md docs/module-graph.zh.md docs/module-graph.i18n.yaml ``` -通过仅 metadata 的本地 registry 测量工作树依赖图与 Git ref。每轮都会创建全新 consumer 与 npm cache，执行 `npm install --package-lock-only`，拒绝下载包归档，并保持仓库不变。`--runs` 控制重复次数，`--timeout-ms` 限制单轮耗时，可选 `--max-ms` 会在最慢一轮超过阈值时让命令失败。 +通过仅 metadata 的本地 registry 测量工作树依赖图与 Git ref。每轮都会创建全新 consumer 与 npm cache，用明确的 peer、hoisting 和 registry 设置替换继承的 npm 配置，执行 `npm install --package-lock-only`，拒绝下载包归档，并保持仓库不变。`--runs` 控制重复次数，`--timeout-ms` 会在期限到达后终止 npm 进程树，可选 `--max-ms` 会在最慢一轮超过阈值时让命令失败。 ```sh pnpm run benchmark:npm-resolution -- --runs=5 --timeout-ms=300000 diff --git a/scripts/benchmark-next-package-dependency.spec.ts b/scripts/benchmark-next-package-dependency.spec.ts index 2a0ee10189..489b72c3cf 100644 --- a/scripts/benchmark-next-package-dependency.spec.ts +++ b/scripts/benchmark-next-package-dependency.spec.ts @@ -73,6 +73,7 @@ describe('next package benchmark graph', () => { sourceLine: "import { runtimeValue } from '@f/runtime'", }], peerRequiredHostDependencies: new Set(), + configurationOnlyDevDependencies: new Set(), clientInject: new Set(), } const index = new Map>([ diff --git a/scripts/benchmark-npm-resolution.spec.ts b/scripts/benchmark-npm-resolution.spec.ts index e450614a44..7511cb34c5 100644 --- a/scripts/benchmark-npm-resolution.spec.ts +++ b/scripts/benchmark-npm-resolution.spec.ts @@ -8,6 +8,7 @@ import { parseBenchmarkOptions, publishWorkspaceRange, resolveNpmPackageLock, + runCommandWithTimeout, type RegistryIndex, } from './benchmark-npm-resolution.ts' @@ -104,4 +105,78 @@ describe('npm resolution benchmark', () => { version: '0.1.0', }) }) + + it('isolates peer resolution from inherited npm configuration', async () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-hostile-npm-config-')) + roots.push(root) + const userConfig = join(root, 'user.npmrc') + writeFileSync(userConfig, '@deepseek-ai:registry=http://127.0.0.1:1/\nlegacy-peer-deps=true\nomit=peer\n') + const previous = { + userConfig: process.env.npm_config_userconfig, + legacyPeerDeps: process.env.npm_config_legacy_peer_deps, + omit: process.env.npm_config_omit, + } + process.env.npm_config_userconfig = userConfig + process.env.npm_config_legacy_peer_deps = 'true' + process.env.npm_config_omit = 'peer' + try { + const index: RegistryIndex = new Map([ + ['@deepseek-ai/dsh', new Map([['0.1.0', { + name: '@deepseek-ai/dsh', + version: '0.1.0', + peerDependencies: { '@deepseek-ai/dsh-peer': '1.0.0' }, + }]])], + ['@deepseek-ai/dsh-peer', new Map([['1.0.0', { + name: '@deepseek-ai/dsh-peer', + version: '1.0.0', + }]])], + ]) + + const result = await resolveNpmPackageLock(index, { '@deepseek-ai/dsh': '0.1.0' }, 10_000) + + expect(result.archiveRequests).toBe(0) + expect(result.packageLock.packages['node_modules/@deepseek-ai/dsh-peer']?.version).toBe('1.0.0') + } finally { + if (previous.userConfig === undefined) delete process.env.npm_config_userconfig + else process.env.npm_config_userconfig = previous.userConfig + if (previous.legacyPeerDeps === undefined) delete process.env.npm_config_legacy_peer_deps + else process.env.npm_config_legacy_peer_deps = previous.legacyPeerDeps + if (previous.omit === undefined) delete process.env.npm_config_omit + else process.env.npm_config_omit = previous.omit + } + }) + + it.skipIf(process.platform === 'win32')('force-kills a timed-out process tree', async () => { + const source = [ + "const { spawn } = require('node:child_process')", + "process.on('SIGTERM', () => {})", + 'const child = spawn(process.execPath, [\'-e\', "process.on(\'SIGTERM\', () => {}); setInterval(() => {}, 1000)"], { stdio: \'ignore\' })', + 'console.log(child.pid)', + 'setInterval(() => {}, 1000)', + ].join(';') + let descendantPid: number | undefined + try { + const result = await runCommandWithTimeout(process.execPath, ['-e', source], { + cwd: process.cwd(), + env: process.env, + timeoutMs: 1_000, + terminationGraceMs: 100, + }) + const reportedPid = Number.parseInt(result.output.trim(), 10) + if (!Number.isSafeInteger(reportedPid)) throw new Error(`child reported invalid pid ${result.output.trim()}`) + descendantPid = reportedPid + + expect(result.timedOut).toBe(true) + expect(result.signal).toBe('SIGKILL') + expect(() => { process.kill(reportedPid, 0) }).toThrow() + } finally { + if (descendantPid !== undefined && Number.isSafeInteger(descendantPid)) { + try { + process.kill(descendantPid, 'SIGKILL') + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error + } + } + } + }) }) diff --git a/scripts/benchmark-npm-resolution.ts b/scripts/benchmark-npm-resolution.ts index 2e7ff71732..b8089117ad 100644 --- a/scripts/benchmark-npm-resolution.ts +++ b/scripts/benchmark-npm-resolution.ts @@ -1,6 +1,6 @@ /** Benchmark npm's dependency-tree resolution against an all-local registry. */ -import { execFileSync, spawn } from 'node:child_process' +import { execFileSync, spawn, spawnSync, type ChildProcess } from 'node:child_process' import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs' import { createServer, type Server } from 'node:http' import { tmpdir } from 'node:os' @@ -10,6 +10,8 @@ import { parseArgs } from 'node:util' const TARGET_PACKAGE = '@deepseek-ai/dsh' const DEFAULT_TIMEOUT_MS = 300_000 +const TERMINATION_GRACE_MS = 1_000 +const FORCED_EXIT_TIMEOUT_MS = 5_000 const WORKSPACE_MANIFEST_GLOBS = [ 'apps/*/package.json', 'packages/*/*/package.json', @@ -271,6 +273,92 @@ function npmExecutable(): string { return process.platform === 'win32' ? 'npm.cmd' : 'npm' } +function delay(ms: number): Promise { + return new Promise(resolveDelay => setTimeout(resolveDelay, ms)) +} + +function signalProcessTree(child: ChildProcess, signal: 'SIGTERM' | 'SIGKILL'): void { + if (child.pid === undefined) { + child.kill(signal) + return + } + if (process.platform === 'win32') { + const force = signal === 'SIGKILL' ? ['/F'] : [] + const result = spawnSync('taskkill', ['/PID', String(child.pid), '/T', ...force], { + stdio: 'ignore', + windowsHide: true, + }) + if (result.error !== undefined) throw result.error + if (result.status !== 0 && child.exitCode === null && child.signalCode === null) child.kill(signal) + return + } + try { + process.kill(-child.pid, signal) + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error + } +} + +/** + * Run one command with bounded process-tree termination after its deadline. + * @param command - Executable path or name. + * @param args - Arguments passed without shell interpolation on POSIX. + * @param options - Working directory, environment, timeout, and termination grace. + * @returns Exit facts, captured output, duration, and whether timeout handling began. + */ +export async function runCommandWithTimeout( + command: string, + args: readonly string[], + options: { + readonly cwd: string + readonly env: NodeJS.ProcessEnv + readonly timeoutMs: number + readonly terminationGraceMs?: number + }, +): Promise<{ status: number | null; signal: NodeJS.Signals | null; durationMs: number; output: string; timedOut: boolean }> { + const started = performance.now() + const child = spawn(command, [...args], { + cwd: options.cwd, + detached: process.platform !== 'win32', + env: options.env, + shell: process.platform === 'win32', + stdio: ['ignore', 'pipe', 'pipe'], + }) + let output = '' + child.stdout.setEncoding('utf8') + child.stderr.setEncoding('utf8') + child.stdout.on('data', (chunk) => { output += String(chunk) }) + child.stderr.on('data', (chunk) => { output += String(chunk) }) + const exited = new Promise<{ status: number | null; signal: NodeJS.Signals | null }>((resolveExit, reject) => { + child.once('error', reject) + child.once('close', (status, signal) => { resolveExit({ status, signal }) }) + }) + let timeout: NodeJS.Timeout | undefined + try { + const first = await Promise.race([ + exited.then(outcome => ({ type: 'exit' as const, outcome })), + new Promise<{ type: 'timeout' }>((resolveTimeout) => { + timeout = setTimeout(() => { resolveTimeout({ type: 'timeout' }) }, options.timeoutMs) + }), + ]) + if (first.type === 'exit') { + return { ...first.outcome, durationMs: performance.now() - started, output, timedOut: false } + } + + signalProcessTree(child, 'SIGTERM') + await delay(options.terminationGraceMs ?? TERMINATION_GRACE_MS) + signalProcessTree(child, 'SIGKILL') + const forced = await Promise.race([ + exited, + delay(FORCED_EXIT_TIMEOUT_MS).then(() => undefined), + ]) + if (forced === undefined) throw new Error('timed-out process tree did not exit after SIGKILL') + return { ...forced, durationMs: performance.now() - started, output, timedOut: true } + } finally { + if (timeout !== undefined) clearTimeout(timeout) + } +} + function readNpmPackageLock(path: string): NpmPackageLock { const parsed: unknown = JSON.parse(readFileSync(path, 'utf8')) if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) { @@ -289,50 +377,39 @@ async function runNpm( registry: string, timeoutMs: number, ): Promise<{ durationMs: number; output: string; timedOut: boolean }> { - const started = performance.now() - const child = spawn(npmExecutable(), [ + const npmrc = join(cwd, '.npmrc') + const globalNpmrc = join(cwd, '.npmrc-global') + writeFileSync(npmrc, `registry=${registry}\n@deepseek-ai:registry=${registry}\n`) + writeFileSync(globalNpmrc, '') + const inheritedEnvironment = Object.fromEntries(Object.entries(process.env) + .filter(([name]) => !name.toLowerCase().startsWith('npm_config_'))) + const result = await runCommandWithTimeout(npmExecutable(), [ 'install', '--package-lock-only', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error', + '--include=peer', + '--install-strategy=hoisted', + '--legacy-peer-deps=false', `--registry=${registry}`, ], { cwd, - // Windows resolves npm through a .cmd shim, which spawn() refuses - // without a shell since the CVE-2024-27980 hardening. - shell: process.platform === 'win32', env: { - ...process.env, + ...inheritedEnvironment, npm_config_cache: join(cwd, '.npm-cache'), + npm_config_globalconfig: globalNpmrc, + npm_config_userconfig: npmrc, npm_config_update_notifier: 'false', }, - stdio: ['ignore', 'pipe', 'pipe'], + timeoutMs, }) - let output = '' - child.stdout.setEncoding('utf8') - child.stderr.setEncoding('utf8') - child.stdout.on('data', (chunk) => { output += String(chunk) }) - child.stderr.on('data', (chunk) => { output += String(chunk) }) - const outcome = await new Promise<{ status: number | null; timedOut: boolean }>((resolveExit, reject) => { - let timeoutReached = false - const timer = setTimeout(() => { - timeoutReached = true - child.kill('SIGTERM') - }, timeoutMs) - child.once('error', reject) - child.once('exit', (status) => { - clearTimeout(timer) - resolveExit({ status, timedOut: timeoutReached }) - }) - }) - const durationMs = performance.now() - started - if (outcome.timedOut) return { durationMs, output, timedOut: true } - if (outcome.status !== 0) { - throw new Error(`npm install exited ${String(outcome.status)} after ${durationMs.toFixed(0)} ms\n${output.trim()}`) + if (result.timedOut) return result + if (result.status !== 0) { + throw new Error(`npm install exited ${String(result.status)} after ${result.durationMs.toFixed(0)} ms\n${result.output.trim()}`) } - return { durationMs, output, timedOut: false } + return result } /** @@ -403,6 +480,7 @@ export async function resolveNpmPackageLock( packageLock: readNpmPackageLock(join(consumer, 'package-lock.json')), } } finally { + server.closeAllConnections() await close(server) rmSync(consumer, { recursive: true, force: true }) } diff --git a/scripts/package-dependency-policy.ts b/scripts/package-dependency-policy.ts index 2d8f7eb56c..50ed98bd17 100644 --- a/scripts/package-dependency-policy.ts +++ b/scripts/package-dependency-policy.ts @@ -35,14 +35,14 @@ const CONFIGURATION_ONLY_DEV_DEPENDENCIES = { const SAFE_HOST_DEPENDENCY_EXPORTS = { '@deepseek-ai/dsh-api-session-controller/remote-events': ['SESSION_CONTROLLER_REMOTE_EVENTS'], '@deepseek-ai/dsh-credentials': ['credentialKey'], - '@deepseek-ai/dsh-host-apiproxy': ['toFetchHandler'], - '@deepseek-ai/dsh-host-apiproxy/api': ['RpcId', 'clientRequestSchema'], '@deepseek-ai/dsh-llm': ['MessageId', 'callConfigEquals', 'deepFreeze', 'freezeMessage'], '@deepseek-ai/dsh-llm/brand': ['ToolCallId'], '@deepseek-ai/dsh-session': ['isJsonValue'], + '@deepseek-ai/dsh-session/types': ['SessionId'], '@deepseek-ai/dsh-settings': ['settingsNamespace'], '@deepseek-ai/dsh-system-prompt': ['FIRST_PARTY_SECTION_ORDER'], '@deepseek-ai/dsh-timeout': ['MAX_TIMER_DELAY_MS'], + '@deepseek-ai/dsh-typert-protocol': ['RemoteError', 'remoteErrorOf'], '@deepseek-ai/dsh-util-crypto': ['randomUUID'], '@deepseek-ai/schemastery': ['default'], } as const satisfies HostDependencyExports @@ -50,7 +50,7 @@ const SAFE_HOST_DEPENDENCY_EXPORTS = { /** Runtime exports that require every consumer to resolve the provider's shared peer instance. */ const PEER_REQUIRED_HOST_EXPORTS = { '@deepseek-ai/dsh-scope': ['carrierKeyOf', 'scopeOf', 'scopeTarget'], - '@deepseek-ai/dsh-typert-protocol': ['TypertLookupFailure', 'TypertRemoteFailure', 'remoteMethods'], + '@deepseek-ai/dsh-typert-protocol': ['Remote', 'TypertRemoteService', 'remoteMethods'], } as const satisfies HostDependencyExports /** Exact import specifier to reviewed runtime exports. */ diff --git a/scripts/verify-package-dependencies.spec.ts b/scripts/verify-package-dependencies.spec.ts index ad4752f9a7..a59e88a215 100644 --- a/scripts/verify-package-dependencies.spec.ts +++ b/scripts/verify-package-dependencies.spec.ts @@ -82,6 +82,7 @@ function facts(manifest: PackageDependencyManifest): PackageDependencyFacts { sourceLine: "import { runtimeValue } from '@deepseek-ai/dsh-runtime'", }], peerRequiredHostDependencies: new Set(), + configurationOnlyDevDependencies: new Set(), clientInject: new Set(), } } @@ -109,11 +110,17 @@ describe('package dependency scope', () => { '@deepseek-ai/dsh-client-ui-tool': ['@deepseek-ai/dsh-api-remotes'], }) expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/schemastery']).toEqual(['default']) + expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/dsh-session/types']).toEqual([ + 'SessionId', + ]) + expect(PACKAGE_DEPENDENCY_POLICY.safeHostDependencyExports['@deepseek-ai/dsh-typert-protocol']).toEqual([ + 'RemoteError', 'remoteErrorOf', + ]) expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-scope']).toEqual([ 'carrierKeyOf', 'scopeOf', 'scopeTarget', ]) expect(PACKAGE_DEPENDENCY_POLICY.peerRequiredHostExports['@deepseek-ai/dsh-typert-protocol']).toEqual([ - 'TypertLookupFailure', 'TypertRemoteFailure', 'remoteMethods', + 'Remote', 'TypertRemoteService', 'remoteMethods', ]) }) @@ -187,6 +194,7 @@ describe('package dependency scope', () => { sourceLine: "import { safeValue } from '@f/provider/api'", }], peerRequiredHostDependencies: new Set(), + configurationOnlyDevDependencies: new Set(), clientInject: new Set(), } @@ -211,6 +219,15 @@ describe('package dependency scope', () => { }) describe('face-aware source classification', () => { + it('fails when a managed Host package has no Host entry', () => { + const root = mkdtempSync(join(tmpdir(), 'dsh-package-missing-host-')) + roots.push(root) + const subject = pkg('@f/host', 'packages/g/host/package.json') + + expect(() => readPackageDependencyFacts(root, subject, 'configured-host', new Set([subject.name]))) + .toThrow('packages/g/host/package.json: Host runtime entry packages/g/host/src/index.ts does not exist') + }) + it('counts Host values as dependencies and Client values as development inputs', () => { const root = mkdtempSync(join(tmpdir(), 'dsh-package-faces-')) roots.push(root) @@ -234,9 +251,12 @@ describe('face-aware source classification', () => { } const found = readPackageDependencyFacts(root, subject, 'client-host', new Set([ CORDIS, '@f/runtime', '@f/types', '@f/nested', '@f/hidden', '@f/browser', '@f/injected', - ])) + ]), policy({ + configurationOnlyDevDependencies: { '@f/dual': ['@f/injected'] }, + })) expect([...found.hostRuntimeSourceUses.keys()].sort()).toEqual(['@f/nested', '@f/runtime']) + expect([...found.configurationOnlyDevDependencies]).toEqual(['@f/injected']) expect(found.hostRuntimeExportUses).toEqual([ { packageName: '@f/nested', @@ -294,6 +314,57 @@ describe('face-aware source classification', () => { }) describe('dependency sections', () => { + it('does not leak repository configuration into captured dependency facts', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-client-locale', + dependencies: { '@deepseek-ai/dsh-runtime': 'workspace:^' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-types': 'workspace:^' }, + peerDependencies: { [CORDIS]: 'workspace:^' }, + } + const base = facts(manifest) + const subject: PackageDependencyFacts = { + ...base, + workspaceNames: new Set([...base.workspaceNames, '@deepseek-ai/dsh-api-remotes']), + } + + expect(collectPackageDependencyViolations({ + facts: [subject], packages: [], policyViolations: [], workspaceNames: subject.workspaceNames, + })).toEqual([]) + }) + + it('requires non-workspace Host runtime imports in dependencies', () => { + const manifest: PackageDependencyManifest = { + name: '@deepseek-ai/dsh-probe', + dependencies: { '@deepseek-ai/dsh-runtime': 'workspace:^' }, + devDependencies: { [CORDIS]: 'workspace:^', '@deepseek-ai/dsh-types': 'workspace:^', external: '^1.0.0' }, + peerDependencies: { [CORDIS]: 'workspace:^' }, + } + const subject: PackageDependencyFacts = { + ...facts(manifest), + hostRuntimeSourceUses: new Map([ + ['@deepseek-ai/dsh-runtime', ['packages/core/probe/src/index.ts']], + ['external', ['packages/core/probe/src/index.ts']], + ]), + } + const state = { + facts: [subject], packages: [], policyViolations: [], workspaceNames: subject.workspaceNames, + } + + expect(collectPackageDependencyViolations(state)).toContain( + 'packages/core/probe/package.json: external (packages/core/probe/src/index.ts) ' + + 'must be dependencies-only; found devDependencies', + ) + repairPackageDependencyManifest(subject) + expect(manifest.dependencies?.external).toBe('^1.0.0') + expect(manifest.devDependencies?.external).toBeUndefined() + + delete manifest.dependencies?.external + expect(collectPackageDependencyViolations(state)).toContain( + 'packages/core/probe/package.json: external (packages/core/probe/src/index.ts) ' + + 'must be dependencies-only; found no dependency section', + ) + }) + it('accepts Host dependencies, development-only inputs, and shared Cordis', () => { const manifest: PackageDependencyManifest = { name: '@deepseek-ai/dsh-probe', diff --git a/scripts/verify-package-dependencies.ts b/scripts/verify-package-dependencies.ts index 3782d61309..b20e16af00 100644 --- a/scripts/verify-package-dependencies.ts +++ b/scripts/verify-package-dependencies.ts @@ -59,6 +59,7 @@ export interface PackageDependencyFacts { readonly hostRuntimeSourceUses: ReadonlyMap readonly hostRuntimeExportUses: readonly HostRuntimeExportUse[] readonly peerRequiredHostDependencies: ReadonlySet + readonly configurationOnlyDevDependencies: ReadonlySet readonly clientInject: ReadonlySet } @@ -296,7 +297,7 @@ function readHostRuntimeUses(root: string, pkg: WorkspacePackageManifest): { const seen = new Set() const visit = (path: string): void => { const normalized = normalize(path) - if (seen.has(normalized) || !existsSync(normalized)) return + if (seen.has(normalized)) return seen.add(normalized) const source = readFileSync(normalized, 'utf8') const displayPath = normalizePath(relative(root, normalized)) @@ -312,7 +313,11 @@ function readHostRuntimeUses(root: string, pkg: WorkspacePackageManifest): { if (target !== undefined) visit(target) } } - visit(resolve(root, pkg.dir, 'src/index.ts')) + const entry = resolve(root, pkg.dir, 'src/index.ts') + if (!existsSync(entry)) { + throw new Error(`${pkg.manifestPath}: Host runtime entry ${normalizePath(relative(root, entry))} does not exist`) + } + visit(entry) return { packageUses, exportUses: [...exportUses.values()].sort((left, right) => @@ -358,6 +363,9 @@ export function readPackageDependencyFacts( peerRequiredHostDependencies: new Set(hostRuntime.exportUses .filter(use => policy.peerRequiredHostExports[use.specifier]?.includes(use.exportName) === true) .map(use => use.packageName)), + configurationOnlyDevDependencies: new Set( + policy.configurationOnlyDevDependencies[pkg.manifest.name ?? ''] ?? [], + ), clientInject: new Set(inject.map(packageNameOf).filter(name => name !== undefined)), } } @@ -405,7 +413,7 @@ export function collectHostDependencyExportPolicyViolations( for (const fact of facts) { for (const use of fact.hostRuntimeExportUses) { if (use.packageName === fact.manifest.name || use.packageName === CORDIS) continue - if (!workspaceNames.has(use.packageName) && fact.manifest.peerDependencies?.[use.packageName] === undefined) continue + if (!workspaceNames.has(use.packageName)) continue if (policy.safeHostDependencyExports[use.specifier]?.includes(use.exportName) === true) continue if (policy.peerRequiredHostExports[use.specifier]?.includes(use.exportName) === true) continue violations.push( @@ -427,12 +435,16 @@ export function readPackageDependencyState( const discovered = discoverPackageDependencyScope(packages.release, policy) const facts = discovered.selected.map(pkg => readPackageDependencyFacts(root, pkg, pkg.role, workspaceNames, policy)) + const selectedNames = new Set(facts.map(fact => fact.manifest.name)) return { facts, packages: packages.release, policyViolations: [ ...discovered.violations, ...collectHostDependencyExportPolicyViolations(facts, workspaceNames, policy), + ...Object.keys(policy.configurationOnlyDevDependencies) + .filter(name => !selectedNames.has(name)) + .map(name => `configurationOnlyDevDependencies names unmanaged package ${name}`), ].sort(), workspaceNames, } @@ -441,7 +453,6 @@ export function readPackageDependencyState( /** Derive the required npm section for each relationship owned by the policy. */ export function expectedPackageDependencies( facts: PackageDependencyFacts, - policy: PackageDependencyPolicy = PACKAGE_DEPENDENCY_POLICY, ): ReadonlyMap { const expected = new Map }>() const add = (name: string, sectionName: ExpectedPackageDependency['section'], origin: string): void => { @@ -463,18 +474,16 @@ export function expectedPackageDependencies( for (const name of facts.clientInject) { if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'dsh.client.inject') } - for (const name of PACKAGE_DEPENDENCY_POLICY.configurationOnlyDevDependencies[facts.manifest.name ?? ''] ?? []) { - if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'configured development-only relationship') - } - for (const name of policy.configurationOnlyDevDependencies[facts.manifest.name ?? ''] ?? []) { + for (const name of facts.configurationOnlyDevDependencies) { if (facts.workspaceNames.has(name)) add(name, 'devDependencies', 'configured development-only relationship') } for (const name of Object.keys(facts.manifest.peerDependencies ?? {})) { if (name !== CORDIS) add(name, 'devDependencies', 'existing non-Cordis peer') } for (const [name, paths] of facts.hostRuntimeSourceUses) { - if (!facts.workspaceNames.has(name) && facts.manifest.peerDependencies?.[name] === undefined) continue - const expectedSection = facts.peerRequiredHostDependencies.has(name) ? 'peer-dev' : 'dependencies' + const expectedSection = facts.workspaceNames.has(name) && facts.peerRequiredHostDependencies.has(name) + ? 'peer-dev' + : 'dependencies' for (const path of paths) add(name, expectedSection, path) } return new Map([...expected].map(([name, rule]) => [name, { From a3207a758b029d764dc4fc029870336b0c1286f4 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 29 Aug 2026 13:29:04 +0800 Subject: [PATCH 32/63] chore: package.json update --- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 709 ++++------------- docs/module-graph.zh.md | 713 ++++-------------- packages/api/gateway/package.json | 12 +- packages/api/remotes/package.json | 32 +- packages/client/connection/package.json | 17 +- packages/client/hmr/package.json | 4 - packages/client/locale/package.json | 14 +- packages/client/modules/package.json | 5 +- packages/client/store/package.json | 3 +- packages/client/ui-agent-preset/package.json | 14 +- packages/client/ui-approval/package.json | 12 +- packages/client/ui-attachment/package.json | 8 +- .../client/ui-brand-official/package.json | 3 - packages/client/ui-chat/package.json | 30 +- packages/client/ui-commands/package.json | 12 +- packages/client/ui-conversation/package.json | 31 +- packages/client/ui-deliverables/package.json | 17 +- .../ui-directory-picker-browse/package.json | 5 - .../ui-directory-picker-native/package.json | 3 - packages/client/ui-goal/package.json | 14 +- packages/client/ui-input-trigger/package.json | 10 +- packages/client/ui-jobs/package.json | 8 +- packages/client/ui-layout/package.json | 5 - .../client/ui-message-feedback/package.json | 13 +- .../client/ui-model-selection/package.json | 13 +- .../client/ui-permission-presets/package.json | 12 +- packages/client/ui-plan/package.json | 10 +- packages/client/ui-primitives/package.json | 1 - packages/client/ui-reference/package.json | 10 - packages/client/ui-renderer/package.json | 1 - packages/client/ui-schedule/package.json | 7 - packages/client/ui-session/package.json | 6 +- .../client/ui-settings-general/package.json | 15 +- .../client/ui-settings-models/package.json | 7 +- .../ui-settings-plugin-inventory/package.json | 7 +- .../client/ui-settings-plugins/package.json | 7 +- packages/client/ui-settings/package.json | 11 +- packages/client/ui-sidebar/package.json | 9 +- packages/client/ui-skill/package.json | 9 - packages/client/ui-slots/package.json | 1 - packages/client/ui-subagent/package.json | 13 +- packages/client/ui-theme/package.json | 14 +- packages/client/ui-tool/package.json | 12 +- packages/client/ui-trajectory/package.json | 14 +- .../client/ui-user-questions/package.json | 12 +- packages/client/ui-workflow-run/package.json | 10 - packages/client/ui-workspace/package.json | 16 +- packages/client/web/package.json | 1 - packages/core/session/package.json | 8 +- .../cordis-client-runner/package.json | 6 - packages/extensions/ui-cordis/package.json | 10 - packages/llm/llm/package.json | 8 +- .../session-log-export/package.json | 49 +- packages/typert/registry/package.json | 5 +- pnpm-lock.yaml | 102 +-- 56 files changed, 459 insertions(+), 1645 deletions(-) diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 7112bfb506..ed60bccd07 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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/module-graph.md -module-graph.md: 7c4ccbf6841070d37116641c1404a70cbb598769 -module-graph.zh.md: 4581a5bdda1e75a9678a731ab109d3b3c71b7434 +module-graph.md: e5225db8618a3d056257bf96e57e3ad99fb73134 +module-graph.zh.md: 9a5f72ef3ddcc8c3823dd59812869611dec77169 diff --git a/docs/module-graph.md b/docs/module-graph.md index 7c4ccbf684..e5225db861 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -1,9 +1,9 @@ -# Module dependency graph +# Shared-instance dependency graph -Inter-package dependencies among the `@deepseek-ai/dsh-*` harness packages, derived from each package's `peerDependencies` (the canonical runtime-dependency signal) and grouped by the `packages//` hierarchy. An edge `a --> b` means package `a` depends on package `b`. Names have the `@deepseek-ai/dsh-` prefix stripped. +Peer dependencies among the `@deepseek-ai/dsh-*` harness packages. A peer means the consumer requires a shared instance; ordinary runtime dependencies and development-only relationships are not shown. The graph is grouped by the `packages//` hierarchy. An edge `a --> b` means package `a` has package `b` as a peer. Names omit the `@deepseek-ai/dsh-` prefix. ```mermaid flowchart TD @@ -375,11 +375,6 @@ flowchart TD pkg_base --> pkg_invariants pkg_sdk_app --> pkg_invariants pkg_sdk_minimal --> pkg_invariants - pkg_client_store --> pkg_invariants - pkg_client_ui_primitives --> pkg_invariants - pkg_client_ui_renderer --> pkg_invariants - pkg_client_ui_slots --> pkg_invariants - pkg_client_web --> pkg_invariants pkg_code_runtime --> pkg_invariants pkg_code_runtime_python --> pkg_invariants pkg_e2b --> pkg_invariants @@ -396,18 +391,37 @@ flowchart TD pkg_win32_process --> pkg_invariants pkg_llm_mock_server --> pkg_invariants pkg_typert_generator --> pkg_invariants + pkg_typert_loader --> pkg_invariants + pkg_typert_loader --> pkg_typert_registry pkg_typert_protocol --> pkg_invariants - pkg_typert_registry --> pkg_invariants + pkg_llm --> pkg_typert_protocol + pkg_session --> pkg_scope + pkg_api_gateway --> pkg_typert_protocol + pkg_api_remotes --> pkg_scope pkg_attachment --> pkg_brand pkg_attachment --> pkg_invariants - pkg_client_modules --> pkg_host_webserver - pkg_client_modules --> pkg_invariants pkg_credentials --> pkg_brand pkg_credentials --> pkg_invariants pkg_subprocess_e2b --> pkg_e2b pkg_subprocess_e2b --> pkg_invariants pkg_subprocess_e2b --> pkg_subprocess pkg_subprocess_e2b --> pkg_timeout + pkg_experimental_inspector --> pkg_client_modules + pkg_experimental_inspector --> pkg_host_webserver + pkg_experimental_inspector --> pkg_invariants + pkg_experimental_webworker_runtime --> pkg_client_connection + pkg_experimental_webworker_runtime --> pkg_client_modules + pkg_experimental_webworker_runtime --> pkg_host_webserver + pkg_experimental_webworker_runtime --> pkg_invariants + pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse + pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native + pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse + pkg_host_directory_picker_auto --> pkg_host_directory_picker_native + pkg_host_directory_picker_auto --> pkg_host_webserver + pkg_host_directory_picker_auto --> pkg_invariants + pkg_host_frontend_static --> pkg_client_connection + pkg_host_frontend_static --> pkg_host_webserver + pkg_host_frontend_static --> pkg_invariants pkg_host_plugin_inventory --> pkg_brand pkg_host_plugin_inventory --> pkg_invariants pkg_host_plugin_inventory --> pkg_typert_protocol @@ -423,32 +437,6 @@ flowchart TD pkg_subprocess_local --> pkg_invariants pkg_subprocess_local --> pkg_subprocess pkg_subprocess_local --> pkg_timeout - pkg_typert_loader --> pkg_invariants - pkg_typert_loader --> pkg_typert_registry - pkg_llm --> pkg_attachment - pkg_llm --> pkg_brand - pkg_llm --> pkg_invariants - pkg_llm --> pkg_timeout - pkg_llm --> pkg_typert_protocol - pkg_attachment_local --> pkg_attachment - pkg_attachment_local --> pkg_home_paths - pkg_attachment_local --> pkg_invariants - pkg_client_hmr --> pkg_client_modules - pkg_client_hmr --> pkg_host_webserver - pkg_client_hmr --> pkg_invariants - pkg_credentials_local --> pkg_atomic_write - pkg_credentials_local --> pkg_credentials - pkg_credentials_local --> pkg_home_paths - pkg_credentials_local --> pkg_invariants - pkg_credentials_local --> pkg_launch_environment - pkg_experimental_inspector --> pkg_client_modules - pkg_experimental_inspector --> pkg_host_webserver - pkg_experimental_inspector --> pkg_invariants - pkg_session --> pkg_brand - pkg_session --> pkg_invariants - pkg_session --> pkg_llm - pkg_session --> pkg_scope - pkg_session --> pkg_typert_protocol pkg_system_prompt --> pkg_invariants pkg_system_prompt --> pkg_llm pkg_system_prompt --> pkg_scope @@ -457,37 +445,28 @@ flowchart TD pkg_skill --> pkg_scope pkg_web --> pkg_invariants pkg_web --> pkg_llm - pkg_authorization --> pkg_credentials - pkg_authorization --> pkg_invariants - pkg_authorization --> pkg_llm - pkg_lsp --> pkg_brand - pkg_lsp --> pkg_invariants - pkg_lsp --> pkg_llm - pkg_skill_badge --> pkg_invariants - pkg_skill_badge --> pkg_skill - pkg_web_fetch_http --> pkg_invariants - pkg_web_fetch_http --> pkg_timeout - pkg_web_fetch_http --> pkg_web - pkg_web_search_exa --> pkg_invariants - pkg_web_search_exa --> pkg_launch_environment - pkg_web_search_exa --> pkg_web - pkg_web_search_perplexity --> pkg_invariants - pkg_web_search_perplexity --> pkg_launch_environment - pkg_web_search_perplexity --> pkg_web pkg_spill --> pkg_brand pkg_spill --> pkg_invariants pkg_spill --> pkg_llm pkg_spill --> pkg_session - pkg_app_boot --> pkg_home_paths - pkg_app_boot --> pkg_invariants - pkg_app_boot --> pkg_launch_environment - pkg_app_boot --> pkg_system_prompt + pkg_attachment_local --> pkg_attachment + pkg_attachment_local --> pkg_home_paths + pkg_attachment_local --> pkg_invariants pkg_code_runtime_worker_thread --> pkg_code_runtime pkg_code_runtime_worker_thread --> pkg_invariants pkg_code_runtime_worker_thread --> pkg_session pkg_code_runtime_worker_thread --> pkg_timeout - pkg_persona --> pkg_invariants - pkg_persona --> pkg_system_prompt + pkg_authorization --> pkg_credentials + pkg_authorization --> pkg_invariants + pkg_authorization --> pkg_llm + pkg_credentials_local --> pkg_atomic_write + pkg_credentials_local --> pkg_credentials + pkg_credentials_local --> pkg_home_paths + pkg_credentials_local --> pkg_invariants + pkg_credentials_local --> pkg_launch_environment + pkg_lsp --> pkg_brand + pkg_lsp --> pkg_invariants + pkg_lsp --> pkg_llm pkg_sandbox --> pkg_invariants pkg_sandbox --> pkg_llm pkg_sandbox --> pkg_session @@ -516,8 +495,23 @@ flowchart TD pkg_fs --> pkg_invariants pkg_fs --> pkg_llm pkg_fs --> pkg_sandbox + pkg_skill_badge --> pkg_invariants + pkg_skill_badge --> pkg_skill + pkg_web_fetch_http --> pkg_invariants + pkg_web_fetch_http --> pkg_timeout + pkg_web_fetch_http --> pkg_web + pkg_web_search_exa --> pkg_invariants + pkg_web_search_exa --> pkg_launch_environment + pkg_web_search_exa --> pkg_web + pkg_web_search_perplexity --> pkg_invariants + pkg_web_search_perplexity --> pkg_launch_environment + pkg_web_search_perplexity --> pkg_web pkg_spill_local --> pkg_invariants pkg_spill_local --> pkg_spill + pkg_app_boot --> pkg_home_paths + pkg_app_boot --> pkg_invariants + pkg_app_boot --> pkg_launch_environment + pkg_app_boot --> pkg_system_prompt pkg_message_feedback --> pkg_brand pkg_message_feedback --> pkg_invariants pkg_message_feedback --> pkg_llm @@ -525,6 +519,8 @@ flowchart TD pkg_message_feedback --> pkg_session_persistence pkg_message_feedback --> pkg_storage_domain pkg_message_feedback --> pkg_typert_protocol + pkg_persona --> pkg_invariants + pkg_persona --> pkg_system_prompt pkg_sandbox_local --> pkg_invariants pkg_sandbox_local --> pkg_llm pkg_sandbox_local --> pkg_sandbox @@ -618,6 +614,14 @@ flowchart TD pkg_hook_protocol --> pkg_invariants pkg_hook_protocol --> pkg_session pkg_hook_protocol --> pkg_shell + pkg_api_workspace_controller --> pkg_api_gateway + pkg_api_workspace_controller --> pkg_client_connection + pkg_api_workspace_controller --> pkg_host_directory_picker + pkg_api_workspace_controller --> pkg_invariants + pkg_api_workspace_controller --> pkg_session + pkg_api_workspace_controller --> pkg_storage_domain + pkg_api_workspace_controller --> pkg_typert_protocol + pkg_api_workspace_controller --> pkg_workspace pkg_file_reference --> pkg_agent pkg_file_reference --> pkg_invariants pkg_time_context --> pkg_agent @@ -1032,17 +1036,6 @@ flowchart TD pkg_web_app --> pkg_invariants pkg_web_app --> pkg_shell_env pkg_web_app --> pkg_system_prompt - pkg_client_connection --> pkg_attachment - pkg_client_connection --> pkg_brand - pkg_client_connection --> pkg_commands - pkg_client_connection --> pkg_credentials - pkg_client_connection --> pkg_host_directory_picker - pkg_client_connection --> pkg_host_webserver - pkg_client_connection --> pkg_invariants - pkg_client_connection --> pkg_llm - pkg_client_connection --> pkg_session - pkg_client_connection --> pkg_settings - pkg_client_connection --> pkg_tool_todo pkg_compaction_tool_result_pruner --> pkg_compaction pkg_compaction_tool_result_pruner --> pkg_invariants pkg_compaction_tool_result_pruner --> pkg_llm @@ -1121,11 +1114,6 @@ flowchart TD pkg_tool_session_query --> pkg_system_prompt pkg_tool_session_query --> pkg_timeout pkg_tool_session_query --> pkg_tools - pkg_api_gateway --> pkg_brand - pkg_api_gateway --> pkg_client_connection - pkg_api_gateway --> pkg_host_webserver - pkg_api_gateway --> pkg_invariants - pkg_api_gateway --> pkg_typert_registry pkg_compaction_basic --> pkg_agent pkg_compaction_basic --> pkg_commands pkg_compaction_basic --> pkg_compaction @@ -1167,13 +1155,6 @@ flowchart TD pkg_agent_spine_demo --> pkg_tool_jobs pkg_agent_spine_demo --> pkg_tool_skill pkg_agent_spine_demo --> pkg_tools - pkg_experimental_webworker_runtime --> pkg_client_connection - pkg_experimental_webworker_runtime --> pkg_client_modules - pkg_experimental_webworker_runtime --> pkg_host_webserver - pkg_experimental_webworker_runtime --> pkg_invariants - pkg_host_frontend_static --> pkg_client_connection - pkg_host_frontend_static --> pkg_host_webserver - pkg_host_frontend_static --> pkg_invariants pkg_webhook_github --> pkg_credentials pkg_webhook_github --> pkg_host_webserver pkg_webhook_github --> pkg_invariants @@ -1261,14 +1242,6 @@ flowchart TD pkg_api_session_controller --> pkg_util_time pkg_api_session_controller --> pkg_util_workspace_path pkg_api_session_controller --> pkg_workspace - pkg_api_workspace_controller --> pkg_api_gateway - pkg_api_workspace_controller --> pkg_client_connection - pkg_api_workspace_controller --> pkg_host_directory_picker - pkg_api_workspace_controller --> pkg_invariants - pkg_api_workspace_controller --> pkg_session - pkg_api_workspace_controller --> pkg_storage_domain - pkg_api_workspace_controller --> pkg_typert_protocol - pkg_api_workspace_controller --> pkg_workspace pkg_experimental_agent_team --> pkg_agent pkg_experimental_agent_team --> pkg_brand pkg_experimental_agent_team --> pkg_invariants @@ -1305,30 +1278,18 @@ flowchart TD pkg_subagent_spawn_in_process --> pkg_invariants pkg_subagent_spawn_in_process --> pkg_subagent pkg_subagent_spawn_in_process --> pkg_subagent_in_process_driver - pkg_api_remotes --> pkg_agent_presets - pkg_api_remotes --> pkg_api_gateway - pkg_api_remotes --> pkg_api_session_controller - pkg_api_remotes --> pkg_api_settings_controller - pkg_api_remotes --> pkg_api_workspace_controller - pkg_api_remotes --> pkg_commands - pkg_api_remotes --> pkg_cordis_host_runner - pkg_api_remotes --> pkg_credentials - pkg_api_remotes --> pkg_file_reference - pkg_api_remotes --> pkg_goal - pkg_api_remotes --> pkg_host_plugin_inventory - pkg_api_remotes --> pkg_invariants - pkg_api_remotes --> pkg_llm - pkg_api_remotes --> pkg_message_feedback - pkg_api_remotes --> pkg_session - pkg_api_remotes --> pkg_session_reference - pkg_api_remotes --> pkg_settings - pkg_api_remotes --> pkg_subagent - pkg_api_remotes --> pkg_user_approval - pkg_api_remotes --> pkg_user_questions - pkg_client_ui_session --> pkg_api_session_controller - pkg_client_ui_session --> pkg_client_ui_renderer - pkg_client_ui_session --> pkg_invariants - pkg_client_ui_session --> pkg_session + pkg_experimental_client_ui_agent_team --> pkg_api_remotes + pkg_experimental_client_ui_agent_team --> pkg_api_session_controller + pkg_experimental_client_ui_agent_team --> pkg_client_locale + pkg_experimental_client_ui_agent_team --> pkg_client_ui_conversation + pkg_experimental_client_ui_agent_team --> pkg_client_ui_primitives + pkg_experimental_client_ui_agent_team --> pkg_client_ui_renderer + pkg_experimental_client_ui_agent_team --> pkg_client_ui_session + pkg_experimental_client_ui_agent_team --> pkg_client_ui_slots + pkg_experimental_client_ui_agent_team --> pkg_experimental_agent_team + pkg_experimental_client_ui_agent_team --> pkg_invariants + pkg_experimental_client_ui_agent_team --> pkg_session + pkg_experimental_client_ui_agent_team --> pkg_typert_protocol pkg_experimental_tool_agent_team --> pkg_agent pkg_experimental_tool_agent_team --> pkg_experimental_agent_team pkg_experimental_tool_agent_team --> pkg_invariants @@ -1348,358 +1309,6 @@ flowchart TD pkg_sdk_jsonrpc_server --> pkg_sdk_protocol pkg_sdk_jsonrpc_server --> pkg_session pkg_sdk_jsonrpc_server --> pkg_subagent - pkg_subagent_dsh_sdk --> pkg_agent - pkg_subagent_dsh_sdk --> pkg_invariants - pkg_subagent_dsh_sdk --> pkg_llm - pkg_subagent_dsh_sdk --> pkg_sdk_client - pkg_subagent_dsh_sdk --> pkg_session - pkg_subagent_dsh_sdk --> pkg_subagent - pkg_subagent_dsh_sdk --> pkg_subprocess - pkg_client_ui_settings --> pkg_api_remotes - pkg_client_ui_settings --> pkg_invariants - pkg_client_ui_settings --> pkg_settings - pkg_client_locale --> pkg_api_remotes - pkg_client_locale --> pkg_client_connection - pkg_client_locale --> pkg_client_ui_renderer - pkg_client_locale --> pkg_client_ui_settings - pkg_client_locale --> pkg_invariants - pkg_client_locale --> pkg_settings - pkg_client_ui_settings_models --> pkg_api_remotes - pkg_client_ui_settings_models --> pkg_client_locale - pkg_client_ui_settings_models --> pkg_client_ui_renderer - pkg_client_ui_settings_models --> pkg_client_ui_settings - pkg_client_ui_settings_models --> pkg_invariants - pkg_client_ui_settings_plugin_inventory --> pkg_api_remotes - pkg_client_ui_settings_plugin_inventory --> pkg_client_locale - pkg_client_ui_settings_plugin_inventory --> pkg_client_ui_renderer - pkg_client_ui_settings_plugin_inventory --> pkg_client_ui_settings - pkg_client_ui_settings_plugin_inventory --> pkg_invariants - pkg_client_ui_settings_plugins --> pkg_api_remotes - pkg_client_ui_settings_plugins --> pkg_client_locale - pkg_client_ui_settings_plugins --> pkg_client_ui_renderer - pkg_client_ui_settings_plugins --> pkg_client_ui_settings - pkg_client_ui_settings_plugins --> pkg_invariants - pkg_client_ui_theme --> pkg_api_remotes - pkg_client_ui_theme --> pkg_client_connection - pkg_client_ui_theme --> pkg_client_locale - pkg_client_ui_theme --> pkg_client_ui_renderer - pkg_client_ui_theme --> pkg_client_ui_settings - pkg_client_ui_theme --> pkg_host_webserver - pkg_client_ui_theme --> pkg_invariants - pkg_client_ui_theme --> pkg_settings - pkg_client_ui_layout --> pkg_client_locale - pkg_client_ui_layout --> pkg_client_ui_renderer - pkg_client_ui_layout --> pkg_client_ui_session - pkg_client_ui_layout --> pkg_client_ui_theme - pkg_client_ui_layout --> pkg_invariants - pkg_cordis_client_runner --> pkg_api_remotes - pkg_cordis_client_runner --> pkg_client_modules - pkg_cordis_client_runner --> pkg_client_ui_renderer - pkg_cordis_client_runner --> pkg_client_ui_theme - pkg_cordis_client_runner --> pkg_invariants - pkg_client_ui_conversation --> pkg_api_remotes - pkg_client_ui_conversation --> pkg_api_session_controller - pkg_client_ui_conversation --> pkg_api_workspace_controller - pkg_client_ui_conversation --> pkg_attachment - pkg_client_ui_conversation --> pkg_brand - pkg_client_ui_conversation --> pkg_client_locale - pkg_client_ui_conversation --> pkg_client_ui_layout - pkg_client_ui_conversation --> pkg_client_ui_renderer - pkg_client_ui_conversation --> pkg_client_ui_session - pkg_client_ui_conversation --> pkg_client_ui_settings - pkg_client_ui_conversation --> pkg_client_ui_workspace - pkg_client_ui_conversation --> pkg_commands - pkg_client_ui_conversation --> pkg_goal - pkg_client_ui_conversation --> pkg_invariants - pkg_client_ui_conversation --> pkg_llm - pkg_client_ui_conversation --> pkg_llm_retry - pkg_client_ui_conversation --> pkg_permission_presets - pkg_client_ui_conversation --> pkg_plan_mode - pkg_client_ui_conversation --> pkg_session - pkg_client_ui_conversation --> pkg_settings - pkg_client_ui_conversation --> pkg_token_meter - pkg_client_ui_conversation --> pkg_tool_todo - pkg_client_ui_conversation --> pkg_util_crypto - pkg_client_ui_conversation --> pkg_util_workspace_path - pkg_client_ui_conversation --> pkg_workspace - pkg_client_ui_sidebar --> pkg_api_workspace_controller - pkg_client_ui_sidebar --> pkg_client_locale - pkg_client_ui_sidebar --> pkg_client_ui_layout - pkg_client_ui_sidebar --> pkg_client_ui_renderer - pkg_client_ui_sidebar --> pkg_client_ui_session - pkg_client_ui_sidebar --> pkg_client_ui_workspace - pkg_client_ui_sidebar --> pkg_invariants - pkg_client_ui_workspace --> pkg_api_remotes - pkg_client_ui_workspace --> pkg_api_session_controller - pkg_client_ui_workspace --> pkg_api_workspace_controller - pkg_client_ui_workspace --> pkg_client_connection - pkg_client_ui_workspace --> pkg_client_locale - pkg_client_ui_workspace --> pkg_client_ui_conversation - pkg_client_ui_workspace --> pkg_client_ui_renderer - pkg_client_ui_workspace --> pkg_client_ui_session - pkg_client_ui_workspace --> pkg_client_ui_sidebar - pkg_client_ui_workspace --> pkg_invariants - pkg_client_ui_workspace --> pkg_schedule - pkg_client_ui_workspace --> pkg_session - pkg_client_ui_workspace --> pkg_typert_protocol - pkg_client_ui_workspace --> pkg_util_workspace_path - pkg_client_ui_agent_preset --> pkg_agent_presets - pkg_client_ui_agent_preset --> pkg_api_remotes - pkg_client_ui_agent_preset --> pkg_api_session_controller - pkg_client_ui_agent_preset --> pkg_client_connection - pkg_client_ui_agent_preset --> pkg_client_locale - pkg_client_ui_agent_preset --> pkg_client_ui_conversation - pkg_client_ui_agent_preset --> pkg_client_ui_renderer - pkg_client_ui_agent_preset --> pkg_client_ui_session - pkg_client_ui_agent_preset --> pkg_client_ui_settings - pkg_client_ui_agent_preset --> pkg_client_ui_workspace - pkg_client_ui_agent_preset --> pkg_invariants - pkg_client_ui_agent_preset --> pkg_session - pkg_client_ui_approval --> pkg_api_remotes - pkg_client_ui_approval --> pkg_api_session_controller - pkg_client_ui_approval --> pkg_client_locale - pkg_client_ui_approval --> pkg_client_ui_conversation - pkg_client_ui_approval --> pkg_client_ui_renderer - pkg_client_ui_approval --> pkg_client_ui_session - pkg_client_ui_approval --> pkg_invariants - pkg_client_ui_approval --> pkg_llm - pkg_client_ui_approval --> pkg_session - pkg_client_ui_approval --> pkg_typert_protocol - pkg_client_ui_brand_official --> pkg_client_ui_renderer - pkg_client_ui_brand_official --> pkg_client_ui_sidebar - pkg_client_ui_brand_official --> pkg_invariants - pkg_client_ui_directory_picker_browse --> pkg_api_remotes - pkg_client_ui_directory_picker_browse --> pkg_client_locale - pkg_client_ui_directory_picker_browse --> pkg_client_ui_renderer - pkg_client_ui_directory_picker_browse --> pkg_client_ui_workspace - pkg_client_ui_directory_picker_browse --> pkg_invariants - pkg_client_ui_directory_picker_native --> pkg_client_ui_renderer - pkg_client_ui_directory_picker_native --> pkg_client_ui_workspace - pkg_client_ui_directory_picker_native --> pkg_invariants - pkg_client_ui_input_trigger --> pkg_api_session_controller - pkg_client_ui_input_trigger --> pkg_client_locale - pkg_client_ui_input_trigger --> pkg_client_ui_conversation - pkg_client_ui_input_trigger --> pkg_client_ui_renderer - pkg_client_ui_input_trigger --> pkg_client_ui_session - pkg_client_ui_input_trigger --> pkg_file_reference - pkg_client_ui_input_trigger --> pkg_invariants - pkg_client_ui_input_trigger --> pkg_session - pkg_client_ui_jobs --> pkg_api_session_controller - pkg_client_ui_jobs --> pkg_client_locale - pkg_client_ui_jobs --> pkg_client_ui_conversation - pkg_client_ui_jobs --> pkg_client_ui_renderer - pkg_client_ui_jobs --> pkg_client_ui_session - pkg_client_ui_jobs --> pkg_invariants - pkg_client_ui_plan --> pkg_api_remotes - pkg_client_ui_plan --> pkg_client_locale - pkg_client_ui_plan --> pkg_client_ui_conversation - pkg_client_ui_plan --> pkg_client_ui_renderer - pkg_client_ui_plan --> pkg_client_ui_session - pkg_client_ui_plan --> pkg_invariants - pkg_client_ui_plan --> pkg_plan_mode - pkg_client_ui_plan --> pkg_session - pkg_client_ui_schedule --> pkg_api_session_controller - pkg_client_ui_schedule --> pkg_client_locale - pkg_client_ui_schedule --> pkg_client_ui_conversation - pkg_client_ui_schedule --> pkg_client_ui_renderer - pkg_client_ui_schedule --> pkg_client_ui_session - pkg_client_ui_schedule --> pkg_invariants - pkg_client_ui_schedule --> pkg_schedule - pkg_client_ui_settings_general --> pkg_api_remotes - pkg_client_ui_settings_general --> pkg_client_connection - pkg_client_ui_settings_general --> pkg_client_locale - pkg_client_ui_settings_general --> pkg_client_ui_renderer - pkg_client_ui_settings_general --> pkg_client_ui_session - pkg_client_ui_settings_general --> pkg_client_ui_settings - pkg_client_ui_settings_general --> pkg_client_ui_sidebar - pkg_client_ui_settings_general --> pkg_invariants - pkg_client_ui_settings_general --> pkg_settings - pkg_client_ui_trajectory --> pkg_agent - pkg_client_ui_trajectory --> pkg_api_session_controller - pkg_client_ui_trajectory --> pkg_attachment - pkg_client_ui_trajectory --> pkg_client_locale - pkg_client_ui_trajectory --> pkg_client_ui_conversation - pkg_client_ui_trajectory --> pkg_client_ui_renderer - pkg_client_ui_trajectory --> pkg_client_ui_session - pkg_client_ui_trajectory --> pkg_compaction - pkg_client_ui_trajectory --> pkg_invariants - pkg_client_ui_trajectory --> pkg_llm - pkg_client_ui_trajectory --> pkg_session - pkg_client_ui_trajectory --> pkg_tools - pkg_client_ui_user_questions --> pkg_api_remotes - pkg_client_ui_user_questions --> pkg_api_session_controller - pkg_client_ui_user_questions --> pkg_client_locale - pkg_client_ui_user_questions --> pkg_client_ui_conversation - pkg_client_ui_user_questions --> pkg_client_ui_renderer - pkg_client_ui_user_questions --> pkg_client_ui_session - pkg_client_ui_user_questions --> pkg_invariants - pkg_client_ui_user_questions --> pkg_session - pkg_client_ui_user_questions --> pkg_typert_protocol - pkg_client_ui_user_questions --> pkg_user_questions - pkg_experimental_client_ui_agent_team --> pkg_api_remotes - pkg_experimental_client_ui_agent_team --> pkg_api_session_controller - pkg_experimental_client_ui_agent_team --> pkg_client_locale - pkg_experimental_client_ui_agent_team --> pkg_client_ui_conversation - pkg_experimental_client_ui_agent_team --> pkg_client_ui_primitives - pkg_experimental_client_ui_agent_team --> pkg_client_ui_renderer - pkg_experimental_client_ui_agent_team --> pkg_client_ui_session - pkg_experimental_client_ui_agent_team --> pkg_client_ui_slots - pkg_experimental_client_ui_agent_team --> pkg_experimental_agent_team - pkg_experimental_client_ui_agent_team --> pkg_invariants - pkg_experimental_client_ui_agent_team --> pkg_session - pkg_experimental_client_ui_agent_team --> pkg_typert_protocol - pkg_client_ui_chat --> pkg_agent - pkg_client_ui_chat --> pkg_api_remotes - pkg_client_ui_chat --> pkg_api_session_controller - pkg_client_ui_chat --> pkg_api_workspace_controller - pkg_client_ui_chat --> pkg_attachment - pkg_client_ui_chat --> pkg_client_locale - pkg_client_ui_chat --> pkg_client_ui_approval - pkg_client_ui_chat --> pkg_client_ui_conversation - pkg_client_ui_chat --> pkg_client_ui_layout - pkg_client_ui_chat --> pkg_client_ui_renderer - pkg_client_ui_chat --> pkg_client_ui_session - pkg_client_ui_chat --> pkg_client_ui_settings - pkg_client_ui_chat --> pkg_client_ui_workspace - pkg_client_ui_chat --> pkg_commands - pkg_client_ui_chat --> pkg_compaction - pkg_client_ui_chat --> pkg_invariants - pkg_client_ui_chat --> pkg_llm - pkg_client_ui_chat --> pkg_llm_retry - pkg_client_ui_chat --> pkg_session - pkg_client_ui_chat --> pkg_session_stats - pkg_client_ui_chat --> pkg_settings - pkg_client_ui_chat --> pkg_token_meter - pkg_client_ui_chat --> pkg_tools - pkg_client_ui_chat --> pkg_util_workspace_path - pkg_client_ui_commands --> pkg_api_remotes - pkg_client_ui_commands --> pkg_api_session_controller - pkg_client_ui_commands --> pkg_client_locale - pkg_client_ui_commands --> pkg_client_ui_conversation - pkg_client_ui_commands --> pkg_client_ui_input_trigger - pkg_client_ui_commands --> pkg_client_ui_renderer - pkg_client_ui_commands --> pkg_client_ui_session - pkg_client_ui_commands --> pkg_commands - pkg_client_ui_commands --> pkg_invariants - pkg_client_ui_commands --> pkg_session - pkg_client_ui_reference --> pkg_api_remotes - pkg_client_ui_reference --> pkg_api_session_controller - pkg_client_ui_reference --> pkg_client_connection - pkg_client_ui_reference --> pkg_client_locale - pkg_client_ui_reference --> pkg_client_ui_input_trigger - pkg_client_ui_reference --> pkg_file_reference - pkg_client_ui_reference --> pkg_invariants - pkg_client_ui_reference --> pkg_session_reference - pkg_client_ui_reference --> pkg_typert_protocol - pkg_client_ui_reference --> pkg_util_workspace_path - pkg_client_ui_subagent --> pkg_api_session_controller - pkg_client_ui_subagent --> pkg_client_connection - pkg_client_ui_subagent --> pkg_client_locale - pkg_client_ui_subagent --> pkg_client_ui_conversation - pkg_client_ui_subagent --> pkg_client_ui_input_trigger - pkg_client_ui_subagent --> pkg_client_ui_renderer - pkg_client_ui_subagent --> pkg_client_ui_session - pkg_client_ui_subagent --> pkg_invariants - pkg_client_ui_subagent --> pkg_session - pkg_client_ui_subagent --> pkg_subagent - pkg_client_ui_subagent --> pkg_token_meter - pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse - pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native - pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse - pkg_host_directory_picker_auto --> pkg_host_directory_picker_native - pkg_host_directory_picker_auto --> pkg_host_webserver - pkg_host_directory_picker_auto --> pkg_invariants - pkg_session_log_export --> pkg_attachment - pkg_session_log_export --> pkg_client_connection - pkg_session_log_export --> pkg_client_locale - pkg_session_log_export --> pkg_client_ui_commands - pkg_session_log_export --> pkg_client_ui_conversation - pkg_session_log_export --> pkg_client_ui_renderer - pkg_session_log_export --> pkg_client_ui_session - pkg_session_log_export --> pkg_commands - pkg_session_log_export --> pkg_invariants - pkg_session_log_export --> pkg_session - pkg_session_log_export --> pkg_session_persistence - pkg_session_log_export --> pkg_session_query - pkg_client_ui_attachment --> pkg_attachment - pkg_client_ui_attachment --> pkg_client_ui_chat - pkg_client_ui_attachment --> pkg_client_ui_conversation - pkg_client_ui_attachment --> pkg_client_ui_renderer - pkg_client_ui_attachment --> pkg_client_ui_trajectory - pkg_client_ui_attachment --> pkg_invariants - pkg_client_ui_deliverables --> pkg_api_remotes - pkg_client_ui_deliverables --> pkg_client_connection - pkg_client_ui_deliverables --> pkg_client_locale - pkg_client_ui_deliverables --> pkg_client_ui_chat - pkg_client_ui_deliverables --> pkg_client_ui_conversation - pkg_client_ui_deliverables --> pkg_client_ui_renderer - pkg_client_ui_deliverables --> pkg_invariants - pkg_client_ui_deliverables --> pkg_session - pkg_client_ui_deliverables --> pkg_system_prompt - pkg_client_ui_goal --> pkg_api_remotes - pkg_client_ui_goal --> pkg_api_session_controller - pkg_client_ui_goal --> pkg_client_locale - pkg_client_ui_goal --> pkg_client_ui_chat - pkg_client_ui_goal --> pkg_client_ui_conversation - pkg_client_ui_goal --> pkg_client_ui_renderer - pkg_client_ui_goal --> pkg_client_ui_session - pkg_client_ui_goal --> pkg_commands - pkg_client_ui_goal --> pkg_goal - pkg_client_ui_goal --> pkg_invariants - pkg_client_ui_goal --> pkg_session - pkg_client_ui_goal --> pkg_typert_protocol - pkg_client_ui_message_feedback --> pkg_api_remotes - pkg_client_ui_message_feedback --> pkg_client_connection - pkg_client_ui_message_feedback --> pkg_client_locale - pkg_client_ui_message_feedback --> pkg_client_ui_chat - pkg_client_ui_message_feedback --> pkg_client_ui_conversation - pkg_client_ui_message_feedback --> pkg_client_ui_renderer - pkg_client_ui_message_feedback --> pkg_client_ui_session - pkg_client_ui_message_feedback --> pkg_invariants - pkg_client_ui_message_feedback --> pkg_message_feedback - pkg_client_ui_message_feedback --> pkg_session - pkg_client_ui_message_feedback --> pkg_typert_protocol - pkg_client_ui_model_selection --> pkg_api_remotes - pkg_client_ui_model_selection --> pkg_api_session_controller - pkg_client_ui_model_selection --> pkg_client_locale - pkg_client_ui_model_selection --> pkg_client_ui_commands - pkg_client_ui_model_selection --> pkg_client_ui_conversation - pkg_client_ui_model_selection --> pkg_client_ui_input_trigger - pkg_client_ui_model_selection --> pkg_client_ui_renderer - pkg_client_ui_model_selection --> pkg_client_ui_session - pkg_client_ui_model_selection --> pkg_invariants - pkg_client_ui_model_selection --> pkg_session - pkg_client_ui_model_selection --> pkg_typert_protocol - pkg_client_ui_permission_presets --> pkg_api_remotes - pkg_client_ui_permission_presets --> pkg_api_session_controller - pkg_client_ui_permission_presets --> pkg_client_locale - pkg_client_ui_permission_presets --> pkg_client_ui_commands - pkg_client_ui_permission_presets --> pkg_client_ui_input_trigger - pkg_client_ui_permission_presets --> pkg_client_ui_renderer - pkg_client_ui_permission_presets --> pkg_client_ui_session - pkg_client_ui_permission_presets --> pkg_client_ui_settings - pkg_client_ui_permission_presets --> pkg_invariants - pkg_client_ui_permission_presets --> pkg_permission_presets - pkg_client_ui_tool --> pkg_api_remotes - pkg_client_ui_tool --> pkg_api_workspace_controller - pkg_client_ui_tool --> pkg_client_connection - pkg_client_ui_tool --> pkg_client_locale - pkg_client_ui_tool --> pkg_client_ui_chat - pkg_client_ui_tool --> pkg_client_ui_conversation - pkg_client_ui_tool --> pkg_client_ui_renderer - pkg_client_ui_tool --> pkg_client_ui_session - pkg_client_ui_tool --> pkg_invariants - pkg_client_ui_tool --> pkg_util_workspace_path - pkg_client_ui_workflow_run --> pkg_api_session_controller - pkg_client_ui_workflow_run --> pkg_client_locale - pkg_client_ui_workflow_run --> pkg_client_ui_chat - pkg_client_ui_workflow_run --> pkg_client_ui_conversation - pkg_client_ui_workflow_run --> pkg_client_ui_renderer - pkg_client_ui_workflow_run --> pkg_client_ui_session - pkg_client_ui_workflow_run --> pkg_invariants - pkg_client_ui_workflow_run --> pkg_session - pkg_client_ui_workflow_run --> pkg_tool_workflow - pkg_client_ui_workflow_run --> pkg_workflow pkg_client_test_runtime --> pkg_api_session_controller pkg_client_test_runtime --> pkg_api_workspace_controller pkg_client_test_runtime --> pkg_attachment @@ -1715,30 +1324,66 @@ flowchart TD pkg_client_test_runtime --> pkg_session pkg_client_test_runtime --> pkg_subagent pkg_client_test_runtime --> pkg_typert_protocol - pkg_client_ui_skill --> pkg_api_remotes - pkg_client_ui_skill --> pkg_api_session_controller - pkg_client_ui_skill --> pkg_client_connection - pkg_client_ui_skill --> pkg_client_locale - pkg_client_ui_skill --> pkg_client_ui_input_trigger - pkg_client_ui_skill --> pkg_client_ui_renderer - pkg_client_ui_skill --> pkg_client_ui_tool - pkg_client_ui_skill --> pkg_invariants - pkg_client_ui_skill --> pkg_session - pkg_client_ui_cordis --> pkg_api_remotes - pkg_client_ui_cordis --> pkg_client_connection - pkg_client_ui_cordis --> pkg_client_locale - pkg_client_ui_cordis --> pkg_client_ui_input_trigger - pkg_client_ui_cordis --> pkg_client_ui_renderer - pkg_client_ui_cordis --> pkg_client_ui_session - pkg_client_ui_cordis --> pkg_client_ui_sidebar - pkg_client_ui_cordis --> pkg_client_ui_tool - pkg_client_ui_cordis --> pkg_cordis_client_runner - pkg_client_ui_cordis --> pkg_invariants + pkg_subagent_dsh_sdk --> pkg_agent + pkg_subagent_dsh_sdk --> pkg_invariants + pkg_subagent_dsh_sdk --> pkg_llm + pkg_subagent_dsh_sdk --> pkg_sdk_client + pkg_subagent_dsh_sdk --> pkg_session + pkg_subagent_dsh_sdk --> pkg_subagent + pkg_subagent_dsh_sdk --> pkg_subprocess ``` -| Package | Group | Depends on | +| Package | Group | Peer dependencies | | --- | --- | --- | +| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | — | +| [`client-connection`](../packages/client/connection) | `client` | — | +| [`client-hmr`](../packages/client/hmr) | `client` | — | +| [`client-locale`](../packages/client/locale) | `client` | — | +| [`client-modules`](../packages/client/modules) | `client` | — | +| [`client-store`](../packages/client/store) | `client` | — | +| [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — | +| [`client-ui-approval`](../packages/client/ui-approval) | `client` | — | +| [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | — | +| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | — | +| [`client-ui-chat`](../packages/client/ui-chat) | `client` | — | +| [`client-ui-commands`](../packages/client/ui-commands) | `client` | — | +| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | — | +| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — | +| [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — | +| [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | +| [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | +| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | +| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — | +| [`client-ui-layout`](../packages/client/ui-layout) | `client` | — | +| [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | — | +| [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | — | +| [`client-ui-permission-presets`](../packages/client/ui-permission-presets) | `client` | — | +| [`client-ui-plan`](../packages/client/ui-plan) | `client` | — | +| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | — | +| [`client-ui-reference`](../packages/client/ui-reference) | `client` | — | +| [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | — | +| [`client-ui-schedule`](../packages/client/ui-schedule) | `client` | — | +| [`client-ui-session`](../packages/client/ui-session) | `client` | — | +| [`client-ui-settings`](../packages/client/ui-settings) | `client` | — | +| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | — | +| [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | — | +| [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | — | +| [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | — | +| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | — | +| [`client-ui-skill`](../packages/client/ui-skill) | `client` | — | +| [`client-ui-slots`](../packages/client/ui-slots) | `client` | — | +| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | — | +| [`client-ui-theme`](../packages/client/ui-theme) | `client` | — | +| [`client-ui-tool`](../packages/client/ui-tool) | `client` | — | +| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | — | +| [`client-ui-user-questions`](../packages/client/ui-user-questions) | `client` | — | +| [`client-ui-workflow-run`](../packages/client/ui-workflow-run) | `client` | — | +| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | — | +| [`client-web`](../packages/client/web) | `client` | — | +| [`client-ui-cordis`](../packages/extensions/ui-cordis) | `extensions` | — | +| [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | — | | [`invariants`](../packages/runtime-diagnostics/invariants) | `runtime-diagnostics` | — | +| [`typert-registry`](../packages/typert/registry) | `typert` | — | | [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`home-paths`](../packages/util/home-paths) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | @@ -1756,11 +1401,6 @@ flowchart TD | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`sdk-app`](../packages/bundle/sdk-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`sdk-minimal`](../packages/bundle/sdk-minimal) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-store`](../packages/client/store) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`code-runtime-python`](../packages/code-runtime/code-runtime-python) | `code-runtime` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`e2b`](../packages/e2b/e2b) | `e2b` | [`invariants`](../packages/runtime-diagnostics/invariants) | @@ -1777,38 +1417,34 @@ flowchart TD | [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) | | [`typert-protocol`](../packages/typert/protocol) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`llm`](../packages/llm/llm) | `llm` | [`typert-protocol`](../packages/typert/protocol) | +| [`session`](../packages/core/session) | `core` | [`scope`](../packages/core/scope) | +| [`api-gateway`](../packages/api/gateway) | `api` | [`typert-protocol`](../packages/typert/protocol) | +| [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) | | [`attachment`](../packages/attachment/attachment) | `attachment` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-modules`](../packages/client/modules) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/runtime-diagnostics/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | +| [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | -| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) | -| [`llm`](../packages/llm/llm) | `llm` | [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`typert-protocol`](../packages/typert/protocol) | -| [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) | -| [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`typert-protocol`](../packages/typert/protocol) | | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | -| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | -| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | -| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | -| [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | -| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | -| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | +| [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | -| [`persona`](../packages/preset/persona) | `preset` | [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) | +| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | +| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) | +| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-log-deepseek`](../packages/session/session-log-deepseek) | `session` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | @@ -1817,8 +1453,14 @@ flowchart TD | [`session-snapshot`](../packages/test-support/session-snapshot) | `test-support` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | +| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | +| [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | +| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | +| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`spill`](../packages/spill/spill) | +| [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) | +| [`persona`](../packages/preset/persona) | `preset` | [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | | [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | @@ -1837,6 +1479,7 @@ flowchart TD | [`skill-filesystem`](../packages/skill/skill-filesystem) | `skill` | [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) | | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | +| [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell) | @@ -1908,7 +1551,6 @@ flowchart TD | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) | | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) | -| [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`host-directory-picker`](../packages/host/directory-picker), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`tool-todo`](../packages/todo/tool-todo) | | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | @@ -1917,12 +1559,9 @@ flowchart TD | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | -| [`api-gateway`](../packages/api/gateway) | `api` | [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) | | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`typert-protocol`](../packages/typert/protocol) | | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs-local`](../packages/jobs/jobs-local), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`shell-env`](../packages/shell/shell-env), [`skill`](../packages/skill/skill), [`skill-filesystem`](../packages/skill/skill-filesystem), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/shell/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) | -| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`webhook-github`](../packages/webhook/webhook-github) | `webhook` | [`credentials`](../packages/credentials/credentials), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`webhook`](../packages/webhook/webhook) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | @@ -1933,57 +1572,15 @@ flowchart TD | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | -| [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`workflow-worker-thread`](../packages/workflow/workflow-worker-thread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | -| [`api-remotes`](../packages/api/remotes) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-settings-controller`](../packages/api/settings-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions) | -| [`client-ui-session`](../packages/client/ui-session) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-ui-renderer`](../packages/client/ui-renderer), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | +| [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-slots`](../packages/client/ui-slots), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | -| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | -| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-modules`](../packages/client/modules), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`util-crypto`](../packages/util/crypto), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | -| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`api-workspace-controller`](../packages/api/workspace-controller), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`schedule`](../packages/schedule/schedule), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`agent-presets`](../packages/preset/agent-presets), [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-approval`](../packages/client/ui-approval) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session) | -| [`client-ui-schedule`](../packages/client/ui-schedule) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`schedule`](../packages/schedule/schedule) | -| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`agent`](../packages/core/agent), [`api-session-controller`](../packages/api/session-controller), [`attachment`](../packages/attachment/attachment), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | -| [`client-ui-user-questions`](../packages/client/ui-user-questions) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol), [`user-questions`](../packages/interaction/user-questions) | -| [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-slots`](../packages/client/ui-slots), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-chat`](../packages/client/ui-chat) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-locale`](../packages/client/locale), [`client-ui-approval`](../packages/client/ui-approval), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-stats`](../packages/session/session-stats), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-commands`](../packages/client/ui-commands) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-reference`](../packages/client/ui-reference) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-reference`](../packages/context/session-reference), [`typert-protocol`](../packages/typert/protocol), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) | -| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-commands`](../packages/client/ui-commands), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | -| [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | [`attachment`](../packages/attachment/attachment), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-trajectory`](../packages/client/ui-trajectory), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | -| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-commands`](../packages/client/ui-commands), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-permission-presets`](../packages/client/ui-permission-presets) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-commands`](../packages/client/ui-commands), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`permission-presets`](../packages/interaction/permission-presets) | -| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`api-remotes`](../packages/api/remotes), [`api-workspace-controller`](../packages/api/workspace-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-workflow-run`](../packages/client/ui-workflow-run) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-cordis`](../packages/extensions/ui-cordis) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`client-ui-tool`](../packages/client/ui-tool), [`cordis-client-runner`](../packages/extensions/cordis-client-runner), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 4581a5bdda..9a5f72ef3d 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -1,11 +1,11 @@ - + -# 模块依赖关系图 +# 共享实例依赖关系图 [English](module-graph.md) | 中文 -`@deepseek-ai/dsh-*` harness 包之间的依赖关系。该关系图根据各包的 `peerDependencies`（规范的运行时依赖信号）生成，并按 `packages//` 层级分组。边 `a --> b` 表示包 `a` 依赖包 `b`。名称中的 `@deepseek-ai/dsh-` 前缀已移除。 +`@deepseek-ai/dsh-*` harness 包之间的 peer 依赖关系。peer 表示消费端需要提供共享实例，不包括普通运行时 dependency 或仅开发期关系。该图按 `packages//` 层级分组；边 `a --> b` 表示包 `a` peer 依赖包 `b`。名称中的 `@deepseek-ai/dsh-` 前缀已移除。 ```mermaid flowchart TD @@ -377,11 +377,6 @@ flowchart TD pkg_base --> pkg_invariants pkg_sdk_app --> pkg_invariants pkg_sdk_minimal --> pkg_invariants - pkg_client_store --> pkg_invariants - pkg_client_ui_primitives --> pkg_invariants - pkg_client_ui_renderer --> pkg_invariants - pkg_client_ui_slots --> pkg_invariants - pkg_client_web --> pkg_invariants pkg_code_runtime --> pkg_invariants pkg_code_runtime_python --> pkg_invariants pkg_e2b --> pkg_invariants @@ -398,18 +393,37 @@ flowchart TD pkg_win32_process --> pkg_invariants pkg_llm_mock_server --> pkg_invariants pkg_typert_generator --> pkg_invariants + pkg_typert_loader --> pkg_invariants + pkg_typert_loader --> pkg_typert_registry pkg_typert_protocol --> pkg_invariants - pkg_typert_registry --> pkg_invariants + pkg_llm --> pkg_typert_protocol + pkg_session --> pkg_scope + pkg_api_gateway --> pkg_typert_protocol + pkg_api_remotes --> pkg_scope pkg_attachment --> pkg_brand pkg_attachment --> pkg_invariants - pkg_client_modules --> pkg_host_webserver - pkg_client_modules --> pkg_invariants pkg_credentials --> pkg_brand pkg_credentials --> pkg_invariants pkg_subprocess_e2b --> pkg_e2b pkg_subprocess_e2b --> pkg_invariants pkg_subprocess_e2b --> pkg_subprocess pkg_subprocess_e2b --> pkg_timeout + pkg_experimental_inspector --> pkg_client_modules + pkg_experimental_inspector --> pkg_host_webserver + pkg_experimental_inspector --> pkg_invariants + pkg_experimental_webworker_runtime --> pkg_client_connection + pkg_experimental_webworker_runtime --> pkg_client_modules + pkg_experimental_webworker_runtime --> pkg_host_webserver + pkg_experimental_webworker_runtime --> pkg_invariants + pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse + pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native + pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse + pkg_host_directory_picker_auto --> pkg_host_directory_picker_native + pkg_host_directory_picker_auto --> pkg_host_webserver + pkg_host_directory_picker_auto --> pkg_invariants + pkg_host_frontend_static --> pkg_client_connection + pkg_host_frontend_static --> pkg_host_webserver + pkg_host_frontend_static --> pkg_invariants pkg_host_plugin_inventory --> pkg_brand pkg_host_plugin_inventory --> pkg_invariants pkg_host_plugin_inventory --> pkg_typert_protocol @@ -425,32 +439,6 @@ flowchart TD pkg_subprocess_local --> pkg_invariants pkg_subprocess_local --> pkg_subprocess pkg_subprocess_local --> pkg_timeout - pkg_typert_loader --> pkg_invariants - pkg_typert_loader --> pkg_typert_registry - pkg_llm --> pkg_attachment - pkg_llm --> pkg_brand - pkg_llm --> pkg_invariants - pkg_llm --> pkg_timeout - pkg_llm --> pkg_typert_protocol - pkg_attachment_local --> pkg_attachment - pkg_attachment_local --> pkg_home_paths - pkg_attachment_local --> pkg_invariants - pkg_client_hmr --> pkg_client_modules - pkg_client_hmr --> pkg_host_webserver - pkg_client_hmr --> pkg_invariants - pkg_credentials_local --> pkg_atomic_write - pkg_credentials_local --> pkg_credentials - pkg_credentials_local --> pkg_home_paths - pkg_credentials_local --> pkg_invariants - pkg_credentials_local --> pkg_launch_environment - pkg_experimental_inspector --> pkg_client_modules - pkg_experimental_inspector --> pkg_host_webserver - pkg_experimental_inspector --> pkg_invariants - pkg_session --> pkg_brand - pkg_session --> pkg_invariants - pkg_session --> pkg_llm - pkg_session --> pkg_scope - pkg_session --> pkg_typert_protocol pkg_system_prompt --> pkg_invariants pkg_system_prompt --> pkg_llm pkg_system_prompt --> pkg_scope @@ -459,37 +447,28 @@ flowchart TD pkg_skill --> pkg_scope pkg_web --> pkg_invariants pkg_web --> pkg_llm - pkg_authorization --> pkg_credentials - pkg_authorization --> pkg_invariants - pkg_authorization --> pkg_llm - pkg_lsp --> pkg_brand - pkg_lsp --> pkg_invariants - pkg_lsp --> pkg_llm - pkg_skill_badge --> pkg_invariants - pkg_skill_badge --> pkg_skill - pkg_web_fetch_http --> pkg_invariants - pkg_web_fetch_http --> pkg_timeout - pkg_web_fetch_http --> pkg_web - pkg_web_search_exa --> pkg_invariants - pkg_web_search_exa --> pkg_launch_environment - pkg_web_search_exa --> pkg_web - pkg_web_search_perplexity --> pkg_invariants - pkg_web_search_perplexity --> pkg_launch_environment - pkg_web_search_perplexity --> pkg_web pkg_spill --> pkg_brand pkg_spill --> pkg_invariants pkg_spill --> pkg_llm pkg_spill --> pkg_session - pkg_app_boot --> pkg_home_paths - pkg_app_boot --> pkg_invariants - pkg_app_boot --> pkg_launch_environment - pkg_app_boot --> pkg_system_prompt + pkg_attachment_local --> pkg_attachment + pkg_attachment_local --> pkg_home_paths + pkg_attachment_local --> pkg_invariants pkg_code_runtime_worker_thread --> pkg_code_runtime pkg_code_runtime_worker_thread --> pkg_invariants pkg_code_runtime_worker_thread --> pkg_session pkg_code_runtime_worker_thread --> pkg_timeout - pkg_persona --> pkg_invariants - pkg_persona --> pkg_system_prompt + pkg_authorization --> pkg_credentials + pkg_authorization --> pkg_invariants + pkg_authorization --> pkg_llm + pkg_credentials_local --> pkg_atomic_write + pkg_credentials_local --> pkg_credentials + pkg_credentials_local --> pkg_home_paths + pkg_credentials_local --> pkg_invariants + pkg_credentials_local --> pkg_launch_environment + pkg_lsp --> pkg_brand + pkg_lsp --> pkg_invariants + pkg_lsp --> pkg_llm pkg_sandbox --> pkg_invariants pkg_sandbox --> pkg_llm pkg_sandbox --> pkg_session @@ -518,8 +497,23 @@ flowchart TD pkg_fs --> pkg_invariants pkg_fs --> pkg_llm pkg_fs --> pkg_sandbox + pkg_skill_badge --> pkg_invariants + pkg_skill_badge --> pkg_skill + pkg_web_fetch_http --> pkg_invariants + pkg_web_fetch_http --> pkg_timeout + pkg_web_fetch_http --> pkg_web + pkg_web_search_exa --> pkg_invariants + pkg_web_search_exa --> pkg_launch_environment + pkg_web_search_exa --> pkg_web + pkg_web_search_perplexity --> pkg_invariants + pkg_web_search_perplexity --> pkg_launch_environment + pkg_web_search_perplexity --> pkg_web pkg_spill_local --> pkg_invariants pkg_spill_local --> pkg_spill + pkg_app_boot --> pkg_home_paths + pkg_app_boot --> pkg_invariants + pkg_app_boot --> pkg_launch_environment + pkg_app_boot --> pkg_system_prompt pkg_message_feedback --> pkg_brand pkg_message_feedback --> pkg_invariants pkg_message_feedback --> pkg_llm @@ -527,6 +521,8 @@ flowchart TD pkg_message_feedback --> pkg_session_persistence pkg_message_feedback --> pkg_storage_domain pkg_message_feedback --> pkg_typert_protocol + pkg_persona --> pkg_invariants + pkg_persona --> pkg_system_prompt pkg_sandbox_local --> pkg_invariants pkg_sandbox_local --> pkg_llm pkg_sandbox_local --> pkg_sandbox @@ -620,6 +616,14 @@ flowchart TD pkg_hook_protocol --> pkg_invariants pkg_hook_protocol --> pkg_session pkg_hook_protocol --> pkg_shell + pkg_api_workspace_controller --> pkg_api_gateway + pkg_api_workspace_controller --> pkg_client_connection + pkg_api_workspace_controller --> pkg_host_directory_picker + pkg_api_workspace_controller --> pkg_invariants + pkg_api_workspace_controller --> pkg_session + pkg_api_workspace_controller --> pkg_storage_domain + pkg_api_workspace_controller --> pkg_typert_protocol + pkg_api_workspace_controller --> pkg_workspace pkg_file_reference --> pkg_agent pkg_file_reference --> pkg_invariants pkg_time_context --> pkg_agent @@ -1034,17 +1038,6 @@ flowchart TD pkg_web_app --> pkg_invariants pkg_web_app --> pkg_shell_env pkg_web_app --> pkg_system_prompt - pkg_client_connection --> pkg_attachment - pkg_client_connection --> pkg_brand - pkg_client_connection --> pkg_commands - pkg_client_connection --> pkg_credentials - pkg_client_connection --> pkg_host_directory_picker - pkg_client_connection --> pkg_host_webserver - pkg_client_connection --> pkg_invariants - pkg_client_connection --> pkg_llm - pkg_client_connection --> pkg_session - pkg_client_connection --> pkg_settings - pkg_client_connection --> pkg_tool_todo pkg_compaction_tool_result_pruner --> pkg_compaction pkg_compaction_tool_result_pruner --> pkg_invariants pkg_compaction_tool_result_pruner --> pkg_llm @@ -1123,11 +1116,6 @@ flowchart TD pkg_tool_session_query --> pkg_system_prompt pkg_tool_session_query --> pkg_timeout pkg_tool_session_query --> pkg_tools - pkg_api_gateway --> pkg_brand - pkg_api_gateway --> pkg_client_connection - pkg_api_gateway --> pkg_host_webserver - pkg_api_gateway --> pkg_invariants - pkg_api_gateway --> pkg_typert_registry pkg_compaction_basic --> pkg_agent pkg_compaction_basic --> pkg_commands pkg_compaction_basic --> pkg_compaction @@ -1169,13 +1157,6 @@ flowchart TD pkg_agent_spine_demo --> pkg_tool_jobs pkg_agent_spine_demo --> pkg_tool_skill pkg_agent_spine_demo --> pkg_tools - pkg_experimental_webworker_runtime --> pkg_client_connection - pkg_experimental_webworker_runtime --> pkg_client_modules - pkg_experimental_webworker_runtime --> pkg_host_webserver - pkg_experimental_webworker_runtime --> pkg_invariants - pkg_host_frontend_static --> pkg_client_connection - pkg_host_frontend_static --> pkg_host_webserver - pkg_host_frontend_static --> pkg_invariants pkg_webhook_github --> pkg_credentials pkg_webhook_github --> pkg_host_webserver pkg_webhook_github --> pkg_invariants @@ -1263,14 +1244,6 @@ flowchart TD pkg_api_session_controller --> pkg_util_time pkg_api_session_controller --> pkg_util_workspace_path pkg_api_session_controller --> pkg_workspace - pkg_api_workspace_controller --> pkg_api_gateway - pkg_api_workspace_controller --> pkg_client_connection - pkg_api_workspace_controller --> pkg_host_directory_picker - pkg_api_workspace_controller --> pkg_invariants - pkg_api_workspace_controller --> pkg_session - pkg_api_workspace_controller --> pkg_storage_domain - pkg_api_workspace_controller --> pkg_typert_protocol - pkg_api_workspace_controller --> pkg_workspace pkg_experimental_agent_team --> pkg_agent pkg_experimental_agent_team --> pkg_brand pkg_experimental_agent_team --> pkg_invariants @@ -1307,30 +1280,18 @@ flowchart TD pkg_subagent_spawn_in_process --> pkg_invariants pkg_subagent_spawn_in_process --> pkg_subagent pkg_subagent_spawn_in_process --> pkg_subagent_in_process_driver - pkg_api_remotes --> pkg_agent_presets - pkg_api_remotes --> pkg_api_gateway - pkg_api_remotes --> pkg_api_session_controller - pkg_api_remotes --> pkg_api_settings_controller - pkg_api_remotes --> pkg_api_workspace_controller - pkg_api_remotes --> pkg_commands - pkg_api_remotes --> pkg_cordis_host_runner - pkg_api_remotes --> pkg_credentials - pkg_api_remotes --> pkg_file_reference - pkg_api_remotes --> pkg_goal - pkg_api_remotes --> pkg_host_plugin_inventory - pkg_api_remotes --> pkg_invariants - pkg_api_remotes --> pkg_llm - pkg_api_remotes --> pkg_message_feedback - pkg_api_remotes --> pkg_session - pkg_api_remotes --> pkg_session_reference - pkg_api_remotes --> pkg_settings - pkg_api_remotes --> pkg_subagent - pkg_api_remotes --> pkg_user_approval - pkg_api_remotes --> pkg_user_questions - pkg_client_ui_session --> pkg_api_session_controller - pkg_client_ui_session --> pkg_client_ui_renderer - pkg_client_ui_session --> pkg_invariants - pkg_client_ui_session --> pkg_session + pkg_experimental_client_ui_agent_team --> pkg_api_remotes + pkg_experimental_client_ui_agent_team --> pkg_api_session_controller + pkg_experimental_client_ui_agent_team --> pkg_client_locale + pkg_experimental_client_ui_agent_team --> pkg_client_ui_conversation + pkg_experimental_client_ui_agent_team --> pkg_client_ui_primitives + pkg_experimental_client_ui_agent_team --> pkg_client_ui_renderer + pkg_experimental_client_ui_agent_team --> pkg_client_ui_session + pkg_experimental_client_ui_agent_team --> pkg_client_ui_slots + pkg_experimental_client_ui_agent_team --> pkg_experimental_agent_team + pkg_experimental_client_ui_agent_team --> pkg_invariants + pkg_experimental_client_ui_agent_team --> pkg_session + pkg_experimental_client_ui_agent_team --> pkg_typert_protocol pkg_experimental_tool_agent_team --> pkg_agent pkg_experimental_tool_agent_team --> pkg_experimental_agent_team pkg_experimental_tool_agent_team --> pkg_invariants @@ -1350,358 +1311,6 @@ flowchart TD pkg_sdk_jsonrpc_server --> pkg_sdk_protocol pkg_sdk_jsonrpc_server --> pkg_session pkg_sdk_jsonrpc_server --> pkg_subagent - pkg_subagent_dsh_sdk --> pkg_agent - pkg_subagent_dsh_sdk --> pkg_invariants - pkg_subagent_dsh_sdk --> pkg_llm - pkg_subagent_dsh_sdk --> pkg_sdk_client - pkg_subagent_dsh_sdk --> pkg_session - pkg_subagent_dsh_sdk --> pkg_subagent - pkg_subagent_dsh_sdk --> pkg_subprocess - pkg_client_ui_settings --> pkg_api_remotes - pkg_client_ui_settings --> pkg_invariants - pkg_client_ui_settings --> pkg_settings - pkg_client_locale --> pkg_api_remotes - pkg_client_locale --> pkg_client_connection - pkg_client_locale --> pkg_client_ui_renderer - pkg_client_locale --> pkg_client_ui_settings - pkg_client_locale --> pkg_invariants - pkg_client_locale --> pkg_settings - pkg_client_ui_settings_models --> pkg_api_remotes - pkg_client_ui_settings_models --> pkg_client_locale - pkg_client_ui_settings_models --> pkg_client_ui_renderer - pkg_client_ui_settings_models --> pkg_client_ui_settings - pkg_client_ui_settings_models --> pkg_invariants - pkg_client_ui_settings_plugin_inventory --> pkg_api_remotes - pkg_client_ui_settings_plugin_inventory --> pkg_client_locale - pkg_client_ui_settings_plugin_inventory --> pkg_client_ui_renderer - pkg_client_ui_settings_plugin_inventory --> pkg_client_ui_settings - pkg_client_ui_settings_plugin_inventory --> pkg_invariants - pkg_client_ui_settings_plugins --> pkg_api_remotes - pkg_client_ui_settings_plugins --> pkg_client_locale - pkg_client_ui_settings_plugins --> pkg_client_ui_renderer - pkg_client_ui_settings_plugins --> pkg_client_ui_settings - pkg_client_ui_settings_plugins --> pkg_invariants - pkg_client_ui_theme --> pkg_api_remotes - pkg_client_ui_theme --> pkg_client_connection - pkg_client_ui_theme --> pkg_client_locale - pkg_client_ui_theme --> pkg_client_ui_renderer - pkg_client_ui_theme --> pkg_client_ui_settings - pkg_client_ui_theme --> pkg_host_webserver - pkg_client_ui_theme --> pkg_invariants - pkg_client_ui_theme --> pkg_settings - pkg_client_ui_layout --> pkg_client_locale - pkg_client_ui_layout --> pkg_client_ui_renderer - pkg_client_ui_layout --> pkg_client_ui_session - pkg_client_ui_layout --> pkg_client_ui_theme - pkg_client_ui_layout --> pkg_invariants - pkg_cordis_client_runner --> pkg_api_remotes - pkg_cordis_client_runner --> pkg_client_modules - pkg_cordis_client_runner --> pkg_client_ui_renderer - pkg_cordis_client_runner --> pkg_client_ui_theme - pkg_cordis_client_runner --> pkg_invariants - pkg_client_ui_conversation --> pkg_api_remotes - pkg_client_ui_conversation --> pkg_api_session_controller - pkg_client_ui_conversation --> pkg_api_workspace_controller - pkg_client_ui_conversation --> pkg_attachment - pkg_client_ui_conversation --> pkg_brand - pkg_client_ui_conversation --> pkg_client_locale - pkg_client_ui_conversation --> pkg_client_ui_layout - pkg_client_ui_conversation --> pkg_client_ui_renderer - pkg_client_ui_conversation --> pkg_client_ui_session - pkg_client_ui_conversation --> pkg_client_ui_settings - pkg_client_ui_conversation --> pkg_client_ui_workspace - pkg_client_ui_conversation --> pkg_commands - pkg_client_ui_conversation --> pkg_goal - pkg_client_ui_conversation --> pkg_invariants - pkg_client_ui_conversation --> pkg_llm - pkg_client_ui_conversation --> pkg_llm_retry - pkg_client_ui_conversation --> pkg_permission_presets - pkg_client_ui_conversation --> pkg_plan_mode - pkg_client_ui_conversation --> pkg_session - pkg_client_ui_conversation --> pkg_settings - pkg_client_ui_conversation --> pkg_token_meter - pkg_client_ui_conversation --> pkg_tool_todo - pkg_client_ui_conversation --> pkg_util_crypto - pkg_client_ui_conversation --> pkg_util_workspace_path - pkg_client_ui_conversation --> pkg_workspace - pkg_client_ui_sidebar --> pkg_api_workspace_controller - pkg_client_ui_sidebar --> pkg_client_locale - pkg_client_ui_sidebar --> pkg_client_ui_layout - pkg_client_ui_sidebar --> pkg_client_ui_renderer - pkg_client_ui_sidebar --> pkg_client_ui_session - pkg_client_ui_sidebar --> pkg_client_ui_workspace - pkg_client_ui_sidebar --> pkg_invariants - pkg_client_ui_workspace --> pkg_api_remotes - pkg_client_ui_workspace --> pkg_api_session_controller - pkg_client_ui_workspace --> pkg_api_workspace_controller - pkg_client_ui_workspace --> pkg_client_connection - pkg_client_ui_workspace --> pkg_client_locale - pkg_client_ui_workspace --> pkg_client_ui_conversation - pkg_client_ui_workspace --> pkg_client_ui_renderer - pkg_client_ui_workspace --> pkg_client_ui_session - pkg_client_ui_workspace --> pkg_client_ui_sidebar - pkg_client_ui_workspace --> pkg_invariants - pkg_client_ui_workspace --> pkg_schedule - pkg_client_ui_workspace --> pkg_session - pkg_client_ui_workspace --> pkg_typert_protocol - pkg_client_ui_workspace --> pkg_util_workspace_path - pkg_client_ui_agent_preset --> pkg_agent_presets - pkg_client_ui_agent_preset --> pkg_api_remotes - pkg_client_ui_agent_preset --> pkg_api_session_controller - pkg_client_ui_agent_preset --> pkg_client_connection - pkg_client_ui_agent_preset --> pkg_client_locale - pkg_client_ui_agent_preset --> pkg_client_ui_conversation - pkg_client_ui_agent_preset --> pkg_client_ui_renderer - pkg_client_ui_agent_preset --> pkg_client_ui_session - pkg_client_ui_agent_preset --> pkg_client_ui_settings - pkg_client_ui_agent_preset --> pkg_client_ui_workspace - pkg_client_ui_agent_preset --> pkg_invariants - pkg_client_ui_agent_preset --> pkg_session - pkg_client_ui_approval --> pkg_api_remotes - pkg_client_ui_approval --> pkg_api_session_controller - pkg_client_ui_approval --> pkg_client_locale - pkg_client_ui_approval --> pkg_client_ui_conversation - pkg_client_ui_approval --> pkg_client_ui_renderer - pkg_client_ui_approval --> pkg_client_ui_session - pkg_client_ui_approval --> pkg_invariants - pkg_client_ui_approval --> pkg_llm - pkg_client_ui_approval --> pkg_session - pkg_client_ui_approval --> pkg_typert_protocol - pkg_client_ui_brand_official --> pkg_client_ui_renderer - pkg_client_ui_brand_official --> pkg_client_ui_sidebar - pkg_client_ui_brand_official --> pkg_invariants - pkg_client_ui_directory_picker_browse --> pkg_api_remotes - pkg_client_ui_directory_picker_browse --> pkg_client_locale - pkg_client_ui_directory_picker_browse --> pkg_client_ui_renderer - pkg_client_ui_directory_picker_browse --> pkg_client_ui_workspace - pkg_client_ui_directory_picker_browse --> pkg_invariants - pkg_client_ui_directory_picker_native --> pkg_client_ui_renderer - pkg_client_ui_directory_picker_native --> pkg_client_ui_workspace - pkg_client_ui_directory_picker_native --> pkg_invariants - pkg_client_ui_input_trigger --> pkg_api_session_controller - pkg_client_ui_input_trigger --> pkg_client_locale - pkg_client_ui_input_trigger --> pkg_client_ui_conversation - pkg_client_ui_input_trigger --> pkg_client_ui_renderer - pkg_client_ui_input_trigger --> pkg_client_ui_session - pkg_client_ui_input_trigger --> pkg_file_reference - pkg_client_ui_input_trigger --> pkg_invariants - pkg_client_ui_input_trigger --> pkg_session - pkg_client_ui_jobs --> pkg_api_session_controller - pkg_client_ui_jobs --> pkg_client_locale - pkg_client_ui_jobs --> pkg_client_ui_conversation - pkg_client_ui_jobs --> pkg_client_ui_renderer - pkg_client_ui_jobs --> pkg_client_ui_session - pkg_client_ui_jobs --> pkg_invariants - pkg_client_ui_plan --> pkg_api_remotes - pkg_client_ui_plan --> pkg_client_locale - pkg_client_ui_plan --> pkg_client_ui_conversation - pkg_client_ui_plan --> pkg_client_ui_renderer - pkg_client_ui_plan --> pkg_client_ui_session - pkg_client_ui_plan --> pkg_invariants - pkg_client_ui_plan --> pkg_plan_mode - pkg_client_ui_plan --> pkg_session - pkg_client_ui_schedule --> pkg_api_session_controller - pkg_client_ui_schedule --> pkg_client_locale - pkg_client_ui_schedule --> pkg_client_ui_conversation - pkg_client_ui_schedule --> pkg_client_ui_renderer - pkg_client_ui_schedule --> pkg_client_ui_session - pkg_client_ui_schedule --> pkg_invariants - pkg_client_ui_schedule --> pkg_schedule - pkg_client_ui_settings_general --> pkg_api_remotes - pkg_client_ui_settings_general --> pkg_client_connection - pkg_client_ui_settings_general --> pkg_client_locale - pkg_client_ui_settings_general --> pkg_client_ui_renderer - pkg_client_ui_settings_general --> pkg_client_ui_session - pkg_client_ui_settings_general --> pkg_client_ui_settings - pkg_client_ui_settings_general --> pkg_client_ui_sidebar - pkg_client_ui_settings_general --> pkg_invariants - pkg_client_ui_settings_general --> pkg_settings - pkg_client_ui_trajectory --> pkg_agent - pkg_client_ui_trajectory --> pkg_api_session_controller - pkg_client_ui_trajectory --> pkg_attachment - pkg_client_ui_trajectory --> pkg_client_locale - pkg_client_ui_trajectory --> pkg_client_ui_conversation - pkg_client_ui_trajectory --> pkg_client_ui_renderer - pkg_client_ui_trajectory --> pkg_client_ui_session - pkg_client_ui_trajectory --> pkg_compaction - pkg_client_ui_trajectory --> pkg_invariants - pkg_client_ui_trajectory --> pkg_llm - pkg_client_ui_trajectory --> pkg_session - pkg_client_ui_trajectory --> pkg_tools - pkg_client_ui_user_questions --> pkg_api_remotes - pkg_client_ui_user_questions --> pkg_api_session_controller - pkg_client_ui_user_questions --> pkg_client_locale - pkg_client_ui_user_questions --> pkg_client_ui_conversation - pkg_client_ui_user_questions --> pkg_client_ui_renderer - pkg_client_ui_user_questions --> pkg_client_ui_session - pkg_client_ui_user_questions --> pkg_invariants - pkg_client_ui_user_questions --> pkg_session - pkg_client_ui_user_questions --> pkg_typert_protocol - pkg_client_ui_user_questions --> pkg_user_questions - pkg_experimental_client_ui_agent_team --> pkg_api_remotes - pkg_experimental_client_ui_agent_team --> pkg_api_session_controller - pkg_experimental_client_ui_agent_team --> pkg_client_locale - pkg_experimental_client_ui_agent_team --> pkg_client_ui_conversation - pkg_experimental_client_ui_agent_team --> pkg_client_ui_primitives - pkg_experimental_client_ui_agent_team --> pkg_client_ui_renderer - pkg_experimental_client_ui_agent_team --> pkg_client_ui_session - pkg_experimental_client_ui_agent_team --> pkg_client_ui_slots - pkg_experimental_client_ui_agent_team --> pkg_experimental_agent_team - pkg_experimental_client_ui_agent_team --> pkg_invariants - pkg_experimental_client_ui_agent_team --> pkg_session - pkg_experimental_client_ui_agent_team --> pkg_typert_protocol - pkg_client_ui_chat --> pkg_agent - pkg_client_ui_chat --> pkg_api_remotes - pkg_client_ui_chat --> pkg_api_session_controller - pkg_client_ui_chat --> pkg_api_workspace_controller - pkg_client_ui_chat --> pkg_attachment - pkg_client_ui_chat --> pkg_client_locale - pkg_client_ui_chat --> pkg_client_ui_approval - pkg_client_ui_chat --> pkg_client_ui_conversation - pkg_client_ui_chat --> pkg_client_ui_layout - pkg_client_ui_chat --> pkg_client_ui_renderer - pkg_client_ui_chat --> pkg_client_ui_session - pkg_client_ui_chat --> pkg_client_ui_settings - pkg_client_ui_chat --> pkg_client_ui_workspace - pkg_client_ui_chat --> pkg_commands - pkg_client_ui_chat --> pkg_compaction - pkg_client_ui_chat --> pkg_invariants - pkg_client_ui_chat --> pkg_llm - pkg_client_ui_chat --> pkg_llm_retry - pkg_client_ui_chat --> pkg_session - pkg_client_ui_chat --> pkg_session_stats - pkg_client_ui_chat --> pkg_settings - pkg_client_ui_chat --> pkg_token_meter - pkg_client_ui_chat --> pkg_tools - pkg_client_ui_chat --> pkg_util_workspace_path - pkg_client_ui_commands --> pkg_api_remotes - pkg_client_ui_commands --> pkg_api_session_controller - pkg_client_ui_commands --> pkg_client_locale - pkg_client_ui_commands --> pkg_client_ui_conversation - pkg_client_ui_commands --> pkg_client_ui_input_trigger - pkg_client_ui_commands --> pkg_client_ui_renderer - pkg_client_ui_commands --> pkg_client_ui_session - pkg_client_ui_commands --> pkg_commands - pkg_client_ui_commands --> pkg_invariants - pkg_client_ui_commands --> pkg_session - pkg_client_ui_reference --> pkg_api_remotes - pkg_client_ui_reference --> pkg_api_session_controller - pkg_client_ui_reference --> pkg_client_connection - pkg_client_ui_reference --> pkg_client_locale - pkg_client_ui_reference --> pkg_client_ui_input_trigger - pkg_client_ui_reference --> pkg_file_reference - pkg_client_ui_reference --> pkg_invariants - pkg_client_ui_reference --> pkg_session_reference - pkg_client_ui_reference --> pkg_typert_protocol - pkg_client_ui_reference --> pkg_util_workspace_path - pkg_client_ui_subagent --> pkg_api_session_controller - pkg_client_ui_subagent --> pkg_client_connection - pkg_client_ui_subagent --> pkg_client_locale - pkg_client_ui_subagent --> pkg_client_ui_conversation - pkg_client_ui_subagent --> pkg_client_ui_input_trigger - pkg_client_ui_subagent --> pkg_client_ui_renderer - pkg_client_ui_subagent --> pkg_client_ui_session - pkg_client_ui_subagent --> pkg_invariants - pkg_client_ui_subagent --> pkg_session - pkg_client_ui_subagent --> pkg_subagent - pkg_client_ui_subagent --> pkg_token_meter - pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_browse - pkg_host_directory_picker_auto --> pkg_client_ui_directory_picker_native - pkg_host_directory_picker_auto --> pkg_host_directory_picker_browse - pkg_host_directory_picker_auto --> pkg_host_directory_picker_native - pkg_host_directory_picker_auto --> pkg_host_webserver - pkg_host_directory_picker_auto --> pkg_invariants - pkg_session_log_export --> pkg_attachment - pkg_session_log_export --> pkg_client_connection - pkg_session_log_export --> pkg_client_locale - pkg_session_log_export --> pkg_client_ui_commands - pkg_session_log_export --> pkg_client_ui_conversation - pkg_session_log_export --> pkg_client_ui_renderer - pkg_session_log_export --> pkg_client_ui_session - pkg_session_log_export --> pkg_commands - pkg_session_log_export --> pkg_invariants - pkg_session_log_export --> pkg_session - pkg_session_log_export --> pkg_session_persistence - pkg_session_log_export --> pkg_session_query - pkg_client_ui_attachment --> pkg_attachment - pkg_client_ui_attachment --> pkg_client_ui_chat - pkg_client_ui_attachment --> pkg_client_ui_conversation - pkg_client_ui_attachment --> pkg_client_ui_renderer - pkg_client_ui_attachment --> pkg_client_ui_trajectory - pkg_client_ui_attachment --> pkg_invariants - pkg_client_ui_deliverables --> pkg_api_remotes - pkg_client_ui_deliverables --> pkg_client_connection - pkg_client_ui_deliverables --> pkg_client_locale - pkg_client_ui_deliverables --> pkg_client_ui_chat - pkg_client_ui_deliverables --> pkg_client_ui_conversation - pkg_client_ui_deliverables --> pkg_client_ui_renderer - pkg_client_ui_deliverables --> pkg_invariants - pkg_client_ui_deliverables --> pkg_session - pkg_client_ui_deliverables --> pkg_system_prompt - pkg_client_ui_goal --> pkg_api_remotes - pkg_client_ui_goal --> pkg_api_session_controller - pkg_client_ui_goal --> pkg_client_locale - pkg_client_ui_goal --> pkg_client_ui_chat - pkg_client_ui_goal --> pkg_client_ui_conversation - pkg_client_ui_goal --> pkg_client_ui_renderer - pkg_client_ui_goal --> pkg_client_ui_session - pkg_client_ui_goal --> pkg_commands - pkg_client_ui_goal --> pkg_goal - pkg_client_ui_goal --> pkg_invariants - pkg_client_ui_goal --> pkg_session - pkg_client_ui_goal --> pkg_typert_protocol - pkg_client_ui_message_feedback --> pkg_api_remotes - pkg_client_ui_message_feedback --> pkg_client_connection - pkg_client_ui_message_feedback --> pkg_client_locale - pkg_client_ui_message_feedback --> pkg_client_ui_chat - pkg_client_ui_message_feedback --> pkg_client_ui_conversation - pkg_client_ui_message_feedback --> pkg_client_ui_renderer - pkg_client_ui_message_feedback --> pkg_client_ui_session - pkg_client_ui_message_feedback --> pkg_invariants - pkg_client_ui_message_feedback --> pkg_message_feedback - pkg_client_ui_message_feedback --> pkg_session - pkg_client_ui_message_feedback --> pkg_typert_protocol - pkg_client_ui_model_selection --> pkg_api_remotes - pkg_client_ui_model_selection --> pkg_api_session_controller - pkg_client_ui_model_selection --> pkg_client_locale - pkg_client_ui_model_selection --> pkg_client_ui_commands - pkg_client_ui_model_selection --> pkg_client_ui_conversation - pkg_client_ui_model_selection --> pkg_client_ui_input_trigger - pkg_client_ui_model_selection --> pkg_client_ui_renderer - pkg_client_ui_model_selection --> pkg_client_ui_session - pkg_client_ui_model_selection --> pkg_invariants - pkg_client_ui_model_selection --> pkg_session - pkg_client_ui_model_selection --> pkg_typert_protocol - pkg_client_ui_permission_presets --> pkg_api_remotes - pkg_client_ui_permission_presets --> pkg_api_session_controller - pkg_client_ui_permission_presets --> pkg_client_locale - pkg_client_ui_permission_presets --> pkg_client_ui_commands - pkg_client_ui_permission_presets --> pkg_client_ui_input_trigger - pkg_client_ui_permission_presets --> pkg_client_ui_renderer - pkg_client_ui_permission_presets --> pkg_client_ui_session - pkg_client_ui_permission_presets --> pkg_client_ui_settings - pkg_client_ui_permission_presets --> pkg_invariants - pkg_client_ui_permission_presets --> pkg_permission_presets - pkg_client_ui_tool --> pkg_api_remotes - pkg_client_ui_tool --> pkg_api_workspace_controller - pkg_client_ui_tool --> pkg_client_connection - pkg_client_ui_tool --> pkg_client_locale - pkg_client_ui_tool --> pkg_client_ui_chat - pkg_client_ui_tool --> pkg_client_ui_conversation - pkg_client_ui_tool --> pkg_client_ui_renderer - pkg_client_ui_tool --> pkg_client_ui_session - pkg_client_ui_tool --> pkg_invariants - pkg_client_ui_tool --> pkg_util_workspace_path - pkg_client_ui_workflow_run --> pkg_api_session_controller - pkg_client_ui_workflow_run --> pkg_client_locale - pkg_client_ui_workflow_run --> pkg_client_ui_chat - pkg_client_ui_workflow_run --> pkg_client_ui_conversation - pkg_client_ui_workflow_run --> pkg_client_ui_renderer - pkg_client_ui_workflow_run --> pkg_client_ui_session - pkg_client_ui_workflow_run --> pkg_invariants - pkg_client_ui_workflow_run --> pkg_session - pkg_client_ui_workflow_run --> pkg_tool_workflow - pkg_client_ui_workflow_run --> pkg_workflow pkg_client_test_runtime --> pkg_api_session_controller pkg_client_test_runtime --> pkg_api_workspace_controller pkg_client_test_runtime --> pkg_attachment @@ -1717,30 +1326,66 @@ flowchart TD pkg_client_test_runtime --> pkg_session pkg_client_test_runtime --> pkg_subagent pkg_client_test_runtime --> pkg_typert_protocol - pkg_client_ui_skill --> pkg_api_remotes - pkg_client_ui_skill --> pkg_api_session_controller - pkg_client_ui_skill --> pkg_client_connection - pkg_client_ui_skill --> pkg_client_locale - pkg_client_ui_skill --> pkg_client_ui_input_trigger - pkg_client_ui_skill --> pkg_client_ui_renderer - pkg_client_ui_skill --> pkg_client_ui_tool - pkg_client_ui_skill --> pkg_invariants - pkg_client_ui_skill --> pkg_session - pkg_client_ui_cordis --> pkg_api_remotes - pkg_client_ui_cordis --> pkg_client_connection - pkg_client_ui_cordis --> pkg_client_locale - pkg_client_ui_cordis --> pkg_client_ui_input_trigger - pkg_client_ui_cordis --> pkg_client_ui_renderer - pkg_client_ui_cordis --> pkg_client_ui_session - pkg_client_ui_cordis --> pkg_client_ui_sidebar - pkg_client_ui_cordis --> pkg_client_ui_tool - pkg_client_ui_cordis --> pkg_cordis_client_runner - pkg_client_ui_cordis --> pkg_invariants + pkg_subagent_dsh_sdk --> pkg_agent + pkg_subagent_dsh_sdk --> pkg_invariants + pkg_subagent_dsh_sdk --> pkg_llm + pkg_subagent_dsh_sdk --> pkg_sdk_client + pkg_subagent_dsh_sdk --> pkg_session + pkg_subagent_dsh_sdk --> pkg_subagent + pkg_subagent_dsh_sdk --> pkg_subprocess ``` -| Package | Group | Depends on | +| 包 | 分组 | Peer 依赖 | | --- | --- | --- | +| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | — | +| [`client-connection`](../packages/client/connection) | `client` | — | +| [`client-hmr`](../packages/client/hmr) | `client` | — | +| [`client-locale`](../packages/client/locale) | `client` | — | +| [`client-modules`](../packages/client/modules) | `client` | — | +| [`client-store`](../packages/client/store) | `client` | — | +| [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | — | +| [`client-ui-approval`](../packages/client/ui-approval) | `client` | — | +| [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | — | +| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | — | +| [`client-ui-chat`](../packages/client/ui-chat) | `client` | — | +| [`client-ui-commands`](../packages/client/ui-commands) | `client` | — | +| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | — | +| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | — | +| [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | — | +| [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | — | +| [`client-ui-goal`](../packages/client/ui-goal) | `client` | — | +| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | — | +| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | — | +| [`client-ui-layout`](../packages/client/ui-layout) | `client` | — | +| [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | — | +| [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | — | +| [`client-ui-permission-presets`](../packages/client/ui-permission-presets) | `client` | — | +| [`client-ui-plan`](../packages/client/ui-plan) | `client` | — | +| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | — | +| [`client-ui-reference`](../packages/client/ui-reference) | `client` | — | +| [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | — | +| [`client-ui-schedule`](../packages/client/ui-schedule) | `client` | — | +| [`client-ui-session`](../packages/client/ui-session) | `client` | — | +| [`client-ui-settings`](../packages/client/ui-settings) | `client` | — | +| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | — | +| [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | — | +| [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | — | +| [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | — | +| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | — | +| [`client-ui-skill`](../packages/client/ui-skill) | `client` | — | +| [`client-ui-slots`](../packages/client/ui-slots) | `client` | — | +| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | — | +| [`client-ui-theme`](../packages/client/ui-theme) | `client` | — | +| [`client-ui-tool`](../packages/client/ui-tool) | `client` | — | +| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | — | +| [`client-ui-user-questions`](../packages/client/ui-user-questions) | `client` | — | +| [`client-ui-workflow-run`](../packages/client/ui-workflow-run) | `client` | — | +| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | — | +| [`client-web`](../packages/client/web) | `client` | — | +| [`client-ui-cordis`](../packages/extensions/ui-cordis) | `extensions` | — | +| [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | — | | [`invariants`](../packages/runtime-diagnostics/invariants) | `runtime-diagnostics` | — | +| [`typert-registry`](../packages/typert/registry) | `typert` | — | | [`atomic-write`](../packages/util/atomic-write) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`home-paths`](../packages/util/home-paths) | `util` | [`invariants`](../packages/runtime-diagnostics/invariants) | @@ -1758,11 +1403,6 @@ flowchart TD | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`sdk-app`](../packages/bundle/sdk-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`sdk-minimal`](../packages/bundle/sdk-minimal) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-store`](../packages/client/store) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-primitives`](../packages/client/ui-primitives) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-renderer`](../packages/client/ui-renderer) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-slots`](../packages/client/ui-slots) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-web`](../packages/client/web) | `client` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`code-runtime-python`](../packages/code-runtime/code-runtime-python) | `code-runtime` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`e2b`](../packages/e2b/e2b) | `e2b` | [`invariants`](../packages/runtime-diagnostics/invariants) | @@ -1779,38 +1419,34 @@ flowchart TD | [`win32-process`](../packages/subprocess/win32-process) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`llm-mock-server`](../packages/test-support/llm-mock-server) | `test-support` | [`invariants`](../packages/runtime-diagnostics/invariants) | | [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) | | [`typert-protocol`](../packages/typert/protocol) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`llm`](../packages/llm/llm) | `llm` | [`typert-protocol`](../packages/typert/protocol) | +| [`session`](../packages/core/session) | `core` | [`scope`](../packages/core/scope) | +| [`api-gateway`](../packages/api/gateway) | `api` | [`typert-protocol`](../packages/typert/protocol) | +| [`api-remotes`](../packages/api/remotes) | `api` | [`scope`](../packages/core/scope) | | [`attachment`](../packages/attachment/attachment) | `attachment` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-modules`](../packages/client/modules) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/runtime-diagnostics/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | +| [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/runtime-diagnostics/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | -| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) | -| [`llm`](../packages/llm/llm) | `llm` | [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`typert-protocol`](../packages/typert/protocol) | -| [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) | -| [`experimental-inspector`](../packages/experimental/inspector) | `experimental` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`typert-protocol`](../packages/typert/protocol) | | [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) | | [`web`](../packages/web/web) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | -| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | -| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | -| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | -| [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | -| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | -| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | | [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | -| [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | +| [`attachment-local`](../packages/attachment/attachment-local) | `attachment` | [`attachment`](../packages/attachment/attachment), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`code-runtime-worker-thread`](../packages/code-runtime/code-runtime-worker-thread) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | -| [`persona`](../packages/preset/persona) | `preset` | [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) | +| [`authorization`](../packages/credentials/authorization) | `credentials` | [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | +| [`credentials-local`](../packages/credentials/credentials-local) | `credentials` | [`atomic-write`](../packages/util/atomic-write), [`credentials`](../packages/credentials/credentials), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment) | +| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm) | | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) | | [`session-log-deepseek`](../packages/session/session-log-deepseek) | `session` | [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`session-persistence`](../packages/session/session-persistence) | `session` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) | @@ -1819,8 +1455,14 @@ flowchart TD | [`session-snapshot`](../packages/test-support/session-snapshot) | `test-support` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | | [`agent`](../packages/core/agent) | `core` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`typert-protocol`](../packages/typert/protocol) | | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) | +| [`skill-badge`](../packages/skill/skill-badge) | `skill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | +| [`web-fetch-http`](../packages/web/web-fetch-http) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) | +| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | +| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`web`](../packages/web/web) | | [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/runtime-diagnostics/invariants), [`spill`](../packages/spill/spill) | +| [`app-boot`](../packages/boot/app-boot) | `boot` | [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`system-prompt`](../packages/core/system-prompt) | | [`message-feedback`](../packages/feedback/message-feedback) | `feedback` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol) | +| [`persona`](../packages/preset/persona) | `preset` | [`invariants`](../packages/runtime-diagnostics/invariants), [`system-prompt`](../packages/core/system-prompt) | | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | | [`session-persistence-sqlite`](../packages/session/session-persistence-sqlite) | `session` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence) | @@ -1839,6 +1481,7 @@ flowchart TD | [`skill-filesystem`](../packages/skill/skill-filesystem) | `skill` | [`fs`](../packages/fs/fs), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`skill`](../packages/skill/skill) | | [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`web`](../packages/web/web) | | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`shell`](../packages/shell/shell) | +| [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`file-reference`](../packages/context/file-reference) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) | | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`shell`](../packages/shell/shell) | @@ -1910,7 +1553,6 @@ flowchart TD | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) | | [`api-settings-controller`](../packages/api/settings-controller) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`credentials`](../packages/credentials/credentials), [`invariants`](../packages/runtime-diagnostics/invariants), [`native-command`](../packages/util/native-command), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`typert-protocol`](../packages/typert/protocol) | | [`web-app`](../packages/bundle/web-app) | `bundle` | [`invariants`](../packages/runtime-diagnostics/invariants), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt) | -| [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`host-directory-picker`](../packages/host/directory-picker), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`tool-todo`](../packages/todo/tool-todo) | | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | @@ -1919,12 +1561,9 @@ flowchart TD | [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time) | | [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | | [`tool-session-query`](../packages/session-query/tool-session-query) | `session-query` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | -| [`api-gateway`](../packages/api/gateway) | `api` | [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-registry`](../packages/typert/registry) | | [`compaction-basic`](../packages/compaction/compaction-basic) | `compaction` | [`agent`](../packages/core/agent), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`session-reference`](../packages/context/session-reference) | `context` | [`agent`](../packages/core/agent), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`typert-protocol`](../packages/typert/protocol) | | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs-local`](../packages/jobs/jobs-local), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`shell-env`](../packages/shell/shell-env), [`skill`](../packages/skill/skill), [`skill-filesystem`](../packages/skill/skill-filesystem), [`system-prompt`](../packages/core/system-prompt), [`tool-bash`](../packages/shell/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-jobs`](../packages/jobs/tool-jobs), [`tool-skill`](../packages/skill/tool-skill), [`tools`](../packages/core/tools) | -| [`experimental-webworker-runtime`](../packages/experimental/webworker-runtime) | `experimental` | [`client-connection`](../packages/client/connection), [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`host-frontend-static`](../packages/host/frontend-static) | `host` | [`client-connection`](../packages/client/connection), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`webhook-github`](../packages/webhook/webhook-github) | `webhook` | [`credentials`](../packages/credentials/credentials), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`webhook`](../packages/webhook/webhook) | | [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | | [`subagent-claude-code`](../packages/subagent/subagent-claude-code) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | @@ -1935,57 +1574,15 @@ flowchart TD | [`tool-subagent-report`](../packages/subagent/tool-subagent-report) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`hooks-claude-code`](../packages/hooks/hooks-claude-code) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) | | [`api-session-controller`](../packages/api/session-controller) | `api` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-connection`](../packages/client/connection), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`native-command`](../packages/util/native-command), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-query`](../packages/session-query/session-query), [`session-title`](../packages/session/session-title), [`skill`](../packages/skill/skill), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-time`](../packages/util/time), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | -| [`api-workspace-controller`](../packages/api/workspace-controller) | `api` | [`api-gateway`](../packages/api/gateway), [`client-connection`](../packages/client/connection), [`host-directory-picker`](../packages/host/directory-picker), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`experimental-agent-team`](../packages/experimental/agent-team) | `experimental` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | | [`sdk-protocol`](../packages/sdk/protocol) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | | [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`workflow-worker-thread`](../packages/workflow/workflow-worker-thread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) | | [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process) | `subagent` | [`invariants`](../packages/runtime-diagnostics/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-in-process-driver`](../packages/subagent/subagent-in-process-driver) | -| [`api-remotes`](../packages/api/remotes) | `api` | [`agent-presets`](../packages/preset/agent-presets), [`api-gateway`](../packages/api/gateway), [`api-session-controller`](../packages/api/session-controller), [`api-settings-controller`](../packages/api/settings-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`commands`](../packages/interaction/commands), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`credentials`](../packages/credentials/credentials), [`file-reference`](../packages/context/file-reference), [`goal`](../packages/goal/goal), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`session-reference`](../packages/context/session-reference), [`settings`](../packages/settings/settings), [`subagent`](../packages/subagent/subagent), [`user-approval`](../packages/interaction/user-approval), [`user-questions`](../packages/interaction/user-questions) | -| [`client-ui-session`](../packages/client/ui-session) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-ui-renderer`](../packages/client/ui-renderer), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | +| [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-slots`](../packages/client/ui-slots), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | | [`experimental-tool-agent-team`](../packages/experimental/tool-agent-team) | `experimental` | [`agent`](../packages/core/agent), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | | [`sdk-client`](../packages/sdk/client) | `sdk` | [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session) | | [`sdk-jsonrpc-server`](../packages/sdk/server) | `sdk` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`sdk-protocol`](../packages/sdk/protocol), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) | -| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | -| [`client-ui-settings`](../packages/client/ui-settings) | `client` | [`api-remotes`](../packages/api/remotes), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-locale`](../packages/client/locale) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-ui-settings-models`](../packages/client/ui-settings-models) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-settings-plugin-inventory`](../packages/client/ui-settings-plugin-inventory) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-settings-plugins`](../packages/client/ui-settings-plugins) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-theme`](../packages/client/ui-theme) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-settings`](../packages/client/ui-settings), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`cordis-client-runner`](../packages/extensions/cordis-client-runner) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-modules`](../packages/client/modules), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission-presets`](../packages/interaction/permission-presets), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tool-todo`](../packages/todo/tool-todo), [`util-crypto`](../packages/util/crypto), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | -| [`client-ui-sidebar`](../packages/client/ui-sidebar) | `client` | [`api-workspace-controller`](../packages/api/workspace-controller), [`client-locale`](../packages/client/locale), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-workspace`](../packages/client/ui-workspace) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`schedule`](../packages/schedule/schedule), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-agent-preset`](../packages/client/ui-agent-preset) | `client` | [`agent-presets`](../packages/preset/agent-presets), [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-approval`](../packages/client/ui-approval) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-brand-official`](../packages/client/ui-brand-official) | `client` | [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native) | `client` | [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-workspace`](../packages/client/ui-workspace), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-input-trigger`](../packages/client/ui-input-trigger) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-jobs`](../packages/client/ui-jobs) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-plan`](../packages/client/ui-plan) | `client` | [`api-remotes`](../packages/api/remotes), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`plan-mode`](../packages/plan/plan-mode), [`session`](../packages/core/session) | -| [`client-ui-schedule`](../packages/client/ui-schedule) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`schedule`](../packages/schedule/schedule) | -| [`client-ui-settings-general`](../packages/client/ui-settings-general) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`invariants`](../packages/runtime-diagnostics/invariants), [`settings`](../packages/settings/settings) | -| [`client-ui-trajectory`](../packages/client/ui-trajectory) | `client` | [`agent`](../packages/core/agent), [`api-session-controller`](../packages/api/session-controller), [`attachment`](../packages/attachment/attachment), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | -| [`client-ui-user-questions`](../packages/client/ui-user-questions) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol), [`user-questions`](../packages/interaction/user-questions) | -| [`experimental-client-ui-agent-team`](../packages/experimental/client-ui-agent-team) | `experimental` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-slots`](../packages/client/ui-slots), [`experimental-agent-team`](../packages/experimental/agent-team), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-chat`](../packages/client/ui-chat) | `client` | [`agent`](../packages/core/agent), [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-locale`](../packages/client/locale), [`client-ui-approval`](../packages/client/ui-approval), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-layout`](../packages/client/ui-layout), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-workspace`](../packages/client/ui-workspace), [`commands`](../packages/interaction/commands), [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-stats`](../packages/session/session-stats), [`settings`](../packages/settings/settings), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-commands`](../packages/client/ui-commands) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-reference`](../packages/client/ui-reference) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`file-reference`](../packages/context/file-reference), [`invariants`](../packages/runtime-diagnostics/invariants), [`session-reference`](../packages/context/session-reference), [`typert-protocol`](../packages/typert/protocol), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-subagent`](../packages/client/ui-subagent) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter) | -| [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`client-ui-directory-picker-browse`](../packages/client/ui-directory-picker-browse), [`client-ui-directory-picker-native`](../packages/client/ui-directory-picker-native), [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`session-log-export`](../packages/session-query/session-log-export) | `session-query` | [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-commands`](../packages/client/ui-commands), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`commands`](../packages/interaction/commands), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) | -| [`client-ui-attachment`](../packages/client/ui-attachment) | `client` | [`attachment`](../packages/attachment/attachment), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-trajectory`](../packages/client/ui-trajectory), [`invariants`](../packages/runtime-diagnostics/invariants) | -| [`client-ui-deliverables`](../packages/client/ui-deliverables) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) | -| [`client-ui-goal`](../packages/client/ui-goal) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-message-feedback`](../packages/client/ui-message-feedback) | `client` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`message-feedback`](../packages/feedback/message-feedback), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-model-selection`](../packages/client/ui-model-selection) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-commands`](../packages/client/ui-commands), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-permission-presets`](../packages/client/ui-permission-presets) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-commands`](../packages/client/ui-commands), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`invariants`](../packages/runtime-diagnostics/invariants), [`permission-presets`](../packages/interaction/permission-presets) | -| [`client-ui-tool`](../packages/client/ui-tool) | `client` | [`api-remotes`](../packages/api/remotes), [`api-workspace-controller`](../packages/api/workspace-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`util-workspace-path`](../packages/util/workspace-path) | -| [`client-ui-workflow-run`](../packages/client/ui-workflow-run) | `client` | [`api-session-controller`](../packages/api/session-controller), [`client-locale`](../packages/client/locale), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`tool-workflow`](../packages/workflow/tool-workflow), [`workflow`](../packages/workflow/workflow) | | [`client-test-runtime`](../packages/test-support/client-runtime) | `test-support` | [`api-session-controller`](../packages/api/session-controller), [`api-workspace-controller`](../packages/api/workspace-controller), [`attachment`](../packages/attachment/attachment), [`client-connection`](../packages/client/connection), [`client-store`](../packages/client/store), [`client-ui-chat`](../packages/client/ui-chat), [`client-ui-conversation`](../packages/client/ui-conversation), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-settings`](../packages/client/ui-settings), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol) | -| [`client-ui-skill`](../packages/client/ui-skill) | `client` | [`api-remotes`](../packages/api/remotes), [`api-session-controller`](../packages/api/session-controller), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-tool`](../packages/client/ui-tool), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session) | -| [`client-ui-cordis`](../packages/extensions/ui-cordis) | `extensions` | [`api-remotes`](../packages/api/remotes), [`client-connection`](../packages/client/connection), [`client-locale`](../packages/client/locale), [`client-ui-input-trigger`](../packages/client/ui-input-trigger), [`client-ui-renderer`](../packages/client/ui-renderer), [`client-ui-session`](../packages/client/ui-session), [`client-ui-sidebar`](../packages/client/ui-sidebar), [`client-ui-tool`](../packages/client/ui-tool), [`cordis-client-runner`](../packages/extensions/cordis-client-runner), [`invariants`](../packages/runtime-diagnostics/invariants) | +| [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`sdk-client`](../packages/sdk/client), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subprocess`](../packages/subprocess/subprocess) | diff --git a/packages/api/gateway/package.json b/packages/api/gateway/package.json index d5601ab188..5d66b7818d 100644 --- a/packages/api/gateway/package.json +++ b/packages/api/gateway/package.json @@ -57,17 +57,12 @@ "license": "MIT", "dependencies": { "@deepseek-ai/dsh-timeout": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/schemastery": "workspace:^", "ws": "^8.21.0" }, "peerDependencies": { - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-host-webserver": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-typert-registry": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-typert-protocol": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-brand": "workspace:^", @@ -78,6 +73,7 @@ "@deepseek-ai/dsh-util-crypto": "workspace:^", "@types/ws": "^8.18.1", "@deepseek-ai/cordis": "workspace:^", - "zod": "^4.4.3" + "zod": "^4.4.3", + "@deepseek-ai/dsh-typert-protocol": "workspace:^" } } diff --git a/packages/api/remotes/package.json b/packages/api/remotes/package.json index 8a271fe29a..40e6e8199c 100644 --- a/packages/api/remotes/package.json +++ b/packages/api/remotes/package.json @@ -55,37 +55,17 @@ "lib/types/**/*.d.ts" ], "dependencies": { - "@deepseek-ai/dsh-scope": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^" + "@deepseek-ai/dsh-api-session-controller": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^" }, "peerDependencies": { "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-agent-presets": "workspace:^", - "@deepseek-ai/dsh-api-gateway": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-api-settings-controller": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-cordis-host-runner": "workspace:^", - "@deepseek-ai/dsh-credentials": "workspace:^", - "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-goal": "workspace:^", - "@deepseek-ai/dsh-host-plugin-inventory": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-message-feedback": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-session-reference": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", - "@deepseek-ai/dsh-subagent": "workspace:^", - "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/dsh-user-questions": "workspace:^" + "@deepseek-ai/dsh-scope": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-agent-presets": "workspace:^", "@deepseek-ai/dsh-api-gateway": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", "@deepseek-ai/dsh-api-settings-controller": "workspace:^", "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", @@ -97,11 +77,13 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-message-feedback": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-reference": "workspace:^", "@deepseek-ai/dsh-settings": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", "@deepseek-ai/dsh-user-approval": "workspace:^", - "@deepseek-ai/dsh-user-questions": "workspace:^" + "@deepseek-ai/dsh-user-questions": "workspace:^", + "@deepseek-ai/dsh-client-connection": "workspace:^", + "@deepseek-ai/dsh-typert-protocol": "workspace:^", + "@deepseek-ai/dsh-scope": "workspace:^" } } diff --git a/packages/client/connection/package.json b/packages/client/connection/package.json index f19f30e40d..0a683d4d15 100644 --- a/packages/client/connection/package.json +++ b/packages/client/connection/package.json @@ -39,7 +39,8 @@ "license": "MIT", "dependencies": { "@deepseek-ai/schemastery": "workspace:^", - "zod": "^4.4.3" + "zod": "^4.4.3", + "@deepseek-ai/dsh-credentials": "workspace:^" }, "files": [ "lib/index.js", @@ -48,24 +49,12 @@ "lib/types/**/*.d.ts" ], "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-credentials": "workspace:^", - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-host-directory-picker": "workspace:^", - "@deepseek-ai/dsh-host-webserver": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", - "@deepseek-ai/dsh-tool-todo": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", "@deepseek-ai/dsh-attachment": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-credentials": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-host-directory-picker": "workspace:^", "@deepseek-ai/dsh-host-webserver": "workspace:^", diff --git a/packages/client/hmr/package.json b/packages/client/hmr/package.json index 35f1beed3c..74bb43f428 100644 --- a/packages/client/hmr/package.json +++ b/packages/client/hmr/package.json @@ -41,10 +41,6 @@ "@deepseek-ai/schemastery": "workspace:^" }, "peerDependencies": { - "@deepseek-ai/cordis-plugin-loader": "workspace:^", - "@deepseek-ai/dsh-client-modules": "workspace:^", - "@deepseek-ai/dsh-host-webserver": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/locale/package.json b/packages/client/locale/package.json index 466734cc9b..da1337c42e 100644 --- a/packages/client/locale/package.json +++ b/packages/client/locale/package.json @@ -43,13 +43,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", @@ -63,11 +57,11 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@types/react": "~18.3.1", "react": "^18.2.0", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^" + "@deepseek-ai/dsh-client-connection": "workspace:^" }, "dependencies": { - "@deepseek-ai/schemastery": "workspace:^" + "@deepseek-ai/schemastery": "workspace:^", + "@deepseek-ai/dsh-settings": "workspace:^" }, "files": [ "lib/index.js", diff --git a/packages/client/modules/package.json b/packages/client/modules/package.json index 1e608f4c58..9ae338e0eb 100644 --- a/packages/client/modules/package.json +++ b/packages/client/modules/package.json @@ -54,9 +54,6 @@ "lib/types/**/*.d.ts" ], "peerDependencies": { - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/cordis-plugin-loader": "workspace:^", - "@deepseek-ai/dsh-host-webserver": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" } } diff --git a/packages/client/store/package.json b/packages/client/store/package.json index e6b8eb47e6..ba0cae3b47 100644 --- a/packages/client/store/package.json +++ b/packages/client/store/package.json @@ -31,8 +31,7 @@ "zustand": "~4.4.7" }, "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-agent-preset/package.json b/packages/client/ui-agent-preset/package.json index 7ec49fd96f..cbc072bb2a 100644 --- a/packages/client/ui-agent-preset/package.json +++ b/packages/client/ui-agent-preset/package.json @@ -50,19 +50,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-agent-presets": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-workspace": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-approval/package.json b/packages/client/ui-approval/package.json index 060cb0f386..a6fafca529 100644 --- a/packages/client/ui-approval/package.json +++ b/packages/client/ui-approval/package.json @@ -48,17 +48,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-attachment/package.json b/packages/client/ui-attachment/package.json index 68efaafcd5..42d140be37 100644 --- a/packages/client/ui-attachment/package.json +++ b/packages/client/ui-attachment/package.json @@ -70,12 +70,6 @@ "lib/types/**/*.d.ts" ], "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-client-ui-chat": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" } } diff --git a/packages/client/ui-brand-official/package.json b/packages/client/ui-brand-official/package.json index 791ce76c9c..03d00017cb 100644 --- a/packages/client/ui-brand-official/package.json +++ b/packages/client/ui-brand-official/package.json @@ -44,9 +44,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-chat/package.json b/packages/client/ui-chat/package.json index 32018de464..f8e7336a26 100644 --- a/packages/client/ui-chat/package.json +++ b/packages/client/ui-chat/package.json @@ -51,31 +51,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-approval": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-layout": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-compaction": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-llm-retry": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-session-stats": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", - "@deepseek-ai/dsh-token-meter": "workspace:^", - "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-util-workspace-path": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", @@ -102,7 +78,6 @@ "@deepseek-ai/dsh-llm-retry": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-stats": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "@deepseek-ai/dsh-util-workspace-path": "workspace:^", @@ -112,7 +87,8 @@ "react-dom": "^18.2.0" }, "dependencies": { - "@deepseek-ai/schemastery": "workspace:^" + "@deepseek-ai/schemastery": "workspace:^", + "@deepseek-ai/dsh-settings": "workspace:^" }, "files": [ "lib/index.js", diff --git a/packages/client/ui-commands/package.json b/packages/client/ui-commands/package.json index a5a15451f2..1e9f5cd3cc 100644 --- a/packages/client/ui-commands/package.json +++ b/packages/client/ui-commands/package.json @@ -49,17 +49,7 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-conversation/package.json b/packages/client/ui-conversation/package.json index e9e434071b..bd46b7dba7 100644 --- a/packages/client/ui-conversation/package.json +++ b/packages/client/ui-conversation/package.json @@ -55,35 +55,11 @@ "@lexical/plain-text": "^0.49.0", "@lexical/text": "^0.49.0", "@lexical/utils": "^0.49.0", - "lexical": "^0.49.0" + "lexical": "^0.49.0", + "@deepseek-ai/dsh-settings": "workspace:^" }, "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^", - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-layout": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-goal": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-llm-retry": "workspace:^", - "@deepseek-ai/dsh-permission-presets": "workspace:^", - "@deepseek-ai/dsh-plan-mode": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", - "@deepseek-ai/dsh-token-meter": "workspace:^", - "@deepseek-ai/dsh-tool-todo": "workspace:^", - "@deepseek-ai/dsh-util-crypto": "workspace:^", - "@deepseek-ai/dsh-workspace": "workspace:^", - "@deepseek-ai/dsh-util-workspace-path": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", @@ -110,7 +86,6 @@ "@deepseek-ai/dsh-permission-presets": "workspace:^", "@deepseek-ai/dsh-plan-mode": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-tool-todo": "workspace:^", "@deepseek-ai/dsh-util-crypto": "workspace:^", diff --git a/packages/client/ui-deliverables/package.json b/packages/client/ui-deliverables/package.json index a977a5e609..b22bbf6109 100644 --- a/packages/client/ui-deliverables/package.json +++ b/packages/client/ui-deliverables/package.json @@ -48,16 +48,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-chat": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-system-prompt": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", @@ -70,7 +61,6 @@ "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-system-prompt": "workspace:^", "@types/react": "~18.3.1", "@deepseek-ai/cordis": "workspace:^", "react": "^18.2.0", @@ -82,5 +72,8 @@ "lib/invariant.js", "lib/client.js", "lib/types/**/*.d.ts" - ] + ], + "dependencies": { + "@deepseek-ai/dsh-system-prompt": "workspace:^" + } } diff --git a/packages/client/ui-directory-picker-browse/package.json b/packages/client/ui-directory-picker-browse/package.json index 90cd0ce667..4b82d5df9a 100644 --- a/packages/client/ui-directory-picker-browse/package.json +++ b/packages/client/ui-directory-picker-browse/package.json @@ -49,11 +49,6 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-directory-picker-native/package.json b/packages/client/ui-directory-picker-native/package.json index 9bb352e7cb..24dae2f8cb 100644 --- a/packages/client/ui-directory-picker-native/package.json +++ b/packages/client/ui-directory-picker-native/package.json @@ -44,9 +44,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-goal/package.json b/packages/client/ui-goal/package.json index 1bd3457b73..2cb4a5f548 100644 --- a/packages/client/ui-goal/package.json +++ b/packages/client/ui-goal/package.json @@ -49,19 +49,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-chat": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-goal": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-input-trigger/package.json b/packages/client/ui-input-trigger/package.json index 6114813aa3..16d607bae9 100644 --- a/packages/client/ui-input-trigger/package.json +++ b/packages/client/ui-input-trigger/package.json @@ -49,15 +49,7 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-client-locale": "workspace:^", diff --git a/packages/client/ui-jobs/package.json b/packages/client/ui-jobs/package.json index e944070fe6..abc3fc54ea 100644 --- a/packages/client/ui-jobs/package.json +++ b/packages/client/ui-jobs/package.json @@ -45,13 +45,7 @@ "access": "public" }, "peerDependencies": { - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-client-locale": "workspace:^", diff --git a/packages/client/ui-layout/package.json b/packages/client/ui-layout/package.json index ea634dbafa..7b43585188 100644 --- a/packages/client/ui-layout/package.json +++ b/packages/client/ui-layout/package.json @@ -46,11 +46,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-theme": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-message-feedback/package.json b/packages/client/ui-message-feedback/package.json index 51ca031762..2671324018 100644 --- a/packages/client/ui-message-feedback/package.json +++ b/packages/client/ui-message-feedback/package.json @@ -46,18 +46,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-message-feedback": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-client-ui-chat": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-model-selection/package.json b/packages/client/ui-model-selection/package.json index e368cfb6a9..d383664da4 100644 --- a/packages/client/ui-model-selection/package.json +++ b/packages/client/ui-model-selection/package.json @@ -46,18 +46,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-commands": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-permission-presets/package.json b/packages/client/ui-permission-presets/package.json index 3531416e93..fbe10f6133 100644 --- a/packages/client/ui-permission-presets/package.json +++ b/packages/client/ui-permission-presets/package.json @@ -47,17 +47,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-commands": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-permission-presets": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-plan/package.json b/packages/client/ui-plan/package.json index 97cd4f4ca4..7831563a6d 100644 --- a/packages/client/ui-plan/package.json +++ b/packages/client/ui-plan/package.json @@ -45,15 +45,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-plan-mode": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-primitives/package.json b/packages/client/ui-primitives/package.json index 8041b7dbf3..a6fba6ba69 100644 --- a/packages/client/ui-primitives/package.json +++ b/packages/client/ui-primitives/package.json @@ -61,7 +61,6 @@ "lib/types/**/*.d.ts" ], "peerDependencies": { - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } } diff --git a/packages/client/ui-reference/package.json b/packages/client/ui-reference/package.json index b0b05a0aa1..741e6e100c 100644 --- a/packages/client/ui-reference/package.json +++ b/packages/client/ui-reference/package.json @@ -47,16 +47,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-file-reference": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session-reference": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", - "@deepseek-ai/dsh-util-workspace-path": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-renderer/package.json b/packages/client/ui-renderer/package.json index 997ac47de6..fbf258b55c 100644 --- a/packages/client/ui-renderer/package.json +++ b/packages/client/ui-renderer/package.json @@ -44,7 +44,6 @@ "use-sync-external-store": "1.2.0" }, "peerDependencies": { - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-schedule/package.json b/packages/client/ui-schedule/package.json index 2abd671289..31d143d7dd 100644 --- a/packages/client/ui-schedule/package.json +++ b/packages/client/ui-schedule/package.json @@ -45,13 +45,6 @@ "access": "public" }, "peerDependencies": { - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-schedule": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-session/package.json b/packages/client/ui-session/package.json index 7ab9428e32..da39a4f1bf 100644 --- a/packages/client/ui-session/package.json +++ b/packages/client/ui-session/package.json @@ -44,11 +44,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-settings-general/package.json b/packages/client/ui-settings-general/package.json index 3f4de05dd4..ea04c835fc 100644 --- a/packages/client/ui-settings-general/package.json +++ b/packages/client/ui-settings-general/package.json @@ -48,19 +48,11 @@ "license": "MIT", "dependencies": { "@deepseek-ai/schemastery": "workspace:^", - "clsx": "^2.0.0" + "clsx": "^2.0.0", + "@deepseek-ai/dsh-settings": "workspace:^" }, "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", @@ -76,7 +68,6 @@ "@deepseek-ai/cordis": "workspace:^", "@types/react": "~18.3.1", "react": "^18.2.0", - "@deepseek-ai/dsh-settings": "workspace:^", "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", "@deepseek-ai/dsh-client-ui-session": "workspace:^" }, diff --git a/packages/client/ui-settings-models/package.json b/packages/client/ui-settings-models/package.json index 8c65aacc8f..7ebdd1f89a 100644 --- a/packages/client/ui-settings-models/package.json +++ b/packages/client/ui-settings-models/package.json @@ -45,12 +45,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-settings-plugin-inventory/package.json b/packages/client/ui-settings-plugin-inventory/package.json index 1049448e57..53566b7eea 100644 --- a/packages/client/ui-settings-plugin-inventory/package.json +++ b/packages/client/ui-settings-plugin-inventory/package.json @@ -45,12 +45,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/ui-settings-plugins/package.json b/packages/client/ui-settings-plugins/package.json index 73e7d06cbd..581bf4ecfa 100644 --- a/packages/client/ui-settings-plugins/package.json +++ b/packages/client/ui-settings-plugins/package.json @@ -45,12 +45,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-settings/package.json b/packages/client/ui-settings/package.json index 02f6a598bb..08290d8fb0 100644 --- a/packages/client/ui-settings/package.json +++ b/packages/client/ui-settings/package.json @@ -42,14 +42,8 @@ "watch": "tsdown --watch" }, "license": "MIT", - "dependencies": { - "@deepseek-ai/schemastery": "workspace:^" - }, "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", @@ -60,7 +54,8 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-settings": "workspace:^", "@types/react": "~18.3.1", - "react": "^18.2.0" + "react": "^18.2.0", + "@deepseek-ai/schemastery": "workspace:^" }, "files": [ "lib/index.js", diff --git a/packages/client/ui-sidebar/package.json b/packages/client/ui-sidebar/package.json index 783a743df5..b74af2dac0 100644 --- a/packages/client/ui-sidebar/package.json +++ b/packages/client/ui-sidebar/package.json @@ -51,14 +51,7 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-workspace": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-client-ui-layout": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", diff --git a/packages/client/ui-skill/package.json b/packages/client/ui-skill/package.json index d6e679509b..78a92c7cb1 100644 --- a/packages/client/ui-skill/package.json +++ b/packages/client/ui-skill/package.json @@ -48,15 +48,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-tool": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-slots/package.json b/packages/client/ui-slots/package.json index 0e317a33ee..b65d871723 100644 --- a/packages/client/ui-slots/package.json +++ b/packages/client/ui-slots/package.json @@ -38,7 +38,6 @@ "lib/types/**/*.d.ts" ], "peerDependencies": { - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } } diff --git a/packages/client/ui-subagent/package.json b/packages/client/ui-subagent/package.json index 75afb63a17..e731e9c422 100644 --- a/packages/client/ui-subagent/package.json +++ b/packages/client/ui-subagent/package.json @@ -47,18 +47,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-subagent": "workspace:^", - "@deepseek-ai/dsh-token-meter": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-client-locale": "workspace:^", diff --git a/packages/client/ui-theme/package.json b/packages/client/ui-theme/package.json index ee343d5a89..72fac3548b 100644 --- a/packages/client/ui-theme/package.json +++ b/packages/client/ui-theme/package.json @@ -44,15 +44,7 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-settings": "workspace:^", - "@deepseek-ai/dsh-host-webserver": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", @@ -67,7 +59,6 @@ "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-host-webserver": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-settings": "workspace:^", "@types/react": "~18.3.1", "react": "^18.2.0" }, @@ -84,6 +75,7 @@ }, "dependencies": { "clsx": "^2.0.0", - "@deepseek-ai/schemastery": "workspace:^" + "@deepseek-ai/schemastery": "workspace:^", + "@deepseek-ai/dsh-settings": "workspace:^" } } diff --git a/packages/client/ui-tool/package.json b/packages/client/ui-tool/package.json index ca96120343..3a26243df1 100644 --- a/packages/client/ui-tool/package.json +++ b/packages/client/ui-tool/package.json @@ -49,17 +49,7 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", - "@deepseek-ai/dsh-client-ui-chat": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-util-workspace-path": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-trajectory/package.json b/packages/client/ui-trajectory/package.json index 242810c753..6ebd62a003 100644 --- a/packages/client/ui-trajectory/package.json +++ b/packages/client/ui-trajectory/package.json @@ -51,19 +51,7 @@ "diff": "^9.0.0" }, "peerDependencies": { - "@deepseek-ai/dsh-agent": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-compaction": "workspace:^", - "@deepseek-ai/dsh-tools": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", diff --git a/packages/client/ui-user-questions/package.json b/packages/client/ui-user-questions/package.json index b8059eecfb..2edeb93223 100644 --- a/packages/client/ui-user-questions/package.json +++ b/packages/client/ui-user-questions/package.json @@ -51,17 +51,7 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", - "@deepseek-ai/dsh-user-questions": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", diff --git a/packages/client/ui-workflow-run/package.json b/packages/client/ui-workflow-run/package.json index bc5273310b..e11e49b338 100644 --- a/packages/client/ui-workflow-run/package.json +++ b/packages/client/ui-workflow-run/package.json @@ -54,16 +54,6 @@ ], "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-chat": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-tool-workflow": "workspace:^", - "@deepseek-ai/dsh-workflow": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/client/ui-workspace/package.json b/packages/client/ui-workspace/package.json index 142ed0f2bd..07dd0260e6 100644 --- a/packages/client/ui-workspace/package.json +++ b/packages/client/ui-workspace/package.json @@ -54,21 +54,7 @@ "clsx": "^2.0.0" }, "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-api-session-controller": "workspace:^", - "@deepseek-ai/dsh-api-workspace-controller": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-schedule": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-util-workspace-path": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-api-remotes": "workspace:^", diff --git a/packages/client/web/package.json b/packages/client/web/package.json index 6d663b1056..bf03741764 100644 --- a/packages/client/web/package.json +++ b/packages/client/web/package.json @@ -42,7 +42,6 @@ "typescript": "^6.0.3" }, "peerDependencies": { - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "files": [ diff --git a/packages/core/session/package.json b/packages/core/session/package.json index 76062c71a3..7a75641d7c 100644 --- a/packages/core/session/package.json +++ b/packages/core/session/package.json @@ -45,20 +45,18 @@ ], "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-scope": "workspace:^", - "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-scope": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/dsh-typert-registry": "workspace:^", "@deepseek-ai/cordis": "workspace:^" + }, + "dependencies": { + "@deepseek-ai/dsh-llm": "workspace:^" } } diff --git a/packages/extensions/cordis-client-runner/package.json b/packages/extensions/cordis-client-runner/package.json index a7c39b524e..cac1ac0781 100644 --- a/packages/extensions/cordis-client-runner/package.json +++ b/packages/extensions/cordis-client-runner/package.json @@ -46,12 +46,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/cordis-plugin-loader": "workspace:^", - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-modules": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-theme": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/extensions/ui-cordis/package.json b/packages/extensions/ui-cordis/package.json index f37b0a8dc5..4a62ad38d8 100644 --- a/packages/extensions/ui-cordis/package.json +++ b/packages/extensions/ui-cordis/package.json @@ -51,16 +51,6 @@ }, "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-api-remotes": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-cordis-client-runner": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^", - "@deepseek-ai/dsh-client-ui-input-trigger": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-client-ui-tool": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { diff --git a/packages/llm/llm/package.json b/packages/llm/llm/package.json index 64c2eb0123..1c3e4c7196 100644 --- a/packages/llm/llm/package.json +++ b/packages/llm/llm/package.json @@ -57,23 +57,19 @@ ], "license": "MIT", "peerDependencies": { - "@deepseek-ai/dsh-attachment": "workspace:^", - "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-timeout": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "dependencies": { "@deepseek-ai/dsh-util-crypto": "workspace:^", "@deepseek-ai/schemastery": "workspace:^", - "zod": "^4.4.3" + "zod": "^4.4.3", + "@deepseek-ai/dsh-timeout": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-attachment": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-timeout": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/cordis": "workspace:^" } diff --git a/packages/session-query/session-log-export/package.json b/packages/session-query/session-log-export/package.json index f4a124c78b..bb6fdd8773 100644 --- a/packages/session-query/session-log-export/package.json +++ b/packages/session-query/session-log-export/package.json @@ -2,7 +2,9 @@ "name": "@deepseek-ai/dsh-session-log-export", "description": "Web Session-log export command and shared download dialog", "version": "0.1.2-alpha.1", - "publishConfig": { "access": "public" }, + "publishConfig": { + "access": "public" + }, "repository": { "type": "git", "url": "git+https://github.com/deepseek-ai/deepseek-harness.git", @@ -12,33 +14,39 @@ "main": "lib/index.js", "types": "lib/types/index.d.ts", "exports": { - ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" }, - "./invariant": { "types": "./lib/types/invariant.d.ts", "default": "./lib/invariant.js" }, - "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" }, + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./invariant": { + "types": "./lib/types/invariant.d.ts", + "default": "./lib/invariant.js" + }, + "./client": { + "types": "./lib/types/client/index.d.ts", + "default": "./lib/client.js" + }, "./src/*": "./src/*", "./package.json": "./package.json" }, - "files": ["lib/index.js", "lib/invariant.js", "lib/client.js", "lib/types/**/*.d.ts"], - "scripts": { "bundle": "tsdown", "watch": "tsdown --watch" }, + "files": [ + "lib/index.js", + "lib/invariant.js", + "lib/client.js", + "lib/types/**/*.d.ts" + ], + "scripts": { + "bundle": "tsdown", + "watch": "tsdown --watch" + }, "license": "MIT", "dependencies": { "@deepseek-ai/schemastery": "workspace:^", - "fflate": "^0.8.2" + "fflate": "^0.8.2", + "@deepseek-ai/dsh-session": "workspace:^" }, "peerDependencies": { - "@deepseek-ai/cordis": "workspace:^", - "@deepseek-ai/dsh-attachment": "workspace:^", - "@deepseek-ai/dsh-client-connection": "workspace:^", - "@deepseek-ai/dsh-client-locale": "workspace:^", - "@deepseek-ai/dsh-client-ui-commands": "workspace:^", - "@deepseek-ai/dsh-client-ui-conversation": "workspace:^", - "@deepseek-ai/dsh-client-ui-renderer": "workspace:^", - "@deepseek-ai/dsh-client-ui-session": "workspace:^", - "@deepseek-ai/dsh-commands": "workspace:^", - "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", - "@deepseek-ai/dsh-session-persistence": "workspace:^", - "@deepseek-ai/dsh-session-query": "workspace:^" + "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/cordis": "workspace:^", @@ -56,7 +64,6 @@ "@deepseek-ai/dsh-client-ui-slots": "workspace:^", "@deepseek-ai/dsh-commands": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-session-persistence": "workspace:^", "@deepseek-ai/dsh-session-query": "workspace:^", "@types/react": "~18.3.1", diff --git a/packages/typert/registry/package.json b/packages/typert/registry/package.json index a567280cf7..e3fc642a2e 100644 --- a/packages/typert/registry/package.json +++ b/packages/typert/registry/package.json @@ -53,15 +53,14 @@ ], "license": "MIT", "dependencies": { - "@deepseek-ai/dsh-typert-protocol": "workspace:^", "zod": "^4.4.3" }, "peerDependencies": { - "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, "devDependencies": { "@deepseek-ai/dsh-invariants": "workspace:^", - "@deepseek-ai/cordis": "workspace:^" + "@deepseek-ai/cordis": "workspace:^", + "@deepseek-ai/dsh-typert-protocol": "workspace:^" } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index f790a3c1a9..60ea772446 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -627,9 +627,6 @@ importers: '@deepseek-ai/dsh-timeout': specifier: workspace:^ version: link:../../util/timeout - '@deepseek-ai/dsh-typert-protocol': - specifier: workspace:^ - version: link:../../typert/protocol '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -652,6 +649,9 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-typert-protocol': + specifier: workspace:^ + version: link:../../typert/protocol '@deepseek-ai/dsh-typert-registry': specifier: workspace:^ version: link:../../typert/registry @@ -667,12 +667,12 @@ importers: packages/api/remotes: dependencies: - '@deepseek-ai/dsh-scope': + '@deepseek-ai/dsh-api-session-controller': specifier: workspace:^ - version: link:../../core/scope - '@deepseek-ai/dsh-typert-protocol': + version: link:../session-controller + '@deepseek-ai/dsh-session': specifier: workspace:^ - version: link:../../typert/protocol + version: link:../../core/session devDependencies: '@deepseek-ai/cordis': specifier: workspace:^ @@ -683,15 +683,15 @@ importers: '@deepseek-ai/dsh-api-gateway': specifier: workspace:^ version: link:../gateway - '@deepseek-ai/dsh-api-session-controller': - specifier: workspace:^ - version: link:../session-controller '@deepseek-ai/dsh-api-settings-controller': specifier: workspace:^ version: link:../settings-controller '@deepseek-ai/dsh-api-workspace-controller': specifier: workspace:^ version: link:../workspace-controller + '@deepseek-ai/dsh-client-connection': + specifier: workspace:^ + version: link:../../client/connection '@deepseek-ai/dsh-commands': specifier: workspace:^ version: link:../../interaction/commands @@ -719,9 +719,9 @@ importers: '@deepseek-ai/dsh-message-feedback': specifier: workspace:^ version: link:../../feedback/message-feedback - '@deepseek-ai/dsh-session': + '@deepseek-ai/dsh-scope': specifier: workspace:^ - version: link:../../core/session + version: link:../../core/scope '@deepseek-ai/dsh-session-reference': specifier: workspace:^ version: link:../../context/session-reference @@ -731,6 +731,9 @@ importers: '@deepseek-ai/dsh-subagent': specifier: workspace:^ version: link:../../subagent/subagent + '@deepseek-ai/dsh-typert-protocol': + specifier: workspace:^ + version: link:../../typert/protocol '@deepseek-ai/dsh-user-approval': specifier: workspace:^ version: link:../../interaction/user-approval @@ -1663,6 +1666,9 @@ importers: packages/client/connection: dependencies: + '@deepseek-ai/dsh-credentials': + specifier: workspace:^ + version: link:../../credentials/credentials '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -1682,9 +1688,6 @@ importers: '@deepseek-ai/dsh-commands': specifier: workspace:^ version: link:../../interaction/commands - '@deepseek-ai/dsh-credentials': - specifier: workspace:^ - version: link:../../credentials/credentials '@deepseek-ai/dsh-host-directory-picker': specifier: workspace:^ version: link:../../host/directory-picker @@ -1731,6 +1734,9 @@ importers: packages/client/locale: dependencies: + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../../settings/settings '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -1765,9 +1771,6 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-settings': - specifier: workspace:^ - version: link:../../settings/settings '@types/react': specifier: ~18.3.1 version: 18.3.31 @@ -1992,6 +1995,9 @@ importers: packages/client/ui-chat: dependencies: + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../../settings/settings '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -2068,9 +2074,6 @@ importers: '@deepseek-ai/dsh-session-stats': specifier: workspace:^ version: link:../../session/session-stats - '@deepseek-ai/dsh-settings': - specifier: workspace:^ - version: link:../../settings/settings '@deepseek-ai/dsh-token-meter': specifier: workspace:^ version: link:../../llm/token-meter @@ -2156,6 +2159,9 @@ importers: packages/client/ui-conversation: dependencies: + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../../settings/settings '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -2250,9 +2256,6 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session - '@deepseek-ai/dsh-settings': - specifier: workspace:^ - version: link:../../settings/settings '@deepseek-ai/dsh-token-meter': specifier: workspace:^ version: link:../../llm/token-meter @@ -2288,6 +2291,10 @@ importers: version: 4.4.3 packages/client/ui-deliverables: + dependencies: + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt devDependencies: '@deepseek-ai/cordis': specifier: workspace:^ @@ -2328,9 +2335,6 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session - '@deepseek-ai/dsh-system-prompt': - specifier: workspace:^ - version: link:../../core/system-prompt '@types/react': specifier: ~18.3.1 version: 18.3.31 @@ -3058,10 +3062,6 @@ importers: version: 18.3.1 packages/client/ui-settings: - dependencies: - '@deepseek-ai/schemastery': - specifier: link:../../../vendor/schemastery - version: link:../../../vendor/schemastery devDependencies: '@deepseek-ai/cordis': specifier: workspace:^ @@ -3084,6 +3084,9 @@ importers: '@deepseek-ai/dsh-settings': specifier: workspace:^ version: link:../../settings/settings + '@deepseek-ai/schemastery': + specifier: link:../../../vendor/schemastery + version: link:../../../vendor/schemastery '@types/react': specifier: ~18.3.1 version: 18.3.31 @@ -3093,6 +3096,9 @@ importers: packages/client/ui-settings-general: dependencies: + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../../settings/settings '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -3139,9 +3145,6 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-settings': - specifier: workspace:^ - version: link:../../settings/settings '@types/react': specifier: ~18.3.1 version: 18.3.31 @@ -3450,6 +3453,9 @@ importers: packages/client/ui-theme: dependencies: + '@deepseek-ai/dsh-settings': + specifier: workspace:^ + version: link:../../settings/settings '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -3493,9 +3499,6 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-settings': - specifier: workspace:^ - version: link:../../settings/settings '@types/react': specifier: ~18.3.1 version: 18.3.31 @@ -4422,6 +4425,10 @@ importers: version: link:../../runtime-diagnostics/invariants packages/core/session: + dependencies: + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm devDependencies: '@deepseek-ai/cordis': specifier: workspace:^ @@ -4432,9 +4439,6 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-llm': - specifier: workspace:^ - version: link:../../llm/llm '@deepseek-ai/dsh-scope': specifier: workspace:^ version: link:../scope @@ -6369,6 +6373,9 @@ importers: packages/llm/llm: dependencies: + '@deepseek-ai/dsh-timeout': + specifier: workspace:^ + version: link:../../util/timeout '@deepseek-ai/dsh-util-crypto': specifier: workspace:^ version: link:../../util/crypto @@ -6391,9 +6398,6 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-timeout': - specifier: workspace:^ - version: link:../../util/timeout '@deepseek-ai/dsh-typert-protocol': specifier: workspace:^ version: link:../../typert/protocol @@ -7162,6 +7166,9 @@ importers: packages/session-query/session-log-export: dependencies: + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session '@deepseek-ai/schemastery': specifier: link:../../../vendor/schemastery version: link:../../../vendor/schemastery @@ -7214,9 +7221,6 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants - '@deepseek-ai/dsh-session': - specifier: workspace:^ - version: link:../../core/session '@deepseek-ai/dsh-session-persistence': specifier: workspace:^ version: link:../../session/session-persistence @@ -9645,9 +9649,6 @@ importers: packages/typert/registry: dependencies: - '@deepseek-ai/dsh-typert-protocol': - specifier: workspace:^ - version: link:../protocol zod: specifier: ^4.4.3 version: 4.4.3 @@ -9658,6 +9659,9 @@ importers: '@deepseek-ai/dsh-invariants': specifier: workspace:^ version: link:../../runtime-diagnostics/invariants + '@deepseek-ai/dsh-typert-protocol': + specifier: workspace:^ + version: link:../protocol packages/util/atomic-write: devDependencies: From 1d81fc7540dd02fe164fbdf7b160b7a319d63ec4 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 14:33:33 +0800 Subject: [PATCH 33/63] docs(testing): give the review checklist its own test-reliability entry The 'Test strength' bullet carried assertion strength, external-state verification, the reliability reference, and the coverage caveat at once. Splitting the reference into an adjacent entry matches how the orientation list above names the same skill, and restores 'Test strength' to one subject. The new entry also names the platform and timeout-budget rules the skill now carries, so the checklist covers what a reviewer is being pointed at. --- .agents/skills/dsh-code-review/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md index a18ac20d4e..d4dd0b491a 100644 --- a/.agents/skills/dsh-code-review/SKILL.md +++ b/.agents/skills/dsh-code-review/SKILL.md @@ -40,7 +40,8 @@ description: Use when reviewing a pull request in the deepseek-harness repo — - **Borrowed and derived state:** determine whether each retained value is borrowed or owned under the package contract, then trace notifications and every cache, prompt, UI echo, replay, and query view to the documented success point and authoritative source. - **Bounds cover the final operation:** locate the owner of the complete emitted or retained result, including wrappers and metadata. Probe tiny and exact limits, oversized single chunks, and multibyte text for byte limits. - **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch invalid Loader exports; a function plugin must named-export its namespace and have no default export. -- **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. For resource-owning, asynchronous, or flaky tests, apply [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) to the real worker/job topology, allocation, restoration, synchronization, and quiescent teardown. Coverage is necessary but not evidence that the scenario is correct. +- **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct. +- **Test reliability:** for a resource-owning, asynchronous, platform-sensitive, or flaky test, apply [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md) to the real worker/job topology, resource allocation, global-state restoration, synchronization, timeout budget, and quiescent teardown. - **Invariant lifecycle and negative controls:** verify candidate observations are rejected before publication where possible, session-backed checks reconstruct durable history after late loading or HMR, and a deliberately invalid case fails through the real runner for the intended rule. - **Implemented Agent Notes match shipped reality:** when a PR implements a proposed Agent Note, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation. - **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review expected-output diffs as behavior changes, not formatting noise. From cc5173f4cfc634559c5b3349be68da714dcc7f84 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 15:31:12 +0800 Subject: [PATCH 34/63] docs(testing): state the concurrent execution model where tests are written MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill carries the reliability rules, but nothing an agent loads by default said that specs run concurrently at all. The testing policy described tiers and evidence without ever stating how a spec is executed, and neither subtree AGENTS.md mentioned it — including scripts/, where the two suites that recently failed on unrelated branches live. docs/testing.md gains the execution model as the one home for the fact: forked workers, concurrent coverage partitions beside other gates, and self-hosted runners sharing a host and volume, with the rule that a spec passing only when run alone is a defect in the spec. It links the skill for the detailed rules. packages/AGENTS.md and scripts/AGENTS.md carry the short actionable form and link that section, so the rule is present in the context loaded while a test in either subtree is being written. Both ceilings are raised for the added words and the targets in docs/AGENTS.md move with them: docs/testing.md 1150 to 1300 (now 1237) and packages/AGENTS.md 675 to 750 (now 712), each keeping the 5% headroom the standard requires. --- docs/AGENTS.md | 2 +- docs/testing.i18n.yaml | 4 ++-- docs/testing.md | 4 ++++ docs/testing.zh.md | 4 ++++ packages/AGENTS.md | 1 + scripts/AGENTS.md | 2 ++ scripts/doc-budgets.manifest.json | 4 ++-- 7 files changed, 16 insertions(+), 5 deletions(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 5efb5c6c40..17d1613e3c 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -54,7 +54,7 @@ When the gate goes red: 2. **Condense** content that belongs here but can be shorter. 3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug. -Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 675 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,150, `examples/AGENTS.md` 310. Review governs unbudgeted tiers. +Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers. ## The slop checklist diff --git a/docs/testing.i18n.yaml b/docs/testing.i18n.yaml index e25a35536c..6264efd8b6 100644 --- a/docs/testing.i18n.yaml +++ b/docs/testing.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/testing.md -testing.md: c21c67bba85387e35e80d16217c2673653281672 -testing.zh.md: 008bee58918510c8afb695a7e0b880828d698227 +testing.md: 25514702e7aa8649c10ec213f5a6bf5c6e9e9a09 +testing.zh.md: 5338e4bc392e1e1ff16c32f708970be917e6efa7 diff --git a/docs/testing.md b/docs/testing.md index c21c67bba8..25514702e7 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -15,6 +15,10 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning Session fixtures keep headers and payloads but omit body sequence/time envelopes. Replay synthesizes them. Fixtures use canonical packed rows; [the migrator](../scripts/migrate-packed-session-fixtures.ts) rewrites old layouts. +## How specs execute + +Forked workers run several spec files at once, the coverage gate splits into concurrent partitions beside the other gates in its job, and the self-hosted runners share one host and one volume. Only the process is isolated: ports, predictable paths, external namespaces, and inherited children are not. Own each acquired resource through its teardown, and read a spec that passes only when it runs alone as a defect in the spec rather than an unstable runner. [dsh-ci-test-reliability](../.agents/skills/dsh-ci-test-reliability/SKILL.md) owns the allocation, restoration, synchronization, timeout-budget, platform, and teardown rules; its [flake diagnosis workflow](../.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md) classifies an existing probabilistic failure. + ## The with-key policy: inference is cheap here We are DeepSeek — do not ration real-API tests. A no-key test proves plumbing; only a with-key run proves the agent works against a real model. Cover file-writing prompts, multi-turn conversations, tool use, and mid-stream cancellation. Highest-value are **smoke tests** that boot a shipped `dsh` profile, send one prompt, and check the world — they catch the "green unit tests, broken product" class that mocks cannot ([postmortem 0001](postmortem/0001-acp-default-export-drops-inject.md)). Self-skip keeps secretless CI and keyless contributors unblocked; it is not a cost signal. Profile-level integration tests live under `apps/cli/tests/profiles/`; package-specific compositions stay with their package tests. diff --git a/docs/testing.zh.md b/docs/testing.zh.md index 008bee5891..5338e4bc39 100644 --- a/docs/testing.zh.md +++ b/docs/testing.zh.md @@ -15,6 +15,10 @@ 会话 fixture 保留 header 与 payload，但省略正文序号／时间 envelope。回放会合成这些字段；运行时持久化不变。fixture 使用规范打包行；[迁移器](../scripts/migrate-packed-session-fixtures.ts)会改写旧布局。 +## spec 如何被执行 + +fork 出的 worker 会同时运行多个 spec 文件，coverage gate 会拆成并发的 partition，与同一个 job 中的其它 gate 并排运行，而自托管 runner 共用同一台宿主机和同一个卷。被隔离的只有进程：端口、可预测路径、外部命名空间和继承而来的子进程都不隔离。为每个占用的资源负责到它的 teardown，并把「只有单独运行时才通过」的 spec 读作该 spec 的缺陷，而不是 runner 不稳定。[dsh-ci-test-reliability](../.agents/skills/dsh-ci-test-reliability/SKILL.md) 负责资源分配、状态恢复、同步、超时预算、平台差异与 teardown 规则；它的 [flake 诊断流程](../.agents/skills/dsh-ci-test-reliability/references/ci-flake-diagnosis.md)用于归类已经存在的概率性失败。 + ## 带密钥策略：推理（inference）在这里很便宜 我们是 DeepSeek，不要吝惜真实 API 测试。无密钥测试只能证明底层通路；只有带密钥运行才能证明 agent（智能体）能对接真实模型正常工作。覆盖文件写入提示词、包含多个轮次的对话、工具使用和流中取消。价值最高的是**冒烟测试**：启动已交付的 `dsh` profile、发送一条提示词，并检查外部世界；它们能捕获「单元测试全绿、产品却坏了」这一类 mock 无法发现的问题（[事故复盘 0001](postmortem/0001-acp-default-export-drops-inject.zh.md)）。自动跳过让无密钥 CI 和无密钥贡献者不受阻塞；它不是成本信号。Profile 级集成测试位于 `apps/cli/tests/profiles/`；包专属组合留在对应包的测试目录中。 diff --git a/packages/AGENTS.md b/packages/AGENTS.md index af47b16740..1385f129ff 100644 --- a/packages/AGENTS.md +++ b/packages/AGENTS.md @@ -15,6 +15,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md - **Publish state only at its commit point.** Emit each notification and update derived state only after the operation succeeds; derive caches, prompts, UI echoes, replay, and query views from one authoritative source. - **Apply bounds to the complete result.** Enforce byte, token, item, and time limits where the complete emitted or retained value, including wrappers and metadata, is known; test tiny and exact limits, oversized single chunks, and multibyte byte limits. - **Registry contributions prove disposal** through the HMR-safety test required by [testing policy](../docs/testing.md): dispose the fiber and observe removal. +- **Specs run concurrently** in forked workers beside other gate processes. Own each acquired port, path, and child process through teardown; a spec that passes only when run alone is a defect in the spec ([execution model](../docs/testing.md#how-specs-execute)). - **Every package owns `./invariant`.** Register the manifest name; check an event/data relation or give empty installers package-specific `No runtime invariant:` reasons. Generated companions, unexplained empties, and ignored reporters fail [`verify-package-invariants`](../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md). [Naming rules](../docs/cookbook/adding-a-package.md#name-the-role-that-exists): diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md index 8a50148e37..d7ec185e34 100644 --- a/scripts/AGENTS.md +++ b/scripts/AGENTS.md @@ -1,3 +1,5 @@ # AGENTS.md — Repository scripts Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to `/` at ingestion, and keep platform adaptation in the gate that needs it instead of a shared platform layer. Source-ownership gates use syntax-aware discovery, guard against an empty or narrowed corpus, and test every admitted/excluded form that changes their detection boundary. + +Script specs run in forked workers beside the rest of the suite and beside the other gate processes in their job, so own every port, temporary path, and child process a spec acquires. A spec that passes only when it runs alone is a defect in the spec; [the testing policy](../docs/testing.md#how-specs-execute) states the execution model and [dsh-ci-test-reliability](../.agents/skills/dsh-ci-test-reliability/SKILL.md) owns the rules. diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 1f7f25cb2a..2017bb43ca 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -4,7 +4,7 @@ "docs/architecture.md": 2400, "docs/cordis-primer.md": 600, "docs/defensive-patterns.md": 550, - "docs/testing.md": 1150, - "packages/AGENTS.md": 675, + "docs/testing.md": 1300, + "packages/AGENTS.md": 750, "packages/README.md": 994 } From d5a9e5b274590a763a498d8008f6a1d94e428914 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 16:52:39 +0800 Subject: [PATCH 35/63] fix(web): publish the drill claim before the descent edit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A pointer drill in the @ menu left no breadcrumb and a crumb click dropped the header, while the keyboard drill worked. InputTriggerController.settle assigned `drilled` after execute() returned, but a pointer mousedown runs outside any Lexical update, so the descent edit commits discretely and re-enters track() during execute() — where refreshHeaders and fetchCandidates both read the claim while it was still clear. settle now claims the drill before dispatching the edit and withdraws it only when the edit is refused, which mutates nothing and so drives no re-entrant track(). --- ...ll-claim-precedes-the-drill-edit.i18n.yaml | 6 +++ ...-29-drill-claim-precedes-the-drill-edit.md | 37 +++++++++++++++++++ ...-drill-claim-precedes-the-drill-edit.zh.md | 37 +++++++++++++++++++ apps/web/tests/reference-composer.e2e.ts | 28 +++++++++++++- .../ui-input-trigger/src/client/controller.ts | 17 +++++---- .../tests/service.client.spec.ts | 28 +++++++++++++- 6 files changed, 143 insertions(+), 10 deletions(-) create mode 100644 .agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.i18n.yaml create mode 100644 .agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.md create mode 100644 .agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.zh.md diff --git a/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.i18n.yaml new file mode 100644 index 0000000000..0760aa642b --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.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-29-drill-claim-precedes-the-drill-edit.md +2026-08-29-drill-claim-precedes-the-drill-edit.md: 35ca60360c2c8647c44ce9a164cff71fa112f942 +2026-08-29-drill-claim-precedes-the-drill-edit.zh.md: 58f7ca84d201726c0630f7cb6e9bf9614de76c20 diff --git a/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.md b/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.md new file mode 100644 index 0000000000..35ca60360c --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.md @@ -0,0 +1,37 @@ +# Agent Note: The drill claim is published before the edit that re-enters tracking + +Status: implemented + +English | [中文](2026-08-29-drill-claim-precedes-the-drill-edit.zh.md) + +## Problem + +A pointer descent in the `@` menu produced no breadcrumb, while the keyboard descent into the same directory produced one (#3310). Clicking a crumb — the gesture the breadcrumb exists for — dropped the header entirely instead of re-listing the step it named. Rows in a pointer-drilled listing also repeated the parent directory the header was supposed to carry. + +The three faults are one ordering defect in `InputTriggerController.settle`. The drill claim (`drilled`) was assigned after `execute()` returned, on the assumption that the input applies a descent edit and re-tracks later. That holds only for the keyboard: `KEY_TAB_COMMAND` handlers run inside a Lexical update, so `SessionInputShell.applyEdit` joins the enclosing update and the commit — with the `track()` call its update listener drives — lands after `settle` has returned. A pointer `mousedown` handler is outside any update, so `applyEdit` runs `editor.update(fn, { discrete: true })`, which sets `_flushSync` and commits synchronously; `track()` therefore re-enters the controller *during* `execute()`, and both readers of the claim — `refreshHeaders` and `fetchCandidates` — saw it still clear. Every existing test modeled the keyboard ordering: the fake insert listener returned `true` and the spec re-tracked afterwards by hand, so the pointer ordering was never exercised. + +## Decision + +`settle` claims the drill before dispatching the edit, and withdraws the claim only when the edit is refused: + +```ts ignore-check +this.reduce({ type: 'close' }) +this.drilled = action === 'drill' +if (!this.execute(outcome, hit.span)) this.drilled = false +``` + +The claim still follows `reduce({ type: 'close' })`, whose teardown clears it. Withdrawal remains exact because a refused edit mutates nothing and so drives no re-entrant `track()`: `insertText` fails its `draftRev` CAS before touching the editor, and `$replaceDetectSpanWithText` returns `false` from `selectSpan` ahead of `$setSelection`. The observable guarantee the [breadcrumb decision](../feature/2026-08-27-web-at-mention-discovery-and-row-content.md) states is unchanged — a header never names a directory nobody descended into — and both descent gestures now reach `header` and `candidates` as a drill. + +## Alternatives considered + +**Re-publish the header after `execute` returns.** Rejected: it treats the visible half of one defect. `fetchCandidates` reads the same claim, so the candidate request would still report `drilled: false` and `ui-reference` would keep repeating the parent directory on every row of a pointer-drilled listing. + +**Defer `execute` to a microtask so the re-entrant track always lands after `settle`.** Rejected: the edit carries `hit.span` for revision CAS, and postponing it past the current task lets an intervening keystroke invalidate the span, turning a working descent into a silently refused one. + +**Make `applyEdit` never flush synchronously.** Rejected: `discrete` is what keeps a programmatic edit and the detect coordinates computed from it in one task; relaxing it to fix a menu flag would loosen the whole input machine's ordering for every caller. + +## Consequences + +- Tab, the row chevron, and a crumb reach one behavior, so the breadcrumb no longer depends on which gesture opened the listing. +- Any future state a source reads through `header` or `candidates` must be published before `execute`, because the input can re-enter `track()` inside it. The claim is instance state on the controller, so the ordering is the only thing enforcing it. +- Coverage: a controller spec whose insert listener re-tracks synchronously — the pointer ordering — asserts both readers, and `reference-composer.e2e.ts` asserts the breadcrumb and the trimmed rows after a chevron drill and walks a two-level trail back through a crumb click. The keyboard ordering keeps its existing spec, so a regression that fixes one gesture by breaking the other fails. diff --git a/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.zh.md b/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.zh.md new file mode 100644 index 0000000000..58f7ca84d2 --- /dev/null +++ b/.agents/notes/implemented/bug-fix/2026-08-29-drill-claim-precedes-the-drill-edit.zh.md @@ -0,0 +1,37 @@ +# Agent Note: The drill claim is published before the edit that re-enters tracking + +Status: implemented + +[English](2026-08-29-drill-claim-precedes-the-drill-edit.md) | 中文 + +## Problem + +在 `@` 菜单里用指针进入目录不产生 breadcrumb,而用键盘进入同一个目录则会产生(#3310)。点击 crumb——breadcrumb 存在的意义所在——不但没有重新列出它所指的那一层,反而让整个 header 消失。指针进入的列表里,每一行还会重复 header 本应承担的父目录。 + +这三处故障是 `InputTriggerController.settle` 中的同一个顺序缺陷。drill 声明(`drilled`)过去在 `execute()` 返回之后才赋值,前提是输入层稍后才应用下钻编辑并重新 track。该前提只对键盘成立:`KEY_TAB_COMMAND` 的处理器运行在 Lexical update 内部,`SessionInputShell.applyEdit` 因此并入外层 update,提交——以及其 update listener 驱动的 `track()` 调用——落在 `settle` 返回之后。指针的 `mousedown` 处理器不在任何 update 内,`applyEdit` 于是执行 `editor.update(fn, { discrete: true })`,该选项置起 `_flushSync` 并同步提交;`track()` 因此在 `execute()` **执行期间**重入控制器,而声明的两个读取方——`refreshHeaders` 与 `fetchCandidates`——看到的仍是未置位的值。既有测试全部按键盘顺序建模:伪造的 insert 监听器只返回 `true`,由用例事后手工重新 track,指针顺序从未被覆盖。 + +## Decision + +`settle` 在派发编辑之前声明 drill,并且只在编辑被拒绝时撤回: + +```ts ignore-check +this.reduce({ type: 'close' }) +this.drilled = action === 'drill' +if (!this.execute(outcome, hit.span)) this.drilled = false +``` + +声明仍然排在 `reduce({ type: 'close' })` 之后,因为后者的清理会把它清掉。撤回依然精确,原因是被拒绝的编辑不做任何变更,因而不会驱动重入的 `track()`:`insertText` 在碰到编辑器之前就没通过 `draftRev` CAS,`$replaceDetectSpanWithText` 也在 `$setSelection` 之前就从 `selectSpan` 返回 `false`。[breadcrumb 决策](../feature/2026-08-27-web-at-mention-discovery-and-row-content.zh.md)所声明的可观察保证不变——header 绝不会指向一个无人进入过的目录——而两种下钻手势现在都以 drill 的身份抵达 `header` 与 `candidates`。 + +## Alternatives considered + +**在 `execute` 返回后重新发布 header。** 否决:这只处理了缺陷中看得见的那一半。`fetchCandidates` 读取同一个声明,候选请求仍会报告 `drilled: false`,`ui-reference` 也就仍会在指针进入的列表中逐行重复父目录。 + +**把 `execute` 推迟到 microtask,使重入的 track 必定落在 `settle` 之后。** 否决:该编辑携带 `hit.span` 用于版本 CAS,把它推迟到当前任务之外,会让插入其间的按键作废该 span,把一次本可成功的下钻变成静默失败。 + +**让 `applyEdit` 永不同步 flush。** 否决:`discrete` 正是让一次程序化编辑与由它算出的 detect 坐标留在同一个任务内的机制;为了修一个菜单标志而放宽它,会为所有调用方松开整个输入机的顺序保证。 + +## Consequences + +- Tab、行内 chevron 与 crumb 收敛到同一种行为,breadcrumb 不再取决于是哪种手势打开了列表。 +- 今后凡是 source 通过 `header` 或 `candidates` 读取的状态,都必须在 `execute` 之前发布,因为输入层可能在其内部重入 `track()`。该声明是控制器上的实例状态,顺序是唯一的约束手段。 +- 覆盖:一个 insert 监听器同步重新 track 的控制器用例——即指针顺序——断言两个读取方;`reference-composer.e2e.ts` 断言 chevron 下钻后的 breadcrumb 与精简后的行,并通过 crumb 点击走完两层路径的回退。键盘顺序保留原有用例,因此「修好一种手势却弄坏另一种」的回归会失败。 diff --git a/apps/web/tests/reference-composer.e2e.ts b/apps/web/tests/reference-composer.e2e.ts index 95e82385da..f8614e9ae7 100644 --- a/apps/web/tests/reference-composer.e2e.ts +++ b/apps/web/tests/reference-composer.e2e.ts @@ -130,6 +130,11 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through await writeFile(join(scaffold.workspaceCwd, 'workspace', 'reference.txt'), 'reference fixture\n') await mkdir(join(scaffold.workspaceCwd, 'workspace', 'folderx'), { recursive: true }) await writeFile(join(scaffold.workspaceCwd, 'workspace', 'folderx', 'child.txt'), 'child fixture\n') + // Two levels down: the breadcrumb needs a step above the current one to + // return to, and a bare '@' lists only the top level, so the deeper tree + // stays out of the menu golden. + await mkdir(join(scaffold.workspaceCwd, 'workspace', 'folderx', 'nested'), { recursive: true }) + await writeFile(join(scaffold.workspaceCwd, 'workspace', 'folderx', 'nested', 'leaf.txt'), 'leaf fixture\n') await page.goto(scaffold.authenticatedUrl, { waitUntil: 'load' }) await page.waitForSelector('[class*="frame"]', { timeout: 30_000 }) await connectFreshWorkspace(page, scaffold.workspaceCwd) @@ -280,13 +285,20 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through await expect.poll(() => input.textContent()).toBe('@folderx/') await menu.getByRole('option', { name: /child\.txt/ }).waitFor() - // The row chevron drills the same way by pointer. + // The row chevron drills the same way by pointer, header included: a + // pointer descent reaches the same listing a Tab descent does. await writeComposerDraft(page, input, '@folderx') const row = menu.getByRole('option', { name: /^folderx\// }) await row.waitFor() await row.getByRole('button', { name: 'Browse folder' }).click() await expect.poll(() => input.textContent()).toBe('@folderx/') await menu.getByRole('option', { name: /child\.txt/ }).waitFor() + await expect.poll(() => page.getByRole('navigation', { name: 'Folder navigation' }) + .getByRole('button').allTextContents()).toEqual(['Workspace', 'folderx']) + // The listing knows it was drilled into, so its rows drop the location the + // header already carries. + await expect.poll(() => menu.getByRole('option', { name: /child\.txt/ }).textContent()) + .toBe('child.txt') await page.keyboard.press('Escape') expect(tripwire.pageErrors).toEqual([]) @@ -318,6 +330,20 @@ describe.skipIf(MODE === 'record')('web e2e: file and session references through await expect.poll(() => menu.getByRole('option', { name: /child\.txt/ }).textContent()) .toBe('child.txt') + // A crumb above the current step re-lists that directory and keeps the + // header, which now names the step it returned to. + await writeComposerDraft(page, input, '@folderx/nested') + const nested = menu.getByRole('option', { name: /^nested\// }) + await nested.waitFor() + await nested.getByRole('button', { name: 'Browse folder' }).click() + await expect.poll(() => input.textContent()).toBe('@folderx/nested/') + await expect.poll(() => crumbs.getByRole('button').allTextContents()) + .toEqual(['Workspace', 'folderx', 'nested']) + await crumbs.getByRole('button', { name: 'folderx' }).click() + await expect.poll(() => input.textContent()).toBe('@folderx/') + await expect.poll(() => crumbs.getByRole('button').allTextContents()) + .toEqual(['Workspace', 'folderx']) + // Clicking the root crumb rewrites the token back to a bare trigger. await crumbs.getByRole('button', { name: 'Workspace' }).click() await expect.poll(() => input.textContent()).toBe('@') diff --git a/packages/client/ui-input-trigger/src/client/controller.ts b/packages/client/ui-input-trigger/src/client/controller.ts index 883a795775..4afb3b5d04 100644 --- a/packages/client/ui-input-trigger/src/client/controller.ts +++ b/packages/client/ui-input-trigger/src/client/controller.ts @@ -490,13 +490,16 @@ export class InputTriggerController { }) this.stopFetch() this.reduce({ type: 'close' }) - const applied = this.execute(outcome, hit.span) - // Set after the close above, so the reducer's own teardown cannot clear - // it, and only when the descent text actually landed: a refused edit - // (stale draft revision, or no listener) leaves the draft where it was, - // and a header over that draft would name a directory nobody descended - // into while hiding the locations its rows still need. - this.drilled = action === 'drill' && applied + // Claimed before the edit, and after the close above so the reducer's own + // teardown cannot clear it: the input may apply the descent through a + // synchronous editor commit that re-enters track(), and the header and + // candidate requests raised there read this flag. A refused edit (stale + // draft revision, or an unmappable span) mutates nothing and so reaches + // no re-entry, which is why withdrawing the claim afterwards still keeps + // a header off a draft nobody descended into — one that would name a + // directory while hiding the locations its rows still need. + this.drilled = action === 'drill' + if (!this.execute(outcome, hit.span)) this.drilled = false } /** Re-poll every header-bearing source in the hit roster and publish their crumbs. */ diff --git a/packages/client/ui-input-trigger/tests/service.client.spec.ts b/packages/client/ui-input-trigger/tests/service.client.spec.ts index 929d1e81e9..6872645dcf 100644 --- a/packages/client/ui-input-trigger/tests/service.client.spec.ts +++ b/packages/client/ui-input-trigger/tests/service.client.spec.ts @@ -595,11 +595,15 @@ describe('header / drilled descent', () => { /** A source that publishes one crumb per path segment of a drilled query. */ function crumbSource() { const requests: Array<{ query: string; quoted?: boolean; drilled: boolean }> = [] + const fetches: boolean[] = [] const picks: InputTriggerPick[] = [] const source: InputTriggerSource = { trigger: '@', name: 'reference', - candidates: () => Promise.resolve([{ name: 'src', drill: true, value: 'src' }]), + candidates: (_session, req) => { + fetches.push(req.drilled) + return Promise.resolve([{ name: 'src', drill: true, value: 'src' }]) + }, header: (_session, req) => { requests.push({ ...req }) if (!req.drilled || !req.query.includes('/')) return undefined @@ -610,7 +614,7 @@ describe('header / drilled descent', () => { return pick.action === 'drill' ? { text: `@${String(pick.candidate.value)}/`, continue: true } : undefined }, } - return { source, requests, picks } + return { source, requests, fetches, picks } } it('publishes no crumbs for a typed path and asks every source how the menu was reached', async () => { @@ -660,6 +664,26 @@ describe('header / drilled descent', () => { expect(picks[0]).toMatchObject({ candidate: { name: 'src', value: 'src' }, action: 'drill', via: 'menu' }) }) + it('publishes crumbs when the input re-tracks inside the drill edit', async () => { + const { source, fetches } = crumbSource() + const { controller, actx } = controllerBench([source]) + // A pointer drill reaches the input outside any editor update, so the + // descent commits synchronously and re-tracks before the pick that asked + // for it has returned — the keyboard drill, dispatched inside an update, + // re-tracks only once that update commits. Both orders must reach the + // header and candidate requests as a drill. + actx.on('slash/input-insert-text', (req) => { + controller.track(req.text, req.text.length, { tier: 'plain' }, 2) + return true + }) + controller.track('@sr', 3, { tier: 'plain' }, 1) + await tick() + controller.pick('reference', 0, 'drill') + await tick() + expect(controller.headers.getSnapshot().get('reference')).toEqual([{ label: 'src', value: 'src' }]) + expect(fetches).toEqual([false, true]) + }) + it('publishes no crumbs when the input refused the drill edit', async () => { const { source } = crumbSource() const { controller } = controllerBench([source]) From 4d92a61e00db8932227276f0caea182bc18ad399 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 29 Aug 2026 16:15:30 +0800 Subject: [PATCH 36/63] test(e2e): reserve pro for adapter coverage --- .../subagent-claude-code/tests/real-deepseek.e2e.ts | 11 ++++++----- snapshots/acp/escalation-approved/cordis.yml | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts b/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts index 9a8b3c2716..5611e4fce2 100644 --- a/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts +++ b/packages/subagent/subagent-claude-code/tests/real-deepseek.e2e.ts @@ -21,6 +21,7 @@ import * as claudeCode from '../src/index.ts' const execFileAsync = promisify(execFile) const OFFICIAL_DEEPSEEK_BASE_URL = 'https://api.deepseek.com' +const DEEPSEEK_MODEL = 'deepseek-v4-flash' const sdkRoot = dirname(fileURLToPath( import.meta.resolve('@anthropic-ai/claude-agent-sdk'), )) @@ -90,11 +91,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)( const env = { ANTHROPIC_AUTH_TOKEN: apiKey, ANTHROPIC_BASE_URL: `${deepSeekBaseUrl()}/anthropic`, - ANTHROPIC_MODEL: 'deepseek-v4-pro[1m]', - ANTHROPIC_DEFAULT_OPUS_MODEL: 'deepseek-v4-pro[1m]', - ANTHROPIC_DEFAULT_SONNET_MODEL: 'deepseek-v4-pro[1m]', - ANTHROPIC_DEFAULT_HAIKU_MODEL: 'deepseek-v4-flash', - CLAUDE_CODE_SUBAGENT_MODEL: 'deepseek-v4-flash', + ANTHROPIC_MODEL: DEEPSEEK_MODEL, + ANTHROPIC_DEFAULT_OPUS_MODEL: DEEPSEEK_MODEL, + ANTHROPIC_DEFAULT_SONNET_MODEL: DEEPSEEK_MODEL, + ANTHROPIC_DEFAULT_HAIKU_MODEL: DEEPSEEK_MODEL, + CLAUDE_CODE_SUBAGENT_MODEL: DEEPSEEK_MODEL, CLAUDE_CODE_EFFORT_LEVEL: 'max', CLAUDE_CONFIG_DIR: claudeConfig, HOME: root, diff --git a/snapshots/acp/escalation-approved/cordis.yml b/snapshots/acp/escalation-approved/cordis.yml index e08f3005c3..cc8f9609f9 100644 --- a/snapshots/acp/escalation-approved/cordis.yml +++ b/snapshots/acp/escalation-approved/cordis.yml @@ -34,7 +34,7 @@ name: '@deepseek-ai/dsh-acp' config: provider: deepseek-official - model: deepseek-v4-pro + model: deepseek-v4-flash - id: system-prompt name: '@deepseek-ai/dsh-system-prompt' From 08bfeda7e8ec33cd25900d769f99b5e45b803c50 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Sat, 29 Aug 2026 16:42:14 +0800 Subject: [PATCH 37/63] test(e2e): use Flash for live adapter coverage --- .../llm/llm-deepseek/tests/adapter.e2e.ts | 44 ++++++++----------- .../llm/llm-deepseek/tests/adapter.spec.ts | 4 +- packages/llm/llm-pi-ai/tests/adapter.e2e.ts | 38 +++++++++------- packages/llm/llm-pi-ai/tests/adapter.spec.ts | 4 +- 4 files changed, 44 insertions(+), 46 deletions(-) diff --git a/packages/llm/llm-deepseek/tests/adapter.e2e.ts b/packages/llm/llm-deepseek/tests/adapter.e2e.ts index cf3d511063..f39aebcc27 100644 --- a/packages/llm/llm-deepseek/tests/adapter.e2e.ts +++ b/packages/llm/llm-deepseek/tests/adapter.e2e.ts @@ -28,14 +28,13 @@ import type { Config } from '@deepseek-ai/dsh-llm-deepseek' import { assemble, type AssembledResult } from './assemble.ts' /** - * Real-API e2e for the direct-fetch adapter: V4 Flash + V4 Pro across - * thinking modes and all official effort levels. The suite skips entirely - * without $DEEPSEEK_API_KEY; the pre-release vision smoke additionally + * Real-API e2e for the direct-fetch adapter: V4 Flash across thinking modes + * and a max-effort tool round trip with reasoning passback. The suite skips + * entirely without $DEEPSEEK_API_KEY; the pre-release vision smoke additionally * requires $DEEPSEEK_VISION_E2E=1 (see vitest.e2e.config.ts). */ const FLASH = 'deepseek-v4-flash' -const PRO = 'deepseek-v4-pro' const VISION = 'deepseek-v4-flash-vision-exp' const VISION_E2E_ENABLED = process.env.DEEPSEEK_VISION_E2E === '1' const TEST_PNG = Uint8Array.from(readFileSync( @@ -266,20 +265,23 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', () expect(withThinking.usage?.reasoningTokens).toBeGreaterThan(0) }) - it.each(['high', 'max'] as const)( - 'pro + thinking enabled (effort %s): tool-call round trip with reasoning passback', - async (effort) => { - const ctx = await harness(PRO, { thinking: 'enabled' }) + it( + 'flash + thinking enabled (effort max): tool-call round trip with reasoning passback', + async () => { + const ctx = await harness(FLASH, { thinking: 'enabled' }) // Turn 1: the model must call the tool (and think before it). const first = await assemble(ctx,{ - model: PRO, - reasoningEffort: ReasoningEffortId(effort), + model: FLASH, + reasoningEffort: ReasoningEffortId('max'), messages: ask('What is the weather in Paris right now? Use the get_weather tool.'), tools: [weatherTool], maxTokens: 2000, }) - expect(first.finish.kind).toBe('tool-calls') + expect( + first.finish.kind, + `DeepSeek Flash tool-call turn finished as ${JSON.stringify(first.finish)}`, + ).toBe('tool-calls') const call = first.message.content.find(block => block.type === 'tool-call') expect(call).toBeDefined() expect(call!.name).toBe('get_weather') @@ -288,8 +290,8 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', () // Turn 2: send the tool result back WITH the assistant's reasoning // block in history (the official thinking+tools passback rule). const second = await assemble(ctx,{ - model: PRO, - reasoningEffort: ReasoningEffortId(effort), + model: FLASH, + reasoningEffort: ReasoningEffortId('max'), messages: [ ...ask('What is the weather in Paris right now? Use the get_weather tool.'), createMessage({ @@ -308,22 +310,14 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-deepseek e2e (real API)', () tools: [weatherTool], maxTokens: 2000, }) - expect(second.finish.kind).toBe('stop') + expect( + second.finish.kind, + `DeepSeek Flash tool-result turn finished as ${JSON.stringify(second.finish)}`, + ).toBe('stop') expect(textOf(second).toLowerCase()).toMatch(/sunny|22/) }, ) - it('pro + thinking disabled: plain generation without reasoning blocks', async () => { - const ctx = await harness(PRO, { thinking: 'disabled' }) - const result = await assemble(ctx,{ - model: PRO, - messages: ask('Reply with exactly the word: pong'), - maxTokens: 50, - }) - expect(result.finish.kind).toBe('stop') - expect(result.message.content.some(block => block.type === 'reasoning')).toBe(false) - }) - it('streams raw chunks in protocol order', async () => { const ctx = await harness(FLASH, { thinking: 'disabled' }) const kinds: string[] = [] diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts index 46d51efc43..39dd9e25b5 100644 --- a/packages/llm/llm-deepseek/tests/adapter.spec.ts +++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts @@ -338,7 +338,7 @@ describe('DeepSeekAdapter against a mock server', () => { const ctx = await harness(server.url) const result = await assemble(ctx, { - model: 'deepseek-v4-flash', + model: 'deepseek-v4-pro', messages: [createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'plugin', plugin: 'test' }, @@ -350,7 +350,7 @@ describe('DeepSeekAdapter against a mock server', () => { // The wire request carried the auth header contents we configured. expect(server.requests[0]).toMatchObject({ - model: 'deepseek-v4-flash', + model: 'deepseek-v4-pro', max_tokens: 256_000, reasoning_effort: 'high', stream: true, diff --git a/packages/llm/llm-pi-ai/tests/adapter.e2e.ts b/packages/llm/llm-pi-ai/tests/adapter.e2e.ts index 99b2be8721..93f684eef1 100644 --- a/packages/llm/llm-pi-ai/tests/adapter.e2e.ts +++ b/packages/llm/llm-pi-ai/tests/adapter.e2e.ts @@ -8,14 +8,12 @@ import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' import { assemble, type AssembledResult } from './assemble.ts' /** - * Real-API e2e for the pi-ai-backed adapter: V4 Flash + V4 Pro with provider - * defaults and representative off/high/max reasoning. Mirrors the native - * adapter's StreamChunk contract and exercises a replayed tool follow-up. - * Key-gated. + * Real-API e2e for the pi-ai-backed adapter: V4 Flash defaults and + * off/high/max reasoning. Mirrors the native adapter's StreamChunk contract + * and exercises a replayed tool follow-up. Key-gated. */ const FLASH = 'deepseek-v4-flash' -const PRO = 'deepseek-v4-pro' const contexts: Context[] = [] async function harness(_model: string, config: Partial = {}) { @@ -67,10 +65,10 @@ const weatherTool: ToolSchema = { } describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () => { - it.each([FLASH, PRO])('%s + provider-default reasoning: plain text generation', async (model) => { - const ctx = await harness(model) + it(`${FLASH} + provider-default reasoning: plain text generation`, async () => { + const ctx = await harness(FLASH) const result = await assemble(ctx,{ - model, + model: FLASH, messages: ask('Reply with exactly the word: pong'), maxTokens: 50, }) @@ -91,10 +89,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () => expect(textOf(result).toLowerCase()).toContain('pong') }) - it.each([FLASH, PRO])('%s + reasoning high: reasoning blocks present', async (model) => { - const ctx = await harness(model) + it(`${FLASH} + reasoning high: reasoning blocks present`, async () => { + const ctx = await harness(FLASH) const result = await assemble(ctx,{ - model, + model: FLASH, reasoningEffort: ReasoningEffortId('high'), messages: ask('Which is larger, 9.11 or 9.8? Answer with just the number.'), maxTokens: 2000, @@ -104,24 +102,27 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () => expect(textOf(result)).toContain('9.8') }) - it('pro + reasoning max: tool-call round trip', async () => { - const ctx = await harness(PRO) + it('flash + reasoning max: tool-call round trip', async () => { + const ctx = await harness(FLASH) const first = await assemble(ctx,{ - model: PRO, + model: FLASH, reasoningEffort: ReasoningEffortId('max'), messages: ask('What is the weather in Paris right now? Use the get_weather tool.'), tools: [weatherTool], maxTokens: 2000, }) - expect(first.finish.kind).toBe('tool-calls') + expect( + first.finish.kind, + `pi-ai Flash tool-call turn finished as ${JSON.stringify(first.finish)}`, + ).toBe('tool-calls') const call = first.message.content.find(block => block.type === 'tool-call') expect(call).toBeDefined() expect(call!.name).toBe('get_weather') expect(JSON.parse(call!.arguments)).toMatchObject({ city: expect.stringMatching(/paris/i) as string }) const second = await assemble(ctx,{ - model: PRO, + model: FLASH, reasoningEffort: ReasoningEffortId('max'), messages: [ ...ask('What is the weather in Paris right now? Use the get_weather tool.'), @@ -138,7 +139,10 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('llm-pi-ai e2e (real API)', () => tools: [weatherTool], maxTokens: 2000, }) - expect(second.finish.kind).toBe('stop') + expect( + second.finish.kind, + `pi-ai Flash tool-result turn finished as ${JSON.stringify(second.finish)}`, + ).toBe('stop') expect(textOf(second).toLowerCase()).toMatch(/sunny|22/) }) diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts index 9b35c6f285..cb2e71fad1 100644 --- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts +++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts @@ -135,14 +135,14 @@ describe('PiAiAdapter provider routing', () => { thinkingBudgets: { high: 2048 }, }) await assemble(ctx, { - model: 'deepseek-v4-flash', + model: 'deepseek-v4-pro', messages: [], temperature: 0.2, maxTokens: 77, sessionId: 'session-for-pi' as never, }) expect(server.requests[0]).toMatchObject({ - model: 'deepseek-v4-flash', + model: 'deepseek-v4-pro', temperature: 0.2, max_tokens: 77, thinking: { type: 'enabled' }, From e5f36cc70fd63fe4e8ca12ef8d4723eee861e8f3 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 17:13:45 +0800 Subject: [PATCH 38/63] feat(plugin-inventory): carry every agent preset's composition and group the settings plugin list by scope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The settings plugin list projected ctx.loader.entries() alone, hiding the plugins sessions actually run and rendering the web overlay's deliberate disabled tombstones (tool-bash, tool-fs, ...) as two dozen plainly disabled rows while the same modules ran in every standard-preset session. - dsh-agent-presets: compositionInventory() answers flattened rows per preset — newest live standing generation when mounted, composition file otherwise with !!js disabled gates evaluated against the Loader context; reading never mounts (regression-tested), refusal stays 'conditional', raced files report broken with the reason. - dsh-host-plugin-inventory: list() gains an optional agentPresets block, resolving the roster as an optional peer and mapping fiber states to the public phase vocabulary. - ui-settings-plugin-inventory: preset group first behind a display-only switcher opening on the default preset; global group collapsed with failures floated; host-disabled modules enabled by >=1 preset fold into a session-plugins drawer naming providers; search spans scopes and points at matches in unselected presets. - ui-agent-preset: the General-settings default-preset row is deleted — the roster section's make-default and the new-session chip keep the field — and the settings store slims to the display roster the header label reads. Docs, catalogs, module graph, settings-chrome goldens, and the bilingual Agent Note ride along. --- ...in-inventory-agent-preset-scopes.i18n.yaml | 6 + ...29-plugin-inventory-agent-preset-scopes.md | 33 ++ ...plugin-inventory-agent-preset-scopes.zh.md | 33 ++ .../settings-chrome/dialog-en.expected.md | 4 - .../settings-chrome/dialog.expected.md | 4 - .../settings-chrome/plugins.expected.md | 4 +- apps/web/tests/settings-chrome.e2e.ts | 15 +- docs/module-graph.i18n.yaml | 4 +- docs/module-graph.md | 9 +- docs/module-graph.zh.md | 9 +- docs/subsystems/core.i18n.yaml | 4 +- docs/subsystems/core.md | 16 + docs/subsystems/core.zh.md | 16 + .../client/ui-agent-preset/README.i18n.yaml | 4 +- packages/client/ui-agent-preset/README.md | 8 +- packages/client/ui-agent-preset/README.zh.md | 8 +- .../src/client/AgentPresetRow.module.css | 60 --- .../src/client/AgentPresetRow.tsx | 89 ---- .../ui-agent-preset/src/client/PresetMenu.tsx | 84 ---- .../ui-agent-preset/src/client/index.ts | 47 +- .../ui-agent-preset/src/client/locales.ts | 10 +- .../src/client/settings-store.ts | 93 +--- .../tests/apply.client.spec.ts | 32 +- .../tests/components.client.spec.tsx | 140 +----- .../tests/settings-store.client.spec.ts | 129 ++--- .../README.i18n.yaml | 4 +- .../ui-settings-plugin-inventory/README.md | 14 +- .../ui-settings-plugin-inventory/README.zh.md | 14 +- .../PluginInventorySettingsTab.module.css | 172 ++++++- .../src/client/PluginInventorySettingsTab.tsx | 441 ++++++++++++++---- .../src/client/locales.ts | 56 ++- .../tests/components.client.spec.tsx | 270 ++++++++--- .../src/client/slot-catalog.ts | 1 - .../extensions/tool-cordis/src/api-catalog.ts | 22 + .../host/plugin-inventory/README.i18n.yaml | 4 +- packages/host/plugin-inventory/README.md | 15 +- packages/host/plugin-inventory/README.zh.md | 15 +- packages/host/plugin-inventory/package.json | 7 + packages/host/plugin-inventory/src/index.ts | 26 +- packages/host/plugin-inventory/src/types.ts | 40 ++ .../plugin-inventory/tests/inventory.spec.ts | 43 +- packages/host/plugin-inventory/tsconfig.json | 3 + .../preset/agent-presets/README.i18n.yaml | 4 +- packages/preset/agent-presets/README.md | 5 + packages/preset/agent-presets/README.zh.md | 5 + .../src/composition-inventory.ts | 195 ++++++++ .../preset/agent-presets/src/discovery.ts | 5 +- packages/preset/agent-presets/src/index.ts | 55 ++- .../tests/composition-inventory.spec.ts | 309 ++++++++++++ packages/preset/agent-presets/tsconfig.json | 3 + pnpm-lock.yaml | 3 + scripts/gen-cordis-catalog.ts | 1 + 52 files changed, 1769 insertions(+), 824 deletions(-) create mode 100644 .agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.i18n.yaml create mode 100644 .agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md create mode 100644 .agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md delete mode 100644 packages/client/ui-agent-preset/src/client/AgentPresetRow.module.css delete mode 100644 packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx delete mode 100644 packages/client/ui-agent-preset/src/client/PresetMenu.tsx create mode 100644 packages/preset/agent-presets/src/composition-inventory.ts create mode 100644 packages/preset/agent-presets/tests/composition-inventory.spec.ts diff --git a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.i18n.yaml new file mode 100644 index 0000000000..bb1705fca7 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.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-29-plugin-inventory-agent-preset-scopes.md +2026-08-29-plugin-inventory-agent-preset-scopes.md: ec738ee0ff325e14677407da0ce4af8ffe3fe718 +2026-08-29-plugin-inventory-agent-preset-scopes.zh.md: 7804203350b4173a6dfd058447aee95e918cda74 diff --git a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md new file mode 100644 index 0000000000..ec738ee0ff --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md @@ -0,0 +1,33 @@ +# Agent Note: The plugin inventory carries every agent preset's composition + +Status: implemented + +English | [中文](2026-08-29-plugin-inventory-agent-preset-scopes.zh.md) + +## Problem + +[Per-session agent presets](2026-08-03-per-session-agent-presets.md) moved every model-facing row onto the agent plane, and the settings plugin list kept projecting `ctx.loader.entries()` alone. The surface therefore hid the plugins sessions actually run — a directly-plugged preset subtree never appears in the Loader's entries — and actively misled about the rest: the web overlay's deliberate `disabled: true` tombstones (`tool-bash`, `tool-fs`, `plan-mode`, …) rendered as two dozen plainly "disabled" rows while the same modules ran in every standard-preset session. Beside it, General settings carried a default-preset dropdown that wrote the same `agent-presets.default` field as the roster section's own make-default action — two editors for one fact, one of them blind to the roster it was choosing from. + +## Decision + +**The inventory speaks for both planes.** `pluginInventory/list` gains an optional `agentPresets` block — one group per roster preset with id, display name, default marking, health, and flattened composition rows — supplied by the new `AgentPresets.compositionInventory()`: a preset with a live standing mount answers from its newest generation's Loader entries, and one never composed since boot answers from its composition file. `dsh-host-plugin-inventory` resolves the roster as an optional peer through `ctx.get('agentPresets')` (the `plugin-package-inventory-deepseek` pattern) and only maps root-fiber states onto its public phase vocabulary, so deployments without a roster keep serving Loader entries alone with the field absent. + +**File answers are evaluated, not guessed, and reading never mounts.** `!!js` disabled gates are platform/environment conditions the [Loader itself evaluates at every mount decision](2026-08-11-loader-entry-disabled-interpolation.md), so the file read evaluates them against the Loader context and reports the decision a mount on this host would make; a gate the evaluator refuses stays `'conditional'` with its expression text carried for display. The read parses and evaluates only — no import, no compose — so listing every preset's plugins activates none of them, and a regression test pins `livePresetMounts()` empty after a full inventory read. + +**The list is grouped by scope, with the misleading rows given their own state.** The preset group renders first behind a display-only switcher that opens on the default preset and writes no settings — inspecting `minimal` must not change what new sessions run. The global group follows collapsed, failures float first, and a global entry that is disabled while at least one preset row for the same module specifier is actually enabled folds into a "session plugins" drawer that names its providers — a third state instead of the generic "disabled" that started this. The provider rule is strict `enabled === true`: counting conditional declarations would claim per-session provision `tool-pwsh` never delivers on POSIX. Search spans both groups, forces the disclosures open, and points at matches sitting in unselected presets. + +**The General row is deleted, not relocated.** The default keeps two surfaces that can still act on it — the roster section's make-default beside the visible roster, and the new-session chip for the session about to start — so `ui-agent-preset` drops the row, its menu, and the write/writability half of its settings store, which slims to the display roster the header label reads. + +## Alternatives considered + +**Render every preset as its own always-open section.** Four shipped presets already put ~100 rows behind the fold; the switcher keeps one composition in view while the drawer's provider list and the search pointers preserve the cross-scope answer the all-at-once layout was buying. + +**Keep file-state gates unevaluated (`conditional` until first mount).** Honest but it re-created the misleading reading this change removes: on a cold host the default preset's `tool-bash` read as "conditional" and its host row fell back to plain "disabled" until the first session mounted the preset. + +**A structured composition viewer in the Agent presets section.** A second home for the same rows; the section keeps its raw-YAML viewer for authors and the plugin list owns the structured view. + +**Enable/disable toggles in the same change.** Writing a row's `disabled` back into a custom preset's `agent.cordis.yml` needs comment-preserving partial YAML edits, applies-to-new-sessions messaging, and a copy-then-edit path for shipped presets — deliberately its own change; this one is read-side truth. + +## Consequences + +Searching "bash" now answers the question that motivated the change in one screen: enabled in the standard preset, provided per session where the global plane disabled it, plainly disabled only where nothing enables it. The wire snapshot's row enablement is the union `boolean | 'conditional'` with the gate expression beside it, and the settings-chrome goldens pin the grouped layout. `ui-agent-preset` loses `AgentPresetRow` and `PresetMenu`; the `settings.agentPreset` locale namespace declaration moved to the plugin entry, and the `settings-chrome` English scenario probes locale resolution through the nav label instead of the deleted row. diff --git a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md new file mode 100644 index 0000000000..7804203350 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md @@ -0,0 +1,33 @@ +# Agent Note：插件清单携带每个 Agent 预设的组合 + +状态：已实现 + +[English](2026-08-29-plugin-inventory-agent-preset-scopes.md) | 中文 + +## 问题 + +[按会话的 agent preset](2026-08-03-per-session-agent-presets.zh.md) 把所有模型侧行移到了 agent 平面，而设置页的插件列表仍只投影 `ctx.loader.entries()`。这个表面因此看不见会话实际运行的插件——直接 plug 的预设子树从不出现在 Loader 条目里——还对其余部分构成误导：web overlay 刻意的 `disabled: true` 墓碑（`tool-bash`、`tool-fs`、`plan-mode`……）渲染成二十多行看似单纯"已停用"的条目，而同名模块在每个标准模式会话里运行。旁边，通用设置还有一个默认预设下拉，与名单分区自己的设为默认动作写同一个 `agent-presets.default` 字段——同一事实两个编辑器，其中一个还看不见它在选择的名单。 + +## 决定 + +**清单同时陈述两个平面。**`pluginInventory/list` 增加可选的 `agentPresets` 块——每个名单预设一组，含 id、显示名、默认标记、健康状态与压平的组合行——由新增的 `AgentPresets.compositionInventory()` 提供：已有存活 standing mount 的预设由其最新世代的 Loader 条目作答，开机以来从未被组合的预设由其组合文件作答。`dsh-host-plugin-inventory` 经 `ctx.get('agentPresets')` 把名单当作可选伙伴解析（即 `plugin-package-inventory-deepseek` 的模式），自己只把根 Fiber 状态映射到公共阶段词汇，因此没有名单的部署继续只提供 Loader 条目、字段缺席。 + +**文件答案靠求值而非猜测，且读取从不挂载。**`!!js` disabled 门是平台/环境条件，[Loader 自己在每次挂载决策时都会求值](2026-08-11-loader-entry-disabled-interpolation.zh.md)，因此文件读取用 Loader 上下文对它们求值，报告本机挂载会做出的决定；求值器拒绝的门保持 `'conditional'` 并携带表达式文本供展示。该读取只解析和求值——不 import、不组合——所以列出所有预设的插件不会激活其中任何一个，回归测试钉住完整清单读取后 `livePresetMounts()` 为空。 + +**列表按作用域分组，误导行获得自己的状态。**预设组在前，其切换器只改显示、初始停在默认预设且不写任何设置——查看 `minimal` 绝不能改变新会话运行什么。全局组随后且默认收起，失败行浮在最前；一个全局停用、而同一模块标识至少有一个预设行实际启用的条目，收进"会话插件"抽屉并列出提供它的预设——用第三种状态取代引发这一切的笼统"已停用"。提供者规则严格取 `enabled === true`：把条件声明也算作提供者，会替 `tool-pwsh` 在 POSIX 上宣称一个它从不兑现的按会话提供。搜索横跨两组、强制撑开折叠，并指出未选中预设里的匹配。 + +**通用设置行是删除，不是搬家。**默认值保留两个仍能作用于它的表面——名单分区的设为默认（名单可见）与新会话 chip（针对即将开始的会话）——因此 `ui-agent-preset` 删掉该行、它的菜单以及 settings store 的写入/可写性半边，后者收敛为标题标签读取的展示名单 store。 + +## 考虑过的替代方案 + +**把每个预设都渲染成常开分节。**四个内置预设已把约 100 行压到折叠线以下；切换器保持一次一个组合可见，抽屉的提供者列表与搜索指引保留了全展开布局想买到的跨作用域答案。 + +**文件态门保持不求值（首次挂载前一律 `conditional`）。**诚实，但重演了本次要消除的误导：冷启动的宿主上，默认预设的 `tool-bash` 读作"条件启用"，其全局行在第一个会话挂载预设之前退回单纯的"已停用"。 + +**在 Agent 预设分区做结构化组合查看器。**同一批行的第二个家；分区保留面向作者的原始 YAML 查看器，插件列表拥有结构化视图。 + +**启停开关随本次一起做。**把行的 `disabled` 写回自定义预设的 `agent.cordis.yml` 需要保注释的局部 YAML 编辑、"对新会话生效"的提示，以及内置预设的复制后编辑路径——刻意留作独立改动；本次只做读侧真相。 + +## 后果 + +搜索 "bash" 现在一屏回答引发本次改动的问题：在标准模式里启用、在全局平面被停用处按会话提供、只有真的无人启用之处才是单纯的已停用。线上快照的行启停是联合类型 `boolean | 'conditional'` 并携带门表达式，settings-chrome 的 golden 钉住分组布局。`ui-agent-preset` 失去 `AgentPresetRow` 与 `PresetMenu`；`settings.agentPreset` 文案命名空间声明移到插件入口，`settings-chrome` 的英文场景改用导航标签而非已删除的行来探测 locale 解析。 diff --git a/apps/web/tests/expected/settings-chrome/dialog-en.expected.md b/apps/web/tests/expected/settings-chrome/dialog-en.expected.md index 10f4e568fe..c47e53bf6c 100644 --- a/apps/web/tests/expected/settings-chrome/dialog-en.expected.md +++ b/apps/web/tests/expected/settings-chrome/dialog-en.expected.md @@ -17,10 +17,6 @@ - button "Close": - img - text: Close - - text: Agent preset Applies to sessions you start from now on. Running sessions keep the preset they began with. - - button "Standard mode": - - text: Standard mode - - img - text: Permission Choose the default permission mode for new sessions - button "Workspace Write": - text: Workspace Write diff --git a/apps/web/tests/expected/settings-chrome/dialog.expected.md b/apps/web/tests/expected/settings-chrome/dialog.expected.md index 1aa949a86d..369dc19e71 100644 --- a/apps/web/tests/expected/settings-chrome/dialog.expected.md +++ b/apps/web/tests/expected/settings-chrome/dialog.expected.md @@ -17,10 +17,6 @@ - button "关闭": - img - text: 关闭 - - text: Agent 预设 对此后新建的会话生效。运行中的会话保持它开始时的预设。 - - button "标准模式": - - text: 标准模式 - - img - text: 权限 选择新会话的默认权限模式 - button "Workspace Write": - text: Workspace Write diff --git a/apps/web/tests/expected/settings-chrome/plugins.expected.md b/apps/web/tests/expected/settings-chrome/plugins.expected.md index 9e8362a942..c4e0cbf9f0 100644 --- a/apps/web/tests/expected/settings-chrome/plugins.expected.md +++ b/apps/web/tests/expected/settings-chrome/plugins.expected.md @@ -1,6 +1,6 @@ - listitem: - - button "ui-settings, 已挂载, 已启用": + - button "ui-settings, 已启用": - strong: ui-settings - - img "已挂载" + - img "运行中" - text: 已启用 - img diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts index 96673df5f8..4a8fe18989 100644 --- a/apps/web/tests/settings-chrome.e2e.ts +++ b/apps/web/tests/settings-chrome.e2e.ts @@ -102,13 +102,22 @@ describe('web e2e: settings modal and General preferences', () => { await dialog.getByRole('button', { name: '插件', exact: true }).click() await dialog.getByRole('heading', { name: '插件', exact: true }).waitFor({ timeout: 10_000 }) await dialog.getByRole('tab', { name: '插件列表', exact: true }).click() + // The preset group opens first with its display-only switcher; the global + // plane starts collapsed and expands on demand, session plugins deeper still. + const presetSwitcher = dialog.getByRole('combobox', { name: '选择要查看的 Agent 预设' }) + await presetSwitcher.waitFor({ timeout: 10_000 }) + await dialog.getByRole('button', { name: /^全局/ }).click() const pluginRow = dialog.locator(PLUGIN_ROW_SELECTOR) await pluginRow.waitFor({ timeout: 10_000 }) + await dialog.getByRole('button', { name: /^会话插件/ }).click() const expectedPluginCount = [...scaffold.ctx.loader.entries()] .filter(entry => !entry.options.group) .length expect(await dialog.getByRole('searchbox', { name: '搜索插件' }).count()).toBe(1) - expect(await dialog.locator('[data-plugin-entry]').count()).toBe(expectedPluginCount) + // Every Loader entry appears exactly once in the global group — the + // session-plugin drawer included, preset compositions excluded. + expect(await dialog.locator('[data-plugin-scope="global"] [data-plugin-entry]').count()) + .toBe(expectedPluginCount) expect(await dialog.locator('[data-plugin-count]').getAttribute('data-plugin-count')) .toBe(String(expectedPluginCount)) expect(await dialog.getByRole('button', { name: '插件', exact: true }).getAttribute('aria-current')).toBe('true') @@ -597,8 +606,8 @@ describe('web e2e: settings modal and General preferences', () => { const dialog = frPage.getByRole('dialog', { name: 'Settings' }) await dialog.waitFor({ timeout: 10_000 }) await dialog.getByRole('button', { name: 'English' }).waitFor({ timeout: 10_000 }) - const preset = dialog.getByRole('button', { name: 'Standard mode' }) - await expect.poll(() => preset.isEnabled(), { timeout: 10_000 }).toBe(true) + // A locale-owned nav label proves the dictionaries resolved to en. + await dialog.getByRole('button', { name: 'Agent presets' }).waitFor({ timeout: 10_000 }) // The markup already ships `en`, so this alone cannot prove the sync ran // — the zh scenario above is the discriminating half. Asserted here too // so a future change that resolves en but writes the wrong tag is caught. diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 445c9ac17a..dee3e77226 100644 --- a/docs/module-graph.i18n.yaml +++ b/docs/module-graph.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/module-graph.md -module-graph.md: b48c197299f1afbf53bf60962f544148f7f6defc -module-graph.zh.md: 1f85ab06c3ca98d6060dab400d2bf8dbfbda8cc5 +module-graph.md: 118aab0cf70b0c7dc9f1279941f9160e158db73d +module-graph.zh.md: d22990142c454d8ec7649b52dd27557c6b71350e diff --git a/docs/module-graph.md b/docs/module-graph.md index b48c197299..118aab0cf7 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -405,9 +405,6 @@ flowchart TD pkg_subprocess_e2b --> pkg_invariants pkg_subprocess_e2b --> pkg_subprocess pkg_subprocess_e2b --> pkg_timeout - pkg_host_plugin_inventory --> pkg_brand - pkg_host_plugin_inventory --> pkg_invariants - pkg_host_plugin_inventory --> pkg_typert_protocol pkg_anonymous_user_id --> pkg_brand pkg_anonymous_user_id --> pkg_home_paths pkg_anonymous_user_id --> pkg_invariants @@ -1040,6 +1037,10 @@ flowchart TD pkg_tool_cordis --> pkg_session pkg_tool_cordis --> pkg_system_prompt pkg_tool_cordis --> pkg_tools + pkg_host_plugin_inventory --> pkg_agent_presets + pkg_host_plugin_inventory --> pkg_brand + pkg_host_plugin_inventory --> pkg_invariants + pkg_host_plugin_inventory --> pkg_typert_protocol pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_invariants pkg_tool_bash --> pkg_jobs @@ -1753,7 +1754,6 @@ flowchart TD | [`client-modules`](../packages/client/modules) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/runtime-diagnostics/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | -| [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | @@ -1881,6 +1881,7 @@ flowchart TD | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`host-directory-picker`](../packages/host/directory-picker), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`tool-todo`](../packages/todo/tool-todo) | | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 1f85ab06c3..d22990142c 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -407,9 +407,6 @@ flowchart TD pkg_subprocess_e2b --> pkg_invariants pkg_subprocess_e2b --> pkg_subprocess pkg_subprocess_e2b --> pkg_timeout - pkg_host_plugin_inventory --> pkg_brand - pkg_host_plugin_inventory --> pkg_invariants - pkg_host_plugin_inventory --> pkg_typert_protocol pkg_anonymous_user_id --> pkg_brand pkg_anonymous_user_id --> pkg_home_paths pkg_anonymous_user_id --> pkg_invariants @@ -1042,6 +1039,10 @@ flowchart TD pkg_tool_cordis --> pkg_session pkg_tool_cordis --> pkg_system_prompt pkg_tool_cordis --> pkg_tools + pkg_host_plugin_inventory --> pkg_agent_presets + pkg_host_plugin_inventory --> pkg_brand + pkg_host_plugin_inventory --> pkg_invariants + pkg_host_plugin_inventory --> pkg_typert_protocol pkg_tool_bash --> pkg_agent pkg_tool_bash --> pkg_invariants pkg_tool_bash --> pkg_jobs @@ -1755,7 +1756,6 @@ flowchart TD | [`client-modules`](../packages/client/modules) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`credentials`](../packages/credentials/credentials) | `credentials` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | `e2b` | [`e2b`](../packages/e2b/e2b), [`invariants`](../packages/runtime-diagnostics/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) | -| [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | | [`anonymous-user-id`](../packages/identity/anonymous-user-id) | `identity` | [`brand`](../packages/util/brand), [`home-paths`](../packages/util/home-paths), [`invariants`](../packages/runtime-diagnostics/invariants) | | [`storage-domain`](../packages/storage/storage-domain) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/runtime-diagnostics/invariants), [`storage`](../packages/storage/storage) | @@ -1883,6 +1883,7 @@ flowchart TD | [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`brand`](../packages/util/brand), [`commands`](../packages/interaction/commands), [`credentials`](../packages/credentials/credentials), [`host-directory-picker`](../packages/host/directory-picker), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`settings`](../packages/settings/settings), [`tool-todo`](../packages/todo/tool-todo) | | [`compaction-tool-result-pruner`](../packages/compaction/compaction-tool-result-pruner) | `compaction` | [`compaction`](../packages/compaction/compaction), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) | | [`tool-cordis`](../packages/extensions/tool-cordis) | `extensions` | [`agent`](../packages/core/agent), [`cordis-host-runner`](../packages/extensions/cordis-host-runner), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) | +| [`host-plugin-inventory`](../packages/host/plugin-inventory) | `host` | [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`typert-protocol`](../packages/typert/protocol) | | [`tool-bash`](../packages/shell/tool-bash) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`tool-pwsh`](../packages/shell/tool-pwsh) | `shell` | [`agent`](../packages/core/agent), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`shell`](../packages/shell/shell), [`shell-env`](../packages/shell/shell-env), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval) | | [`webhook`](../packages/webhook/webhook) | `webhook` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`agent-presets`](../packages/preset/agent-presets), [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`session`](../packages/core/session), [`session-title`](../packages/session/session-title), [`workspace`](../packages/workspace/workspace) | diff --git a/docs/subsystems/core.i18n.yaml b/docs/subsystems/core.i18n.yaml index 06bfe0a937..2ce0d29de1 100644 --- a/docs/subsystems/core.i18n.yaml +++ b/docs/subsystems/core.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/core.md -core.md: dbe12dfc9bfdafe0f59d7e52eefc5695b1c8d063 -core.zh.md: 50fd2e4e76ee72653c02c2ffeca06042191aa9c4 +core.md: 8af708c4e12677e376bfc2adf2ff52490f5ec1a5 +core.zh.md: 1680e51a9f3a0363c28b3582d8a3e5399d5b2530 diff --git a/docs/subsystems/core.md b/docs/subsystems/core.md index dbe12dfc9b..8af708c4e1 100644 --- a/docs/subsystems/core.md +++ b/docs/subsystems/core.md @@ -410,6 +410,22 @@ async list(): Promise */ @Remote('list') async remoteExportList(): Promise +/** + * Every preset's composition as flattened plugin rows, for plugin-listing + * surfaces beside the roster's own picker. + * + * A preset with a live standing mount answers from its newest generation's + * Loader entries — the composition new sessions join — and one never + * composed since boot answers from its file, with `!!js` disabled gates + * evaluated against the Loader context so both answers reflect the same + * host. Reading never mounts: an unmounted preset is parsed, not composed, + * so listing a preset's plugins cannot activate them early. A composition + * that stopped reading between discovery's health verdict and this read is + * reported broken with the raced reason rather than dropped. + * @returns one composition per roster preset, in roster order. + */ +async compositionInventory(): Promise + /** * Resolve one preset by id. * diff --git a/docs/subsystems/core.zh.md b/docs/subsystems/core.zh.md index 50fd2e4e76..1680e51a9f 100644 --- a/docs/subsystems/core.zh.md +++ b/docs/subsystems/core.zh.md @@ -420,6 +420,22 @@ async list(): Promise */ @Remote('list') async remoteExportList(): Promise +/** + * Every preset's composition as flattened plugin rows, for plugin-listing + * surfaces beside the roster's own picker. + * + * A preset with a live standing mount answers from its newest generation's + * Loader entries — the composition new sessions join — and one never + * composed since boot answers from its file, with `!!js` disabled gates + * evaluated against the Loader context so both answers reflect the same + * host. Reading never mounts: an unmounted preset is parsed, not composed, + * so listing a preset's plugins cannot activate them early. A composition + * that stopped reading between discovery's health verdict and this read is + * reported broken with the raced reason rather than dropped. + * @returns one composition per roster preset, in roster order. + */ +async compositionInventory(): Promise + /** * Resolve one preset by id. * diff --git a/packages/client/ui-agent-preset/README.i18n.yaml b/packages/client/ui-agent-preset/README.i18n.yaml index 042caf6f1b..3e1e1a14de 100644 --- a/packages/client/ui-agent-preset/README.i18n.yaml +++ b/packages/client/ui-agent-preset/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-agent-preset/README.md -README.md: 60a7f0ec9356c6107a32bb7c828746d54511d0f6 -README.zh.md: 64663fd76e0a8e3fd4cb799b05e81db7b62c0bde +README.md: e6bf3d1633e3d6bd6988692241803fa9b59898ac +README.zh.md: 5f202f53a20ac8a35574ddf715d27d86926a45d1 diff --git a/packages/client/ui-agent-preset/README.md b/packages/client/ui-agent-preset/README.md index 60a7f0ec93..e6bf3d1633 100644 --- a/packages/client/ui-agent-preset/README.md +++ b/packages/client/ui-agent-preset/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -This package provides the agent-preset surfaces of the Web GUI: a General-settings row choosing which preset new sessions are composed from, a chip on the new-session screen choosing the next session's preset, a read-only label in the session header, and a settings section that manages the roster — copy, delete, default, and the way into a preset's own files. A session's preset is fixed at creation, so the choice applies to sessions started afterwards while running sessions keep the composition they began with. When a deployment composes no presets, all four surfaces render nothing and every session shares the host composition. +This package provides the agent-preset surfaces of the Web GUI: a chip on the new-session screen choosing the next session's preset, a read-only label in the session header, and a settings section that manages the roster — copy, delete, default, and the way into a preset's own files. A session's preset is fixed at creation, so the choice applies to sessions started afterwards while running sessions keep the composition they began with; the default preset is edited in the settings section, where the roster is visible, so General settings carries no duplicate control for the same field. When a deployment composes no presets, all three surfaces render nothing and every session shares the host composition. ## Table of Contents @@ -25,7 +25,7 @@ This package provides the agent-preset surfaces of the Web GUI: a General-settin ## Use this package -Mount this plugin alongside the settings and conversation packages; the preset surfaces then appear where their slots render. The General-settings row opens on the deployment default and applies to sessions started afterwards; the new-session chip stages a pick that lands on the next blank session and is spent on first use, so the following new session opens on the default again. +Mount this plugin alongside the settings and conversation packages; the preset surfaces then appear where their slots render. The new-session chip opens on the deployment default and stages a pick that lands on the next blank session; the stage is spent on first use, so the following new session opens on the default again. ### Managing the roster @@ -43,7 +43,7 @@ When the roster carries the self-referential `cordis` preset, a dashed add-card
Implementation internals — click to expand -Options and the current default both come from one `agentPresets/list` call — the roster already reports which id a session with no explicit choice gets, so the row needs no settings-schema introspection — and the write targets the `agent-presets` settings namespace's `default` field, which is what the host resolves at creation. The settings section queries `settings.canOpenAgentPresetDirectory()` when it first loads and joins that result with the roster; a failed query removes only the native-open affordance. The new-session chip and the header label share one controller, because the staged choice belongs to the flow rather than to any one session; the stage is applied when a session arrives (covering both the session a workspace connect created and the blank one it reused) and dropped on refusal. A refusal announces itself as a transient banner over the composer column, because the chip's label has already reverted and a preset the host refuses to mount is one discovery reported healthy — its roster card carries no reason to go back and read. Only a pick a person just made is announced; the applier that runs when a session becomes current is not. [`dsh-client-connection`](../connection/README.md) authenticates `agentPresets/read`, `agentPresets/copy`, `settings/openAgentPresetDirectory`, `agentPresets/deletePreset`, `agentPresets/list`, and every other Host API method with the same browser session. A composition still names the plugins a session runs, so reading one is reconnaissance, while copy, delete, and the settings-owned directory opener manage the roster and drive the host desktop. The section re-reads on its own actions, `settings/document-updated`, and `connection/reset`, because composition files are edited outside the browser and nothing on the wire announces a file change. +The display options come from one `agentPresets/list` call — the roster already reports which id a session with no explicit choice gets, so no surface introspects the settings schema — and the default write, the settings section's make-default action, targets the `agent-presets` settings namespace's `default` field, which is what the host resolves at creation. The settings section queries `settings.canOpenAgentPresetDirectory()` when it first loads and joins that result with the roster; a failed query removes only the native-open affordance. The new-session chip and the header label share one controller, because the staged choice belongs to the flow rather than to any one session; the stage is applied when a session arrives (covering both the session a workspace connect created and the blank one it reused) and dropped on refusal. A refusal announces itself as a transient banner over the composer column, because the chip's label has already reverted and a preset the host refuses to mount is one discovery reported healthy — its roster card carries no reason to go back and read. Only a pick a person just made is announced; the applier that runs when a session becomes current is not. [`dsh-client-connection`](../connection/README.md) authenticates `agentPresets/read`, `agentPresets/copy`, `settings/openAgentPresetDirectory`, `agentPresets/deletePreset`, `agentPresets/list`, and every other Host API method with the same browser session. A composition still names the plugins a session runs, so reading one is reconnaissance, while copy, delete, and the settings-owned directory opener manage the roster and drive the host desktop. The section re-reads on its own actions, `settings/document-updated`, and `connection/reset`, because composition files are edited outside the browser and nothing on the wire announces a file change.
@@ -56,7 +56,7 @@ Read these pages when the preset surface is not enough. They move from the brows - [dsh-agent-presets](../../preset/agent-presets/README.md) — the host roster and composition the surfaces read and manage. - [ui-conversation](../ui-conversation/README.md) — declares the hero and session-header slots the chip and label fill. -- [ui-settings](../ui-settings/README.md) — the settings shell that hosts the General row and the roster section. +- [ui-settings](../ui-settings/README.md) — the settings shell that hosts the roster section. - [Client package map](../README.md) — adjacent browser UI packages. ----- diff --git a/packages/client/ui-agent-preset/README.zh.md b/packages/client/ui-agent-preset/README.zh.md index 64663fd76e..5f202f53a2 100644 --- a/packages/client/ui-agent-preset/README.zh.md +++ b/packages/client/ui-agent-preset/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -本包提供 Web GUI 的 agent preset 表面：通用设置中的一行，选择新建会话据以组装的 preset；新建会话界面的一枚 chip，选择下一个会话的 preset；会话标题旁的一个只读标签；以及一个设置分区，用于管理名单——复制、删除、默认值，以及通往 preset 自身文件的入口。会话的 preset 在创建时即固定，因此选择作用于此后开启的会话，运行中的会话保持它们开始时的组装。当部署未组装任何 preset 时，四个表面都不渲染任何内容，每个会话共用宿主组装。 +本包提供 Web GUI 的 agent preset 表面：新建会话界面的一枚 chip，选择下一个会话的 preset；会话标题旁的一个只读标签；以及一个设置分区，用于管理名单——复制、删除、默认值，以及通往 preset 自身文件的入口。会话的 preset 在创建时即固定，因此选择作用于此后开启的会话，运行中的会话保持它们开始时的组装；默认 preset 在能看到名单的设置分区里编辑，通用设置不再为同一字段保留重复控件。当部署未组装任何 preset 时，三个表面都不渲染任何内容，每个会话共用宿主组装。 ## 目录 @@ -25,7 +25,7 @@ kind: "package-reference" ## 使用本包 -与设置与对话包一起挂载本插件；preset 表面随即出现在各自槽位渲染之处。通用设置行以部署默认值打开，作用于此后开启的会话；新建会话 chip 暂存一个选择，落到下一个空白会话上，一经使用即被清空，因此再下一个新会话重新以默认值打开。 +与设置与对话包一起挂载本插件；preset 表面随即出现在各自槽位渲染之处。新建会话 chip 以部署默认值打开并暂存一个选择，落到下一个空白会话上；暂存一经使用即被清空，因此再下一个新会话重新以默认值打开。 ### 管理名单 @@ -43,7 +43,7 @@ kind: "package-reference"
实现细节——点击展开 -选项与当前默认值都来自同一次 `agentPresets/list` 调用——名单本身已报告未显式选择的会话会得到哪个 id，因此该行无需对 settings schema 做内省——写入目标是 `agent-presets` settings 命名空间的 `default` 字段，也正是 Host 在创建时解析的字段。设置分区首次加载时查询 `settings.canOpenAgentPresetDirectory()`，并把结果与名单合并；查询失败只会移除原生打开动作。新建会话 chip 与标题标签共用一个控制器，因为暂存选择属于流程而非任何单个会话；暂存值在会话到达时应用（既覆盖工作区连接新建的会话，也覆盖它复用的空白会话），被拒绝时丢弃。被拒绝会以一条瞬时横幅在 composer 列上方自报，因为 chip 的标签此时已经弹回，而被 Host 拒绝挂载的 preset 正是发现过程报告为健康的那一种——它的名单卡片上没有任何原因可供回头查看。只有人刚做出的选择会被自报；会话成为当前会话时触发的应用器不会。[`dsh-client-connection`](../connection/README.zh.md) 使用同一浏览器会话认证 `agentPresets/read`、`agentPresets/copy`、`settings/openAgentPresetDirectory`、`agentPresets/deletePreset`、`agentPresets/list` 及其他所有 Host API 方法。组装仍会指明一个会话所运行的插件，因此读取属于侦察，而 copy、delete 与 settings 所有的目录打开操作负责管理名单并驱动 Host 桌面。分区在自身操作、`settings/document-updated` 与 `connection/reset` 时重读，因为组装文件在浏览器之外编辑，线上没有任何机制宣布文件变动。 +展示选项来自同一次 `agentPresets/list` 调用——名单本身已报告未显式选择的会话会得到哪个 id，因此任何表面都无需对 settings schema 做内省——默认值的写入即设置分区的设为默认动作，目标是 `agent-presets` settings 命名空间的 `default` 字段，也正是 Host 在创建时解析的字段。设置分区首次加载时查询 `settings.canOpenAgentPresetDirectory()`，并把结果与名单合并；查询失败只会移除原生打开动作。新建会话 chip 与标题标签共用一个控制器，因为暂存选择属于流程而非任何单个会话；暂存值在会话到达时应用（既覆盖工作区连接新建的会话，也覆盖它复用的空白会话），被拒绝时丢弃。被拒绝会以一条瞬时横幅在 composer 列上方自报，因为 chip 的标签此时已经弹回，而被 Host 拒绝挂载的 preset 正是发现过程报告为健康的那一种——它的名单卡片上没有任何原因可供回头查看。只有人刚做出的选择会被自报；会话成为当前会话时触发的应用器不会。[`dsh-client-connection`](../connection/README.zh.md) 使用同一浏览器会话认证 `agentPresets/read`、`agentPresets/copy`、`settings/openAgentPresetDirectory`、`agentPresets/deletePreset`、`agentPresets/list` 及其他所有 Host API 方法。组装仍会指明一个会话所运行的插件，因此读取属于侦察，而 copy、delete 与 settings 所有的目录打开操作负责管理名单并驱动 Host 桌面。分区在自身操作、`settings/document-updated` 与 `connection/reset` 时重读，因为组装文件在浏览器之外编辑，线上没有任何机制宣布文件变动。
@@ -56,7 +56,7 @@ kind: "package-reference" - [dsh-agent-presets](../../preset/agent-presets/README.zh.md)——这些表面读取并管理的宿主名单与组装。 - [ui-conversation](../ui-conversation/README.zh.md)——声明 chip 与标签填充的首屏与会话头部槽位。 -- [ui-settings](../ui-settings/README.zh.md)——承载通用行与名单分区的设置外壳。 +- [ui-settings](../ui-settings/README.zh.md)——承载名单分区的设置外壳。 - [客户端包映射](../README.zh.md)——相邻的浏览器 UI 包。 ----- diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetRow.module.css b/packages/client/ui-agent-preset/src/client/AgentPresetRow.module.css deleted file mode 100644 index d0f7134329..0000000000 --- a/packages/client/ui-agent-preset/src/client/AgentPresetRow.module.css +++ /dev/null @@ -1,60 +0,0 @@ -/* Agent-preset row: title/description plus the preset selector pill. */ - -.row { - display: flex; - align-items: center; - gap: 8px; - padding: 16px 0; - border-bottom: 1px solid var(--dsw-alias-border-l2); -} - -.rowText { - flex: 1; - min-width: 0; - display: flex; - flex-direction: column; - gap: 4px; - padding-right: 48px; -} - -.title { - font-size: 14px; - font-weight: 400; - line-height: 22px; - color: var(--dsw-alias-label-primary); -} - -.desc { - font-size: 12px; - font-weight: 400; - line-height: 18px; - color: var(--dsw-alias-label-tertiary); -} - -.selector { - display: inline-flex; - align-items: center; - gap: 12px; - height: 36px; - padding: 0 14px; - border: none; - border-radius: 18px; - background: var(--dsw-alias-bg-module-platform); - font: inherit; - font-size: 14px; - line-height: 22px; - color: var(--dsw-alias-label-primary); - cursor: pointer; -} - -.selector:hover:not(:disabled) { - background: var(--dsw-alias-interactive-bg-hover); -} - -.selector:disabled { - cursor: default; -} - -.chevron { - flex: none; -} diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx deleted file mode 100644 index d2338596ba..0000000000 --- a/packages/client/ui-agent-preset/src/client/AgentPresetRow.tsx +++ /dev/null @@ -1,89 +0,0 @@ -/** - * Agent-preset preference row: the preset new sessions are composed from. - * A running session keeps the composition it began with, so this row never - * disturbs work in progress. - */ - -import { useEffect, useState } from 'react' -import type { SnapshotStore } from '@deepseek-ai/dsh-client-store' -import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' -import type { AgentPresetSettingsState } from './settings-store.ts' -import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts' -import { PresetMenu } from './PresetMenu.tsx' -import css from './AgentPresetRow.module.css' - -/** Registration-side business face for the host-backed preference. */ -export interface AgentPresetRowInjected { - hooks: { - /** Agent-preset settings snapshot bound by the renderer as useAgentPreset. */ - agentPreset: SnapshotStore - } - /** Load the roster when the row first renders. */ - load: () => Promise - /** Persist one preset as the default for later sessions. */ - select: (id: string) => Promise -} - -/** Full component props. */ -export type AgentPresetRowProps = - PropsRuntime<'settings.general.item'> - & PropsLocale<'settings.agentPreset'> - & InjectFace - -/** - * Render the new-session agent-preset selector. - * @param props - composed slot props. - * @returns the row, or null when the deployment composes no presets. - */ -export function AgentPresetRow({ load, select, useAgentPreset, t }: AgentPresetRowProps) { - const state = useAgentPreset(snapshot => snapshot) - const [open, setOpen] = useState(false) - - useEffect(() => { - void load() - }, [load]) - - useEffect(() => { - if (state.writable && state.status !== 'unavailable') return - setOpen(false) - }, [state.status, state.writable]) - - // A deployment that composes no presets has nothing to choose between, and - // every session shares the host composition — the row simply does not exist. - if (state.status === 'unavailable') return null - const busy = state.status === 'loading' || state.status === 'saving' - // Every preset surface applies the same display-copy rule. The id remains - // addressing rather than a label, except where no display name exists. - const chosen = state.options.find(option => option.id === state.currentValue) - const chosenText = chosen === undefined ? undefined : presetDisplayText(chosen, t) - const label = state.currentValue === '' ? t('loading') : (chosenText?.name ?? state.currentValue) - const description: string = state.error ?? t('description') - - return ( -
-
-
{t('title')}
-
{description}
-
- { void select(id) }} - /> -
- ) -} - -declare module '@deepseek-ai/dsh-client-ui-slots' { - interface LocaleNamespaceMap { - /** Agent-preset row copy. */ - 'settings.agentPreset': AgentPresetSettingsKey - } -} diff --git a/packages/client/ui-agent-preset/src/client/PresetMenu.tsx b/packages/client/ui-agent-preset/src/client/PresetMenu.tsx deleted file mode 100644 index 4b78d8ce6e..0000000000 --- a/packages/client/ui-agent-preset/src/client/PresetMenu.tsx +++ /dev/null @@ -1,84 +0,0 @@ -/** - * The preset picker both surfaces render: a menu of presets over a button - * naming the current one. - * - * The settings row and the composer seat differ in where they sit, what they - * call the current value, and when they refuse a pick — not in how the picker - * itself behaves. Trust is the one thing the list always says: a locally - * authored preset is exactly as privileged as the plugins it names, so the - * label marks it rather than presenting every preset as shipped and vetted. - */ - -import { IconChevronDownOutline14, Menu } from '@deepseek-ai/dsh-client-ui-primitives' -import type { AgentPresetOption } from './settings-store.ts' -import { presetDisplayText, type AgentPresetSettingsKey } from './locales.ts' - -/** What one surface passes to the shared picker. */ -export interface PresetMenuProps { - /** Presets to offer, in roster order. */ - options: readonly AgentPresetOption[] - /** The preset the button names and the menu marks selected. */ - selectedId: string - /** Text on the button; the surfaces word a pending roster differently. */ - label: string - /** Active Web locale lookup. */ - t: (key: AgentPresetSettingsKey) => string - /** Class for the trigger button, owned by the calling surface. */ - buttonClassName: string | undefined - /** Class for the chevron, owned by the calling surface. */ - chevronClassName: string | undefined - /** Whether the trigger refuses interaction. */ - disabled: boolean - /** Whether the menu is open — the surface owns this so it can force it shut. */ - open: boolean - /** Report the menu's next open state. */ - onOpenChange: (open: boolean) => void - /** Called with the picked preset once the menu has closed. */ - onSelect: (id: string) => void -} - -/** - * Render the preset picker. - * @param props - the calling surface's copy, styling, and handlers. - * @returns the menu and its trigger. - */ -export function PresetMenu({ - options, selectedId, label, t, buttonClassName, chevronClassName, - disabled, open, onOpenChange, onSelect, -}: PresetMenuProps) { - return ( - { onOpenChange(false) }} - items={options.map((option) => { - const name = presetDisplayText(option, t).name - return { - id: option.id, - // All preset surfaces resolve copy the same way; the id is addressing, - // not a label, except where no display name exists. - label: option.trust === 'user' ? `${name} · ${t('userTrust')}` : name, - } - })} - selectedId={selectedId} - onSelect={(id) => { - onOpenChange(false) - onSelect(id) - }} - align="end" - portal - anchor={( - - )} - /> - ) -} diff --git a/packages/client/ui-agent-preset/src/client/index.ts b/packages/client/ui-agent-preset/src/client/index.ts index 4926d7c001..3b1e608de4 100644 --- a/packages/client/ui-agent-preset/src/client/index.ts +++ b/packages/client/ui-agent-preset/src/client/index.ts @@ -1,14 +1,15 @@ /** - * Agent-preset surface plugin, browser half — four surfaces over one roster: - * a General-settings row for the default preset, a chip on the new-session - * screen for the session about to start, a read-only label in the session - * header, and a settings section that manages the roster (copy, delete, - * default, and the way into a preset's own files). + * Agent-preset surface plugin, browser half — three surfaces over one roster: + * a chip on the new-session screen for the session about to start, a + * read-only label in the session header, and a settings section that manages + * the roster (copy, delete, default, and the way into a preset's own files). * * A running session keeps the composition it began with (the host refuses to * adopt an existing session under a different preset). That is what splits - * the choice from the display: the General row and the hero chip are both - * before-the-fact, while the header only reports what a session already runs. + * the choice from the display: the hero chip is before-the-fact, while the + * header only reports what a session already runs. The default preset is + * edited where the roster is visible — the settings section's "make default" + * — so General settings carries no duplicate control for the same field. */ // Type-only: pulls the Session Controller service merge (ctx.sessions). @@ -26,19 +27,23 @@ import type {} from '@deepseek-ai/dsh-client-ui-workspace/client' import type { Context as ClientContext } from '@deepseek-ai/cordis' import { AgentPresetLabel } from './AgentPresetLabel.tsx' import type { AgentPresetLabelInjected } from './AgentPresetLabel.tsx' -import { AgentPresetRow } from './AgentPresetRow.tsx' -import type { AgentPresetRowInjected } from './AgentPresetRow.tsx' import { AgentPresetSeat } from './AgentPresetSeat.tsx' import type { AgentPresetSeatInjected } from './AgentPresetSeat.tsx' import { AgentPresetSection } from './AgentPresetSection.tsx' import type { AgentPresetSectionInjected } from './AgentPresetSection.tsx' import { AgentPresetSeatController } from './seat-store.ts' import { AgentPresetSectionController } from './section-store.ts' -import { en, zh } from './locales.ts' +import { en, zh, type AgentPresetSettingsKey } from './locales.ts' import { AGENT_PRESET_SETTINGS_NS, AgentPresetSettingsController } from './settings-store.ts' +declare module '@deepseek-ai/dsh-client-ui-slots' { + interface LocaleNamespaceMap { + /** Agent-preset surface copy. */ + 'settings.agentPreset': AgentPresetSettingsKey + } +} + export type { AgentPresetLabelInjected, AgentPresetLabelProps } from './AgentPresetLabel.tsx' -export type { AgentPresetRowInjected, AgentPresetRowProps } from './AgentPresetRow.tsx' export type { AgentPresetSeatInjected, AgentPresetSeatProps } from './AgentPresetSeat.tsx' export type { AgentPresetSectionInjected, AgentPresetSectionProps } from './AgentPresetSection.tsx' export type { AgentPresetSeatState } from './seat-store.ts' @@ -50,16 +55,15 @@ export { AGENT_PRESET_SETTINGS_NS, writeDefaultPreset } from './settings-store.t /** Required services (cordis fiber inject). */ export const inject = [ - 'slots', 'locale', 'remote', 'remote.agentPresets', 'remote.settings', 'settingsScope', + 'slots', 'locale', 'remote', 'remote.agentPresets', 'remote.settings', ] /** - * Mount the General-settings row. + * Mount the roster surfaces: hero chip, session-header label, settings section. * @param ctx - the browser plugin context. */ export function apply(ctx: ClientContext): void { - const settingsWire = { settings: ctx.remote.settings } - const controller = new AgentPresetSettingsController(settingsWire, ctx.remote, ctx.settingsScope.describe()) + const controller = new AgentPresetSettingsController(ctx.remote) // One roster, four surfaces. The chip is registered in a later scope, so it // subscribes here rather than being reached from this one. const rosterReaders = new Set<() => void>() @@ -70,12 +74,6 @@ export function apply(ctx: ClientContext): void { ctx.effect(() => ctx.locale.register('settings.agentPreset', { zh, en }), 'ui-agent-preset: settings row dictionaries') - const injected = (): AgentPresetRowInjected => ({ - hooks: { agentPreset: controller.store }, - load: () => controller.load(), - select: (id: string) => controller.select(id), - }) - ctx.effect(() => { // The roster is a live directory and the default is a settings field, so // both an external settings edit and a reconnect can move this row. @@ -193,13 +191,6 @@ export function apply(ctx: ClientContext): void { makeDefault: (id: string) => section.makeDefault(id), }) - ctx.slots.inject('settings.general.item', () => ctx.slots.register({ - name: 'settings.general.item', - id: 'agent-preset', - order: -25, - locale: 'settings.agentPreset', - inject: injected, - }, AgentPresetRow)) // Ordered after Models: choosing a model is routine, and composing an // agent is the deployment-shaping act behind it. ctx.slots.inject('settings.section', () => ctx.slots.register({ diff --git a/packages/client/ui-agent-preset/src/client/locales.ts b/packages/client/ui-agent-preset/src/client/locales.ts index b8e9f8b6e2..64b9d4b0ad 100644 --- a/packages/client/ui-agent-preset/src/client/locales.ts +++ b/packages/client/ui-agent-preset/src/client/locales.ts @@ -1,8 +1,8 @@ -/** Locale bundles for the agent-preset settings row, hero chip, header label, and management section. */ +/** Locale bundles for the agent-preset hero chip, header label, and management section. */ /** Locale keys these surfaces render. */ export type AgentPresetSettingsKey = - | 'title' | 'description' | 'loading' | 'error' | 'userTrust' | 'seatHint' | 'headerHint' + | 'error' | 'userTrust' | 'seatHint' | 'headerHint' | 'nav' | 'sectionIntro' | 'builtIn' | 'setDefault' | 'view' | 'presetStandardName' | 'presetStandardDescription' | 'presetPtcName' | 'presetPtcDescription' @@ -20,9 +20,6 @@ export type AgentPresetSettingsKey = /** English copy. */ export const en: Record = { - title: 'Agent preset', - description: 'Applies to sessions you start from now on. Running sessions keep the preset they began with.', - loading: 'Loading presets…', error: 'Could not load agent presets.', userTrust: 'Custom', seatHint: 'Agent preset for the session you are about to start', @@ -87,9 +84,6 @@ export const en: Record = { /** Simplified Chinese copy. */ export const zh: Record = { - title: 'Agent 预设', - description: '对此后新建的会话生效。运行中的会话保持它开始时的预设。', - loading: '正在加载预设…', error: '无法加载 Agent 预设。', userTrust: '自定义', seatHint: '即将开始的这个会话所用的 Agent 预设', 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 398b781e67..df8bed68d4 100644 --- a/packages/client/ui-agent-preset/src/client/settings-store.ts +++ b/packages/client/ui-agent-preset/src/client/settings-store.ts @@ -1,16 +1,15 @@ /** - * Agent-preset default-settings controller. + * Agent-preset roster store shared by the display surfaces. * - * Options and the current default both come from one `agentPresets.list` call: - * the roster already reports which id a session with no explicit choice gets, - * so the row needs no schema introspection. Writes target the settings - * namespace's `default` field, which is what the host resolves at creation. + * Options come from one `agentPresets.list` call. Writes target the settings + * namespace's `default` field, which is what the host resolves at creation; + * the management section is the surface that writes it. */ import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client' import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-store' import type { AgentPresetRoster } from '@deepseek-ai/dsh-agent-presets/types' -import type { SettingsDescribeFace, SettingsWireFace } from '@deepseek-ai/dsh-client-ui-settings/client' +import type { SettingsWireFace } from '@deepseek-ai/dsh-client-ui-settings/client' /** The agent-preset settings namespace on the host wire. */ export const AGENT_PRESET_SETTINGS_NS = 'agent-presets' @@ -29,9 +28,9 @@ export function messageOf(error: unknown): string { /** * Persist one preset as the default for sessions created later. * - * The default is a settings field rather than a preset property, so both the - * General row and the management section write it here — one home for which - * namespace and field the host resolves at session creation. + * The default is a settings field rather than a preset property; the + * management section writes it here — one home for which namespace and field + * the host resolves at session creation. * @param api - the settings wire face. * @param id - the preset to make default. * @returns the failure message, or undefined once the write landed. @@ -126,14 +125,14 @@ export async function beginRosterRead = createSnapshotStore(INITIAL) /** - * @param api - the settings wire face (the default write). * @param remote - the agent-preset Remote namespace (the roster read). - * @param describeFace - the shared mirror's describe face (writability source). */ constructor( - private readonly api: SettingsWireFace, private readonly remote: Pick, - private readonly describeFace: SettingsDescribeFace, ) {} private set(patch: Partial): void { @@ -196,53 +179,23 @@ export class AgentPresetSettingsController { /** * Load the roster. An empty roster means the deployment composes no - * presets, which is a valid deployment rather than a failure — the row - * reports `unavailable` and renders nothing. + * presets, which is a valid deployment rather than a failure — the + * surfaces report `unavailable` and render nothing. * @returns once the snapshot reflects the host. */ async load(): Promise { const roster = await beginRosterRead(this.remote, this.store) if (roster === undefined) return const { presets } = roster - const [first] = presets - if (first === undefined) { - this.set({ status: 'unavailable', options: [], currentValue: '' }) + if (presets.length === 0) { + this.set({ status: 'unavailable', options: [] }) return } - // The roster says what may be chosen; the shared mirror says whether this - // browser may write the choice down. A non-loopback browser's mirror never - // answers, so the row stays read-only rather than offering a control - // whose write the Host would refuse. - await this.describeFace.ensure() this.set({ status: 'ready', error: null, - writable: this.describeFace.getSnapshot().view?.writable ?? false, options: presetOptions(presets), - // A roster can mark nothing default: settings can name a preset that - // was since deleted, and the picker still has to show something. - currentValue: presets.find(preset => preset.isDefault)?.id ?? first.id, }) } - /** - * Persist one preset as the default for sessions created later. Running - * sessions keep the composition they were created with, so this never - * disturbs work in progress. - * @param id - the preset to make default. - * @returns once the write settled and the roster was re-read. - */ - async select(id: string): Promise { - const before = this.store.getSnapshot() - if (before.status === 'saving' || id === before.currentValue) return - this.set({ status: 'saving', error: null, currentValue: id }) - const failure = await writeDefaultPreset(this.api, id) - if (failure !== undefined) { - this.set({ status: 'ready', currentValue: before.currentValue, error: failure }) - return - } - // Re-read rather than trust the patch: the host resolves the default - // through the same roster the row displays. - await this.load() - } } diff --git a/packages/client/ui-agent-preset/tests/apply.client.spec.ts b/packages/client/ui-agent-preset/tests/apply.client.spec.ts index c2488de4af..a4fc61c717 100644 --- a/packages/client/ui-agent-preset/tests/apply.client.spec.ts +++ b/packages/client/ui-agent-preset/tests/apply.client.spec.ts @@ -16,8 +16,6 @@ import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/d import { apply, inject } from '@deepseek-ai/dsh-client-ui-agent-preset/client' import { AgentPresetLabel } from '../src/client/AgentPresetLabel.tsx' import type { AgentPresetLabelInjected } from '../src/client/AgentPresetLabel.tsx' -import { AgentPresetRow } from '../src/client/AgentPresetRow.tsx' -import type { AgentPresetRowInjected } from '../src/client/AgentPresetRow.tsx' import { AgentPresetSection } from '../src/client/AgentPresetSection.tsx' import type { AgentPresetSectionInjected } from '../src/client/AgentPresetSection.tsx' import { AgentPresetSeat } from '../src/client/AgentPresetSeat.tsx' @@ -177,19 +175,19 @@ function sessionsDouble(state: { describe('ui-agent-preset apply', () => { it('declares the services it uses', () => { expect(inject).toEqual([ - 'slots', 'locale', 'remote', 'remote.agentPresets', 'remote.settings', 'settingsScope', + 'slots', 'locale', 'remote', 'remote.agentPresets', 'remote.settings', ]) }) - it('registers the General row and the settings section', async () => { + it('registers the settings section and no General row', async () => { const { ctx, slots } = await bench() declareRoot(slots) await ctx.plugin({ inject: [...inject], apply }).await() - const row = slots.entries('settings.general.item')[0]! - expect(row.component).toBe(AgentPresetRow) - expect(row.options).toMatchObject({ id: 'agent-preset', order: -25 }) + // The default preset is edited in the section, where the roster is + // visible; a General row would duplicate the same settings field. + expect(slots.entries('settings.general.item')).toHaveLength(0) const section = slots.entries('settings.section')[0]! expect(section.component).toBe(AgentPresetSection) expect(section.options).toMatchObject({ id: 'agent-presets', order: 20 }) @@ -206,21 +204,14 @@ describe('ui-agent-preset apply', () => { await vi.waitFor(() => { expect(slots.entries('settings.section')).toHaveLength(1) }) }) - it('hands each surface its own store and actions', async () => { + it('hands the section its own store and default write', async () => { const { ctx, slots } = await bench() declareRoot(slots) await ctx.plugin({ inject: [...inject], apply }).await() - const row = (slots.entries('settings.general.item')[0]!.inject as unknown as () => AgentPresetRowInjected)() const section = (slots.entries('settings.section')[0]!.inject as unknown as () => AgentPresetSectionInjected)() - expect(row.hooks.agentPreset).not.toBe(section.hooks.agentPresetSection) - // Each thunk reaches its own controller: the row's load fills the row's - // store, and the section's default write does not go through the row. - await row.load() - await row.select('standard') await section.makeDefault('standard') - expect(row.hooks.agentPreset.getSnapshot().options).toEqual([{ id: 'standard', trust: 'system' }]) expect(section.hooks.agentPresetSection.getSnapshot().rows) .toEqual([{ id: 'standard', trust: 'system', isDefault: true }]) }) @@ -294,8 +285,8 @@ describe('ui-agent-preset apply', () => { remote.emit('settings/document-updated', ['agent-presets', 1]) await vi.waitFor(() => { expect(calls.length).toBeGreaterThan(before) }) - // Only the General row reloads: a section nobody opened has nothing to - // converge, and reading the roster for it would be a wasted round trip. + // Only the header label's roster reloads: a section nobody opened has + // nothing to converge, and reading the roster for it would be wasted. expect(calls.length - before).toBe(1) }) @@ -471,7 +462,7 @@ describe('ui-agent-preset apply', () => { expect(calls.filter(call => call === 'select:minimal')).toHaveLength(spent) }) - it('gives the header label the same roster the General row reads', async () => { + it('loads the header label from the shared roster store', async () => { const { ctx, slots } = await bench() declareRoot(slots) declareConversation(slots) @@ -481,14 +472,9 @@ describe('ui-agent-preset apply', () => { await ctx.plugin({ inject: [...inject, 'conversation', 'sessions', 'uiWorkspace'], apply }).await() const label = (slots.entries('conversation.session.header.actions')[0]! .inject as unknown as () => AgentPresetLabelInjected)() - const row = (slots.entries('settings.general.item')[0]! - .inject as unknown as () => AgentPresetRowInjected)() await label.load() - // One roster behind both: the label resolves a name the settings row's own - // load already fetched, rather than issuing a second read per session. - expect(label.hooks.agentPresets).toBe(row.hooks.agentPreset) expect(label.hooks.agentPresets.getSnapshot().options).toEqual([{ id: 'standard', trust: 'system' }]) }) diff --git a/packages/client/ui-agent-preset/tests/components.client.spec.tsx b/packages/client/ui-agent-preset/tests/components.client.spec.tsx index b2c9bcfac6..5a3904efa3 100644 --- a/packages/client/ui-agent-preset/tests/components.client.spec.tsx +++ b/packages/client/ui-agent-preset/tests/components.client.spec.tsx @@ -1,10 +1,9 @@ // @vitest-environment jsdom /** - * The three conversation-adjacent surfaces: the General-settings row naming the - * default for later sessions, the new-session chip naming the next one's, and - * the session header's read-only label. The split is the host's rule — a - * session's history is produced under its preset's tools, so the choice is - * only ever offered before one starts. + * The two conversation-adjacent surfaces: the new-session chip naming the + * next session's preset, and the session header's read-only label. The split + * is the host's rule — a session's history is produced under its preset's + * tools, so the choice is only ever offered before one starts. */ import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react' @@ -13,8 +12,6 @@ import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime' import { createSnapshotStore } from '@deepseek-ai/dsh-client-store' import { AgentPresetLabel } from '../src/client/AgentPresetLabel.tsx' import type { AgentPresetLabelProps } from '../src/client/AgentPresetLabel.tsx' -import { AgentPresetRow } from '../src/client/AgentPresetRow.tsx' -import type { AgentPresetRowProps } from '../src/client/AgentPresetRow.tsx' import { AgentPresetSeat } from '../src/client/AgentPresetSeat.tsx' import type { AgentPresetSeatProps } from '../src/client/AgentPresetSeat.tsx' import type { AgentPresetSettingsState } from '../src/client/settings-store.ts' @@ -23,13 +20,9 @@ import { en } from '../src/client/locales.ts' afterEach(cleanup) -const ROW_READY: AgentPresetSettingsState = { +const ROSTER_READY: AgentPresetSettingsState = { status: 'ready', error: null, - writable: true, - currentValue: 'standard', - // `mine` deliberately names itself nothing: the row must fall back to the - // id for a preset whose author wrote no metadata. options: [{ id: 'standard', trust: 'system', name: '标准模式' }, { id: 'mine', trust: 'user' }], } @@ -44,17 +37,6 @@ const SEAT_READY: AgentPresetSeatState = { introduce: false, } -function renderRow(state: Partial = {}) { - const store = createSnapshotStore({ ...ROW_READY, ...state }) - const actions = { load: vi.fn(() => Promise.resolve()), select: vi.fn(() => Promise.resolve()) } - render( en[key], - } as unknown as AgentPresetRowProps)} />) - return actions -} - /** The runtime's own `{name}` substitution, so a test reads the shown text. */ function translate(key: keyof typeof en, params?: Record): string { const template = en[key] @@ -83,7 +65,7 @@ function renderLabel( ) { // The chip and the label read the same roster, metadata included. const store = createSnapshotStore({ - ...ROW_READY, options: SEAT_READY.options, ...roster, + ...ROSTER_READY, options: SEAT_READY.options, ...roster, }) const sessions = createSnapshotStore({ byId: summary === undefined ? {} : { s1: summary } }) const load = vi.fn(() => Promise.resolve()) @@ -97,116 +79,6 @@ function renderLabel( return { load, view } } -describe('the General-settings row', () => { - it('reads the roster once and shows the current default', async () => { - const actions = renderRow() - - await waitFor(() => { expect(actions.load).toHaveBeenCalledTimes(1) }) - expect(screen.getByRole('button').textContent).toContain(en.presetStandardName) - }) - - it('marks a locally authored option as local', () => { - renderRow() - - fireEvent.click(screen.getByRole('button')) - - // A local preset is exactly as privileged as the plugins it names, so the - // list says which rows are local rather than presenting all as vetted. - expect(screen.getByText(`mine · ${en.userTrust}`)).toBeTruthy() - // The shipped one carries no marker; only local rows are called out. - expect(screen.getAllByText(en.presetStandardName)).toHaveLength(2) - }) - - it('falls back to the id for a preset that published no name', () => { - renderRow({ - currentValue: 'mine', - options: [ - { id: 'standard', trust: 'system', name: '标准模式' }, - { id: 'bare', trust: 'system' }, - { id: 'mine', trust: 'user' }, - { id: 'ours', trust: 'user', name: '团队模式' }, - ], - }) - - // The trigger names the preset; with no metadata the id is all there is. - expect(screen.getByRole('button').textContent).toContain('mine') - - fireEvent.click(screen.getByRole('button')) - - // A locally authored preset is marked whether or not it named itself. - expect(screen.getByText(`团队模式 · ${en.userTrust}`)).toBeTruthy() - expect(screen.getByText(`mine · ${en.userTrust}`)).toBeTruthy() - // A shipped preset with no metadata is listed by id and carries no mark. - expect(screen.getByText('bare')).toBeTruthy() - }) - - it('shows the selected id until a stale roster contains it', () => { - renderRow({ currentValue: 'arriving', options: [] }) - - expect(screen.getByRole('button').textContent).toContain('arriving') - }) - - it('writes the picked preset and closes the menu', () => { - const actions = renderRow() - fireEvent.click(screen.getByRole('button')) - - fireEvent.click(screen.getByText(`mine · ${en.userTrust}`)) - - expect(actions.select).toHaveBeenCalledWith('mine') - expect(screen.getByRole('button').getAttribute('aria-expanded')).toBe('false') - }) - - it('closes on an outside dismissal', () => { - renderRow() - fireEvent.click(screen.getByRole('button')) - - fireEvent.keyDown(document, { key: 'Escape' }) - - expect(screen.getByRole('button').getAttribute('aria-expanded')).toBe('false') - }) - - it('says it is loading before the roster answers', () => { - renderRow({ status: 'loading', currentValue: '' }) - - expect(screen.getByRole('button').textContent).toContain(en.loading) - expect(screen.getByRole('button')).toHaveProperty('disabled', true) - }) - - it('shows a failure in place of the description', () => { - renderRow({ error: 'roster unavailable' }) - - expect(screen.getByRole('alert').textContent).toBe('roster unavailable') - }) - - it('renders nothing when the deployment composes no presets', () => { - const { container } = render( Promise.resolve()), - select: vi.fn(() => Promise.resolve()), - useAgentPreset: bindSnapshotSelector( - createSnapshotStore({ ...ROW_READY, status: 'unavailable', options: [] })), - t: (key: keyof typeof en) => en[key], - } as unknown as AgentPresetRowProps)} />) - - expect(container.firstChild).toBeNull() - }) - - it('closes and locks the menu when the settings turn read-only', () => { - const store = createSnapshotStore(ROW_READY) - render( Promise.resolve()), - select: vi.fn(() => Promise.resolve()), - useAgentPreset: bindSnapshotSelector(store), - t: (key: keyof typeof en) => en[key], - } as unknown as AgentPresetRowProps)} />) - fireEvent.click(screen.getByRole('button')) - - act(() => { store.set({ ...ROW_READY, writable: false }) }) - - expect(screen.getByRole('button').getAttribute('aria-expanded')).toBe('false') - expect(screen.getByRole('button')).toHaveProperty('disabled', true) - }) -}) - describe('the new-session chip', () => { it('reads the roster once and shows the staged preset by name', async () => { const actions = renderSeat() 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 4d8544dfcf..2b1022de62 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 @@ -1,29 +1,29 @@ /** - * The agent-preset settings controller: it derives both the options and the - * current default from one roster call, writes only the `default` field, and - * treats an empty roster as "this deployment composes no presets" rather than - * as a failure. + * The agent-preset roster store: it derives the display options from one + * roster call and treats an empty roster as "this deployment composes no + * presets" rather than as a failure. The default is written by the + * management section through `writeDefaultPreset`, which targets only the + * `default` field of the agent-presets namespace. */ import { describe, expect, it } from 'vitest' import type { ClientRemote } from '@deepseek-ai/dsh-api-remotes/client' import type { SettingsWireFace } from '@deepseek-ai/dsh-client-ui-settings/client' import type { SessionSummary } from '@deepseek-ai/dsh-api-session-controller/client' -import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts' import type { SessionId } from '@deepseek-ai/dsh-session/types' import { - AGENT_PRESET_SETTINGS_NS, AgentPresetSettingsController, messageOf, + AGENT_PRESET_SETTINGS_NS, AgentPresetSettingsController, messageOf, writeDefaultPreset, } from '../src/client/settings-store.ts' -/** The two faces the row reads: the roster Remote and the settings wire. */ +/** The two faces these tests drive: the roster Remote and the settings wire. */ interface FakeWire { api: SettingsWireFace remote: Pick } -/** Controller over a real mirror derived from the same fake wire. */ +/** The roster store over the fake wire's Remote face. */ function derivedController(wire: FakeWire) { - return new AgentPresetSettingsController(wire.api, wire.remote, new SettingsDescribeMirror(wire.api)) + return new AgentPresetSettingsController(wire.remote) } import { AgentPresetSeatController } from '../src/client/seat-store.ts' @@ -59,17 +59,10 @@ function fakeApi( failWrite?: string failList?: string failWriteWith?: Error - readOnly?: boolean } = {}, ): FakeWire { const api = { settings: { - // Host persistence is enabled in production only on the selected client path; a read-only provider answers writable:false - // and the row disables its control instead of offering a refused write. - describe: () => Promise.resolve({ - ok: true as const, - value: { writable: options.readOnly !== true, hasDocument: true, namespaces: [] }, - }), update: (ns: string, patch: { default?: unknown }) => { options.writes?.push({ ns, ops: patch }) if (options.failWriteWith !== undefined) return Promise.reject(options.failWriteWith) @@ -90,22 +83,8 @@ function fakeApi( } } -describe('the agent-preset settings controller', () => { - it('disables the control when this browser may not write settings', async () => { - const controller = derivedController(fakeApi([ - { id: 'standard', trust: 'system', isDefault: true }, - ], { readOnly: true })) - - await controller.load() - - // The enabled `settings.describe` path reports a read-only provider; - // 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') - }) - - it('derives options and the current default from one roster call', async () => { +describe('the agent-preset roster store', () => { + it('derives the display options from one roster call', async () => { const controller = derivedController(fakeApi([ { id: 'standard', trust: 'system', isDefault: true }, { id: 'mine', trust: 'user', isDefault: false }, @@ -115,7 +94,6 @@ describe('the agent-preset settings controller', () => { const state = controller.store.getSnapshot() expect(state.status).toBe('ready') - expect(state.currentValue).toBe('standard') expect(state.options).toEqual([ { id: 'standard', trust: 'system' }, { id: 'mine', trust: 'user' }, @@ -156,7 +134,7 @@ describe('the agent-preset settings controller', () => { await controller.load() // A deployment composing no presets is valid: every session shares the - // host composition and the row renders nothing. + // host composition and the surfaces render nothing. expect(controller.store.getSnapshot().status).toBe('unavailable') expect(controller.store.getSnapshot().error).toBeNull() }) @@ -175,48 +153,27 @@ describe('the agent-preset settings controller', () => { expect(controller.store.getSnapshot()).toMatchObject({ status: 'unavailable', error: null, options: [] }) }) - it('writes only the default field, into the agent-presets namespace', async () => { + it('writeDefaultPreset writes only the default field, into the agent-presets namespace', async () => { const writes: Recorded[] = [] - const controller = derivedController(fakeApi([ + const wire = fakeApi([ { id: 'standard', trust: 'system', isDefault: true }, { id: 'minimal', trust: 'system', isDefault: false }, - ], { writes })) - await controller.load() + ], { writes }) - await controller.select('minimal') + expect(await writeDefaultPreset(wire.api, 'minimal')).toBeUndefined() expect(writes).toEqual([{ ns: AGENT_PRESET_SETTINGS_NS, ops: { default: 'minimal' }, }]) - expect(controller.store.getSnapshot().currentValue).toBe('minimal') }) - it('restores the previous value and surfaces the message when the write fails', async () => { - const controller = derivedController(fakeApi([ + it('writeDefaultPreset surfaces the refusal message when the write fails', async () => { + const wire = fakeApi([ { id: 'standard', trust: 'system', isDefault: true }, - { id: 'minimal', trust: 'system', isDefault: false }, - ], { failWrite: 'read-only settings' })) - await controller.load() + ], { failWrite: 'read-only settings' }) - await controller.select('minimal') - - const state = controller.store.getSnapshot() - expect(state.currentValue).toBe('standard') - expect(state.error).toBe('read-only settings') - expect(state.status).toBe('ready') - }) - - it('ignores a pick that is already the default', async () => { - const writes: Recorded[] = [] - const controller = derivedController(fakeApi([ - { id: 'standard', trust: 'system', isDefault: true }, - ], { writes })) - await controller.load() - - await controller.select('standard') - - expect(writes).toEqual([]) + expect(await writeDefaultPreset(wire.api, 'minimal')).toBe('read-only settings') }) it('surfaces a roster failure without claiming the deployment has no presets', async () => { @@ -229,19 +186,6 @@ describe('the agent-preset settings controller', () => { expect(state.error).toBe('host down') }) - it('shows the first preset when the roster marks none default', async () => { - // Settings can name a preset that was since deleted; the picker still has - // to show something rather than an empty control. - const controller = derivedController(fakeApi([ - { id: 'standard', trust: 'system', isDefault: false }, - { id: 'mine', trust: 'user', isDefault: false }, - ])) - - await controller.load() - - expect(controller.store.getSnapshot().currentValue).toBe('standard') - }) - it('ignores a load while one is already in flight', async () => { const writes: Recorded[] = [] const controller = derivedController(fakeApi( @@ -270,18 +214,15 @@ describe('the agent-preset settings controller', () => { expect(controller.store.getSnapshot()).toMatchObject({ status: 'error', error: 'socket closed' }) }) - it('reports a transport that rejects mid-write and keeps the old default showing', async () => { - const controller = derivedController(fakeApi([ + it('writeDefaultPreset reports a transport that rejects mid-write', async () => { + const wire = fakeApi([ { id: 'standard', trust: 'system', isDefault: true }, { id: 'mine', trust: 'user', isDefault: false }, - ], { failWriteWith: new Error('socket closed') })) - await controller.load() + ], { failWriteWith: new Error('socket closed') }) - await controller.select('mine') - - // The value snaps back because the host never took it; a picker still - // showing "mine" would be claiming a default that does not exist. - expect(controller.store.getSnapshot()).toMatchObject({ currentValue: 'standard', error: 'socket closed' }) + // The caller must be able to say the host never took the value; a surface + // still showing "mine" would be claiming a default that does not exist. + expect(await writeDefaultPreset(wire.api, 'mine')).toBe('socket closed') }) }) @@ -567,22 +508,4 @@ describe('the new-session chip controller', () => { expect(controller.store.getSnapshot().error).toBe('socket closed') }) - it('degrades to a read-only row while the mirror holds no answer', async () => { - const controller = derivedController({ - // The roster answered; the mirror's read is what failed, so the row - // shows the current default without offering a write it never confirmed. - api: { settings: { describe: () => Promise.reject(new Error('socket closed')) } } as unknown as SettingsWireFace, - remote: fakeRoster([{ id: 'standard', trust: 'system', isDefault: true }]), - }) - - await controller.load() - - expect(controller.store.getSnapshot()).toMatchObject({ - status: 'ready', - writable: false, - currentValue: 'standard', - }) - }) - - }) diff --git a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml b/packages/client/ui-settings-plugin-inventory/README.i18n.yaml index 198b22aa97..f1a56b6c18 100644 --- a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml +++ b/packages/client/ui-settings-plugin-inventory/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-plugin-inventory/README.md -README.md: c44e150e528f20349429f9a49d416367f1ca3c41 -README.zh.md: ae2e2cd1105464f0fb262a07e96b66082a6e7166 +README.md: bc89b60e89e0fe257c6f422a2749bd4188fe796c +README.zh.md: 13c09aaeb108120ba22f05d9828da75088a7deb8 diff --git a/packages/client/ui-settings-plugin-inventory/README.md b/packages/client/ui-settings-plugin-inventory/README.md index c44e150e52..bc89b60e89 100644 --- a/packages/client/ui-settings-plugin-inventory/README.md +++ b/packages/client/ui-settings-plugin-inventory/README.md @@ -1,5 +1,5 @@ --- -description: "Read-only Cordis Loader inventory tab in Web Plugins settings for the dsh web client: searchable plugin catalog with enablement state and configuration." +description: "Scope-grouped read-only plugin inventory tab in Web Plugins settings for the dsh web client: agent-preset compositions first, the global plane behind a disclosure, search across both." kind: "package-reference" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-client-ui-settings-plugin-inventory` contributes the read-only **Plugin list** tab to the Web Settings Plugins section. The tab lazily calls `ctx.remote.pluginInventory.list()` the first time it is selected and renders a searchable two-column catalog of compact disclosure cards: each collapsed card shows the short module name, an effective-enablement tag, and (for enabled entries) a colored root-fiber status dot; expanding a card reveals the Loader-tree entry id, effective configuration, and Cordis status. Loading, empty, no-match, and generic failure states stay local to the mounted component, and a failed read can be retried without exposing transport details. +`dsh-client-ui-settings-plugin-inventory` contributes the read-only **Plugin list** tab to the Web Settings Plugins section. The tab lazily calls `ctx.remote.pluginInventory.list()` the first time it is selected and renders the inventory in two groups. The agent-preset group comes first: a display-only switcher over the roster opens on the default preset, and each composition row is a compact disclosure card carrying its enablement — including `conditional` for a disabled gate only a mount can decide — with provenance facts behind the disclosure. The global group follows collapsed, its header carrying the entry count and a failure count; expanded, failures float first, and entries disabled globally but enabled by presets fold into a session-plugins drawer naming their providers instead of reading as plainly disabled. Search filters both groups, forces the collapsed disclosures open, and points at matches sitting in unselected presets. Loading, empty, no-match, and generic failure states stay local to the mounted component, and a failed read can be retried without exposing transport details; without a roster the tab renders the global plane alone, expanded. ## Table of Contents @@ -29,7 +29,11 @@ Open the Plugins section in Settings and select the **Plugin list** tab to inspe ### Reading a card -Each collapsed card uses the short module name as its title and a small effective-enablement tag; enabled entries also show a colored root-fiber status dot. Expanding one card reveals its Loader-tree entry id, followed by the effective configuration and, for enabled entries, Cordis status; disabled entries omit the redundant unmounted runtime state. Search filters the catalog by name and entry id. +Each collapsed card uses the short module name as its title and a small enablement tag; enabled entries also show a colored root-fiber status dot. Expanding one card reveals the declared entry id, the full module specifier, and the state facts: a preset row names the preset it comes from, its runtime status when the composition is live, and its enable condition when it carries one; a session-plugins drawer row explains that agent presets provide it per session, names the presets that enable it, and offers a jump into the preset group. Search filters both groups by module name and entry id. + +### The preset switcher + +The switcher lists every roster preset — the default suffixed as such, broken ones marked — and changes only what the list shows: it writes no settings, and selecting a broken preset shows the discovery-reported reason in place of rows. Choosing the default preset or a session's preset stays where it was: the Agent presets section and the new-session screen. ### Retrying a failed read @@ -51,7 +55,7 @@ The browser plugin registers one localized `settings.plugins.tab` contribution w ### Rendering -The entry id remains the React key, disclosure identity, detail value, and an additional search target; it is never classified by string shape. +Row keys are scope-qualified (`global:`, `drawer:`, `preset::`), so one module appearing in several scopes keeps distinct disclosure state; an entry id is shown as detail only when the row declares one and is never classified by string shape. The session-plugins drawer is derived client-side: a global entry joins it when it is disabled there while at least one preset row for the same module specifier is actually enabled, so a module every preset gates off (or declares only conditionally) stays plainly disabled rather than over-claiming provision. @@ -86,7 +90,7 @@ None; this package neither assembles nor sends a provider request. These limits define the freshness and reach of the inventory view; they are current package constraints. - **One snapshot per Settings mount or retry** — the tab does not subscribe to Loader changes or automatically refetch after reconnect; switching tabs preserves the current snapshot, while reopening Settings obtains a new one. -- **Read-only Loader view** — local search does not add provenance, current-browser activation diagnosis, grouping by source, or plugin mutation controls. +- **Read-only in both planes** — the tab shows global and preset enablement but mutates neither; enable/disable controls that write a custom preset's own composition file are deliberate follow-up work. ### Dev Note diff --git a/packages/client/ui-settings-plugin-inventory/README.zh.md b/packages/client/ui-settings-plugin-inventory/README.zh.md index ae2e2cd110..13c09aaeb1 100644 --- a/packages/client/ui-settings-plugin-inventory/README.zh.md +++ b/packages/client/ui-settings-plugin-inventory/README.zh.md @@ -1,5 +1,5 @@ --- -description: "dsh Web 客户端设置中的只读 Cordis Loader 清单标签页：可搜索的插件目录，含启停状态与配置。" +description: "dsh Web 客户端设置中按作用域分组的只读插件清单标签页：Agent 预设组合在前，全局平面收在折叠分组里，搜索跨两组。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-client-ui-settings-plugin-inventory` 向 Web 设置的「插件」分区贡献只读的**插件列表**标签页。该标签页在首次被选择时懒调用 `ctx.remote.pluginInventory.list()`，并以可搜索的双列紧凑折叠卡片展示清单：每张收起的卡片显示模块短名称、有效启停标签，以及（对已启用条目）彩色根 fiber 状态圆点；展开卡片会显示 Loader 树条目 id、有效配置与 Cordis 状态。加载、空结果、无匹配与通用失败状态只属于已挂载组件，读取失败后可以重试，且不会暴露传输细节。 +`dsh-client-ui-settings-plugin-inventory` 向 Web 设置的「插件」分区贡献只读的**插件列表**标签页。该标签页在首次被选择时懒调用 `ctx.remote.pluginInventory.list()`，并把清单分成两组渲染。Agent 预设组在前：一个只改显示的切换器覆盖 roster、初始停在默认预设，每个组合行是一张紧凑折叠卡片，携带其启停状态——含只有挂载才能裁决的 disabled 门对应的 `conditional`——出处事实收在折叠里。全局组随后且默认收起，组头带条目计数与失败计数；展开后失败行浮在最前，全局停用但被预设启用的条目收进「会话插件」抽屉并列出提供它的预设，而不是读作单纯的已停用。搜索同时过滤两组、强制撑开收起的折叠，并指出未选中预设里的匹配。加载、空结果、无匹配与通用失败状态只属于已挂载组件，读取失败后可以重试，且不会暴露传输细节；没有 roster 时标签页只渲染全局平面并保持展开。 ## 目录 @@ -29,7 +29,11 @@ kind: "package-reference" ### 阅读卡片 -每张收起的卡片使用模块短名称作为标题，并以小标签表示有效启停状态；已启用的条目还会显示彩色根 fiber 状态圆点。展开卡片后会直接展示 Loader 树条目 id、有效配置，已启用条目还会显示 Cordis 状态；已停用条目省略重复的「未挂载」运行状态。搜索按名称与条目 id 过滤目录。 +每张收起的卡片使用模块短名称作为标题，并以小标签表示启停状态；已启用的条目还会显示彩色根 fiber 状态圆点。展开卡片后会显示声明的条目 id、完整模块标识与状态事实：预设行说明它来自哪个预设、组合存活时的运行状态，以及它携带的启用条件；「会话插件」抽屉行说明它由 Agent 预设按会话提供、列出启用它的预设，并提供跳转到预设组的入口。搜索按模块名称与条目 id 过滤两组。 + +### 预设切换器 + +切换器列出 roster 的每个预设——默认项带后缀、坏预设带标记——并且只改变列表显示什么：它不写任何设置，选中坏预设时在行的位置展示 discovery 报告的原因。选默认预设或某个会话的预设仍在原处：Agent 预设分区与新会话页。 ### 重试失败的读取 @@ -51,7 +55,7 @@ kind: "package-reference" ### 渲染 -条目 id 仍作为 React key、展开标识、详情值与额外的搜索目标；代码不按字符串形状对它分类。 +行 key 按作用域限定（`global:`、`drawer:`、`preset::`），因此同一模块出现在多个作用域时保持各自的展开状态；条目 id 只在行声明了它时作为详情展示，代码不按字符串形状对它分类。「会话插件」抽屉在客户端推导：一个全局条目在全局被停用、且至少一个预设行对同一模块标识实际启用时才归入抽屉，因此被所有预设关掉（或仅条件声明）的模块保持单纯的已停用，而不是夸大提供关系。 @@ -86,7 +90,7 @@ kind: "package-reference" 这些限制定义清单视图的新鲜度与触达范围；它们是当前包约束。 - **每次 Settings 挂载或重试只读取一份快照**：标签页不订阅 Loader 变化，也不会在重连后自动重新读取；切换标签页会保留当前快照，重新打开 Settings 则会取得新快照。 -- **只读 Loader 视图**：本地搜索不会额外引入来源、按来源分组、当前浏览器激活诊断或插件修改控件。 +- **两个平面都只读**：标签页展示全局与预设的启停状态但都不修改；写回自定义预设组合文件的启停控件是刻意留作后续的工作。 ### 开发备注 diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css index de10a3bd36..41c2d7ef59 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css @@ -201,11 +201,181 @@ white-space: nowrap; } -.configTag[data-enabled='true'] { +.configTag[data-kind='enabled'] { background: color-mix(in srgb, var(--dsw-alias-state-success-primary) 10%, transparent); color: var(--dsw-alias-state-success-primary); } +.configTag[data-kind='preset'] { + background: color-mix(in srgb, var(--dsw-alias-state-business-primary) 10%, transparent); + color: var(--dsw-alias-state-business-primary); +} + +.configTag[data-kind='conditional'] { + background: color-mix(in srgb, var(--dsw-alias-state-warning-primary, #b45309) 12%, transparent); + color: var(--dsw-alias-state-warning-primary, #b45309); +} + +.configTag[data-kind='failed'] { + background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent); + color: var(--dsw-alias-state-error-primary); +} + +.group { + display: flex; + flex-direction: column; + gap: 10px; + border: 1px solid var(--dsw-alias-border-l2); + border-radius: 12px; + padding: 10px 12px 12px; +} + +.groupHeader, +.groupToggle { + display: flex; + align-items: center; + gap: 8px; + min-height: 28px; +} + +.groupToggle { + width: 100%; + border: 0; + padding: 0; + background: transparent; + color: inherit; + font: inherit; + text-align: left; + cursor: pointer; +} + +.groupToggle:focus-visible { + outline: 2px solid var(--dsw-alias-state-business-primary); + outline-offset: 2px; +} + +.groupToggle > .chevron { + transform: rotate(-90deg); +} + +.groupToggle[aria-expanded='true'] > .chevron { + transform: none; +} + +.groupTitle { + font-size: 13px; + line-height: 20px; + font-weight: 600; +} + +.groupSubtitle { + overflow: hidden; + color: var(--dsw-alias-label-tertiary); + font-size: 12px; + line-height: 18px; + text-overflow: ellipsis; + white-space: nowrap; +} + +.groupCount { + margin-left: auto; + color: var(--dsw-alias-label-tertiary); + font-size: 12px; + line-height: 18px; + font-variant-numeric: tabular-nums; +} + +.failedCount { + flex: none; + color: var(--dsw-alias-state-error-primary); + font-size: 12px; + line-height: 18px; +} + +.switcher { + max-width: 60%; + border: 1px solid var(--dsw-alias-border-l2); + border-radius: 8px; + padding: 3px 8px; + background: var(--dsw-alias-bg-layer-1); + color: var(--dsw-alias-label-primary); + font: inherit; + font-size: 13px; + font-weight: 600; +} + +.badge { + flex: none; + border-radius: 999px; + padding: 1px 8px; + font-size: 11px; + line-height: 16px; +} + +.badge[data-kind='default'] { + background: var(--dsw-alias-label-primary); + color: var(--dsw-alias-bg-layer-3); +} + +.badge[data-kind='broken'] { + background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent); + color: var(--dsw-alias-state-error-primary); +} + +.brokenNote { + margin: 0; + border-radius: 8px; + padding: 8px 10px; + background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 8%, transparent); + color: var(--dsw-alias-state-error-primary); + font-size: 12.5px; + line-height: 18px; + overflow-wrap: anywhere; + white-space: pre-line; +} + +.hint { + display: flex; + flex-wrap: wrap; + align-items: baseline; + gap: 4px 8px; + margin: 0; + color: var(--dsw-alias-label-tertiary); + font-size: 12.5px; + line-height: 18px; +} + +.jumpLink { + border: 0; + padding: 0; + background: transparent; + color: var(--dsw-alias-state-business-primary); + font: inherit; + font-size: 12.5px; + cursor: pointer; +} + +.drawer { + display: flex; + flex-direction: column; + gap: 10px; + margin-top: 10px; + border: 1px dashed var(--dsw-alias-border-l1); + border-radius: 10px; + padding: 8px 10px 10px; +} + +.enabledIn { + display: flex; + flex-wrap: wrap; + align-items: baseline; + gap: 4px 10px; +} + +.card[data-failed='true'] { + border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent); +} + .chevron { flex: none; color: var(--dsw-alias-label-tertiary); diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx index 12fd3d2a7a..7726a9b1ab 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx @@ -15,6 +15,8 @@ export interface PluginInventorySettingsTabInjected { } type PluginInventoryEntry = PluginInventorySnapshot['entries'][number] +type AgentPresetGroup = NonNullable[number] +type AgentPresetRow = AgentPresetGroup['rows'][number] type PluginFiberPhase = PluginInventoryEntry['fiberPhase'] /** Full component props assembled by the Settings slot renderer. */ @@ -23,6 +25,8 @@ export type PluginInventorySettingsTabProps = & PropsLocale<'settings.pluginInventory'> & InjectFace +type Translate = PluginInventorySettingsTabProps['t'] + type ViewState = | { readonly status: 'loading' } | { readonly status: 'error' } @@ -37,10 +41,7 @@ const PHASE_KEYS = { } satisfies Record, PluginInventoryLocaleKey> /** Localized accessible label for one root Fiber phase. */ -function phaseLabel( - phase: PluginFiberPhase, - t: PluginInventorySettingsTabProps['t'], -): string { +function phaseLabel(phase: PluginFiberPhase, t: Translate): string { return phase === null ? t('unobserved') : t(PHASE_KEYS[phase]) } @@ -53,19 +54,121 @@ function moduleShortName(moduleName: string): string { .replace(/^dsh-(?:host-|client-)?/, '') } -/** Whether an inventory row matches the local catalog query. */ -function matches(entry: PluginInventoryEntry, normalizedQuery: string): boolean { +/** Whether one row's module name or entry id matches the catalog query. */ +function matches(moduleName: string, entryId: string | null, normalizedQuery: string): boolean { if (normalizedQuery.length === 0) return true - return [entry.moduleName, entry.entryId] + return [moduleName, ...entryId === null ? [] : [entryId]] .some(value => value.toLocaleLowerCase().includes(normalizedQuery)) } -/** Render the read-only current Loader inventory. */ +/** The roster row shown when the preset switcher has no explicit choice. */ +function fallbackPreset(presets: readonly AgentPresetGroup[]): AgentPresetGroup | undefined { + return presets.find(preset => preset.isDefault) ?? presets[0] +} + +/** The switcher's display label for one preset. */ +function presetLabel(preset: AgentPresetGroup, t: Translate): string { + const name = preset.name ?? preset.id + if (preset.broken !== undefined) return t('presetOptionBroken', { name }) + if (preset.isDefault) return t('presetOptionDefault', { name }) + return name +} + +/** One expandable plugin card; the caller owns the trailing status content. */ +function PluginCard({ rowKey, moduleName, entryId, trailing, ariaLabel, failed, expanded, onToggle, children }: { + readonly rowKey: string + readonly moduleName: string + readonly entryId: string | null + readonly trailing: ReactNode + readonly ariaLabel: string + readonly failed: boolean + readonly expanded: string | null + readonly onToggle: (key: string) => void + readonly children: ReactNode +}): ReactNode { + const open = expanded === rowKey + const detailId = `plugin-details-${encodeURIComponent(rowKey)}` + return ( +
  • + + {open ?
    {children}
    : null} +
    • + ) +} + +/** Detail rows shared by every card: the Loader identity, then labeled facts. */ +function CardFacts({ moduleName, moduleLabel, entryId, facts }: { + readonly moduleName: string + readonly moduleLabel: string + readonly entryId: string | null + readonly facts: readonly (readonly [label: string, value: ReactNode])[] +}): ReactNode { + return ( + <> + {entryId === null ? null : {entryId}} +
    +
    +
    {moduleLabel}
    +
    {moduleName}
    +
    + {facts.map(([label, value]) => ( +
    +
    {label}
    +
    {value}
    +
    + ))} +
    + + ) +} + +/** Status dot naming the root-fiber phase. */ +function PhaseDot({ phase, t }: { readonly phase: PluginFiberPhase; readonly t: Translate }): ReactNode { + const status = phaseLabel(phase, t) + return ( + + ) +} + +/** Enablement tag; `kind` selects the palette. */ +function StateTag({ kind, label }: { readonly kind: string; readonly label: string }): ReactNode { + return {label} +} + +/** Render the read-only plugin inventory: agent presets first, then the global plane. */ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsTabProps): ReactNode { - const catalogId = useId() + const sectionId = useId() const [request, setRequest] = useState(0) const [query, setQuery] = useState('') - const [expanded, setExpanded] = useState(null) + const [expanded, setExpanded] = useState(null) + const [chosenPreset, setChosenPreset] = useState(null) + const [globalOpen, setGlobalOpen] = useState(null) + const [drawerOpen, setDrawerOpen] = useState(false) const [state, setState] = useState({ status: 'loading' }) useEffect(() => { @@ -78,23 +181,160 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT }, [list, request]) const normalizedQuery = query.trim().toLocaleLowerCase() - const filteredEntries = useMemo( - () => state.status === 'ready' - ? state.snapshot.entries.filter(entry => matches(entry, normalizedQuery)) - : [], - [normalizedQuery, state], - ) + const searching = normalizedQuery.length > 0 + const snapshot = state.status === 'ready' ? state.snapshot : undefined + const presets = snapshot?.agentPresets ?? [] + const selected = presets.find(preset => preset.id === chosenPreset) ?? fallbackPreset(presets) - useEffect(() => { - if (expanded !== null && !filteredEntries.some(entry => entry.entryId === expanded)) { - setExpanded(null) + /** Presets that actually enable a module, keyed by module name. */ + const enabledIn = useMemo(() => { + const found = new Map() + for (const preset of presets) { + for (const row of preset.rows) { + if (row.enabled !== true) continue + const groups = found.get(row.moduleName) + if (groups === undefined) found.set(row.moduleName, [preset]) + else if (!groups.includes(preset)) groups.push(preset) + } } - }, [expanded, filteredEntries]) + return found + }, [presets]) + + const entries = snapshot?.entries ?? [] + const failedEntries: PluginInventoryEntry[] = [] + const drawerEntries: { entry: PluginInventoryEntry; providers: readonly [AgentPresetGroup, ...AgentPresetGroup[]] }[] = [] + const regularEntries: PluginInventoryEntry[] = [] + for (const entry of entries) { + const providers = enabledIn.get(entry.moduleName) + if (entry.fiberPhase === 'failed') failedEntries.push(entry) + else if (!entry.enabled && providers !== undefined) drawerEntries.push({ entry, providers }) + else regularEntries.push(entry) + } + + const entryMatch = (entry: PluginInventoryEntry): boolean => matches(entry.moduleName, entry.entryId, normalizedQuery) + const rowMatch = (row: AgentPresetRow): boolean => matches(row.moduleName, row.entryId, normalizedQuery) + const filteredFailed = failedEntries.filter(entryMatch) + const filteredDrawer = drawerEntries.filter(drawerRow => entryMatch(drawerRow.entry)) + const filteredRegular = regularEntries.filter(entryMatch) + const globalCount = filteredFailed.length + filteredDrawer.length + filteredRegular.length + const selectedRows = selected === undefined ? [] : selected.rows.filter(rowMatch) + const otherPresetMatches = searching + ? presets.filter(preset => preset !== selected && preset.rows.some(rowMatch)) + : [] + const otherMatchCount = otherPresetMatches + .reduce((total, preset) => total + preset.rows.filter(rowMatch).length, 0) + + const globalEffectiveOpen = searching || (globalOpen ?? presets.length === 0) + const drawerEffectiveOpen = searching || drawerOpen + const nothingMatches = searching && globalCount === 0 && selectedRows.length === 0 + && otherPresetMatches.length === 0 const retry = (): void => { setState({ status: 'loading' }) setRequest(value => value + 1) } + const toggleRow = (key: string): void => { + setExpanded(current => current === key ? null : key) + } + + /** Trailing status and detail facts for one row of the selected preset. */ + const presetRowCard = (preset: AgentPresetGroup, row: AgentPresetRow, index: number): ReactNode => { + const key = `preset:${preset.id}:${String(index)}` + const title = moduleShortName(row.moduleName) + const failed = row.fiberPhase === 'failed' + const stateText = failed + ? t('failedTag') + : row.enabled === true ? t('enabledTag') : row.enabled === false ? t('disabledTag') : t('conditionalTag') + const kind = failed ? 'failed' : row.enabled === true ? 'enabled' : row.enabled === false ? 'disabled' : 'conditional' + return ( + + {row.enabled === true && !failed ? : null} + + + )} + > + {row.condition}] as const], + ]} + /> + + ) + } + + /** One global-plane row; a drawer row carries the presets that enable it. */ + const globalRowCard = ( + entry: PluginInventoryEntry, + providers?: readonly [AgentPresetGroup, ...AgentPresetGroup[]], + ): ReactNode => { + const key = `${providers === undefined ? 'global' : 'drawer'}:${entry.entryId}` + const title = moduleShortName(entry.moduleName) + const failed = entry.fiberPhase === 'failed' + const stateText = failed + ? t('failedTag') + : providers !== undefined ? t('presetEnabledTag') : t(entry.enabled ? 'enabledTag' : 'disabledTag') + const kind = failed ? 'failed' : providers !== undefined ? 'preset' : entry.enabled ? 'enabled' : 'disabled' + return ( + + {entry.enabled && !failed ? : null} + + + )} + > + + {providers.map(preset => preset.name ?? preset.id).join(' · ')} + + + )], + ] + : [ + [t('configuration'), t(entry.enabled ? 'enabledTag' : 'disabledTag')], + ...entry.enabled ? [[t('runtime'), phaseLabel(entry.fiberPhase, t)] as const] : [], + ]} + /> + + ) + } return (
    @@ -105,7 +345,7 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT
    ) : null} - {state.status === 'ready' ? ( + {snapshot !== undefined ? (
    -
    -

    {t('catalog')}

    - {filteredEntries.length} -
    - {state.snapshot.entries.length === 0 ?

    {t('empty')}

    : null} - {state.snapshot.entries.length > 0 && filteredEntries.length === 0 - ?

    {t('emptySearch')}

    - : null} - {filteredEntries.length > 0 ? ( -
      - {filteredEntries.map((entry) => { - const status = phaseLabel(entry.fiberPhase, t) - const title = moduleShortName(entry.moduleName) - const configuration = t(entry.enabled ? 'enabledTag' : 'disabledTag') - const open = expanded === entry.entryId - const detailId = `${catalogId}-details-${encodeURIComponent(entry.entryId)}` - return ( -
    • + {entries.length === 0 && presets.length === 0 ?

      {t('empty')}

      : null} + {nothingMatches ?

      {t('emptySearch')}

      : null} + + {selected !== undefined ? ( +
      +
      + + {t('presetSubtitle')} + + {selectedRows.length} + +
      + {selected.broken !== undefined ? ( +

      {selected.broken}

      + ) : null} + {selectedRows.length > 0 ? ( +
        + {selectedRows.map((row, index) => presetRowCard(selected, row, index))} +
      + ) : null} + {otherMatchCount > 0 ? ( +

      + {t('matchesInOtherPresets', { count: String(otherMatchCount) })} + {otherPresetMatches.map(preset => ( - {open ? ( -

      - {entry.entryId} -
      -
      -
      {t('configuration')}
      -
      {configuration}
      -
      - {entry.enabled ? ( -
      -
      {t('cordis')}
      -
      {status}
      -
      - ) : null} -
      -
      - ) : null} -
      • - ) - })} -
    + ))} +

    + ) : null} + + ) : null} + + {entries.length > 0 ? ( +
    + + {globalEffectiveOpen ? ( +
    + {filteredFailed.length + filteredRegular.length > 0 ? ( +
      + {filteredFailed.map(entry => globalRowCard(entry))} + {filteredRegular.map(entry => globalRowCard(entry))} +
    + ) : null} + {drawerEntries.length > 0 ? ( +
    + + {drawerEffectiveOpen && filteredDrawer.length > 0 ? ( +
      + {filteredDrawer.map(drawerRow => globalRowCard(drawerRow.entry, drawerRow.providers))} +
    + ) : null} +
    + ) : null} +
    + ) : null} +
    ) : null}
    ) : null} diff --git a/packages/client/ui-settings-plugin-inventory/src/client/locales.ts b/packages/client/ui-settings-plugin-inventory/src/client/locales.ts index 866937016c..3857204a93 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/locales.ts +++ b/packages/client/ui-settings-plugin-inventory/src/client/locales.ts @@ -7,18 +7,36 @@ export const zh = { error: '暂时无法读取插件。', retry: '重试', search: '搜索插件', - catalog: '插件列表', empty: '暂无插件。', emptySearch: '没有匹配的插件。', + presetSubtitle: '会话使用的插件', + switcherLabel: '选择要查看的 Agent 预设', + presetOptionDefault: '{name}（默认）', + presetOptionBroken: '{name}（加载失败）', + globalTitle: '全局', + globalSubtitle: '系统与所有会话共用', + drawerTitle: '会话插件', + drawerSubtitle: '不在全局运行，由 Agent 预设按会话提供', + drawerDetail: '全局已停用，由 Agent 预设按会话提供', + enabledIn: '启用于', + viewInPreset: '去预设分组查看', + matchesInOtherPresets: '其他预设中还有 {count} 个匹配：', + failedCountLabel: '个失败', enabledTag: '已启用', disabledTag: '已停用', + conditionalTag: '条件启用', + presetEnabledTag: '预设中启用', + failedTag: '启动失败', + moduleLabel: '完整名称', + fromPreset: '来自', + condition: '启用条件', configuration: '配置状态', - cordis: 'Cordis 状态', - unobserved: '未挂载', + runtime: '运行状态', + unobserved: '未运行', pending: '等待依赖', loadingPhase: '加载中', - active: '已挂载', - failed: '挂载失败', + active: '运行中', + failed: '启动失败', unloading: '卸载中', } satisfies Record @@ -32,17 +50,35 @@ export const en = { error: 'Plugins are temporarily unavailable.', retry: 'Retry', search: 'Search plugins', - catalog: 'Plugin list', empty: 'No plugins are available.', emptySearch: 'No matching plugins.', + presetSubtitle: 'Plugins your sessions run', + switcherLabel: 'Choose the agent preset to inspect', + presetOptionDefault: '{name} (default)', + presetOptionBroken: '{name} (failed to load)', + globalTitle: 'Global', + globalSubtitle: 'Shared by the system and every session', + drawerTitle: 'Session plugins', + drawerSubtitle: 'Not running globally; agent presets provide them per session', + drawerDetail: 'Disabled globally; agent presets provide it per session', + enabledIn: 'Enabled in', + viewInPreset: 'View in the preset group', + matchesInOtherPresets: '{count} more matches in other presets: ', + failedCountLabel: 'failed', enabledTag: 'Enabled', disabledTag: 'Disabled', + conditionalTag: 'Conditional', + presetEnabledTag: 'Enabled via presets', + failedTag: 'Failed', + moduleLabel: 'Module', + fromPreset: 'From', + condition: 'Enable condition', configuration: 'Configuration', - cordis: 'Cordis status', - unobserved: 'Not mounted', + runtime: 'Status', + unobserved: 'Not running', pending: 'Waiting for dependencies', loadingPhase: 'Loading', - active: 'Mounted', - failed: 'Mount failed', + active: 'Running', + failed: 'Failed to start', unloading: 'Unloading', } satisfies Record diff --git a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx index bec1d64706..3310d87e6d 100644 --- a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx +++ b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx @@ -11,7 +11,11 @@ import { en, type PluginInventoryLocaleKey } from '../src/client/locales.ts' afterEach(cleanup) type Snapshot = Awaited> -const t = ((key: PluginInventoryLocaleKey): string => en[key]) as PluginInventorySettingsTabProps['t'] +const t = ((key: PluginInventoryLocaleKey, params?: Record): string => + Object.entries(params ?? {}).reduce( + (text, [name, value]) => text.replaceAll(`{${name}}`, value), + en[key], + )) as PluginInventorySettingsTabProps['t'] function props(list: PluginInventorySettingsTabInjected['list']): PluginInventorySettingsTabProps { return { @@ -20,79 +24,234 @@ function props(list: PluginInventorySettingsTabInjected['list']): PluginInventor } as PluginInventorySettingsTabProps } +/** A deployment with a roster: one failed global row, two preset-provided rows. */ const SNAPSHOT = { entries: [ + { entryId: 'telemetry', moduleName: '@fixture/telemetry', enabled: true, fiberPhase: 'failed' }, + { entryId: 'timer', moduleName: 'cordis:timer', enabled: true, fiberPhase: 'active' }, { entryId: '8a1b2c3d', moduleName: '@deepseek-ai/cordis-plugin-hmr', enabled: true, fiberPhase: 'active' }, - { entryId: 'pending', moduleName: 'cordis:pending-name', enabled: true, fiberPhase: 'pending' }, - { entryId: 'loading', moduleName: '@fixture/loading-name', enabled: true, fiberPhase: 'loading' }, - { entryId: 'failed', moduleName: '@fixture/failed-name', enabled: true, fiberPhase: 'failed' }, - { entryId: 'unloading', moduleName: '@fixture/unloading-name', enabled: true, fiberPhase: 'unloading' }, { entryId: 'unobserved', moduleName: '@fixture/unobserved-name', enabled: true, fiberPhase: null }, - { entryId: 'disabled-entry', moduleName: '@deepseek-ai/dsh-host-directory-picker-native', enabled: false, fiberPhase: null }, + { entryId: 'bash-host', moduleName: '@deepseek-ai/dsh-tool-bash', enabled: false, fiberPhase: null }, + { entryId: 'fs-host', moduleName: '@deepseek-ai/dsh-tool-fs', enabled: false, fiberPhase: null }, + { entryId: 'dormant', moduleName: '@fixture/dormant', enabled: false, fiberPhase: null }, + ], + agentPresets: [ + { + id: 'standard', + name: '标准模式', + isDefault: true, + rows: [ + { entryId: 'bash', moduleName: '@deepseek-ai/dsh-tool-bash', enabled: true, fiberPhase: 'active' }, + { entryId: 'fs', moduleName: '@deepseek-ai/dsh-tool-fs', enabled: true, fiberPhase: null }, + { + entryId: 'pwsh', + moduleName: '@fixture/pwsh', + enabled: 'conditional', + condition: 'process.platform === \'win32\'', + fiberPhase: null, + }, + { entryId: 'codex', moduleName: '@fixture/codex', enabled: false, fiberPhase: null }, + { entryId: 'crashy', moduleName: '@fixture/crashy', enabled: true, fiberPhase: 'failed' }, + { entryId: null, moduleName: '@fixture/anonymous', enabled: true, fiberPhase: null }, + ], + }, + { + id: 'ptc', + isDefault: false, + rows: [ + { entryId: 'bash', moduleName: '@deepseek-ai/dsh-tool-bash', enabled: true, fiberPhase: null }, + { entryId: 'bash-fork', moduleName: '@deepseek-ai/dsh-tool-bash', enabled: true, fiberPhase: null }, + { entryId: 'fs', moduleName: '@deepseek-ai/dsh-tool-fs', enabled: 'conditional', fiberPhase: null }, + ], + }, + { id: 'shattered', name: '坏预设', isDefault: false, broken: 'the composition file is missing', rows: [] }, ], } as unknown as Snapshot +async function renderReady(snapshot: Snapshot = SNAPSHOT): Promise> { + const view = render( snapshot)} />) + await screen.findByRole('searchbox', { name: en.search }) + return view +} + +const globalToggle = (): HTMLElement => + screen.getByRole('button', { name: (name: string) => name.startsWith(en.globalTitle) }) +const drawerToggle = (): HTMLElement => + screen.getByRole('button', { name: (name: string) => name.startsWith(en.drawerTitle) }) + describe('PluginInventorySettingsTab', () => { - it('renders runtime status only for enabled plugins', async () => { - const deferred = Promise.withResolvers() - const list = vi.fn(() => deferred.promise) - const view = render() - expect(screen.getByText(en.loading)).toBeTruthy() + it('shows the default preset first and keeps the global plane collapsed', async () => { + const view = await renderReady() - await act(async () => { deferred.resolve(SNAPSHOT) }) - expect(list).toHaveBeenCalledOnce() - expect(screen.getByRole('searchbox', { name: en.search })).toBeTruthy() - expect(screen.getByRole('heading', { name: en.catalog })).toBeTruthy() - expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('7') - expect(screen.getAllByRole('listitem')).toHaveLength(7) - expect(screen.getAllByText(en.enabledTag)).toHaveLength(6) + const switcher = screen.getByRole('combobox', { name: en.switcherLabel }) + expect((switcher as HTMLSelectElement).value).toBe('standard') + expect(screen.getAllByRole('option').map(option => option.textContent)).toEqual([ + '标准模式 (default)', + 'ptc', + '坏预设 (failed to load)', + ]) + expect(screen.getByText(en.presetSubtitle)).toBeTruthy() + expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('6') + + // Only the preset group lists rows while the global plane stays collapsed. + expect(screen.getAllByRole('listitem')).toHaveLength(6) + expect(screen.getAllByText(en.enabledTag)).toHaveLength(3) + expect(screen.getByText(en.conditionalTag)).toBeTruthy() expect(screen.getByText(en.disabledTag)).toBeTruthy() - for (const value of [ - 'Mounted', - 'Waiting for dependencies', - 'Loading', - 'Mount failed', - 'Unloading', - 'Not mounted', - ]) { - expect(screen.getByRole('img', { name: value })).toBeTruthy() - } - const active = screen.getByRole('button', { name: 'hmr, Mounted, Enabled' }) - expect(active.getAttribute('aria-expanded')).toBe('false') - fireEvent.click(active) - expect(active.getAttribute('aria-expanded')).toBe('true') - expect(view.container.querySelector('[data-loader-entry]')?.textContent).toBe('8a1b2c3d') - expect(screen.getByText(en.configuration)).toBeTruthy() - expect(screen.getByText(en.cordis)).toBeTruthy() - fireEvent.click(active) - expect(view.container.querySelector('[data-loader-entry]')).toBeNull() + expect(screen.getByText(en.failedTag)).toBeTruthy() + expect(screen.getByRole('img', { name: 'Running' })).toBeTruthy() + expect(screen.getAllByRole('img', { name: 'Not running' })).toHaveLength(2) - fireEvent.click(active) - fireEvent.change(screen.getByRole('searchbox', { name: en.search }), { - target: { value: 'disabled-entry' }, - }) + expect(globalToggle().getAttribute('aria-expanded')).toBe('false') + expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('7') + expect(screen.getByText(`1 ${en.failedCountLabel}`)).toBeTruthy() + + // A preset row expands into its provenance facts. + fireEvent.click(screen.getByRole('button', { name: 'pwsh, Conditional' })) + expect(screen.getByText(en.fromPreset)).toBeTruthy() + expect(screen.getByText('标准模式')).toBeTruthy() + expect(screen.getByText(en.condition)).toBeTruthy() + expect(screen.getByText('process.platform === \'win32\'')).toBeTruthy() + fireEvent.click(screen.getByRole('button', { name: 'pwsh, Conditional' })) + expect(screen.queryByText(en.condition)).toBeNull() + + // A failed preset row names its runtime state instead of a condition. + fireEvent.click(screen.getByRole('button', { name: 'crashy, Failed' })) + expect(screen.getByText(en.runtime)).toBeTruthy() + expect(screen.getByText('Failed to start')).toBeTruthy() + + // A row declaring no id has no Loader identity line, only its module. + fireEvent.click(screen.getByRole('button', { name: 'anonymous, Enabled' })) expect(view.container.querySelector('[data-loader-entry]')).toBeNull() - fireEvent.click(screen.getByRole('button', { name: 'directory-picker-native, Disabled' })) - expect(screen.getAllByText(en.disabledTag)).toHaveLength(2) - expect(screen.queryByText(en.cordis)).toBeNull() - expect(screen.queryByText(en.unobserved)).toBeNull() + expect(screen.getByText(en.moduleLabel).nextElementSibling?.textContent).toBe('@fixture/anonymous') }) - it('filters by module name or Loader entry id', async () => { - render( SNAPSHOT)} />) - const search = await screen.findByRole('searchbox', { name: en.search }) + it('expands the global plane with failures first and the session-plugin drawer', async () => { + const view = await renderReady() - fireEvent.change(search, { target: { value: 'disabled-entry' } }) - expect(screen.getAllByRole('listitem')).toHaveLength(1) - expect(screen.getByText('directory-picker-native')).toBeTruthy() + fireEvent.click(globalToggle()) + expect(globalToggle().getAttribute('aria-expanded')).toBe('true') + const failed = view.container.querySelector('[data-plugin-scope="global"] [data-failed="true"]') + expect(failed?.getAttribute('data-plugin-entry')).toBe('telemetry') + // Failures float above the Loader-ordered remainder. + expect(view.container.querySelector('[data-plugin-scope="global"] li')).toBe(failed) - fireEvent.change(search, { target: { value: 'cordis-plugin-hmr' } }) - expect(screen.getAllByRole('listitem')).toHaveLength(1) - expect(screen.getByText('hmr')).toBeTruthy() + // The drawer stays collapsed until opened, then names its providers. + expect(drawerToggle().getAttribute('aria-expanded')).toBe('false') + expect(screen.queryByText(en.presetEnabledTag)).toBeNull() + fireEvent.click(drawerToggle()) + expect(screen.getAllByText(en.presetEnabledTag)).toHaveLength(2) + + fireEvent.click(screen.getByRole('button', { name: 'tool-bash, Enabled via presets' })) + expect(screen.getByText(en.drawerDetail)).toBeTruthy() + expect(screen.getByText(en.enabledIn)).toBeTruthy() + expect(screen.getByText('标准模式 · ptc')).toBeTruthy() + + // The failed global card reports its runtime state. + fireEvent.click(screen.getByRole('button', { name: 'telemetry, Failed' })) + expect(screen.getByText('Failed to start')).toBeTruthy() + + // A disabled row outside every preset stays plainly disabled. + fireEvent.click(screen.getByRole('button', { name: 'dormant, Disabled' })) + expect(screen.queryByText(en.drawerDetail)).toBeNull() + + fireEvent.click(drawerToggle()) + expect(screen.queryByText(en.presetEnabledTag)).toBeNull() + fireEvent.click(globalToggle()) + expect(globalToggle().getAttribute('aria-expanded')).toBe('false') + }) + + it('switches the inspected preset in place, including broken ones', async () => { + const view = await renderReady() + const switcher = screen.getByRole('combobox', { name: en.switcherLabel }) + + fireEvent.change(switcher, { target: { value: 'ptc' } }) + expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('3') + fireEvent.click(screen.getAllByRole('button', { name: 'tool-bash, Enabled' })[0]!) + // An unnamed preset labels provenance by its id. + expect(screen.getByText(en.fromPreset).nextElementSibling?.textContent).toBe('ptc') + + fireEvent.change(switcher, { target: { value: 'shattered' } }) + expect(screen.getByRole('alert').textContent).toBe('the composition file is missing') + expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('0') + }) + + it('jumps from a drawer row to the preset that enables it', async () => { + await renderReady() + const switcher = screen.getByRole('combobox', { name: en.switcherLabel }) + fireEvent.change(switcher, { target: { value: 'ptc' } }) + + fireEvent.click(globalToggle()) + fireEvent.click(drawerToggle()) + fireEvent.click(screen.getByRole('button', { name: 'tool-bash, Enabled via presets' })) + fireEvent.click(screen.getByRole('button', { name: en.viewInPreset })) + expect((switcher as HTMLSelectElement).value).toBe('standard') + }) + + it('searches across scopes and points at matches in other presets', async () => { + const view = await renderReady() + const search = screen.getByRole('searchbox', { name: en.search }) + + fireEvent.change(search, { target: { value: 'tool-bash' } }) + // Searching forces the collapsed global plane and drawer open. + expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('1') + expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('1') + expect(screen.getByText(en.presetEnabledTag)).toBeTruthy() + expect(screen.queryByText(`1 ${en.failedCountLabel}`)).toBeNull() + const hint = screen.getByText((text: string) => text.startsWith('2 more matches')) + expect(hint).toBeTruthy() + fireEvent.click(screen.getByRole('button', { name: 'ptc' })) + expect(screen.getByRole('combobox', { name: en.switcherLabel }).value).toBe('ptc') + + // A match visible only in another preset keeps the pointer without rows. + fireEvent.change(search, { target: { value: 'crashy' } }) + expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('0') + expect(screen.getByText((text: string) => text.startsWith('1 more matches'))).toBeTruthy() + expect(screen.queryByText(en.emptySearch)).toBeNull() + + // A match on a Loader entry id only reaches the global plane. + fireEvent.change(search, { target: { value: '8a1b2c3d' } }) + expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('1') + expect(screen.queryByText((text: string) => text.includes('more matches'))).toBeNull() fireEvent.change(search, { target: { value: 'not-a-plugin' } }) - expect(screen.queryAllByRole('listitem')).toHaveLength(0) expect(screen.getByText(en.emptySearch)).toBeTruthy() + expect(screen.queryAllByRole('listitem')).toHaveLength(0) + }) + + it('renders a rosterless deployment as one expanded global list', async () => { + const view = await renderReady({ + entries: [ + { entryId: 'hmr', moduleName: '@deepseek-ai/cordis-plugin-hmr', enabled: true, fiberPhase: 'active' }, + { entryId: 'off', moduleName: '@fixture/off', enabled: false, fiberPhase: null }, + ], + } as unknown as Snapshot) + + expect(screen.queryByRole('combobox', { name: en.switcherLabel })).toBeNull() + expect(globalToggle().getAttribute('aria-expanded')).toBe('true') + expect(screen.getAllByRole('listitem')).toHaveLength(2) + + fireEvent.click(screen.getByRole('button', { name: 'hmr, Enabled' })) + expect(screen.getByText(en.runtime)).toBeTruthy() + expect(view.container.querySelector('[data-loader-entry]')?.textContent).toBe('hmr') + fireEvent.click(screen.getByRole('button', { name: 'off, Disabled' })) + expect(screen.getAllByText(en.moduleLabel).length).toBeGreaterThan(0) + expect(screen.queryByText(en.runtime)).toBeNull() + }) + + it('renders a preset-only snapshot without the global section', async () => { + await renderReady({ + entries: [], + agentPresets: [{ + id: 'solo', + isDefault: false, + rows: [{ entryId: 'one', moduleName: '@fixture/one', enabled: true, fiberPhase: null }], + }], + }) + + expect(screen.queryByRole('button', { name: (name: string) => name.startsWith(en.globalTitle) })).toBeNull() + expect(screen.queryByText(en.empty)).toBeNull() + expect(screen.getAllByRole('listitem')).toHaveLength(1) }) it('shows a generic failure and retries into the empty state', async () => { @@ -116,6 +275,7 @@ describe('PluginInventorySettingsTab', () => { const deferred = Promise.withResolvers() const pending = render( deferred.promise)} />) + expect(screen.getByText(en.loading)).toBeTruthy() pending.unmount() await act(async () => { deferred.resolve(SNAPSHOT) }) diff --git a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts index cb8f1a7ebc..939c9abaca 100644 --- a/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/slot-catalog.ts @@ -1526,7 +1526,6 @@ export const CLIENT_SLOT_API: readonly ClientSlotEntry[] = [ declaredBy: 'an entry in \'settings.section\' (client-ui-settings-general), so it exists while that entry is mounted', occupants: [ 'client-locale LanguageRow id \'language\'', - 'client-ui-agent-preset AgentPresetRow id \'agent-preset\'', 'client-ui-chat TranscriptViewRow id \'transcript-view\'', 'client-ui-conversation EnterBehaviorRow id \'composer-enter\'', 'client-ui-permission-presets PermissionRow id \'permission\'', diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 8edd7adb9d..c68d5dd823 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -147,6 +147,12 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ parameters: [], returns: 'the rows and the authoring capability.', }, + { + signature: 'async compositionInventory(): Promise', + description: 'Every preset\'s composition as flattened plugin rows, for plugin-listing surfaces beside the roster\'s own picker.\n\nA preset with a live standing mount answers from its newest generation\'s Loader entries — the composition new sessions join — and one never composed since boot answers from its file, with `!!js` disabled gates evaluated against the Loader context so both answers reflect the same host. Reading never mounts: an unmounted preset is parsed, not composed, so listing a preset\'s plugins cannot activate them early. A composition that stopped reading between discovery\'s health verdict and this read is reported broken with the raced reason rather than dropped.', + parameters: [], + returns: 'one composition per roster preset, in roster order.', + }, { signature: 'async resolve(id?: string): Promise', description: 'Resolve one preset by id.\n\nA broken preset resolves — deleting one, reading one, and reporting one all need the row — and the mounting paths refuse it AFTER resolution through resolveMountable.', @@ -3410,6 +3416,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'AgentPreset', declaration: 'export interface AgentPreset {\n readonly id: string;\n readonly trust: PresetTrust;\n readonly path: string;\n readonly name?: string;\n readonly description?: string;\n readonly order?: number;\n readonly broken?: string;\n}', }, + { + name: 'AgentPresetComposition', + declaration: 'export interface AgentPresetComposition {\n readonly id: string;\n readonly name?: string;\n readonly isDefault: boolean;\n readonly broken?: string;\n readonly rows: readonly AgentPresetCompositionRow[];\n}', + }, + { + name: 'AgentPresetCompositionRow', + declaration: 'export interface AgentPresetCompositionRow {\n readonly entryId: string | null;\n readonly moduleName: string;\n readonly enabled: CompositionRowEnablement;\n readonly condition?: string;\n readonly fiberState?: FiberState;\n}', + }, { name: 'AgentPresetDirectoryOpenValue', declaration: 'export type AgentPresetDirectoryOpenValue = {\n readonly opened: true;\n} | {\n readonly opened: false;\n readonly path: string;\n};', @@ -3674,6 +3688,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'CompactionTrigger', declaration: 'export type CompactionTrigger = \'pressure\' | \'context-overflow\';', }, + { + name: 'CompositionRowEnablement', + declaration: 'export type CompositionRowEnablement = boolean | \'conditional\';', + }, { name: 'ConfinedArgv', declaration: 'export interface ConfinedArgv {\n argv: string[];\n enforcement: SandboxEnforcement;\n denialSignatures: readonly string[];\n runnerFailureRules: readonly RunnerFailureRule[];\n}', @@ -3966,6 +3984,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'EpochHeader', declaration: 'export interface EpochHeader {\n config: LlmCallConfig;\n adapterDefaults?: LlmCallConfigAdapterDefaults;\n system?: string;\n tools?: ToolSchema[];\n}', }, + { + name: 'FiberState', + declaration: 'export type FiberState = FiberStateEnum;', + }, { name: 'FileDiff', declaration: 'export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n}', diff --git a/packages/host/plugin-inventory/README.i18n.yaml b/packages/host/plugin-inventory/README.i18n.yaml index 93797f6893..bdb058c1cf 100644 --- a/packages/host/plugin-inventory/README.i18n.yaml +++ b/packages/host/plugin-inventory/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/host/plugin-inventory/README.md -README.md: 3f982ebcfdc85f3abd81d1615efccbec6b6bbbed -README.zh.md: eab5409c230ce64f2da66e267c0e203b709daa91 +README.md: 84b437b9952e06bf5231515d15c8fa6419b990be +README.zh.md: 6dacf80788ad7641bea162624e608f340dac1dca diff --git a/packages/host/plugin-inventory/README.md b/packages/host/plugin-inventory/README.md index 3f982ebcfd..84b437b995 100644 --- a/packages/host/plugin-inventory/README.md +++ b/packages/host/plugin-inventory/README.md @@ -1,5 +1,5 @@ --- -description: "Read-only projection of the current Cordis Loader plugin state: the pluginInventory service and its pluginInventory/list Remote for web GUI host clients." +description: "Read-only projection of the current Cordis Loader plugin state with each agent preset's composition beside it: the pluginInventory service and its pluginInventory/list Remote for web GUI host clients." kind: "package-reference" --- @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Clients and settings pages can show what is currently composed in the host: calling `pluginInventory/list` returns the current non-group Loader entries in Loader order — entry id, module specifier, effective enablement, and root Fiber phase (`pending`, `loading`, `active`, `failed`, or `unloading`, or `null` when an entry has no live root Fiber). The snapshot is point-in-time: the Loader is the sole lifecycle authority, and this package owns no cache, history, provenance model, event stream, or mutation path. Client packages consume the Remote through the explicit [`api-remotes`](../../api/remotes/README.md) assembly rather than importing the Host implementation. +Clients and settings pages can show what is currently composed in the host: calling `pluginInventory/list` returns the current non-group Loader entries in Loader order — entry id, module specifier, effective enablement, and root Fiber phase (`pending`, `loading`, `active`, `failed`, or `unloading`, or `null` when an entry has no live root Fiber). When an agent-preset roster is composed, the snapshot also carries one group per preset — id, display name, default marking, health, and flattened composition rows — because a deployment that mounts the roster runs its model-facing plugins there rather than on the Loader's own entries. The snapshot is point-in-time: the Loader is the sole lifecycle authority, and this package owns no cache, history, provenance model, event stream, or mutation path. Client packages consume the Remote through the explicit [`api-remotes`](../../api/remotes/README.md) assembly rather than importing the Host implementation. ## Table of Contents @@ -25,12 +25,16 @@ Clients and settings pages can show what is currently composed in the host: call ## Use this package -Call `pluginInventory/list` when a client or settings page needs to show what is currently composed in the host — which plugins are loaded, enabled, and alive. The Remote is the only entry point: the service is Remote-only and deliberately declares no same-process Cordis `Context` merge. +Call `pluginInventory/list` when a client or settings page needs to show what is currently composed in the host — which plugins are loaded, enabled, and alive, and what each agent preset would give a session. The Remote is the only entry point: the service is Remote-only and deliberately declares no same-process Cordis `Context` merge. ### What a snapshot contains Each row is one non-group Loader entry: its entry id, the exact module specifier, the effective enablement (including disabled ancestor groups), and the current root Fiber phase. `pending` means the entry waits to load, `loading` that it is being read, `active` that it is running, `failed` that its fiber rejected, and `unloading` that it is being torn down; `null` means no live root Fiber exists at all. Structural group rows are skipped. +### Per-preset compositions + +With a roster composed, `agentPresets` carries one group per preset in roster order: its id, published display name, whether a session naming no preset composes it, and flattened plugin rows — entry id (null when the file row declares none), module specifier, effective enablement, the row's own `!!js` disabled expression when it carries one, and a root-fiber phase when the composition is live. A preset some session already composed answers from its newest standing generation; one never composed since boot answers from its composition file with disabled gates evaluated against the Loader context, and reading never mounts a preset. `conditional` enablement marks a gate the Host could not evaluate, and a broken preset stays listed with its reason and no rows. Without a roster the field is absent. + ### What you can and cannot do with it The inventory is a snapshot for display and diagnostics: a client can render the roster, flag failed entries, and detect changes by comparing snapshots. It cannot enable, disable, add, or remove plugins, and it carries no history — a fiber that already failed and was removed is absent. Because the service reads the Loader on every call, the answer always reflects the current composition rather than a cached view. @@ -45,7 +49,7 @@ The inventory is a snapshot for display and diagnostics: a client can render the ### Design concept -The gateway is a direct projection with no second lifecycle truth: every `list()` call reads `ctx.loader.entries()` and maps each non-group entry to its public row. Cordis's internal plugin/status events already maintain `Entry.fiber` and `Fiber.state`, so a cache would only add another lifecycle truth to keep synchronized. +The gateway is a direct projection with no second lifecycle truth: every `list()` call reads `ctx.loader.entries()` and maps each non-group entry to its public row. Cordis's internal plugin/status events already maintain `Entry.fiber` and `Fiber.state`, so a cache would only add another lifecycle truth to keep synchronized. The agent-preset roster is an optional peer resolved per call through `ctx.get('agentPresets')`: its `compositionInventory()` owns every preset read, and this package only maps root-fiber states onto the public phase vocabulary. ### The phase mapping @@ -93,7 +97,8 @@ None; this package neither assembles nor sends a provider request. These limits define what a point-in-time inventory cannot tell a client. They are current package constraints, not a task backlog. - **Point-in-time state only** — the result contains no durable failure history or subscription; a missing root Fiber is reported as `null`, regardless of why no live root exists. -- **No provenance or mutation** — the service does not identify which bundle, profile, or override introduced an entry, and it cannot enable, disable, add, or remove plugins. +- **No provenance or mutation** — the service does not identify which bundle, profile, or override introduced an entry, and it cannot enable, disable, add, or remove plugins in either plane. +- **Presets appear only with a roster** — a deployment without `dsh-agent-presets` serves Loader entries alone; the `agentPresets` field is absent rather than empty. ### Dev Note diff --git a/packages/host/plugin-inventory/README.zh.md b/packages/host/plugin-inventory/README.zh.md index eab5409c23..6dacf80788 100644 --- a/packages/host/plugin-inventory/README.zh.md +++ b/packages/host/plugin-inventory/README.zh.md @@ -1,5 +1,5 @@ --- -description: "当前 Cordis Loader 插件状态的只读投影：面向 web GUI 宿主客户端的 pluginInventory 服务及其 pluginInventory/list Remote。" +description: "当前 Cordis Loader 插件状态的只读投影，并附带每个 Agent 预设的组合：面向 web GUI 宿主客户端的 pluginInventory 服务及其 pluginInventory/list Remote。" kind: "package-reference" --- @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -客户端与设置页可以展示宿主当前组合了什么：调用 `pluginInventory/list` 即按 Loader 顺序返回当前的非组条目——条目 id、模块标识、有效启用状态与根 Fiber 阶段（`pending`、`loading`、`active`、`failed` 或 `unloading`；条目没有存活根 Fiber 时为 `null`）。该快照只表示调用当下：Loader 是唯一的生命周期权威，本包不拥有缓存、历史、来源模型、事件流或修改路径。Client 包通过显式的 [`api-remotes`](../../api/remotes/README.zh.md) 组合消费这个 Remote，而不导入 Host 实现。 +客户端与设置页可以展示宿主当前组合了什么：调用 `pluginInventory/list` 即按 Loader 顺序返回当前的非组条目——条目 id、模块标识、有效启用状态与根 Fiber 阶段（`pending`、`loading`、`active`、`failed` 或 `unloading`；条目没有存活根 Fiber 时为 `null`）。当部署组合了 Agent 预设 roster 时，快照还携带每个预设一组——id、显示名、默认标记、健康状态与压平后的组合行——因为挂载 roster 的部署把模型侧插件运行在预设组合里，而不是 Loader 自己的条目上。该快照只表示调用当下：Loader 是唯一的生命周期权威，本包不拥有缓存、历史、来源模型、事件流或修改路径。Client 包通过显式的 [`api-remotes`](../../api/remotes/README.zh.md) 组合消费这个 Remote，而不导入 Host 实现。 ## 目录 @@ -25,12 +25,16 @@ kind: "package-reference" ## 使用本包 -当客户端或设置页需要展示宿主当前组合了什么——哪些插件已加载、已启用、是否存活——时调用 `pluginInventory/list`。Remote 是唯一入口：该服务仅供 Remote 使用，刻意不声明同进程 Cordis `Context` merge。 +当客户端或设置页需要展示宿主当前组合了什么——哪些插件已加载、已启用、是否存活，以及每个 Agent 预设会给会话什么——时调用 `pluginInventory/list`。Remote 是唯一入口：该服务仅供 Remote 使用，刻意不声明同进程 Cordis `Context` merge。 ### 快照包含什么 每一行是一个非组 Loader 条目：其条目 id、精确模块标识、有效启用状态（含被禁用的祖先组）与当前根 Fiber 阶段。`pending` 表示条目等待加载，`loading` 表示正在读取，`active` 表示正在运行，`failed` 表示其 fiber 被拒绝，`unloading` 表示正在拆除；`null` 表示完全不存在存活的根 Fiber。结构性的 group 行会被跳过。 +### 每个预设的组合 + +组合了 roster 时，`agentPresets` 按 roster 顺序携带每个预设一组：其 id、发布的显示名、未指名预设的会话是否组合它，以及压平后的插件行——条目 id（文件行未声明时为 null）、模块标识、有效启用状态、行自带的 `!!js` disabled 表达式（如有），以及组合存活时的根 Fiber 阶段。已有会话组合过的预设由其最新 standing 世代作答；开机以来从未被组合的预设由其组合文件作答，disabled 门用 Loader 上下文求值，且读取从不挂载预设。`conditional` 表示宿主无法求值的门；坏预设保留在列表中，携带原因且没有行。没有 roster 时该字段缺席。 + ### 你能用它做什么、不能做什么 该清单是供展示与诊断的快照：客户端可以渲染名单、标出失败条目，并通过比较快照检测变化。它不能启用、停用、添加或移除插件，也不携带历史——已经失败并被移除的 fiber 缺席。由于服务每次调用都读取 Loader，答案总是反映当前组合，而不是缓存视图。 @@ -45,7 +49,7 @@ kind: "package-reference" ### 设计理念 -网关是一层没有第二个生命周期真源的直接投影：每次 `list()` 调用都读取 `ctx.loader.entries()`，并把每个非组条目映射为公共行。Cordis 内部的 plugin/status 事件已经维护了 `Entry.fiber` 与 `Fiber.state`，因此再加缓存只会多出一个需要同步的生命周期真源。 +网关是一层没有第二个生命周期真源的直接投影：每次 `list()` 调用都读取 `ctx.loader.entries()`，并把每个非组条目映射为公共行。Cordis 内部的 plugin/status 事件已经维护了 `Entry.fiber` 与 `Fiber.state`，因此再加缓存只会多出一个需要同步的生命周期真源。Agent 预设 roster 是每次调用经 `ctx.get('agentPresets')` 解析的可选伙伴：所有预设读取都由它的 `compositionInventory()` 负责，本包只把根 Fiber 状态映射到公共阶段词汇。 ### 阶段映射 @@ -93,7 +97,8 @@ Typert 生成由 `./typert` 与 `./remote` 导出的 Host 和 Client Remote 产 这些限制说明一个点时刻清单无法告诉客户端什么。它们是当前包约束，不是任务积压。 - **仅表示调用当下**——结果不包含持久的失败历史或订阅；只要不存在存活的根 Fiber，就会报告 `null`，而不区分其原因。 -- **无来源与修改能力**——服务不识别条目由哪个 bundle、profile 或 override 引入，也不能启用、停用、添加或移除插件。 +- **无来源与修改能力**——服务不识别条目由哪个 bundle、profile 或 override 引入，也不能在任一平面启用、停用、添加或移除插件。 +- **预设仅随 roster 出现**——未装 `dsh-agent-presets` 的部署只提供 Loader 条目；`agentPresets` 字段缺席而非为空。 ### 开发备注 diff --git a/packages/host/plugin-inventory/package.json b/packages/host/plugin-inventory/package.json index e9db804471..8c96377d6a 100644 --- a/packages/host/plugin-inventory/package.json +++ b/packages/host/plugin-inventory/package.json @@ -53,13 +53,20 @@ }, "peerDependencies": { "@deepseek-ai/cordis-plugin-loader": "workspace:^", + "@deepseek-ai/dsh-agent-presets": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", "@deepseek-ai/cordis": "workspace:^" }, + "peerDependenciesMeta": { + "@deepseek-ai/dsh-agent-presets": { + "optional": true + } + }, "devDependencies": { "@deepseek-ai/cordis-plugin-loader": "workspace:^", + "@deepseek-ai/dsh-agent-presets": "workspace:^", "@deepseek-ai/dsh-brand": "workspace:^", "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-typert-protocol": "workspace:^", diff --git a/packages/host/plugin-inventory/src/index.ts b/packages/host/plugin-inventory/src/index.ts index ff5394c564..3beef6f0c0 100644 --- a/packages/host/plugin-inventory/src/index.ts +++ b/packages/host/plugin-inventory/src/index.ts @@ -2,10 +2,13 @@ import type { Context, FiberState } from '@deepseek-ai/cordis' import type {} from '@deepseek-ai/cordis-plugin-loader' +// Type-only: the optional agent-preset roster resolved through `ctx.get`. +import type {} from '@deepseek-ai/dsh-agent-presets' import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol' // Typert-generated ./typert and ./remote artifacts import Zod at runtime. import type {} from 'zod' import type { + AgentPresetPluginGroup, PluginEntryId, PluginFiberPhase, PluginInventoryEntry, @@ -51,10 +54,16 @@ export class PluginInventoryGateway extends TypertRemoteService { * Read the Loader directly on every call. Cordis's internal plugin/status * events already maintain Entry.fiber and Fiber.state, so a second cache * would only add another lifecycle truth to keep synchronized. - * @returns Current non-group Loader entries in Loader order. + * + * When an agent-preset roster is composed, the snapshot also carries each + * preset's composition rows, because those rows — not the Loader's own + * entries — are where a deployment that mounts the roster runs its + * model-facing plugins. + * @returns Current non-group Loader entries in Loader order, with per-preset + * compositions when a roster is composed. */ @Remote('list') - list(): PluginInventorySnapshot { + async list(): Promise { const entries: PluginInventoryEntry[] = [] for (const entry of this.ctx.loader.entries()) { if (entry.options.group) continue @@ -65,7 +74,18 @@ export class PluginInventoryGateway extends TypertRemoteService { fiberPhase: entry.fiber === undefined ? null : FIBER_PHASE[entry.fiber.state], }) } - return { entries } + const presets = this.ctx.get('agentPresets') + if (presets === undefined) return { entries } + const agentPresets: AgentPresetPluginGroup[] = (await presets.compositionInventory()).map( + composition => ({ + ...composition, + rows: composition.rows.map(({ fiberState, ...row }) => ({ + ...row, + fiberPhase: fiberState === undefined ? null : FIBER_PHASE[fiberState], + })), + }), + ) + return { entries, agentPresets } } } diff --git a/packages/host/plugin-inventory/src/types.ts b/packages/host/plugin-inventory/src/types.ts index f5678fc3c2..301e194a65 100644 --- a/packages/host/plugin-inventory/src/types.ts +++ b/packages/host/plugin-inventory/src/types.ts @@ -22,7 +22,47 @@ export interface PluginInventoryEntry { readonly fiberPhase: PluginFiberPhase } +/** Effective enablement of one preset composition row. */ +export type PresetPluginEnablement = boolean | 'conditional' + +/** One plugin row an agent preset's composition names. */ +export interface AgentPresetPluginRow { + /** Composition row id, or null when the row declares none. */ + readonly entryId: string | null + /** Module specifier the row names. */ + readonly moduleName: string + /** + * Effective enablement, including disabled ancestor groups. `'conditional'` + * marks a `!!js` disabled expression on a composition no session has + * mounted, which only a Loader context can decide. + */ + readonly enabled: PresetPluginEnablement + /** The row's own `!!js` disabled expression, when it carries one. */ + readonly condition?: string + /** Root-fiber phase when the composition is live; null otherwise. */ + readonly fiberPhase: PluginFiberPhase +} + +/** One agent preset's identity and flattened composition in the inventory. */ +export interface AgentPresetPluginGroup { + /** Stable preset id. */ + readonly id: string + /** Display name the preset published; a reader falls back to the id. */ + readonly name?: string + /** Whether a session naming no preset composes this one. */ + readonly isDefault: boolean + /** Why this preset's composition cannot be read; absent when rows answer. */ + readonly broken?: string + /** Plugin rows in composition order; empty when the preset is broken. */ + readonly rows: readonly AgentPresetPluginRow[] +} + /** Point-in-time inventory returned by the plugin inventory Remote. */ export interface PluginInventorySnapshot { readonly entries: readonly PluginInventoryEntry[] + /** + * Per-preset compositions, present only when an agent-preset roster is + * composed in this deployment. + */ + readonly agentPresets?: readonly AgentPresetPluginGroup[] } diff --git a/packages/host/plugin-inventory/tests/inventory.spec.ts b/packages/host/plugin-inventory/tests/inventory.spec.ts index cd43c492a8..107a0db6ee 100644 --- a/packages/host/plugin-inventory/tests/inventory.spec.ts +++ b/packages/host/plugin-inventory/tests/inventory.spec.ts @@ -1,7 +1,8 @@ import { afterEach, describe, expect, it } from 'vitest' -import { Context, type Plugin } from '@deepseek-ai/cordis' +import { Context, FiberState, type Plugin } from '@deepseek-ai/cordis' import Loader from '@deepseek-ai/cordis-plugin-loader' import { remoteMethods } from '@deepseek-ai/dsh-typert-protocol' +import type { AgentPresets } from '@deepseek-ai/dsh-agent-presets' import PluginInventoryGateway from '../src/index.ts' const contexts: Context[] = [] @@ -52,7 +53,9 @@ describe('PluginInventoryGateway', () => { }) await ctx.loader.create({ name: 'cordis:active', group: true }) - const snapshot = inventory.list() + const snapshot = await inventory.list() + // No agent-preset roster is composed, so the snapshot carries no presets. + expect(snapshot.agentPresets).toBeUndefined() expect(snapshot.entries).toHaveLength(3) expect(snapshot.entries).toEqual(expect.arrayContaining([ { @@ -76,7 +79,7 @@ describe('PluginInventoryGateway', () => { ])) await ctx.loader.update(activeId, { disabled: true }) - expect(inventory.list().entries.find(entry => entry.entryId === activeId)).toEqual({ + expect((await inventory.list()).entries.find(entry => entry.entryId === activeId)).toEqual({ entryId: activeId, moduleName: 'cordis:active', enabled: false, @@ -84,6 +87,38 @@ describe('PluginInventoryGateway', () => { }) await ctx.loader.remove(pendingId) - expect(inventory.list().entries.some(entry => entry.entryId === pendingId)).toBe(false) + expect((await inventory.list()).entries.some(entry => entry.entryId === pendingId)).toBe(false) + }) + + it('carries each composed preset with root-fiber states mapped to phases', async () => { + const { ctx, inventory } = await harness() + ctx.provide('agentPresets', { + compositionInventory: async () => [ + { + id: 'standard', + name: '标准模式', + isDefault: true, + rows: [ + { entryId: 'alpha', moduleName: 'pkg-alpha', enabled: true, fiberState: FiberState.ACTIVE }, + { entryId: null, moduleName: 'pkg-file', enabled: 'conditional', condition: 'x' }, + ], + }, + { id: 'damaged', isDefault: false, broken: 'the composition file is missing', rows: [] }, + ], + } as Partial as never) + + const snapshot = await inventory.list() + expect(snapshot.agentPresets).toEqual([ + { + id: 'standard', + name: '标准模式', + isDefault: true, + rows: [ + { entryId: 'alpha', moduleName: 'pkg-alpha', enabled: true, fiberPhase: 'active' }, + { entryId: null, moduleName: 'pkg-file', enabled: 'conditional', condition: 'x', fiberPhase: null }, + ], + }, + { id: 'damaged', isDefault: false, broken: 'the composition file is missing', rows: [] }, + ]) }) }) diff --git a/packages/host/plugin-inventory/tsconfig.json b/packages/host/plugin-inventory/tsconfig.json index 5bd45b3f3c..b56a8291ec 100644 --- a/packages/host/plugin-inventory/tsconfig.json +++ b/packages/host/plugin-inventory/tsconfig.json @@ -14,6 +14,9 @@ { "path": "../../../vendor/loader" }, + { + "path": "../../preset/agent-presets" + }, { "path": "../../util/brand" }, diff --git a/packages/preset/agent-presets/README.i18n.yaml b/packages/preset/agent-presets/README.i18n.yaml index 0ff1f1d20f..401ec1eefe 100644 --- a/packages/preset/agent-presets/README.i18n.yaml +++ b/packages/preset/agent-presets/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/preset/agent-presets/README.md -README.md: 5b83ed85a6691dabb6ec340b6462f17d5281efdd -README.zh.md: f55f1e383d11b28fa1d8ff52aec1e94a351914f7 +README.md: bc157f664ecc2aabb61baaa4527f0134133aa344 +README.zh.md: 7680fcf76653f299d068290d74779e21969cf6a6 diff --git a/packages/preset/agent-presets/README.md b/packages/preset/agent-presets/README.md index 5b83ed85a6..bc157f664e 100644 --- a/packages/preset/agent-presets/README.md +++ b/packages/preset/agent-presets/README.md @@ -105,6 +105,7 @@ This section explains the design behind the roster and the standing mount; obser |---|---| | [`src/index.ts`](src/index.ts) | Service entry: `Config` schema, settings namespace, roster API, standing-mount coordination | | [`src/discovery.ts`](src/discovery.ts) | Filesystem discovery: root scanning, health checks, id validation, ordering | +| [`src/composition-inventory.ts`](src/composition-inventory.ts) | Flattened composition rows for plugin-listing surfaces: file reads with evaluated disabled gates, mount reads with fiber states | | [`src/preset.ts`](src/preset.ts) | Vocabulary: preset id rule, `AgentPreset` and `PresetRoot`, error types | | [`src/mount.ts`](src/mount.ts) | Subtree mounting, host base-URL handling, mount audit, `write()` suppression | | [`src/authoring.ts`](src/authoring.ts) | Copy/delete/read of locally authored presets, permission tightening | @@ -117,6 +118,10 @@ This section explains the design behind the roster and the standing mount; obser `ensureStanding` keeps one pending promise per preset id, single-flight, so two agents racing the first use of a preset share one composition. A settled failure is removed so a later session retries a preset whose file has been fixed. The mount runs in the roster service's own untraced context — a subtree minted from a traced context would resolve services through the caller's shadow fiber — so it survives every agent and unwinds only with whole-tree teardown. `serviceForAgent` reads an agent's instance of a service its preset mounted behind an `isolate` realm, which is otherwise invisible outside the group. +### The composition inventory + +`compositionInventory()` answers plugin-listing surfaces with each preset's flattened rows beside its roster identity: a preset with a live standing mount answers from its newest generation's Loader entries, and one never composed since boot answers from its composition file with `!!js` disabled gates evaluated against the Loader context, so both answers reflect the same host. Reading never mounts a preset — a settings page listing every composition activates none of them. A gate the evaluator refuses stays `'conditional'`, and a file that stopped reading as a composition between discovery's health verdict and the row read is reported broken with the raced reason rather than dropped. + ### The mount audit A directly-plugged subtree is absent from `ctx.loader.entries()`, so no boot audit covers it; `mountPreset` proves the result usable itself and rejects three shapes: an unscoped target (the preset's tools would register globally), a row still waiting for a service the composition never supplies, and a row that published a service into the root realm (process-global, so the second preset publishing the same name collides). The invariant companion re-checks the last rule on every service notification, because a row publishing from a timer or an asynchronous continuation would escape the one-shot audit. diff --git a/packages/preset/agent-presets/README.zh.md b/packages/preset/agent-presets/README.zh.md index f55f1e383d..7680fcf766 100644 --- a/packages/preset/agent-presets/README.zh.md +++ b/packages/preset/agent-presets/README.zh.md @@ -105,6 +105,7 @@ agent-presets: |---|---| | [`src/index.ts`](src/index.ts) | 服务入口：`Config` schema、settings 命名空间、名单 API、常驻挂载协调 | | [`src/discovery.ts`](src/discovery.ts) | 文件系统发现：根目录扫描、健康检查、id 校验、排序 | +| [`src/composition-inventory.ts`](src/composition-inventory.ts) | 面向插件清单表面的压平组合行：文件读取（求值 disabled 门）与挂载读取（携带 fiber 状态） | | [`src/preset.ts`](src/preset.ts) | 词汇体系：preset id 规则、`AgentPreset` 与 `PresetRoot`、错误类型 | | [`src/mount.ts`](src/mount.ts) | 子树挂载、宿主 base-URL 处理、挂载审计、`write()` 抑制 | | [`src/authoring.ts`](src/authoring.ts) | 本地创作 preset 的复制/删除/读取、权限收紧 | @@ -117,6 +118,10 @@ agent-presets: `ensureStanding` 为每个 preset id 保留一个进行中的 promise（single-flight），因此两个竞争首次使用同一 preset 的 agent 共享一份组装。已结算的失败会被移除，以便后续会话重试文件已被修复的 preset。挂载运行在 roster 服务自己的未追踪上下文中——从被追踪上下文派生的子树会经调用方的 shadow fiber 解析服务——因此它比任何 agent 都活得久，只随整棵树卸载。`serviceForAgent` 读取某 agent 对其 preset 挂在 `isolate` realm 之后（组外不可见）的某个服务实例。 +### 组合清单 + +`compositionInventory()` 向插件清单表面提供每个预设的压平行及其名单身份：已有存活 standing mount 的预设由其最新世代的 Loader 条目作答，开机以来从未被组合的预设由其组合文件作答，`!!js` disabled 门用 Loader 上下文求值，使两种答案反映同一台宿主。读取从不挂载预设——列出所有组合的设置页不会激活其中任何一个。求值器拒绝的门保持 `'conditional'`；在发现的健康裁决与行读取之间变得不可读的文件，会携带竞态原因报告为 broken，而不是被静默丢弃。 + ### 挂载审计 直接挂载的子树不会出现在 `ctx.loader.entries()` 中，因此没有启动审计能覆盖它；`mountPreset` 自行证明结果可用，并拒绝三种形态：无 scope 的目标（preset 的工具会注册成全局的）、仍在等待组装从未提供的服务的行、以及把服务发布进根 realm 的行（进程级全局，第二个发布同名服务的 preset 会相撞）。不变式伴生插件在每次服务通知时复查最后一条规则，因为从定时器或异步续体发布的行会绕过一次性审计。 diff --git a/packages/preset/agent-presets/src/composition-inventory.ts b/packages/preset/agent-presets/src/composition-inventory.ts new file mode 100644 index 0000000000..29ac401eaa --- /dev/null +++ b/packages/preset/agent-presets/src/composition-inventory.ts @@ -0,0 +1,195 @@ +/** + * Structured composition reads for plugin-listing surfaces: the plugin rows + * each preset names, with each row's effective enablement. A preset with a + * live standing mount answers from that mount's Loader entries — evaluated + * `disabled`, real root-fiber states; a preset no session has composed since + * boot answers from its composition file, with `!!js` disabled expressions + * evaluated through the caller-supplied Loader evaluator so the file answer + * matches the decision a mount on this host would make. A row whose + * expression the evaluator refuses stays `'conditional'`. + * @module @deepseek-ai/dsh-agent-presets/composition-inventory + */ + +import { readFile } from 'node:fs/promises' +import { load } from 'js-yaml' +import type { FiberState } from '@deepseek-ai/cordis' +import { isJsExpr, type EntryTree } from '@deepseek-ai/cordis-plugin-loader' +import { entryListSchema } from '@deepseek-ai/cordis-plugin-include' +import { entryListProblem } from './discovery.ts' + +/** + * Effective enablement of one composition row: a literal or evaluated + * boolean, or `'conditional'` when a `!!js` disabled expression could not be + * evaluated outside a mount. + */ +export type CompositionRowEnablement = boolean | 'conditional' + +/** + * Evaluate one `!!js` disabled expression the way the Loader would at a mount + * decision. Throwing refuses the answer: the row is reported `'conditional'` + * rather than guessed. + */ +export type DisabledExpressionEvaluator = (expression: string) => unknown + +/** One plugin row a preset composition names. */ +export interface AgentPresetCompositionRow { + /** + * The Loader-tree entry id when read from a live mount, else the id the + * composition file declares; null when the file row declares none. + */ + readonly entryId: string | null + /** Module specifier the row names. */ + readonly moduleName: string + /** Effective enablement, including disabled ancestor groups. */ + readonly enabled: CompositionRowEnablement + /** The row's own `!!js` disabled expression, when it carries one. */ + readonly condition?: string + /** Root-fiber state, present only when read from a live mount. */ + readonly fiberState?: FiberState +} + +/** One preset's roster identity beside its composition rows. */ +export interface AgentPresetComposition { + /** Stable preset id. */ + readonly id: string + /** Display name the preset published. */ + readonly name?: string + /** Whether a session naming no preset composes this one. */ + readonly isDefault: boolean + /** Why this preset's rows cannot be read; absent when {@link rows} answers. */ + readonly broken?: string + /** Composition rows in composition order; empty when the preset is broken. */ + readonly rows: readonly AgentPresetCompositionRow[] +} + +/** + * One `disabled` node's contribution to effective enablement, mirroring the + * Loader's own reading: a `!!js` expression is asked of the evaluator — a + * refusal (throw) leaves the decision to a mount — and anything else disables + * exactly when `Boolean(value)` does. + * @param value - the raw `disabled` node of one composition row. + * @param evaluateExpression - the Loader-context evaluator for `!!js` nodes. + * @returns true (disabled), false (enabled), or `'conditional'`. + */ +function disabledContribution( + value: unknown, + evaluateExpression: DisabledExpressionEvaluator, +): boolean | 'conditional' { + if (isJsExpr(value)) { + try { + return Boolean(evaluateExpression(value.__jsExpr)) + } catch { + // The evaluator refused (a malformed or context-dependent expression); + // only a real mount decision can answer, so the row stays conditional. + return 'conditional' + } + } + return Boolean(value) +} + +/** + * Combine an ancestor group's disabled state with a row's own, the way the + * Loader walks owning groups: any literal true disables, otherwise any + * expression leaves the decision to a mount. + * @param outer - the combined ancestor contribution. + * @param own - this row's contribution. + * @returns the row's effective disabled state. + */ +function combineDisabled( + outer: boolean | 'conditional', + own: boolean | 'conditional', +): boolean | 'conditional' { + if (outer === true || own === true) return true + if (outer === 'conditional' || own === 'conditional') return 'conditional' + return false +} + +/** A parsed composition row after {@link entryListProblem} accepted the list. */ +interface RawRow { + readonly id?: unknown + readonly name: string + readonly group?: unknown + readonly config?: unknown + readonly disabled?: unknown +} + +/** + * Flatten one parsed row list into plugin rows. Group rows are structural — + * the Loader reports a group entry as always enabled and lets children + * inherit its `disabled` — so only their children are emitted. + * @param rows - the parsed rows, shape-checked by the caller. + * @param outerDisabled - the combined ancestor-group disabled state. + * @param evaluateExpression - the Loader-context evaluator for `!!js` nodes. + * @param found - the accumulator receiving flattened rows. + */ +function flattenRows( + rows: readonly unknown[], + outerDisabled: boolean | 'conditional', + evaluateExpression: DisabledExpressionEvaluator, + found: AgentPresetCompositionRow[], +): void { + for (const value of rows) { + const row = value as RawRow + const disabled = combineDisabled(outerDisabled, disabledContribution(row.disabled, evaluateExpression)) + if (row.group === true) { + flattenRows(row.config as readonly unknown[], disabled, evaluateExpression, found) + continue + } + found.push({ + entryId: typeof row.id === 'string' && row.id !== '' ? row.id : null, + moduleName: row.name, + enabled: disabled === true ? false : disabled === 'conditional' ? 'conditional' : true, + ...isJsExpr(row.disabled) ? { condition: row.disabled.__jsExpr } : {}, + }) + } +} + +/** + * Plugin rows of one composition file, for a preset with no live mount. + * + * Parsed with the Loader's own dialect ({@link entryListSchema}), so the rows + * reported are the rows a mount would start from. A file that stopped reading + * as a composition — discovery judged the preset healthy moments earlier, so + * only an edit racing this read gets here — answers as broken with the raced + * reason rather than dropping the rows silently. + * @param path - absolute path of the composition file. + * @param evaluateExpression - the Loader-context evaluator for `!!js` nodes. + * @returns flattened rows in composition order, or why they cannot be read. + */ +export async function fileComposition( + path: string, + evaluateExpression: DisabledExpressionEvaluator, +): Promise<{ rows: AgentPresetCompositionRow[] } | { broken: string }> { + let rows: unknown + try { + rows = load(await readFile(path, 'utf8'), { schema: entryListSchema }) + } catch (error) { + /* v8 ignore next -- fs and js-yaml throw Errors for every failure here; the fallback keeps a hostile value readable */ + return { broken: error instanceof Error ? error.message : String(error) } + } + const problem = entryListProblem(rows) + if (problem !== undefined) return { broken: problem } + const found: AgentPresetCompositionRow[] = [] + flattenRows(rows as readonly unknown[], false, evaluateExpression, found) + return { rows: found } +} + +/** + * Plugin rows of one live standing composition, in Loader-entry order. + * @param tree - the standing mount's entry tree. + * @returns rows with the Loader's evaluated enablement and root-fiber states. + */ +export function mountedCompositionRows(tree: EntryTree): AgentPresetCompositionRow[] { + const found: AgentPresetCompositionRow[] = [] + for (const entry of tree.entries()) { + if (entry.options.group) continue + found.push({ + entryId: entry.id, + moduleName: entry.options.name, + enabled: !entry.disabled, + ...isJsExpr(entry.options.disabled) ? { condition: entry.options.disabled.__jsExpr } : {}, + ...entry.fiber === undefined ? {} : { fiberState: entry.fiber.state }, + }) + } + return found +} diff --git a/packages/preset/agent-presets/src/discovery.ts b/packages/preset/agent-presets/src/discovery.ts index 915ee90f45..8d39410b00 100644 --- a/packages/preset/agent-presets/src/discovery.ts +++ b/packages/preset/agent-presets/src/discovery.ts @@ -67,11 +67,14 @@ export const SHIPPED_PRESET_ROOT = fileURLToPath(new URL('../presets/', import.m * that produces a file the loader cannot even begin with — and it must accept * everything the loader accepts, which is why rows are only required to be * maps carrying a plugin `name` (groups recurse into their own lists). + * + * Shared with the composition inventory, whose file reads race edits against + * the health verdict and must judge the raced content by the same rule. * @param rows - the parsed composition document. * @param at - row-path prefix for nested diagnostics, empty at the top level. * @returns one human-readable reason, or undefined when the shape holds. */ -function entryListProblem(rows: unknown, at = ''): string | undefined { +export function entryListProblem(rows: unknown, at = ''): string | undefined { if (!Array.isArray(rows)) { return at === '' ? 'the composition must be a top-level list of plugin rows' diff --git a/packages/preset/agent-presets/src/index.ts b/packages/preset/agent-presets/src/index.ts index 7dbcefb3d3..3033cf47b9 100644 --- a/packages/preset/agent-presets/src/index.ts +++ b/packages/preset/agent-presets/src/index.ts @@ -23,6 +23,7 @@ import { stat } from 'node:fs/promises' import { Context } from '@deepseek-ai/cordis' +import { evaluate } from '@deepseek-ai/cordis-plugin-loader' import z from '@deepseek-ai/schemastery' import { Remote, TypertRemoteFailure, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol' import { bindScopeParent, createScope, scopeOf, type Scope, type ScopeKey, type ScopeParentBinding } from '@deepseek-ai/dsh-scope' @@ -40,13 +41,20 @@ import { copyComposition, deleteComposition, readComposition, InvalidPresetIdError, PresetExistsError, PresetNotWritableError, } from './authoring.ts' -import { mountPreset, serviceForAgent, standingMountFor } from './mount.ts' +import { livePresetMounts, mountPreset, serviceForAgent, standingMountFor } from './mount.ts' +import { + fileComposition, mountedCompositionRows, + type AgentPresetComposition, +} from './composition-inventory.ts' import { PresetLockedError, PresetMountError, UnknownPresetError, type AgentPreset, type Config, type PresetRoot, } from './preset.ts' import { agentPresetProjectionDefinition } from './session.ts' export type * from './types.ts' +export type { + AgentPresetComposition, AgentPresetCompositionRow, CompositionRowEnablement, +} from './composition-inventory.ts' /** Settings namespace carrying the user's chosen default preset. */ export const SETTINGS_NAMESPACE = 'agent-presets' @@ -330,6 +338,51 @@ export class AgentPresets extends TypertRemoteService { } } + /** + * Every preset's composition as flattened plugin rows, for plugin-listing + * surfaces beside the roster's own picker. + * + * A preset with a live standing mount answers from its newest generation's + * Loader entries — the composition new sessions join — and one never + * composed since boot answers from its file, with `!!js` disabled gates + * evaluated against the Loader context so both answers reflect the same + * host. Reading never mounts: an unmounted preset is parsed, not composed, + * so listing a preset's plugins cannot activate them early. A composition + * that stopped reading between discovery's health verdict and this read is + * reported broken with the raced reason rather than dropped. + * @returns one composition per roster preset, in roster order. + */ + async compositionInventory(): Promise { + const defaultId = this.defaultId + // The Loader's own expression scope: what a mount decision would consult + // (entry.ctx only adds the entry itself, which no disabled gate reads). + const evaluateExpression = (expression: string): unknown => evaluate(this.ctx.loader.ctx, expression) + const found: AgentPresetComposition[] = [] + for (const preset of await this.list()) { + const identity = { + id: preset.id, + ...preset.name === undefined ? {} : { name: preset.name }, + isDefault: preset.id === defaultId, + } + if (preset.broken !== undefined) { + found.push({ ...identity, broken: preset.broken, rows: [] }) + continue + } + // Newest generation last: mount records keep insertion order, and a + // superseded generation's record precedes its replacement's. + const mount = livePresetMounts().findLast(candidate => candidate.presetId === preset.id) + if (mount !== undefined) { + found.push({ ...identity, rows: mountedCompositionRows(mount.tree) }) + continue + } + const read = await fileComposition(preset.path, evaluateExpression) + found.push('broken' in read + ? { ...identity, broken: read.broken, rows: [] } + : { ...identity, rows: read.rows }) + } + return found + } + /** * Resolve one preset by id. * diff --git a/packages/preset/agent-presets/tests/composition-inventory.spec.ts b/packages/preset/agent-presets/tests/composition-inventory.spec.ts new file mode 100644 index 0000000000..8240ce557f --- /dev/null +++ b/packages/preset/agent-presets/tests/composition-inventory.spec.ts @@ -0,0 +1,309 @@ +/** + * Structured composition reads: the flattened plugin rows a preset names, + * answered from the composition file while no session has mounted the preset + * and from the standing mount once one has, with a composition that cannot be + * read reported broken by reason instead of dropped. + */ + +import { mkdir, mkdtemp, writeFile } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { dirname, join } from 'node:path' +import { fileURLToPath, pathToFileURL } from 'node:url' +import { Context, FiberState } from '@deepseek-ai/cordis' +import Loader from '@deepseek-ai/cordis-plugin-loader' +import Include from '@deepseek-ai/cordis-plugin-include' +import LlmRuntime from '@deepseek-ai/dsh-llm' +import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRuntime from '@deepseek-ai/dsh-tools' +import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentLoop from '@deepseek-ai/dsh-agent-loop' +import { afterEach, describe, expect, it, vi } from 'vitest' +import AgentPresets, { COMPOSITION_FILE, METADATA_FILE } from '@deepseek-ai/dsh-agent-presets' +import type { Config } from '@deepseek-ai/dsh-agent-presets' +import { evaluate } from '@deepseek-ai/cordis-plugin-loader' +import { fileComposition, mountedCompositionRows } from '../src/composition-inventory.ts' +import { livePresetMounts } from '../src/mount.ts' + +const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), 'fixtures') +const SYSTEM_ROOT = { path: join(FIXTURES, 'system'), trust: 'system' as const } +// A row naming a package installed beside the harness, the way authored rows do. +const VALID = '- id: prompt\n name: \'@deepseek-ai/dsh-system-prompt\'\n' + +const contexts: Context[] = [] + +/** A Loader-context evaluator over an empty scope, enough for literal gates. */ +const evaluateExpression = (expression: string): unknown => evaluate({}, expression) +/** An evaluator that refuses every expression, leaving rows conditional. */ +const refuseExpression = (): never => { throw new Error('no loader context') } + +afterEach(async () => { + vi.restoreAllMocks() + await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose())) +}) + +async function harness(roster: Config): Promise { + const ctx = new Context() + contexts.push(ctx) + ctx.baseUrl = pathToFileURL(FIXTURES).href + '/' + await ctx.plugin(Loader) + ctx.loader.builtins.include = Include + await ctx.plugin(LlmRuntime) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: '' }) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(AgentPresets, roster) + return ctx +} + +describe('fileComposition', () => { + it('flattens groups and keeps refused expressions conditional', async () => { + const dir = await mkdtemp(join(tmpdir(), 'dsh-composition-')) + const path = join(dir, COMPOSITION_FILE) + await writeFile(path, [ + '- id: alpha', + ' name: pkg-alpha', + '- name: pkg-anonymous', + '- id: off', + ' name: pkg-off', + ' disabled: true', + '- id: cond', + ' name: pkg-cond', + ' disabled: !!js process.platform === \'win32\'', + '- id: grp', + ' name: cordis:group', + ' group: true', + ' config:', + ' - id: child', + ' name: pkg-child', + ' - id: child-off', + ' name: pkg-child-off', + ' disabled: true', + '- id: grp-off', + ' name: cordis:group', + ' group: true', + ' disabled: true', + ' config:', + ' - id: buried', + ' name: pkg-buried', + '- id: grp-cond', + ' name: cordis:group', + ' group: true', + ' disabled: !!js 1', + ' config:', + ' - id: maybe', + ' name: pkg-maybe', + ' - id: certainly-off', + ' name: pkg-certainly-off', + ' disabled: true', + ].join('\n')) + + expect(await fileComposition(path, refuseExpression)).toEqual({ + rows: [ + { entryId: 'alpha', moduleName: 'pkg-alpha', enabled: true }, + { entryId: null, moduleName: 'pkg-anonymous', enabled: true }, + { entryId: 'off', moduleName: 'pkg-off', enabled: false }, + { + entryId: 'cond', + moduleName: 'pkg-cond', + enabled: 'conditional', + condition: 'process.platform === \'win32\'', + }, + { entryId: 'child', moduleName: 'pkg-child', enabled: true }, + { entryId: 'child-off', moduleName: 'pkg-child-off', enabled: false }, + { entryId: 'buried', moduleName: 'pkg-buried', enabled: false }, + { entryId: 'maybe', moduleName: 'pkg-maybe', enabled: 'conditional' }, + { entryId: 'certainly-off', moduleName: 'pkg-certainly-off', enabled: false }, + ], + }) + }) + + it('evaluates decidable gates the way a mount would', async () => { + const dir = await mkdtemp(join(tmpdir(), 'dsh-composition-')) + const path = join(dir, COMPOSITION_FILE) + await writeFile(path, [ + '- id: off', + ' name: pkg-off', + ' disabled: !!js 1 === 1', + '- id: on', + ' name: pkg-on', + ' disabled: !!js 1 === 2', + ].join('\n')) + + expect(await fileComposition(path, evaluateExpression)).toEqual({ + rows: [ + { entryId: 'off', moduleName: 'pkg-off', enabled: false, condition: '1 === 1' }, + { entryId: 'on', moduleName: 'pkg-on', enabled: true, condition: '1 === 2' }, + ], + }) + }) + + it('answers broken for a file that stopped reading as a composition', async () => { + const dir = await mkdtemp(join(tmpdir(), 'dsh-composition-')) + + const missing = await fileComposition(join(dir, COMPOSITION_FILE), refuseExpression) + expect(missing).toHaveProperty('broken') + + const unparsable = join(dir, 'unparsable.yml') + await writeFile(unparsable, 'foo: [') + const yaml = await fileComposition(unparsable, refuseExpression) + expect('broken' in yaml && yaml.broken.length > 0).toBe(true) + + const rowless = join(dir, 'rowless.yml') + await writeFile(rowless, 'foo: bar\n') + expect(await fileComposition(rowless, refuseExpression)).toEqual({ + broken: 'the composition must be a top-level list of plugin rows', + }) + }) +}) + +describe('mountedCompositionRows', () => { + it('reads evaluated enablement and root-fiber states, skipping group rows', async () => { + const ctx = new Context() + contexts.push(ctx) + await ctx.plugin(Loader) + ctx.loader.builtins.active = () => {} + const activeId = await ctx.loader.create({ name: 'cordis:active' }) + const disabledId = await ctx.loader.create({ name: 'cordis:active', disabled: true }) + const evaluatedId = await ctx.loader.create({ + name: 'cordis:active', + // The YAML `!!js` tag deserializes to exactly this object; EntryOptions + // types the field by its literal form only. + disabled: { __jsExpr: 'false' } as unknown as boolean, + }) + await ctx.loader.create({ name: 'cordis:active', group: true }) + + expect(mountedCompositionRows(ctx.loader)).toEqual([ + { entryId: activeId, moduleName: 'cordis:active', enabled: true, fiberState: FiberState.ACTIVE }, + { entryId: disabledId, moduleName: 'cordis:active', enabled: false }, + { + entryId: evaluatedId, + moduleName: 'cordis:active', + enabled: true, + condition: 'false', + fiberState: FiberState.ACTIVE, + }, + ]) + }) +}) + +describe('AgentPresets.compositionInventory', () => { + it('reads unmounted presets from their files, marking the default and metadata', async () => { + const userRoot = await mkdtemp(join(tmpdir(), 'dsh-composition-roster-')) + await mkdir(join(userRoot, 'documented')) + await writeFile(join(userRoot, 'documented', COMPOSITION_FILE), [ + VALID.trimEnd(), + '- id: gated', + ' name: \'@deepseek-ai/dsh-system-prompt\'', + ' disabled: !!js 1 === 1', + '- id: undecidable', + ' name: \'@deepseek-ai/dsh-system-prompt\'', + ' disabled: !!js nothing.here', + ].join('\n')) + await writeFile(join(userRoot, 'documented', METADATA_FILE), 'name: 我的模式\n') + const ctx = await harness({ + default: 'minimal', + roots: [SYSTEM_ROOT, { path: userRoot, trust: 'user' }], + includeShippedRoot: false, + includeUserRoot: false, + }) + + expect(await ctx.agentPresets.compositionInventory()).toEqual([ + { + id: 'minimal', + isDefault: true, + rows: [{ entryId: 'beta', moduleName: '../../plugins/contribute.js', enabled: true }], + }, + { + id: 'standard', + isDefault: false, + rows: [ + { entryId: 'alpha', moduleName: '../../plugins/contribute.js', enabled: true }, + { entryId: 'alpha-extra', moduleName: '../../plugins/contribute.js', enabled: false }, + ], + }, + { + id: 'documented', + name: '我的模式', + isDefault: false, + rows: [ + { entryId: 'prompt', moduleName: '@deepseek-ai/dsh-system-prompt', enabled: true }, + // The platform-gate shape: the service evaluates it with the + // Loader's own scope, so the file answer matches a mount's. + { entryId: 'gated', moduleName: '@deepseek-ai/dsh-system-prompt', enabled: false, condition: '1 === 1' }, + // An expression the evaluator refuses stays a mount's decision. + { + entryId: 'undecidable', + moduleName: '@deepseek-ai/dsh-system-prompt', + enabled: 'conditional', + condition: 'nothing.here', + }, + ], + }, + ]) + // Reading is never mounting: every unmounted preset above was answered + // from its file, so listing plugins cannot activate a preset early. + expect(livePresetMounts()).toEqual([]) + }) + + it('reads a mounted preset from its standing composition', async () => { + const ctx = await harness({ + default: 'standard', + roots: [SYSTEM_ROOT], + includeShippedRoot: false, + includeUserRoot: false, + }) + await ctx.agents.create({ + sessionId: SessionId('composition-inventory'), + setup: async (agentCtx: Context) => void await ctx.agentPresets.mount(agentCtx, 'standard'), + }) + + const standard = (await ctx.agentPresets.compositionInventory()) + .find(composition => composition.id === 'standard') + expect(standard?.rows).toEqual([ + { + entryId: 'alpha', + moduleName: '../../plugins/contribute.js', + enabled: true, + fiberState: FiberState.ACTIVE, + }, + { entryId: 'alpha-extra', moduleName: '../../plugins/contribute.js', enabled: false }, + ]) + }) + + it('keeps a broken preset on the inventory with its discovery reason', async () => { + const userRoot = await mkdtemp(join(tmpdir(), 'dsh-composition-roster-')) + await mkdir(join(userRoot, 'damaged')) + const ctx = await harness({ + default: 'minimal', + roots: [SYSTEM_ROOT, { path: userRoot, trust: 'user' }], + includeShippedRoot: false, + includeUserRoot: false, + }) + + const damaged = (await ctx.agentPresets.compositionInventory()) + .find(composition => composition.id === 'damaged') + expect(damaged?.rows).toEqual([]) + expect(damaged?.broken).toContain('is missing') + }) + + it('reports a composition that raced discovery as broken instead of dropping it', async () => { + const ctx = await harness({ + default: 'minimal', + roots: [SYSTEM_ROOT], + includeShippedRoot: false, + includeUserRoot: false, + }) + // Discovery judged the preset healthy, then the file vanished before the + // row read: the inventory keeps the preset and carries the raced reason. + vi.spyOn(ctx.agentPresets, 'list').mockResolvedValue([ + { id: 'ghost', trust: 'user', path: join(FIXTURES, 'ghost', COMPOSITION_FILE) }, + ]) + + const [ghost] = await ctx.agentPresets.compositionInventory() + expect(ghost?.rows).toEqual([]) + expect(ghost?.broken).toBeDefined() + }) +}) diff --git a/packages/preset/agent-presets/tsconfig.json b/packages/preset/agent-presets/tsconfig.json index 926ed9ce51..c357b1f257 100644 --- a/packages/preset/agent-presets/tsconfig.json +++ b/packages/preset/agent-presets/tsconfig.json @@ -18,6 +18,9 @@ { "path": "../../../vendor/include" }, + { + "path": "../../../vendor/loader" + }, { "path": "../../core/agent" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 06d5d75a10..eebbf4be72 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -5919,6 +5919,9 @@ importers: '@deepseek-ai/cordis-plugin-loader': specifier: workspace:^ version: link:../../../vendor/loader + '@deepseek-ai/dsh-agent-presets': + specifier: workspace:^ + version: link:../../preset/agent-presets '@deepseek-ai/dsh-brand': specifier: workspace:^ version: link:../../util/brand diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 1bae81253b..266438678a 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -656,6 +656,7 @@ export const TYPE_LINK_EXEMPTIONS: Readonly> = { AgentPreset: 'discovered preset record is owned by packages/preset/agent-presets/README.md', AgentPresetRoster: 'path-free preset roster is owned by packages/preset/agent-presets/README.md', AgentPresetDocument: 'preset composition view is owned by packages/preset/agent-presets/README.md', + AgentPresetComposition: 'flattened composition rows are owned by packages/preset/agent-presets/README.md', PresetMetadata: 'preset display text is owned by packages/preset/agent-presets/README.md', BashEnvContributor: 'service-local extension type is owned by packages/shell/tool-bash/src/index.ts', BashEnvVariableInfo: 'service-local metadata type is owned by packages/shell/tool-bash/src/index.ts', From 5eb7195f9ddeb338b4c8f04e5cea4255872826af Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 17:13:45 +0800 Subject: [PATCH 39/63] refactor(plugin-inventory): menu-pill preset switcher, collapsible groups, inline preset-provided rows Review-driven refinements to the scope-grouped plugin list: - The preset switcher becomes the General-settings selector pill over the shared Menu primitive instead of a native select, and the preset group is collapsible like the global one (search still forces both open). - The session-plugins drawer is removed: rows the presets took over sit inline in the global list with the preset-provided tag and per-preset details, since the preset group above already shows those compositions. - The status dot renders only for a live root fiber, so file-state rows of an unmounted preset carry their enablement tag alone instead of a column of grey dots. - PresetTree reclaims the owning entry's subtree slot: EntryTree's constructor filed the standing mount under the roster's own Loader row, so after the first session composed a preset the whole composition leaked into root loader.entries() as host rows (each preset overwriting the last). A regression test holds the root entry list identical across a mount. --- ...in-inventory-agent-preset-scopes.i18n.yaml | 4 +- ...29-plugin-inventory-agent-preset-scopes.md | 6 +- ...plugin-inventory-agent-preset-scopes.zh.md | 6 +- apps/web/tests/settings-chrome.e2e.ts | 9 +- .../README.i18n.yaml | 4 +- .../ui-settings-plugin-inventory/README.md | 8 +- .../ui-settings-plugin-inventory/README.zh.md | 8 +- .../PluginInventorySettingsTab.module.css | 64 ++++--- .../src/client/PluginInventorySettingsTab.tsx | 160 +++++++++--------- .../src/client/locales.ts | 8 +- .../tests/components.client.spec.tsx | 77 ++++++--- packages/preset/agent-presets/src/mount.ts | 8 + .../tests/composition-inventory.spec.ts | 32 ++++ 13 files changed, 239 insertions(+), 155 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.i18n.yaml index bb1705fca7..dd06ae7c96 100644 --- a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.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-08-29-plugin-inventory-agent-preset-scopes.md -2026-08-29-plugin-inventory-agent-preset-scopes.md: ec738ee0ff325e14677407da0ce4af8ffe3fe718 -2026-08-29-plugin-inventory-agent-preset-scopes.zh.md: 7804203350b4173a6dfd058447aee95e918cda74 +2026-08-29-plugin-inventory-agent-preset-scopes.md: 8615e057bec7b269fe58c18678d8cc96479d451f +2026-08-29-plugin-inventory-agent-preset-scopes.zh.md: d71ddf2dc082193c5c7530ba34680102ce8c3d2e diff --git a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md index ec738ee0ff..8615e057be 100644 --- a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md +++ b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.md @@ -12,15 +12,15 @@ English | [中文](2026-08-29-plugin-inventory-agent-preset-scopes.zh.md) **The inventory speaks for both planes.** `pluginInventory/list` gains an optional `agentPresets` block — one group per roster preset with id, display name, default marking, health, and flattened composition rows — supplied by the new `AgentPresets.compositionInventory()`: a preset with a live standing mount answers from its newest generation's Loader entries, and one never composed since boot answers from its composition file. `dsh-host-plugin-inventory` resolves the roster as an optional peer through `ctx.get('agentPresets')` (the `plugin-package-inventory-deepseek` pattern) and only maps root-fiber states onto its public phase vocabulary, so deployments without a roster keep serving Loader entries alone with the field absent. -**File answers are evaluated, not guessed, and reading never mounts.** `!!js` disabled gates are platform/environment conditions the [Loader itself evaluates at every mount decision](2026-08-11-loader-entry-disabled-interpolation.md), so the file read evaluates them against the Loader context and reports the decision a mount on this host would make; a gate the evaluator refuses stays `'conditional'` with its expression text carried for display. The read parses and evaluates only — no import, no compose — so listing every preset's plugins activates none of them, and a regression test pins `livePresetMounts()` empty after a full inventory read. +**File answers are evaluated, not guessed, and reading never mounts.** `!!js` disabled gates are platform/environment conditions the [Loader itself evaluates at every mount decision](2026-08-11-loader-entry-disabled-interpolation.md), so the file read evaluates them against the Loader context and reports the decision a mount on this host would make; a gate the evaluator refuses stays `'conditional'` with its expression text carried for display. The read parses and evaluates only — no import, no compose — so listing every preset's plugins activates none of them, and a regression test pins `livePresetMounts()` empty after a full inventory read. Building this surface also exposed the reverse leak: `EntryTree`'s constructor files every new tree under the nearest owning Loader entry's `subtree` slot, so the first standing mount hung the whole preset composition off the roster's own row and root `loader.entries()` walked it as host entries. `PresetTree` now reclaims the slot, restoring the standing mount's documented absence from the Loader, and a regression test holds the root entry list identical across a mount. -**The list is grouped by scope, with the misleading rows given their own state.** The preset group renders first behind a display-only switcher that opens on the default preset and writes no settings — inspecting `minimal` must not change what new sessions run. The global group follows collapsed, failures float first, and a global entry that is disabled while at least one preset row for the same module specifier is actually enabled folds into a "session plugins" drawer that names its providers — a third state instead of the generic "disabled" that started this. The provider rule is strict `enabled === true`: counting conditional declarations would claim per-session provision `tool-pwsh` never delivers on POSIX. Search spans both groups, forces the disclosures open, and points at matches sitting in unselected presets. +**The list is grouped by scope, with the misleading rows given their own state.** The preset group renders first, collapsible and open by default, behind a display-only switcher — the General-settings selector pill over a menu — that opens on the default preset and writes no settings, because inspecting `minimal` must not change what new sessions run. The global group follows collapsed, failures float first, and a global entry that is disabled while at least one preset row for the same module specifier is actually enabled is marked preset-provided in place, its details naming the enabling presets — a third state instead of the generic "disabled" that started this, and deliberately not a sub-group: the preset group above already shows those plugins as compositions, so a second cluster restating them earned its removal. The status dot appears only for a live root fiber — a file-state row carries its enablement tag alone, so an unmounted preset does not read as a column of grey mystery dots. The provider rule is strict `enabled === true`: counting conditional declarations would claim per-session provision `tool-pwsh` never delivers on POSIX. Search spans both groups, forces them open, and points at matches sitting in unselected presets. **The General row is deleted, not relocated.** The default keeps two surfaces that can still act on it — the roster section's make-default beside the visible roster, and the new-session chip for the session about to start — so `ui-agent-preset` drops the row, its menu, and the write/writability half of its settings store, which slims to the display roster the header label reads. ## Alternatives considered -**Render every preset as its own always-open section.** Four shipped presets already put ~100 rows behind the fold; the switcher keeps one composition in view while the drawer's provider list and the search pointers preserve the cross-scope answer the all-at-once layout was buying. +**Render every preset as its own always-open section.** Four shipped presets already put ~100 rows behind the fold; the switcher keeps one composition in view while the per-row provider details and the search pointers preserve the cross-scope answer the all-at-once layout was buying. **Keep file-state gates unevaluated (`conditional` until first mount).** Honest but it re-created the misleading reading this change removes: on a cold host the default preset's `tool-bash` read as "conditional" and its host row fell back to plain "disabled" until the first session mounted the preset. diff --git a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md index 7804203350..d71ddf2dc0 100644 --- a/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-29-plugin-inventory-agent-preset-scopes.zh.md @@ -12,15 +12,15 @@ **清单同时陈述两个平面。**`pluginInventory/list` 增加可选的 `agentPresets` 块——每个名单预设一组，含 id、显示名、默认标记、健康状态与压平的组合行——由新增的 `AgentPresets.compositionInventory()` 提供：已有存活 standing mount 的预设由其最新世代的 Loader 条目作答，开机以来从未被组合的预设由其组合文件作答。`dsh-host-plugin-inventory` 经 `ctx.get('agentPresets')` 把名单当作可选伙伴解析（即 `plugin-package-inventory-deepseek` 的模式），自己只把根 Fiber 状态映射到公共阶段词汇，因此没有名单的部署继续只提供 Loader 条目、字段缺席。 -**文件答案靠求值而非猜测，且读取从不挂载。**`!!js` disabled 门是平台/环境条件，[Loader 自己在每次挂载决策时都会求值](2026-08-11-loader-entry-disabled-interpolation.zh.md)，因此文件读取用 Loader 上下文对它们求值，报告本机挂载会做出的决定；求值器拒绝的门保持 `'conditional'` 并携带表达式文本供展示。该读取只解析和求值——不 import、不组合——所以列出所有预设的插件不会激活其中任何一个，回归测试钉住完整清单读取后 `livePresetMounts()` 为空。 +**文件答案靠求值而非猜测，且读取从不挂载。**`!!js` disabled 门是平台/环境条件，[Loader 自己在每次挂载决策时都会求值](2026-08-11-loader-entry-disabled-interpolation.zh.md)，因此文件读取用 Loader 上下文对它们求值，报告本机挂载会做出的决定；求值器拒绝的门保持 `'conditional'` 并携带表达式文本供展示。该读取只解析和求值——不 import、不组合——所以列出所有预设的插件不会激活其中任何一个，回归测试钉住完整清单读取后 `livePresetMounts()` 为空。搭这个表面还暴露了反向泄漏：`EntryTree` 的构造器把每棵新树挂到最近拥有者 Loader 条目的 `subtree` 槽上，于是第一个 standing mount 把整棵预设组合挂在了 roster 自己的行下，根 `loader.entries()` 把它当宿主条目走了一遍。`PresetTree` 现在归还该槽位，恢复 standing mount「不在 Loader 里」的书面契约；回归测试钉住挂载前后根条目列表逐项相同。 -**列表按作用域分组，误导行获得自己的状态。**预设组在前，其切换器只改显示、初始停在默认预设且不写任何设置——查看 `minimal` 绝不能改变新会话运行什么。全局组随后且默认收起，失败行浮在最前；一个全局停用、而同一模块标识至少有一个预设行实际启用的条目，收进"会话插件"抽屉并列出提供它的预设——用第三种状态取代引发这一切的笼统"已停用"。提供者规则严格取 `enabled === true`：把条件声明也算作提供者，会替 `tool-pwsh` 在 POSIX 上宣称一个它从不兑现的按会话提供。搜索横跨两组、强制撑开折叠，并指出未选中预设里的匹配。 +**列表按作用域分组，误导行获得自己的状态。**预设组在前、可折叠且默认展开，其切换器是通用设置同款的「选择胶囊 + 菜单」控件，只改显示、初始停在默认预设且不写任何设置——查看 `minimal` 绝不能改变新会话运行什么。全局组随后且默认收起，失败行浮在最前；一个全局停用、而同一模块标识至少有一个预设行实际启用的条目，就地标记为预设提供并在详情里列出启用它的预设——用第三种状态取代引发这一切的笼统"已停用"，并且刻意不做成子分组：上方的预设组已经把这些插件按组合展示，一个复述它们的第二个聚簇理应被移除。状态圆点只为存活的根 fiber 渲染——文件态的行只带启停标签，未挂载的预设不会读作一列灰色的谜之圆点。提供者规则严格取 `enabled === true`：把条件声明也算作提供者，会替 `tool-pwsh` 在 POSIX 上宣称一个它从不兑现的按会话提供。搜索横跨两组、强制撑开分组，并指出未选中预设里的匹配。 **通用设置行是删除，不是搬家。**默认值保留两个仍能作用于它的表面——名单分区的设为默认（名单可见）与新会话 chip（针对即将开始的会话）——因此 `ui-agent-preset` 删掉该行、它的菜单以及 settings store 的写入/可写性半边，后者收敛为标题标签读取的展示名单 store。 ## 考虑过的替代方案 -**把每个预设都渲染成常开分节。**四个内置预设已把约 100 行压到折叠线以下；切换器保持一次一个组合可见，抽屉的提供者列表与搜索指引保留了全展开布局想买到的跨作用域答案。 +**把每个预设都渲染成常开分节。**四个内置预设已把约 100 行压到折叠线以下；切换器保持一次一个组合可见，行级的提供者详情与搜索指引保留了全展开布局想买到的跨作用域答案。 **文件态门保持不求值（首次挂载前一律 `conditional`）。**诚实，但重演了本次要消除的误导：冷启动的宿主上，默认预设的 `tool-bash` 读作"条件启用"，其全局行在第一个会话挂载预设之前退回单纯的"已停用"。 diff --git a/apps/web/tests/settings-chrome.e2e.ts b/apps/web/tests/settings-chrome.e2e.ts index 4a8fe18989..648bb9c260 100644 --- a/apps/web/tests/settings-chrome.e2e.ts +++ b/apps/web/tests/settings-chrome.e2e.ts @@ -103,19 +103,18 @@ describe('web e2e: settings modal and General preferences', () => { await dialog.getByRole('heading', { name: '插件', exact: true }).waitFor({ timeout: 10_000 }) await dialog.getByRole('tab', { name: '插件列表', exact: true }).click() // The preset group opens first with its display-only switcher; the global - // plane starts collapsed and expands on demand, session plugins deeper still. - const presetSwitcher = dialog.getByRole('combobox', { name: '选择要查看的 Agent 预设' }) + // plane starts collapsed and expands on demand. + const presetSwitcher = dialog.getByRole('button', { name: '选择要查看的 Agent 预设' }) await presetSwitcher.waitFor({ timeout: 10_000 }) await dialog.getByRole('button', { name: /^全局/ }).click() const pluginRow = dialog.locator(PLUGIN_ROW_SELECTOR) await pluginRow.waitFor({ timeout: 10_000 }) - await dialog.getByRole('button', { name: /^会话插件/ }).click() const expectedPluginCount = [...scaffold.ctx.loader.entries()] .filter(entry => !entry.options.group) .length expect(await dialog.getByRole('searchbox', { name: '搜索插件' }).count()).toBe(1) - // Every Loader entry appears exactly once in the global group — the - // session-plugin drawer included, preset compositions excluded. + // Every Loader entry appears exactly once in the global group — rows the + // presets took over included, preset compositions excluded. expect(await dialog.locator('[data-plugin-scope="global"] [data-plugin-entry]').count()) .toBe(expectedPluginCount) expect(await dialog.locator('[data-plugin-count]').getAttribute('data-plugin-count')) diff --git a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml b/packages/client/ui-settings-plugin-inventory/README.i18n.yaml index f1a56b6c18..0047cf9e07 100644 --- a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml +++ b/packages/client/ui-settings-plugin-inventory/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-plugin-inventory/README.md -README.md: bc89b60e89e0fe257c6f422a2749bd4188fe796c -README.zh.md: 13c09aaeb108120ba22f05d9828da75088a7deb8 +README.md: 718139cc135b8213ea2f3d1aec384f550b57a641 +README.zh.md: 7ebb7d75e6ebd285010a72f175c02ab7c2e802fd diff --git a/packages/client/ui-settings-plugin-inventory/README.md b/packages/client/ui-settings-plugin-inventory/README.md index bc89b60e89..718139cc13 100644 --- a/packages/client/ui-settings-plugin-inventory/README.md +++ b/packages/client/ui-settings-plugin-inventory/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-client-ui-settings-plugin-inventory` contributes the read-only **Plugin list** tab to the Web Settings Plugins section. The tab lazily calls `ctx.remote.pluginInventory.list()` the first time it is selected and renders the inventory in two groups. The agent-preset group comes first: a display-only switcher over the roster opens on the default preset, and each composition row is a compact disclosure card carrying its enablement — including `conditional` for a disabled gate only a mount can decide — with provenance facts behind the disclosure. The global group follows collapsed, its header carrying the entry count and a failure count; expanded, failures float first, and entries disabled globally but enabled by presets fold into a session-plugins drawer naming their providers instead of reading as plainly disabled. Search filters both groups, forces the collapsed disclosures open, and points at matches sitting in unselected presets. Loading, empty, no-match, and generic failure states stay local to the mounted component, and a failed read can be retried without exposing transport details; without a roster the tab renders the global plane alone, expanded. +`dsh-client-ui-settings-plugin-inventory` contributes the read-only **Plugin list** tab to the Web Settings Plugins section. The tab lazily calls `ctx.remote.pluginInventory.list()` the first time it is selected and renders the inventory in two collapsible groups. The agent-preset group comes first, open by default: a display-only switcher pill over the roster opens on the default preset, and each composition row is a compact disclosure card carrying its enablement — including `conditional` for a disabled gate the Host could not evaluate — with provenance facts behind the disclosure. The global group follows collapsed, its header carrying the entry count and a failure count; expanded, failures float first, and an entry disabled globally but enabled by at least one preset is marked as preset-provided in place — its details name the enabling presets — instead of reading as plainly disabled. Search filters both groups, forces the collapsed groups open, and points at matches sitting in unselected presets. Loading, empty, no-match, and generic failure states stay local to the mounted component, and a failed read can be retried without exposing transport details; without a roster the tab renders the global plane alone, expanded. ## Table of Contents @@ -29,11 +29,11 @@ Open the Plugins section in Settings and select the **Plugin list** tab to inspe ### Reading a card -Each collapsed card uses the short module name as its title and a small enablement tag; enabled entries also show a colored root-fiber status dot. Expanding one card reveals the declared entry id, the full module specifier, and the state facts: a preset row names the preset it comes from, its runtime status when the composition is live, and its enable condition when it carries one; a session-plugins drawer row explains that agent presets provide it per session, names the presets that enable it, and offers a jump into the preset group. Search filters both groups by module name and entry id. +Each collapsed card uses the short module name as its title and a small enablement tag; enabled entries also show a colored root-fiber status dot. Expanding one card reveals the declared entry id, the full module specifier, and the state facts: a preset row names the preset it comes from, its runtime status when the composition is live, and its enable condition when it carries one; a preset-provided global row explains that agent presets provide it per session, names the presets that enable it, and offers a jump into the preset group. Search filters both groups by module name and entry id. ### The preset switcher -The switcher lists every roster preset — the default suffixed as such, broken ones marked — and changes only what the list shows: it writes no settings, and selecting a broken preset shows the discovery-reported reason in place of rows. Choosing the default preset or a session's preset stays where it was: the Agent presets section and the new-session screen. +The switcher is the same selector-pill-plus-menu control the General settings rows use. It lists every roster preset — the default suffixed as such, broken ones marked — and changes only what the list shows: it writes no settings, and selecting a broken preset shows the discovery-reported reason in place of rows. Choosing the default preset or a session's preset stays where it was: the Agent presets section and the new-session screen. ### Retrying a failed read @@ -55,7 +55,7 @@ The browser plugin registers one localized `settings.plugins.tab` contribution w ### Rendering -Row keys are scope-qualified (`global:`, `drawer:`, `preset::`), so one module appearing in several scopes keeps distinct disclosure state; an entry id is shown as detail only when the row declares one and is never classified by string shape. The session-plugins drawer is derived client-side: a global entry joins it when it is disabled there while at least one preset row for the same module specifier is actually enabled, so a module every preset gates off (or declares only conditionally) stays plainly disabled rather than over-claiming provision. +Row keys are scope-qualified (`global:`, `preset::`), so one module appearing in both scopes keeps distinct disclosure state; an entry id is shown as detail only when the row declares one and is never classified by string shape. The preset-provided marking is derived client-side: a global entry carries it when it is disabled there while at least one preset row for the same module specifier is actually enabled, so a module every preset gates off (or declares only conditionally) stays plainly disabled rather than over-claiming provision. diff --git a/packages/client/ui-settings-plugin-inventory/README.zh.md b/packages/client/ui-settings-plugin-inventory/README.zh.md index 13c09aaeb1..7ebb7d75e6 100644 --- a/packages/client/ui-settings-plugin-inventory/README.zh.md +++ b/packages/client/ui-settings-plugin-inventory/README.zh.md @@ -9,7 +9,7 @@ kind: "package-reference" ## 概述 -`dsh-client-ui-settings-plugin-inventory` 向 Web 设置的「插件」分区贡献只读的**插件列表**标签页。该标签页在首次被选择时懒调用 `ctx.remote.pluginInventory.list()`，并把清单分成两组渲染。Agent 预设组在前：一个只改显示的切换器覆盖 roster、初始停在默认预设，每个组合行是一张紧凑折叠卡片，携带其启停状态——含只有挂载才能裁决的 disabled 门对应的 `conditional`——出处事实收在折叠里。全局组随后且默认收起，组头带条目计数与失败计数；展开后失败行浮在最前，全局停用但被预设启用的条目收进「会话插件」抽屉并列出提供它的预设，而不是读作单纯的已停用。搜索同时过滤两组、强制撑开收起的折叠，并指出未选中预设里的匹配。加载、空结果、无匹配与通用失败状态只属于已挂载组件，读取失败后可以重试，且不会暴露传输细节；没有 roster 时标签页只渲染全局平面并保持展开。 +`dsh-client-ui-settings-plugin-inventory` 向 Web 设置的「插件」分区贡献只读的**插件列表**标签页。该标签页在首次被选择时懒调用 `ctx.remote.pluginInventory.list()`，并把清单分成两个可折叠分组渲染。Agent 预设组在前、默认展开：一个只改显示的切换器胶囊覆盖 roster、初始停在默认预设，每个组合行是一张紧凑折叠卡片，携带其启停状态——含宿主无法求值的 disabled 门对应的 `conditional`——出处事实收在折叠里。全局组随后且默认收起，组头带条目计数与失败计数；展开后失败行浮在最前，全局停用但被至少一个预设启用的条目就地标记为预设提供——详情列出启用它的预设——而不是读作单纯的已停用。搜索同时过滤两组、强制撑开收起的分组，并指出未选中预设里的匹配。加载、空结果、无匹配与通用失败状态只属于已挂载组件，读取失败后可以重试，且不会暴露传输细节；没有 roster 时标签页只渲染全局平面并保持展开。 ## 目录 @@ -29,11 +29,11 @@ kind: "package-reference" ### 阅读卡片 -每张收起的卡片使用模块短名称作为标题，并以小标签表示启停状态；已启用的条目还会显示彩色根 fiber 状态圆点。展开卡片后会显示声明的条目 id、完整模块标识与状态事实：预设行说明它来自哪个预设、组合存活时的运行状态，以及它携带的启用条件；「会话插件」抽屉行说明它由 Agent 预设按会话提供、列出启用它的预设，并提供跳转到预设组的入口。搜索按模块名称与条目 id 过滤两组。 +每张收起的卡片使用模块短名称作为标题，并以小标签表示启停状态；已启用的条目还会显示彩色根 fiber 状态圆点。展开卡片后会显示声明的条目 id、完整模块标识与状态事实：预设行说明它来自哪个预设、组合存活时的运行状态，以及它携带的启用条件；被预设提供的全局行说明它由 Agent 预设按会话提供、列出启用它的预设，并提供跳转到预设组的入口。搜索按模块名称与条目 id 过滤两组。 ### 预设切换器 -切换器列出 roster 的每个预设——默认项带后缀、坏预设带标记——并且只改变列表显示什么：它不写任何设置，选中坏预设时在行的位置展示 discovery 报告的原因。选默认预设或某个会话的预设仍在原处：Agent 预设分区与新会话页。 +切换器与通用设置各行使用同一种「选择胶囊 + 菜单」控件。它列出 roster 的每个预设——默认项带后缀、坏预设带标记——并且只改变列表显示什么：它不写任何设置，选中坏预设时在行的位置展示 discovery 报告的原因。选默认预设或某个会话的预设仍在原处：Agent 预设分区与新会话页。 ### 重试失败的读取 @@ -55,7 +55,7 @@ kind: "package-reference" ### 渲染 -行 key 按作用域限定（`global:`、`drawer:`、`preset::`），因此同一模块出现在多个作用域时保持各自的展开状态；条目 id 只在行声明了它时作为详情展示，代码不按字符串形状对它分类。「会话插件」抽屉在客户端推导：一个全局条目在全局被停用、且至少一个预设行对同一模块标识实际启用时才归入抽屉，因此被所有预设关掉（或仅条件声明）的模块保持单纯的已停用，而不是夸大提供关系。 +行 key 按作用域限定（`global:`、`preset::`），因此同一模块出现在两个作用域时保持各自的展开状态；条目 id 只在行声明了它时作为详情展示，代码不按字符串形状对它分类。预设提供标记在客户端推导：一个全局条目在全局被停用、且至少一个预设行对同一模块标识实际启用时才携带它，因此被所有预设关掉（或仅条件声明）的模块保持单纯的已停用，而不是夸大提供关系。 diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css index 41c2d7ef59..60673d222f 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css @@ -292,36 +292,59 @@ line-height: 18px; } +/* The preset switcher trigger mirrors the General-settings selector pill. */ .switcher { - max-width: 60%; - border: 1px solid var(--dsw-alias-border-l2); - border-radius: 8px; - padding: 3px 8px; - background: var(--dsw-alias-bg-layer-1); + display: inline-flex; + flex: none; + align-items: center; + gap: 10px; + height: 30px; + white-space: nowrap; + border: none; + border-radius: 15px; + padding: 0 12px; + background: var(--dsw-alias-bg-module-platform); color: var(--dsw-alias-label-primary); font: inherit; font-size: 13px; + line-height: 20px; font-weight: 600; + cursor: pointer; } -.badge { +.switcher:hover { + background: var(--dsw-alias-interactive-bg-hover); +} + +.switcher:focus-visible { + outline: 2px solid var(--dsw-alias-state-business-primary); + outline-offset: 2px; +} + +.switcher > .chevron { flex: none; - border-radius: 999px; - padding: 1px 8px; - font-size: 11px; - line-height: 16px; } -.badge[data-kind='default'] { - background: var(--dsw-alias-label-primary); - color: var(--dsw-alias-bg-layer-3); +.switcherLabel { + max-width: 240px; + overflow: hidden; + text-overflow: ellipsis; } -.badge[data-kind='broken'] { - background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent); - color: var(--dsw-alias-state-error-primary); +.iconToggle { + flex: none; + width: auto; + min-height: 0; + padding: 4px; } +.groupBody { + display: flex; + flex-direction: column; + gap: 10px; +} + + .brokenNote { margin: 0; border-radius: 8px; @@ -355,15 +378,6 @@ cursor: pointer; } -.drawer { - display: flex; - flex-direction: column; - gap: 10px; - margin-top: 10px; - border: 1px dashed var(--dsw-alias-border-l1); - border-radius: 10px; - padding: 8px 10px 10px; -} .enabledIn { display: flex; diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx index 7726a9b1ab..e56cbfdef8 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx @@ -3,6 +3,7 @@ import type { PluginInventorySnapshot } from '@deepseek-ai/dsh-api-remotes/clien import { IconChevronDownOutline14, IconSearchOutline16, + Menu, } from '@deepseek-ai/dsh-client-ui-primitives' import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots' import type { PluginInventoryLocaleKey } from './locales.ts' @@ -141,13 +142,13 @@ function CardFacts({ moduleName, moduleLabel, entryId, facts }: { ) } -/** Status dot naming the root-fiber phase. */ -function PhaseDot({ phase, t }: { readonly phase: PluginFiberPhase; readonly t: Translate }): ReactNode { +/** Status dot naming a live root-fiber phase; rows with no live fiber show none. */ +function PhaseDot({ phase, t }: { readonly phase: NonNullable; readonly t: Translate }): ReactNode { const status = phaseLabel(phase, t) return ( (null) const [chosenPreset, setChosenPreset] = useState(null) + const [switcherOpen, setSwitcherOpen] = useState(false) + const [presetOpen, setPresetOpen] = useState(null) const [globalOpen, setGlobalOpen] = useState(null) - const [drawerOpen, setDrawerOpen] = useState(false) const [state, setState] = useState({ status: 'loading' }) useEffect(() => { @@ -202,21 +204,17 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT const entries = snapshot?.entries ?? [] const failedEntries: PluginInventoryEntry[] = [] - const drawerEntries: { entry: PluginInventoryEntry; providers: readonly [AgentPresetGroup, ...AgentPresetGroup[]] }[] = [] const regularEntries: PluginInventoryEntry[] = [] for (const entry of entries) { - const providers = enabledIn.get(entry.moduleName) if (entry.fiberPhase === 'failed') failedEntries.push(entry) - else if (!entry.enabled && providers !== undefined) drawerEntries.push({ entry, providers }) else regularEntries.push(entry) } const entryMatch = (entry: PluginInventoryEntry): boolean => matches(entry.moduleName, entry.entryId, normalizedQuery) const rowMatch = (row: AgentPresetRow): boolean => matches(row.moduleName, row.entryId, normalizedQuery) const filteredFailed = failedEntries.filter(entryMatch) - const filteredDrawer = drawerEntries.filter(drawerRow => entryMatch(drawerRow.entry)) const filteredRegular = regularEntries.filter(entryMatch) - const globalCount = filteredFailed.length + filteredDrawer.length + filteredRegular.length + const globalCount = filteredFailed.length + filteredRegular.length const selectedRows = selected === undefined ? [] : selected.rows.filter(rowMatch) const otherPresetMatches = searching ? presets.filter(preset => preset !== selected && preset.rows.some(rowMatch)) @@ -224,8 +222,8 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT const otherMatchCount = otherPresetMatches .reduce((total, preset) => total + preset.rows.filter(rowMatch).length, 0) + const presetEffectiveOpen = searching || (presetOpen ?? true) const globalEffectiveOpen = searching || (globalOpen ?? presets.length === 0) - const drawerEffectiveOpen = searching || drawerOpen const nothingMatches = searching && globalCount === 0 && selectedRows.length === 0 && otherPresetMatches.length === 0 @@ -258,7 +256,9 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT ariaLabel={`${title}, ${stateText}`} trailing={( <> - {row.enabled === true && !failed ? : null} + {row.enabled === true && !failed && row.fiberPhase !== null + ? + : null} )} @@ -278,12 +278,12 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT ) } - /** One global-plane row; a drawer row carries the presets that enable it. */ + /** One global-plane row; a preset-provided row carries the presets that enable it. */ const globalRowCard = ( entry: PluginInventoryEntry, providers?: readonly [AgentPresetGroup, ...AgentPresetGroup[]], ): ReactNode => { - const key = `${providers === undefined ? 'global' : 'drawer'}:${entry.entryId}` + const key = `global:${entry.entryId}` const title = moduleShortName(entry.moduleName) const failed = entry.fiberPhase === 'failed' const stateText = failed @@ -302,7 +302,9 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT ariaLabel={`${title}, ${stateText}`} trailing={( <> - {entry.enabled && !failed ? : null} + {entry.enabled && !failed && entry.fiberPhase !== null + ? + : null} )} @@ -313,7 +315,7 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT entryId={entry.entryId} facts={providers !== undefined ? [ - [t('configuration'), t('drawerDetail')], + [t('configuration'), t('presetProvidedDetail')], [t('enabledIn'), ( {providers.map(preset => preset.name ?? preset.id).join(' · ')} @@ -364,43 +366,71 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT {selected !== undefined ? (
    - +
    - {selected.broken !== undefined ? ( -

    {selected.broken}

    - ) : null} - {selectedRows.length > 0 ? ( -
      - {selectedRows.map((row, index) => presetRowCard(selected, row, index))} -
    - ) : null} - {otherMatchCount > 0 ? ( -

    - {t('matchesInOtherPresets', { count: String(otherMatchCount) })} - {otherPresetMatches.map(preset => ( - - ))} -

    + {presetEffectiveOpen ? ( +
    + {selected.broken !== undefined ? ( +

    {selected.broken}

    + ) : null} + {selectedRows.length > 0 ? ( +
      + {selectedRows.map((row, index) => presetRowCard(selected, row, index))} +
    + ) : null} + {otherMatchCount > 0 ? ( +

    + {t('matchesInOtherPresets', { count: String(otherMatchCount) })} + {otherPresetMatches.map(preset => ( + + ))} +

    + ) : null} +
    ) : null}
    ) : null} @@ -422,36 +452,14 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT {filteredFailed.length} {t('failedCountLabel')} ) : null} - {globalEffectiveOpen ? ( -
    - {filteredFailed.length + filteredRegular.length > 0 ? ( -
      - {filteredFailed.map(entry => globalRowCard(entry))} - {filteredRegular.map(entry => globalRowCard(entry))} -
    - ) : null} - {drawerEntries.length > 0 ? ( -
    - - {drawerEffectiveOpen && filteredDrawer.length > 0 ? ( -
      - {filteredDrawer.map(drawerRow => globalRowCard(drawerRow.entry, drawerRow.providers))} -
    - ) : null} -
    - ) : null} -
    + {globalEffectiveOpen && globalCount > 0 ? ( +
      + {filteredFailed.map(entry => globalRowCard(entry))} + {filteredRegular.map(entry => globalRowCard( + entry, + entry.enabled ? undefined : enabledIn.get(entry.moduleName), + ))} +
    ) : null} ) : null} diff --git a/packages/client/ui-settings-plugin-inventory/src/client/locales.ts b/packages/client/ui-settings-plugin-inventory/src/client/locales.ts index 3857204a93..8bad8a698e 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/locales.ts +++ b/packages/client/ui-settings-plugin-inventory/src/client/locales.ts @@ -15,9 +15,7 @@ export const zh = { presetOptionBroken: '{name}（加载失败）', globalTitle: '全局', globalSubtitle: '系统与所有会话共用', - drawerTitle: '会话插件', - drawerSubtitle: '不在全局运行，由 Agent 预设按会话提供', - drawerDetail: '全局已停用，由 Agent 预设按会话提供', + presetProvidedDetail: '全局已停用，由 Agent 预设按会话提供', enabledIn: '启用于', viewInPreset: '去预设分组查看', matchesInOtherPresets: '其他预设中还有 {count} 个匹配：', @@ -58,9 +56,7 @@ export const en = { presetOptionBroken: '{name} (failed to load)', globalTitle: 'Global', globalSubtitle: 'Shared by the system and every session', - drawerTitle: 'Session plugins', - drawerSubtitle: 'Not running globally; agent presets provide them per session', - drawerDetail: 'Disabled globally; agent presets provide it per session', + presetProvidedDetail: 'Disabled globally; agent presets provide it per session', enabledIn: 'Enabled in', viewInPreset: 'View in the preset group', matchesInOtherPresets: '{count} more matches in other presets: ', diff --git a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx index 3310d87e6d..6a3702d7ae 100644 --- a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx +++ b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx @@ -76,20 +76,21 @@ async function renderReady(snapshot: Snapshot = SNAPSHOT): Promise screen.getByRole('button', { name: (name: string) => name.startsWith(en.globalTitle) }) -const drawerToggle = (): HTMLElement => - screen.getByRole('button', { name: (name: string) => name.startsWith(en.drawerTitle) }) describe('PluginInventorySettingsTab', () => { it('shows the default preset first and keeps the global plane collapsed', async () => { const view = await renderReady() - const switcher = screen.getByRole('combobox', { name: en.switcherLabel }) - expect((switcher as HTMLSelectElement).value).toBe('standard') - expect(screen.getAllByRole('option').map(option => option.textContent)).toEqual([ + const switcher = screen.getByRole('button', { name: en.switcherLabel }) + expect(switcher.textContent).toBe('标准模式 (default)') + fireEvent.click(switcher) + expect(screen.getAllByRole('menuitem').map(item => item.textContent)).toEqual([ '标准模式 (default)', 'ptc', '坏预设 (failed to load)', ]) + fireEvent.keyDown(document, { key: 'Escape' }) + expect(screen.queryAllByRole('menuitem')).toHaveLength(0) expect(screen.getByText(en.presetSubtitle)).toBeTruthy() expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('6') @@ -100,7 +101,8 @@ describe('PluginInventorySettingsTab', () => { expect(screen.getByText(en.disabledTag)).toBeTruthy() expect(screen.getByText(en.failedTag)).toBeTruthy() expect(screen.getByRole('img', { name: 'Running' })).toBeTruthy() - expect(screen.getAllByRole('img', { name: 'Not running' })).toHaveLength(2) + // No live fiber, no dot: file-state rows carry only their enablement tag. + expect(screen.queryByRole('img', { name: 'Not running' })).toBeNull() expect(globalToggle().getAttribute('aria-expanded')).toBe('false') expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('7') @@ -126,9 +128,10 @@ describe('PluginInventorySettingsTab', () => { expect(screen.getByText(en.moduleLabel).nextElementSibling?.textContent).toBe('@fixture/anonymous') }) - it('expands the global plane with failures first and the session-plugin drawer', async () => { + it('expands the global plane with failures first and preset-provided rows inline', async () => { const view = await renderReady() + expect(screen.queryByText(en.presetEnabledTag)).toBeNull() fireEvent.click(globalToggle()) expect(globalToggle().getAttribute('aria-expanded')).toBe('true') const failed = view.container.querySelector('[data-plugin-scope="global"] [data-failed="true"]') @@ -136,14 +139,11 @@ describe('PluginInventorySettingsTab', () => { // Failures float above the Loader-ordered remainder. expect(view.container.querySelector('[data-plugin-scope="global"] li')).toBe(failed) - // The drawer stays collapsed until opened, then names its providers. - expect(drawerToggle().getAttribute('aria-expanded')).toBe('false') - expect(screen.queryByText(en.presetEnabledTag)).toBeNull() - fireEvent.click(drawerToggle()) + // Rows the presets took over sit inline, marked instead of plainly disabled. expect(screen.getAllByText(en.presetEnabledTag)).toHaveLength(2) fireEvent.click(screen.getByRole('button', { name: 'tool-bash, Enabled via presets' })) - expect(screen.getByText(en.drawerDetail)).toBeTruthy() + expect(screen.getByText(en.presetProvidedDetail)).toBeTruthy() expect(screen.getByText(en.enabledIn)).toBeTruthy() expect(screen.getByText('标准模式 · ptc')).toBeTruthy() @@ -151,41 +151,68 @@ describe('PluginInventorySettingsTab', () => { fireEvent.click(screen.getByRole('button', { name: 'telemetry, Failed' })) expect(screen.getByText('Failed to start')).toBeTruthy() + // An enabled entry with no live fiber says so in its details, dot-free. + fireEvent.click(screen.getByRole('button', { name: 'unobserved-name, Enabled' })) + expect(screen.getByText('Not running')).toBeTruthy() + // A disabled row outside every preset stays plainly disabled. fireEvent.click(screen.getByRole('button', { name: 'dormant, Disabled' })) - expect(screen.queryByText(en.drawerDetail)).toBeNull() + expect(screen.queryByText(en.presetProvidedDetail)).toBeNull() - fireEvent.click(drawerToggle()) - expect(screen.queryByText(en.presetEnabledTag)).toBeNull() fireEvent.click(globalToggle()) expect(globalToggle().getAttribute('aria-expanded')).toBe('false') + expect(screen.queryByText(en.presetEnabledTag)).toBeNull() }) it('switches the inspected preset in place, including broken ones', async () => { const view = await renderReady() - const switcher = screen.getByRole('combobox', { name: en.switcherLabel }) + const pickPreset = (label: string): void => { + fireEvent.click(screen.getByRole('button', { name: en.switcherLabel })) + fireEvent.click(screen.getByRole('menuitem', { name: label })) + } - fireEvent.change(switcher, { target: { value: 'ptc' } }) + pickPreset('ptc') expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('3') fireEvent.click(screen.getAllByRole('button', { name: 'tool-bash, Enabled' })[0]!) // An unnamed preset labels provenance by its id. expect(screen.getByText(en.fromPreset).nextElementSibling?.textContent).toBe('ptc') - fireEvent.change(switcher, { target: { value: 'shattered' } }) + pickPreset('坏预设 (failed to load)') expect(screen.getByRole('alert').textContent).toBe('the composition file is missing') expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('0') }) - it('jumps from a drawer row to the preset that enables it', async () => { + it('collapses the preset group until a search forces it open', async () => { + const view = await renderReady() + const toggle = screen.getByRole('button', { name: en.presetSubtitle }) + + expect(toggle.getAttribute('aria-expanded')).toBe('true') + fireEvent.click(toggle) + expect(toggle.getAttribute('aria-expanded')).toBe('false') + // The header keeps its count while the rows are folded away. + expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('6') + expect(view.container.querySelectorAll('[data-plugin-scope="preset"] li')).toHaveLength(0) + + fireEvent.change(screen.getByRole('searchbox', { name: en.search }), { target: { value: 'pwsh' } }) + expect(toggle.getAttribute('aria-expanded')).toBe('true') + expect(screen.getByText(en.conditionalTag)).toBeTruthy() + + fireEvent.change(screen.getByRole('searchbox', { name: en.search }), { target: { value: '' } }) + expect(toggle.getAttribute('aria-expanded')).toBe('false') + fireEvent.click(toggle) + expect(toggle.getAttribute('aria-expanded')).toBe('true') + }) + + it('jumps from a preset-provided row to the preset that enables it', async () => { await renderReady() - const switcher = screen.getByRole('combobox', { name: en.switcherLabel }) - fireEvent.change(switcher, { target: { value: 'ptc' } }) + fireEvent.click(screen.getByRole('button', { name: en.switcherLabel })) + fireEvent.click(screen.getByRole('menuitem', { name: 'ptc' })) fireEvent.click(globalToggle()) - fireEvent.click(drawerToggle()) fireEvent.click(screen.getByRole('button', { name: 'tool-bash, Enabled via presets' })) fireEvent.click(screen.getByRole('button', { name: en.viewInPreset })) - expect((switcher as HTMLSelectElement).value).toBe('standard') + expect(screen.getByRole('button', { name: en.switcherLabel }).textContent) + .toBe('标准模式 (default)') }) it('searches across scopes and points at matches in other presets', async () => { @@ -201,7 +228,7 @@ describe('PluginInventorySettingsTab', () => { const hint = screen.getByText((text: string) => text.startsWith('2 more matches')) expect(hint).toBeTruthy() fireEvent.click(screen.getByRole('button', { name: 'ptc' })) - expect(screen.getByRole('combobox', { name: en.switcherLabel }).value).toBe('ptc') + expect(screen.getByRole('button', { name: en.switcherLabel }).textContent).toBe('ptc') // A match visible only in another preset keeps the pointer without rows. fireEvent.change(search, { target: { value: 'crashy' } }) @@ -227,7 +254,7 @@ describe('PluginInventorySettingsTab', () => { ], } as unknown as Snapshot) - expect(screen.queryByRole('combobox', { name: en.switcherLabel })).toBeNull() + expect(screen.queryByRole('button', { name: en.switcherLabel })).toBeNull() expect(globalToggle().getAttribute('aria-expanded')).toBe('true') expect(screen.getAllByRole('listitem')).toHaveLength(2) diff --git a/packages/preset/agent-presets/src/mount.ts b/packages/preset/agent-presets/src/mount.ts index d9a92d6a27..b1514b3495 100644 --- a/packages/preset/agent-presets/src/mount.ts +++ b/packages/preset/agent-presets/src/mount.ts @@ -57,6 +57,14 @@ const harnessBase = new WeakMap() class PresetTree extends Include { constructor(ctx: Context, config: Include.Config) { super(ctx, config) + // EntryTree's constructor files every new tree under the nearest owning + // Loader entry's `subtree` slot — here the roster's own row, because the + // standing scope descends from the roster's fiber. Left in place, root + // `loader.entries()` would walk this composition as host entries (each + // preset overwriting the last), against the standing mount's contract of + // not being a Loader entry. Reclaim the slot. + const owner = this.ctx.fiber.entry + if (owner?.subtree === this) delete owner.subtree mounted.set(config, { tree: this, fiber: ctx.fiber }) } diff --git a/packages/preset/agent-presets/tests/composition-inventory.spec.ts b/packages/preset/agent-presets/tests/composition-inventory.spec.ts index 8240ce557f..2fcf872fc2 100644 --- a/packages/preset/agent-presets/tests/composition-inventory.spec.ts +++ b/packages/preset/agent-presets/tests/composition-inventory.spec.ts @@ -289,6 +289,38 @@ describe('AgentPresets.compositionInventory', () => { expect(damaged?.broken).toContain('is missing') }) + it('keeps a standing composition out of the root Loader entries', async () => { + const ctx = new Context() + contexts.push(ctx) + ctx.baseUrl = pathToFileURL(FIXTURES).href + '/' + await ctx.plugin(Loader) + ctx.loader.builtins.include = Include + ctx.loader.builtins['agent-presets'] = AgentPresets + await ctx.plugin(LlmRuntime) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: '' }) + await ctx.plugin(ToolRuntime) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + // The roster itself loads as a Loader entry, the way profiles mount it: + // the standing scope then descends from a fiber that OWNS an entry, which + // is exactly the shape that made EntryTree file the mount under it. + await ctx.loader.create({ + name: 'cordis:agent-presets', + config: { default: 'standard', roots: [SYSTEM_ROOT], includeShippedRoot: false, includeUserRoot: false }, + }) + const before = [...ctx.loader.entries()].map(entry => entry.id) + + await ctx.agents.create({ + sessionId: SessionId('loader-entry-guard'), + setup: async (agentCtx: Context) => void await ctx.agentPresets.mount(agentCtx, 'standard'), + }) + + // The agent joined a standing composition without the composition + // becoming host Loader entries. + expect([...ctx.loader.entries()].map(entry => entry.id)).toEqual(before) + }) + it('reports a composition that raced discovery as broken instead of dropping it', async () => { const ctx = await harness({ default: 'minimal', From 0f06f973c411c99bc391afdb7bdff20b057c441d Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 17:13:45 +0800 Subject: [PATCH 40/63] refactor(plugin-inventory): settings-row style group headers Both scope groups drop their boxed chrome for the General-settings row idiom: a title row (session-plugins title with the right-aligned preset selector pill; global-plugins title), a grey subtitle line carrying the count, a hairline divider between groups, and the cards grid below. Counts ride the subtitle as text while the data attributes keep the raw numbers for tests. --- .../PluginInventorySettingsTab.module.css | 54 +++++------ .../src/client/PluginInventorySettingsTab.tsx | 95 ++++++++++--------- .../src/client/locales.ts | 12 ++- .../tests/components.client.spec.tsx | 20 ++-- 4 files changed, 94 insertions(+), 87 deletions(-) diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css index 60673d222f..fa312a68fa 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css @@ -225,21 +225,29 @@ display: flex; flex-direction: column; gap: 10px; - border: 1px solid var(--dsw-alias-border-l2); - border-radius: 12px; - padding: 10px 12px 12px; } -.groupHeader, -.groupToggle { +.groupTitleRow { display: flex; align-items: center; gap: 8px; - min-height: 28px; + min-height: 32px; +} + +.group + .group { + border-top: 1px solid var(--dsw-alias-border-l2); + padding-top: 14px; +} + +.headerEnd { + margin-left: auto; } .groupToggle { - width: 100%; + display: flex; + flex: none; + align-items: center; + gap: 8px; border: 0; padding: 0; background: transparent; @@ -263,22 +271,17 @@ } .groupTitle { - font-size: 13px; - line-height: 20px; - font-weight: 600; + font-size: 14px; + line-height: 22px; + font-weight: 500; + color: var(--dsw-alias-label-primary); } -.groupSubtitle { - overflow: hidden; - color: var(--dsw-alias-label-tertiary); - font-size: 12px; - line-height: 18px; - text-overflow: ellipsis; - white-space: nowrap; -} - -.groupCount { - margin-left: auto; +.groupSub { + display: flex; + flex-wrap: wrap; + gap: 4px 8px; + margin: -6px 0 0 20px; color: var(--dsw-alias-label-tertiary); font-size: 12px; line-height: 18px; @@ -286,10 +289,7 @@ } .failedCount { - flex: none; color: var(--dsw-alias-state-error-primary); - font-size: 12px; - line-height: 18px; } /* The preset switcher trigger mirrors the General-settings selector pill. */ @@ -331,12 +331,6 @@ text-overflow: ellipsis; } -.iconToggle { - flex: none; - width: auto; - min-height: 0; - padding: 4px; -} .groupBody { display: flex; diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx index e56cbfdef8..fa78d36872 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx @@ -365,46 +365,51 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT {selected !== undefined ? (
    -
    +
    - { setSwitcherOpen(false) }} - items={presets.map(preset => ({ id: preset.id, label: presetLabel(preset, t) }))} - selectedId={selected.id} - onSelect={(id) => { - setSwitcherOpen(false) - setChosenPreset(id) - }} - portal - anchor={( - - )} - /> - {t('presetSubtitle')} - - {selectedRows.length} - +
    + { setSwitcherOpen(false) }} + items={presets.map(preset => ({ id: preset.id, label: presetLabel(preset, t) }))} + selectedId={selected.id} + onSelect={(id) => { + setSwitcherOpen(false) + setChosenPreset(id) + }} + align="end" + portal + anchor={( + + )} + /> +
    +

    + {t('presetSubtitle')} + + {` · ${String(selectedRows.length)} ${t('countUnit')}`} + +

    {presetEffectiveOpen ? (
    {selected.broken !== undefined ? ( @@ -437,21 +442,25 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT {entries.length > 0 ? (
    - +
    +

    + {t('globalSubtitle')} + {` · ${String(globalCount)} ${t('countUnit')}`} {filteredFailed.length > 0 ? ( {filteredFailed.length} {t('failedCountLabel')} ) : null} - +

    {globalEffectiveOpen && globalCount > 0 ? (
      {filteredFailed.map(entry => globalRowCard(entry))} diff --git a/packages/client/ui-settings-plugin-inventory/src/client/locales.ts b/packages/client/ui-settings-plugin-inventory/src/client/locales.ts index 8bad8a698e..603c1ce38b 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/locales.ts +++ b/packages/client/ui-settings-plugin-inventory/src/client/locales.ts @@ -9,11 +9,13 @@ export const zh = { search: '搜索插件', empty: '暂无插件。', emptySearch: '没有匹配的插件。', - presetSubtitle: '会话使用的插件', + presetTitle: '会话插件', + presetSubtitle: '由 Agent 预设按会话组成', + countUnit: '个', switcherLabel: '选择要查看的 Agent 预设', presetOptionDefault: '{name}（默认）', presetOptionBroken: '{name}（加载失败）', - globalTitle: '全局', + globalTitle: '全局插件', globalSubtitle: '系统与所有会话共用', presetProvidedDetail: '全局已停用，由 Agent 预设按会话提供', enabledIn: '启用于', @@ -50,11 +52,13 @@ export const en = { search: 'Search plugins', empty: 'No plugins are available.', emptySearch: 'No matching plugins.', - presetSubtitle: 'Plugins your sessions run', + presetTitle: 'Session plugins', + presetSubtitle: 'Composed per session by agent presets', + countUnit: 'plugins', switcherLabel: 'Choose the agent preset to inspect', presetOptionDefault: '{name} (default)', presetOptionBroken: '{name} (failed to load)', - globalTitle: 'Global', + globalTitle: 'Global plugins', globalSubtitle: 'Shared by the system and every session', presetProvidedDetail: 'Disabled globally; agent presets provide it per session', enabledIn: 'Enabled in', diff --git a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx index 6a3702d7ae..69ce356a49 100644 --- a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx +++ b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx @@ -92,7 +92,7 @@ describe('PluginInventorySettingsTab', () => { fireEvent.keyDown(document, { key: 'Escape' }) expect(screen.queryAllByRole('menuitem')).toHaveLength(0) expect(screen.getByText(en.presetSubtitle)).toBeTruthy() - expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('6') + expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('6') // Only the preset group lists rows while the global plane stays collapsed. expect(screen.getAllByRole('listitem')).toHaveLength(6) @@ -105,7 +105,7 @@ describe('PluginInventorySettingsTab', () => { expect(screen.queryByRole('img', { name: 'Not running' })).toBeNull() expect(globalToggle().getAttribute('aria-expanded')).toBe('false') - expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('7') + expect(view.container.querySelector('[data-plugin-count]')?.getAttribute('data-plugin-count')).toBe('7') expect(screen.getByText(`1 ${en.failedCountLabel}`)).toBeTruthy() // A preset row expands into its provenance facts. @@ -172,25 +172,25 @@ describe('PluginInventorySettingsTab', () => { } pickPreset('ptc') - expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('3') + expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('3') fireEvent.click(screen.getAllByRole('button', { name: 'tool-bash, Enabled' })[0]!) // An unnamed preset labels provenance by its id. expect(screen.getByText(en.fromPreset).nextElementSibling?.textContent).toBe('ptc') pickPreset('坏预设 (failed to load)') expect(screen.getByRole('alert').textContent).toBe('the composition file is missing') - expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('0') + expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('0') }) it('collapses the preset group until a search forces it open', async () => { const view = await renderReady() - const toggle = screen.getByRole('button', { name: en.presetSubtitle }) + const toggle = screen.getByRole('button', { name: en.presetTitle }) expect(toggle.getAttribute('aria-expanded')).toBe('true') fireEvent.click(toggle) expect(toggle.getAttribute('aria-expanded')).toBe('false') // The header keeps its count while the rows are folded away. - expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('6') + expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('6') expect(view.container.querySelectorAll('[data-plugin-scope="preset"] li')).toHaveLength(0) fireEvent.change(screen.getByRole('searchbox', { name: en.search }), { target: { value: 'pwsh' } }) @@ -221,8 +221,8 @@ describe('PluginInventorySettingsTab', () => { fireEvent.change(search, { target: { value: 'tool-bash' } }) // Searching forces the collapsed global plane and drawer open. - expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('1') - expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('1') + expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('1') + expect(view.container.querySelector('[data-plugin-count]')?.getAttribute('data-plugin-count')).toBe('1') expect(screen.getByText(en.presetEnabledTag)).toBeTruthy() expect(screen.queryByText(`1 ${en.failedCountLabel}`)).toBeNull() const hint = screen.getByText((text: string) => text.startsWith('2 more matches')) @@ -232,13 +232,13 @@ describe('PluginInventorySettingsTab', () => { // A match visible only in another preset keeps the pointer without rows. fireEvent.change(search, { target: { value: 'crashy' } }) - expect(view.container.querySelector('[data-preset-plugin-count]')?.textContent).toBe('0') + expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('0') expect(screen.getByText((text: string) => text.startsWith('1 more matches'))).toBeTruthy() expect(screen.queryByText(en.emptySearch)).toBeNull() // A match on a Loader entry id only reaches the global plane. fireEvent.change(search, { target: { value: '8a1b2c3d' } }) - expect(view.container.querySelector('[data-plugin-count]')?.textContent).toBe('1') + expect(view.container.querySelector('[data-plugin-count]')?.getAttribute('data-plugin-count')).toBe('1') expect(screen.queryByText((text: string) => text.includes('more matches'))).toBeNull() fireEvent.change(search, { target: { value: 'not-a-plugin' } }) From cebd0a2031dbb6901802df9e862b8b7792315ba8 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Sat, 29 Aug 2026 17:26:05 +0800 Subject: [PATCH 41/63] refactor(plugin-inventory): match group title and switcher pill to the General-settings row idiom --- .../client/PluginInventorySettingsTab.module.css | 15 +++++++-------- .../src/client/PluginInventorySettingsTab.tsx | 2 +- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css index fa312a68fa..3a1626a4f0 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.module.css @@ -273,7 +273,7 @@ .groupTitle { font-size: 14px; line-height: 22px; - font-weight: 500; + font-weight: 400; color: var(--dsw-alias-label-primary); } @@ -297,18 +297,17 @@ display: inline-flex; flex: none; align-items: center; - gap: 10px; - height: 30px; + gap: 12px; + height: 36px; white-space: nowrap; border: none; - border-radius: 15px; - padding: 0 12px; + border-radius: 18px; + padding: 0 14px; background: var(--dsw-alias-bg-module-platform); color: var(--dsw-alias-label-primary); font: inherit; - font-size: 13px; - line-height: 20px; - font-weight: 600; + font-size: 14px; + line-height: 22px; cursor: pointer; } diff --git a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx index fa78d36872..9e6bb7f951 100644 --- a/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx +++ b/packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx @@ -398,7 +398,7 @@ export function PluginInventorySettingsTab({ list, t }: PluginInventorySettingsT onClick={() => { setSwitcherOpen(value => !value) }} > {presetLabel(selected, t)} -