diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml new file mode 100644 index 0000000000..8245fb8396 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.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-23-client-derived-tool-presentation.md +2026-08-23-client-derived-tool-presentation.md: 3643c003058f2c17c297606357e35fb43f2e5280 +2026-08-23-client-derived-tool-presentation.zh.md: 31d3a9f082b937dd8d8002bfbc30ef85200ba367 diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md new file mode 100644 index 0000000000..3643c00305 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md @@ -0,0 +1,696 @@ +# Agent Note: Client-Derived Presentation from Raw Session Tool Events + +Status: implemented + +English | [中文](2026-08-23-client-derived-tool-presentation.zh.md) + +## Problem + +Session history is a durable journal interface, while tool cards are Client presentation. Computing card views during `page` or `follow` would couple history reads to the Tools registry, Agent presets, restored scopes, presenter execution, and transient UI types. + +A `tool/result` does not repeat the tool name or arguments. Host-side result presentation therefore requires either a call index or a backward scan by `callId`; repeated scans over a tool-dense page can approach quadratic work because `maxMessages` does not directly bound the event count. + +Host projection would also duplicate structured data. Read, diff, search, and web results already persist bounded facts in `tool/result.data.meta`; another view object increases Remote payload size and Client decoding without adding durable meaning. + +The Client already owns a complete tool-presentation entry point. `ui-chat` assembles `tool/call`, `tool/result`, and Code Dispatch events into stable `ToolCallBlock` values. `ui-tool` owns the recursive call tree, the `tool.call.toolview` keyed slot dispatched by tool name, the Generic fallback, card models, and details output. A business Client plugin can register a renderer for its own tool names. + +Splitting presentation between Host presenters and Client keyed renderers creates two interpretations of the same event. The keyed renderer is the Web extension point, so an intermediate Host view provides no independent Web capability. + +`ToolDefinition.presentCall` and `presentResult` remain useful Host APIs even though ACP is automation-only and the repository has no production TUI consumer. Removing their definitions is a separate decision from keeping Session reads independent of presentation. + +The required result is one raw Session journal and one Client presentation owner without visual degradation or incidental enhancement. Specialized cards, interactions, and Code Dispatch topology remain stable while the transport stops carrying transient views. + +## Decision + +The Session Remote journal sends only raw, validated, persistable Session events. `session.page` and `session.follow` do not parse tool arguments, query the Tools registry, restore a presenter scope, execute `presentCall` or `presentResult`, or construct or clone any tool view. + +The Client Conversation layer continues to own tool call/result identity, pairing, lifecycle, Code Dispatch topology, and stable Chat Nodes. It does not interpret individual tool names or produce terminal, diff, read, search, or web component props. + +Client `ui-tool` continues to own card models and concrete renderers. Each card model directly reads the tool name, raw arguments, result content, error, durable metadata, Session cwd, and Host home from `ToolCallBlock`, and produces the same component props as the current page. + +The Client has no second presenter registry. Tool-name dispatch uses only the existing `tool.call.toolview` keyed slot. Pure Client card-model helpers are renderer implementation details, not a Cordis service, public registry, or wire DTO. + +The Host `ToolDefinition.presentCall`, `ToolDefinition.presentResult`, `ToolCallView`, `ToolResultView`, and existing tool presenter implementations remain. The Session Controller does not invoke them, and the Client does not import or consume them. A future non-Client consumer is outside this decision. + +`ToolOutputDefinition.presentationMeta` and durable `tool/result.data.meta` remain. They carry execution-result facts required by existing specialized cards that the model-visible result text cannot represent losslessly. The Client validates and consumes `meta` directly rather than requiring the Host to convert it into a view during history reads. + +### Goals and non-goals + +| Category | Decision | +|---|---| +| Absent | `SessionEventEntry.view`, `SessionToolView`, and `SessionToolCallView` | +| Absent | `viewFor`, `backscanArgs`, `parseToolCall`, `jsonView`, and presenter-scope lookup from `history.ts` | +| Absent | `openCalls` and fallback event scans used only for follow presentation | +| Absent | the Client Session's parallel `views` array, Conversation input `view`, and Tool block `callView`/`resultView` | +| Derived | terminal, diff, read, search, and web card models read raw blocks and metadata | +| Derived | Deliverables reads successful mutation names and arguments | +| Retained | Host `ToolDefinition.presentCall`/`presentResult` APIs, types, implementations, and direct tests | +| Retained | `output.presentationMeta` and durable `tool/result.data.meta` | +| Retained | the Session log format, Remote journal lifecycle, and Conversation identity/topology | +| Retained | the existing keyed slot, Generic fallback, and Chat, Details, and Trajectory structure | +| Forbidden | a new Client presenter service, parallel registry, or wire renderer id | +| Forbidden | new cards, visual redesign, interaction redesign, or Code Dispatch rich-card enhancements | +| Forbidden | compatibility dual-writing, version negotiation, or retention of the old `view` field | + +## Terminology + +**Raw Session event** means a `SessionEvent` fact from the durable log, including the `name` and raw `arguments` string on `tool/call`, and the `content`, `isError`, structured error, and optional `meta` on `tool/result`. + +**Durable metadata** means the JSON value produced by `ToolOutputDefinition.presentationMeta` after a tool succeeds and stored in `tool/result.data.meta`. It is part of the result facts, not a pre-laid-out React or card DTO. + +**Host tool view** means the `ToolCallView` or `ToolResultView` returned by `ToolDefinition.presentCall` or `presentResult`. Session Remote does not transport it. + +**Client card model** means the pure props data under `ui-tool/src/client/tool/models/` consumed directly by `TerminalBlock`, `DiffBlock`, `ReadBlock`, `SearchBlock`, `WebBlock`, or `ToolRow`. + +**Specialized card** means the structured terminal, diff, read, search, or web body. Titles, summaries, status dots, and ordinary IN/OUT text remain part of the generic tool row. + +**Equivalent** means that the same supported input produces the user-visible result and interaction pinned by the existing component, assembly, and browser evidence. It does not require the same intermediate TypeScript types or internal calls. + +**No enhancement** means that this decision does not give an input pinned to Generic fallback a new specialized card or expand an existing card's data or interactions. + +## Architecture and Ownership + +### Tool execution and persistence + +1. A tool registers `output.schema`, `output.render`, and optional `output.presentationMeta`. +2. Successful execution produces a canonical JSON value. +3. The Tools runtime snapshots, schema-validates, and freezes the value. +4. `output.render(args, value)` produces model-visible `ContentBlock[]`. +5. When a top-level call declares `output.presentationMeta`, the runtime also produces JSON-safe metadata. +6. The agent loop writes the model-visible result and metadata into a `tool/result` Session event. +7. The Session log does not store `ToolCallView` or `ToolResultView`. + +### Host journal reads + +1. `session.page` obtains attached or persisted events. +2. `paginate()` cuts pages on append-origin user/assistant message boundaries. +3. A tail page obtains its baseline from the registered projection snapshot/restore path. +4. Every page entry contains only `{event}`. +5. `session.follow` establishes its listener before catch-up reads, emits the opening cursor, and then streams contiguous `{event}` frames. +6. Neither path resolves a preset or Tools scope for presentation, parses tool arguments, invokes presenters, or indexes calls. + +### Client data and presentation + +1. The Client Session stores one contiguous raw event window. +2. `SessionEventSource` publishes `SessionEventEntry` values containing only events. +3. `ui-conversation` folds each event without a presentation companion. +4. The Chat and Trajectory Tool Definitions pair top-level calls and results by callId and assemble Code Dispatch subtrees. +5. `RunningToolCall` and `ToolResultNode` retain raw facts, metadata, and existing parent identity. +6. `ToolCallTree` dispatches `tool.call.toolview` by wire tool name. +7. `ui-tool` derives card component props from the block at the render site. + +### Production consumer audit + +| Object | Producer | Production consumer | Decision | +|---|---|---|---| +| `presentCall`/`presentResult` | Host tools | non-Client callers, if any | retained outside Session Remote | +| `SessionEventEntry.view` | none | none | absent from the wire | +| `callView`/`resultView` | none | none | absent from the Client model | +| `presentationMeta` | Tools runtime | `tool/result`, Client card models, and Host presenters | retained durable input | +| fixture presenter mirror | none | none | fixtures send raw metadata | + +ACP does not consume a Session tool view or map Host render intent. The repository has no production TUI consumer. Host presenters remain available without making Session Remote their transport. + +## Data Flow + +```text +Tool execute + -> canonical value + -> output.render(args, value) + -> model-visible result content + -> output.presentationMeta(args, value), when declared + -> durable tool/result event + +Session page/follow + -> raw Session event envelope + -> no tool lookup + -> no preset lookup for presentation + -> no call backscan + -> no render-intent serialization + +Client SessionEventSource + -> Conversation Tool Definition + -> root call/result pairing + Code Dispatch topology + -> ToolCallBlock(name, argsRaw, content, error, meta) + -> tool.call.toolview keyed dispatch + -> Client card model + -> existing React component +``` + +This path retains one durable metadata projection because it runs while the canonical result is still in memory. It removes the second presentation projection performed while reading history. + +### Layer responsibilities + +| Layer | Owns | Does not own | +|---|---|---| +| Tools runtime | execution, canonical value, model text, replayable metadata | Web card selection and component props | +| Session log | durable facts, ordering, replay | transient card DTOs | +| Session Controller | addressing, authority, cold reads, pagination, follow, projection baseline | tool lookup, presenters, presentation scope | +| Client Session | Remote journal lifecycle and contiguous window | tool meaning and card types | +| Conversation Tool Definition | call/result pairing, lifecycle, root/subcall topology | mapping a tool name to a component | +| `ui-tool` | card models, Generic fallback, Chat/Details presentation | Session pagination and the Host registry | +| Business Client plugin | keyed renderer for its own tool name | root/subcall assembly and a global registry | +| `ui-deliverables` | produced paths for current first-party mutations | UI cards or Host render intent | + +## Remote and Durable Data Contracts + +### `SessionEventEntry` + +`SessionEventEntry` remains the journal-entry envelope and contains only `event: SessionWireEvent`. This change does not also turn page entries into bare events or refactor the general `RemoteJournalStream` entry contract. + +`SessionPage.events` remains `SessionEventEntry[]`. + +`SessionFollowFrame` remains either an opening frame or an event frame containing `event`. + +`SessionToolCallView`, `SessionToolView`, and `SessionEventEntry.view` are deleted. + +The Client connection stops re-exporting `ToolCallView` and `ToolResultView` from `dsh-tools/presentation` for Session consumers. + +Generated catalogs and graphs derive the narrowed Remote types and package dependencies from their owning sources. + +### Durable log + +- `tool/call.data.name` remains unchanged. +- `tool/call.data.arguments` remains the model-produced raw JSON string. +- `tool/result.data.message.content` remains the model-visible result. +- `tool/result.data.error` remains the structured failure identity. +- `tool/result.data.meta` remains a tool-private JSON value. +- Client card models do not write to the Session log. +- Renderer keys and Host tool implementation ids do not enter the Session log. +- Existing durable Sessions need no migration, and `SESSION_FORMAT_VERSION` does not change. + +### `presentationMeta` + +`presentationMeta` is not a Host tool view. It reads the canonical value when tool execution completes, and that value is not persisted. Removing it would make the following existing presentation impossible to reconstruct losslessly: + +- read path, offset, lines, totalLines, and lang; +- applied contextual hunks for write/edit; +- grouped grep/glob results, truncation flag, and total; +- web_search source fields and provider answer; +- web_fetch final URL, HTTP status, and effective truncation flag. + +The Client narrows `meta` locally at runtime. Renaming `presentationMeta` to more neutral result metadata is outside this decision. + +## Host Design + +After obtaining source events, `SessionHistoryController.page()` performs only pagination and the existing projection-baseline calculation. Attached Sessions use the projection registry snapshot; detached Sessions use its restore path over the inspected log. History does not mount a preset to change the registered projection set. + +`SessionHistoryController.follow()` retains listener-first setup, opening cursors, gap-free replay, live buffering, cancellation, and teardown. It maintains no additional state for tool events. + +The controller has no `presenterScopeFor()`, `viewFor()`, `backscanArgs()`, `parseToolCall()`, or `jsonView()` path. Page state contains no presenter scope or argument resolver; follow state contains no `openCalls`, `fallbackEvents`, or presentation argument resolver. Each page/follow event is wrapped only as `{event}` while addressing, ownership, cursor, sequence, and projection logic remains intact. + +An immutable event-conversion helper may remain narrow or be inlined; its name is irrelevant as long as history performs no presentation work. + +Session Controller dependencies remain only when another package responsibility requires them. Manifest and project references contain no presentation-only dependency. + +### Performance constraints + +- `page()` performs no tool-specific work. +- Adding tool results to a page does not cause repeated scans over existing page events. +- `follow()` maintains no presentation index. +- History does not trigger the Cordis `tools` service proxy. +- History does not wait for a presenter standing scope. +- History does not parse tool-argument JSON. +- History does not perform tool-view JSON clones. +- The Remote payload does not repeat structured data already expressed by `meta`. +- The Client does not scan the complete Session event window to build one card. +- The Client derives a card model again only when the corresponding immutable Tool block changes. + +## Client Session and Conversation + +The Client Session has no private `views` array parallel to the raw event window. `installWindow()`, `prependWindow()`, and `appendLive()` handle only event entries, cursor/hasMore state, queues, projection, and notifications. + +`ConversationEventInput` contains only `event`. The Conversation assembler does not know `SessionToolView`; its replace/prepend/append behavior, Context identity, Location, and publication cadence remain unchanged. + +The Chat and Trajectory Tool Definitions read no views. They derive the following data from events: + +- callId; +- tool name; +- raw arguments; +- turn, step, seq, and time; +- result content; +- isError and structured error; +- result metadata; +- root/subcall parent-child topology; +- synthetic interruption results. + +`RunningToolCall` has no `callView`. + +`ToolResultNode` has no `callView` or `resultView`. + +`ToolCallBlock` does not gain a generic `view`, `card`, `kind`, or `locations` field to replace the deleted fields. Concrete presentation remains the responsibility of `ui-tool` and keyed renderers. + +### Root and Code Dispatch subcalls + +Host presenter APIs describe top-level calls and results. Code Dispatch subcalls use the Generic, flattened Client presentation; recognizing a subcall name does not grant it a structured card. + +Code Dispatch start and result events already carry `parentCallId`. Conversation preserves that existing fact on each child `ToolCallBlock`; root Session calls omit it. The five structured card models accept only blocks without `parentCallId`, while existing renderers that intentionally support nested calls continue receiving the same child block. + +The Details panel delegates the selected block unchanged. The same card models observe `parentCallId` and keep a selected Code Dispatch child on the existing raw fallback, so the Details slot needs no placement field. + +The keyed slot continues dispatching every subcall by its real tool name. `parentCallId` controls only the terminal, diff, read, search, and web structured models covered by this decision. Existing specialized renderers such as Skill and Cordis, which already read raw blocks, remain unchanged. + +### Missing call head + +When a result node has no matching call in the current window, `ToolResultNode.call` remains `null`. The Client does not scan the window, issue another RPC, or infer a tool name from result text. + +A specialized derivation that needs the name or arguments uses the current Generic fallback when `call === null`. A model that could use result metadata alone does not gain new presentation, because the current Host `presentResult` must first recover the matching call. + +If a later older page supplies the call head, the Conversation Context rebuilds under existing replay rules and may then produce the already-supported specialized card. + +### Argument and metadata narrowing + +The Client parses JSON from `argsRaw`; a parse failure returns the Generic form instead of throwing a React render error. + +Chat and Details reuse parsing for the same block through pure helpers. Any future cache must use immutable block identity and must not create cross-Session global state keyed by callId. + +Each specialized model checks only the fields it needs. The Client does not copy complete Host tool schemas or invoke a Host `defineTool` validator. + +Valid first-party events must be equivalent to current presenter output. Malformed, old-version, or manually edited logs promise only a crash-free Generic fallback. + +## Client Card-Model Design + +The existing `ui-tool/src/client/tool/models/` directory remains the single source of shared derivation for Chat and Details. Helpers return component props directly; they do not return `ToolCallView` or `ToolResultView`, and they do not create an isomorphic `ClientToolView` union. + +Branches on tool name exist only in `ui-tool` card models, existing row-classification tables, or the Client plugin that owns a keyed renderer for that tool. They must not enter the Session Controller, Client Session, Conversation assembler, or generic Slot renderer. + +Unknown tools continue to use `GenericToolCard` with the name, raw arguments, result content, and error. + +### Generic tool row + +`toolRowModel()` derives the generic row directly from `toolName`, `argsRaw`, result content, error, cwd, and home. It preserves: + +- classification into `search`, `read`, `bash`, `write`, `edit`, `code`, and `others`; +- existing titles and tool-specific titles; +- summary-field priority and single-line truncation; +- comma joining of multiple queries; +- cwd-relative paths and home abbreviation; +- file-path clicks; +- pretty JSON arguments and non-JSON raw-text fallback; +- flattened result content and structured-error fallback; +- running, ok, error, and stopped states. + +The title, kind, rawInput, content, and locations from Generic Host `presentCall` do not currently drive an ordinary Web row. Generic `presentResult.content` also does not drive Web output, so the Client need not copy these unconsumed values. + +### Terminal card + +The Client terminal model derives existing `TerminalBlock` props from the tool name, call arguments, result content, error, existing `parentCallId`, and Session cwd. + +| Input | Preserved result | +|---|---| +| running standard `bash`/`pwsh` foreground call | terminal prompt, description, cwd, and running state | +| successful standard foreground call | terminal output, exit code/signal, and success or failure status dot | +| `run_in_background:true` | Generic row and raw result | +| tool execution error | Generic IN/OUT and error summary | +| running persistent `bash`/`pwsh` | terminal prompt | +| settled persistent `bash`/`pwsh` | Generic flattened result, with no new exit card | +| foreground `terminal_send` | terminal prompt and output | +| background/error `terminal_send` | Generic result | +| Code Dispatch child | current flattened Generic form | + +Standard shell results continue parsing trailing `[exit code: N]` and `[killed by signal: X]` markers. A parsed marker is removed from the body; timeout, sandbox denial, and markers without a pill remain in the body. + +Call `description` remains above the card and overrides the collapsed summary. Workdir continues handling absolute, relative, and missing values. Relative paths resolve against the Session cwd while preserving normalization for `.`, `..`, drive letters, and UNC roots. + +Standard and persistent providers sharing the same tool name are a special compatibility point. The Client uses currently valid argument and result features to preserve their delivered differences. Input that cannot be identified unambiguously uses a Generic settled result rather than gaining new presentation. + +`TerminalBlock` ANSI handling, cursor replay, wide characters, line limits, expansion, copying, and assistive text remain unchanged. + +### Diff card + +| Input | Preserved result | +|---|---| +| running `write` | intended added-only diff from `file_path` and `content` | +| running `edit` | intended replacement diff from `file_path`, `old_string`, and `new_string` | +| successful settled `write`/`edit` | applied contextual hunks from `meta.diffs` | +| write create or missing/malformed/empty applied metadata | current argument fallback | +| error, malformed arguments, edit with malformed metadata, or Code Dispatch child | Generic | + +Paths, `oldText:null`, `newText`, result-over-call diff precedence, the eight-line Chat limit, full-height Details presentation, and file-opening behavior remain unchanged. + +### Read card + +A running `read` continues to show only the summary row. A successful settled `read` reads path, offset, lines, totalLines, and lang from result metadata and confirms that the result is one text block matching the read envelope. + +Missing metadata, malformed fields, a mismatched result envelope, an error, a missing call head, or a Code Dispatch child all use Generic. Cwd-relative path labels, home abbreviation, syntax language, total line count, the eight-line Chat limit, and full-height Details presentation remain unchanged. + +The Client does not need to construct Host `ReadResultView.content`; Generic fallback can always read raw result content directly. + +### Search card + +A running `grep` or `glob` continues to show only the argument summary. Successful results produce grouped matches or a path list from `meta.shape:'matches'` and `meta.shape:'paths'`, respectively. + +The Client validates path, lineNumber, line, truncated, and total. Empty matches or paths form a valid card. Missing or malformed metadata, an unknown shape, an error, a missing call head, or a Code Dispatch child uses Generic. + +When `truncated:true`, the card continues to show a recovery locator from raw result content. It does not show one when untruncated. The eight-line Chat limit, full-height Details presentation, and expansion behavior remain unchanged. + +### Web card + +A running `web_search` or `web_fetch` continues to show only the summary row. A successful search builds the card from `meta.sources`, `meta.answer`, and `meta.truncated`; a successful fetch builds it from `meta.url`, `meta.statusCode`, and `meta.truncated`. + +The Client validates every source's url, title, snippet, and publishedAt, and continues rendering only http/https URLs as links. Missing or malformed metadata, an error, a missing call head, or a Code Dispatch child uses Generic. + +Search answer text, source ordering, label fallback, and truncation notice remain unchanged. The fetch final URL, status, truncation notice, and raw body below Details remain unchanged. + +### Renderers already using raw blocks + +- Todo rows continue deriving completed/active summaries from arguments. +- Question rows continue deriving waiting, answered, cancelled, and interrupted states from result content and errors. +- Skill rows continue deriving names and states from calls and results. +- Cordis define/run/action rows continue deriving from calls, results, and their own Client services. +- These renderers retain their props, slot keys, registration order, and visible results. + +## Deliverables + +`ui-deliverables` derives mutation business facts independently of presentation intent, so produced-file behavior is not coupled to card screenshots. + +The Deliverables Definition observes root `tool/call` and successful `tool/result` events by callId and retains a minimal Client-owned mutation candidate without scanning the Session window or depending on a UI renderer. + +| Tool | Mutation condition | Path source | +|---|---|---| +| `write` | any successful call | `file_path` | +| `edit` | any successful call | `file_path` | +| `str_replace_editor` | `create`, `str_replace`, or `insert` | `path` | +| `str_replace_editor` | `view` | produces no path | +| Other | no current first-party mutation semantics | produces no path | + +Failures, interruptions, orphan results, missing paths, and malformed arguments produce no deliverable. Paths retain first-seen deduplication, and results settled after the closing Assistant seq remain excluded. + +This change does not add a general tool-side-effect registry. The ability for a Host-only third-party presenter to join Deliverables automatically through `kind:'edit'` or `locations` is intentionally removed. A future real third-party mutation requirement must use a Client business contribution and cannot restore Session views. + +## Fixtures and Test Data + +The Client fixture deletes its handwritten `presentCall()`, `presentResult()`, `viewFor()`, and fixture tool-view types. It continues producing the same raw calls, result content, and result metadata as a real log. + +| Fixture | Raw facts that must remain | +|---|---| +| terminal | arguments and real result status markers | +| diff | arguments and result `meta.diffs` | +| read | result metadata path/offset/lines/totalLines/lang | +| grep/glob | result metadata shape/files or paths/truncated/total | +| web | result metadata sources/answer or url/statusCode/truncated | +| generic/custom | name, argsRaw, content, and error | + +The fixture does not import Host tool packages to compute page presentation and retains no presenter mirror. The same raw fixture continues to drive jsdom, built Web snapshots, and the `?fixture` browser path. + +## Presentation-Equivalence Matrix + +“Current presentation” is defined by committed component tests, assembly tests, and Web browser expected outputs. A transport or ownership refactor does not justify refreshing snapshots; an approved product change requires separate evidence. + +| Scenario | Required presentation | +|---|---| +| unknown tool, running | Generic row with tool name and argument summary | +| unknown tool, settled | Generic row and raw output | +| malformed arguments | safe Generic fallback | +| orphan result | callId title and Generic output | +| interrupted call | warning/stopped state | +| foreground bash/pwsh | current terminal prompt, body, cwd, and state | +| background/error bash/pwsh | current Generic IN/OUT | +| persistent shell | current running terminal and settled Generic form | +| terminal_send | current foreground terminal and background/error Generic form | +| write/edit | current intended/applied diff and error fallback | +| read | current running summary, settled ReadBlock, and error fallback | +| grep/glob | current grouped/path card, truncation, and recovery | +| web_search/web_fetch | current source/summary card and raw body | +| Todo/Question/Skill/Cordis | current specialized rows | +| Code Dispatch subcall | current Generic/flattened form | +| Chat and Details | identical card fields for the same call | +| Trajectory | current identity, tree, selection, and details | +| Deliverables | current successful-mutation chips and links | + +## Client Extension Contract + +`tool.call.toolview` remains the sole tool UI registration mechanism. A tool that needs specialized Client presentation must have a Client plugin register its wire tool name. + +The registrant receives the raw `ToolCallBlock`, Session path information, and host actions, and validates the argument and metadata fields it recognizes. It does not call the Host tool registry, depend on `presentCall` or `presentResult`, or require `SessionEventEntry.view`. + +A tool with no Client renderer consistently degrades to Generic. Only one keyed registration for a tool name can be active, and duplicate keys continue to fail loudly. + +A Session-scoped slot can express Client-side Session differences, but no renderer variant is inferred from a preset. A Host-only presenter does not grant a Web rich card automatically. This is the explicit boundary between “the Host describes presentation” and “the Client plugin owns presentation.” + +## Failures and Fallback + +- The Client treats arguments and metadata as wire JSON and narrows them at the consumption site. +- Argument JSON parse failure uses Generic. +- A known tool missing required fields uses Generic. +- Missing or malformed metadata uses Generic, except successful `write`, whose current presenter preserves its argument-derived whole-file diff. +- An error result does not show a success card merely because metadata is present. +- A missing call head does not trigger guesses about the tool name or arguments. +- Unknown metadata fields are ignored. +- A new metadata variant uses Generic in an older Client. +- Card-model helpers catch expected parse failures instead of relying on a React error boundary for ordinary fallback. +- Unexpected failures inside a keyed renderer remain isolated by existing Slot error handling. + +## Same-Named Host Providers + +The Host registry allows different scopes to provide different definitions under the same tool name. Through presenter scope, a Session view can theoretically select a different render intent by preset. After removing the view, the Client keyed slot observes only the wire name and cannot observe Host definition identity. + +The notable current first-party examples are standard and persistent `bash` and `pwsh`. Client derivation uses valid argument and result features to preserve their delivered differences without a provider-id wire field. Malformed or custom same-name provider input that cannot be distinguished uses Generic. + +This change does not promise to preserve differences expressed only through a Host presenter by third-party same-name providers. If the product later requires distinct Client presentation for same-name providers, it must define a stable, non-presentational Client identity and must not restore per-page Host view computation. + +## Shipped Scope + +### Session Controller + +- `SessionEventEntry` contains only the raw event. +- Both Session tool-view types are absent. +- History has no presentation imports, helpers, or page/follow presentation state. +- Addressing, pagination, follow, and projection logic remain in the Session owner. +- Host tests assert the raw journal contract. + +### Session Controller Client + +- `Session.views` is absent. +- EventSource replace/prepend/append deltas remain unchanged. +- Transport, fixture, and test-support types carry raw entries. +- Event identity and reference stability remain unchanged. + +### UI Conversation, Chat, and Trajectory + +- Conversation input and Tool blocks contain no view fields. +- Chat and Trajectory Tool Definitions read raw events. +- Event pairing, Context replay, trees, and target snapshots remain unchanged. +- Child Tool blocks preserve the existing Code Dispatch `parentCallId`; row and Details slot owner props add no separate placement field. + +### UI Tool and Deliverables + +- Card models derive from raw blocks and metadata. +- Chat and Details share the same helpers. +- Generic fallback and keyed dispatch remain unchanged. +- Deliverables recognizes first-party mutation arguments. + +### Fixtures, documentation, and generated artifacts + +- Fixtures send only raw events and metadata. +- Session Controller and Client README/JSDoc contracts describe the raw journal and Client presentation owner. +- The tool cookbook documents the Web Client integration path. +- This Agent Note is the decision owner; retained Host presenter notes keep their independent decisions. +- Authored Remote types, dependencies, READMEs, pairing records, and generated references remain synchronized. + +## Verification Matrix + +### Host + +- page returns contiguous raw event entries. +- follow returns an opening cursor and contiguous raw event entries. +- page/follow behave identically without the Tools service. +- A cold page does not resolve or mount a preset. +- A tail page computes its baseline through the standard projection registry; provider availability follows the projection composition rather than a history-side setup path. +- Addressing, ownership, message-aligned boundaries, and tail projection remain unchanged. +- Listener-before-read, reconnect catch-up, and gap repair remain unchanged. +- Many tool results do not trigger a backscan per result. +- Wire results contain no view. + +`session-history-journal.host.spec.ts` owns pagination, continuity, and history error behavior without presenter assertions. + +### Client Conversation + +- replace, prepend, and append accept entries without views. +- Chat and Trajectory root call/result pairing remains unchanged. +- The Code Dispatch tree remains unchanged. +- Result-only fallback remains unchanged. +- A synthetic interruption result copies no view. +- Node identity across registry rebuild, older prepend, and live append remains unchanged. + +### Client card model + +- terminal produces the pinned props from raw arguments/content. +- diff produces the pinned diffs from arguments/metadata. +- read produces the pinned lines from metadata/content. +- search produces the pinned grouped/path card and recovery from metadata/content. +- web produces the pinned sources/fetch summary from metadata/content. +- unknown, malformed, error, missing-call, and missing-metadata cases remain Generic. +- absent and present `parentCallId` cases prove that structured presentation does not reach Code Dispatch descendants. +- Chat and Details produce identical card fields for the same block. + +### Deliverables + +- Successful write/edit calls produce `file_path`. +- str_replace_editor create/str_replace/insert calls produce `path`. +- str_replace_editor view produces no path. +- failure, interruption, malformed input, and orphan results produce no path. +- First-seen deduplication and the closing-seq cutoff remain unchanged. + +### Assembly and browser + +- terminal, diff, read, search, and web browser expected outputs all pass without refresh. +- Visible assertions for the tool tree, details, trajectory, and deliverables retain their expected values. +- The built Client still displays the same cards after obtaining raw events from real Remote page/follow operations. +- Fixtures and the real Host use the same Client derivation. +- A minimal preset independently pins persistent-shell behavior. + +### Static and documentation + +- Production code contains no `SessionToolView` or `SessionToolCallView`. +- Session history does not reference `dsh-tools/presentation`, `ctx.tools`, `presenterScopeFor`, or `backscanArgs`. +- Client Conversation does not reference `ToolCallView` or `ToolResultView`. +- Client models do not read `callView` or `resultView`. +- The fixture defines no presenter mirror. +- Host `presentCall`, `presentResult`, and `presentationMeta` remain. +- No new Client registry or Host-to-Client presentation hint exists. +- Affected authored types, READMEs, Agent Notes, catalogs, and graphs are synchronized. + +## Verification Commands + +Changes to this decision use `dsh-pre-push-checks` to select commands for the final diff. Required evidence includes: + +- focused Session Controller history/transport tests; +- ui-chat and ui-trajectory Tool Definition tests; +- ui-tool terminal, diff, read, search, web, row, tree, and details tests; +- ui-deliverables produced-file tests; +- connection fixture and Client runtime tests; +- affected Host and Client TypeScript faces; +- lint and duplication; +- per-file 100% coverage for affected source files; +- `DSH_SNAPSHOT=replay pnpm run test:web`, without refreshing existing presentation goldens; +- authored Remote type and TypeScript checks; +- `pnpm run doc-sync`; +- `git diff --check`. + +## Shipped Invariants + +- Session page/follow does not read the Tools registry or a presenter scope. +- Session history has no callId backscan, presentation cache, or view clone. +- A Remote Session entry carries no view. +- The Session log and `SESSION_FORMAT_VERSION` remain unchanged. +- Result metadata passes byte-for-byte through the log and Remote to the Client. +- Conversation assembles `ToolCallBlock` only from raw events. +- `ToolCallBlock` contains no Host render-intent fields. +- The five structured card models read only raw blocks, their existing `parentCallId`, and Session path facts. +- Generic, Todo, Question, Skill, and Cordis rows remain unchanged. +- Deliverables does not depend on render intent and preserves current paths. +- Text, components, expanded content, states, links, and ordering for all first-party top-level tools remain unchanged. +- Malformed, missing-metadata, error, orphan, and unknown-tool cases continue to fall back safely. +- Code Dispatch subcalls remain Generic and flattened. +- Chat, Details, and Trajectory behavior remains unchanged. +- Existing Web browser expected outputs pass without refresh. +- Host presenter APIs, implementations, and direct tests remain unchanged. +- ACP output remains unchanged. +- No new downstream presentation field or second Client registry is introduced. +- Pagination cost no longer grows as the number of results multiplied by page event count. +- Downstream payloads no longer duplicate result metadata in a card DTO. + +## Alternatives considered + +### Optimize only `backscanArgs` and retain views + +Building one `callId → {name,args}` Map before processing a page would make backscan linear, and live follow already has an `openCalls` fast path. It would leave Host lookups, preset scopes, presenters, JSON clones, duplicate payloads, and dual ownership intact, so this alternative is rejected. + +### Add a presenter registry to the Client + +Copying the `presentCall` and `presentResult` interfaces into the browser would duplicate the registration, lifecycle, fallback, and override semantics of the `tool.call.toolview` slot. Renderers would still have to convert presenter DTOs into component props, so this alternative is rejected. + +### Have the Conversation Tool Definition produce one unified view + +This would put tool names and UI-card semantics into the target-neutral Conversation owner and recreate an intermediate DTO isomorphic to the Host view, so this alternative is rejected. + +### Delete `presentationMeta` + +Read line structure, applied diffs, search grouping, web sources, and effective truncation cannot be recovered losslessly from model text. Parsing free-form text would also bind the UI to output wording, so this alternative is rejected. + +### Persist canonical tool results + +This would enlarge the Session log, expose internal result structures, change the durable format, and potentially store objects far larger than presentation requires. Existing metadata is sufficient, so this alternative is rejected. + +### Delete Host presenter APIs + +Deleting them would shrink more code, but the decision preserves Host `presentCall` and `presentResult`. Their APIs, implementations, tests, and types remain independent of Session Remote. + +### Import Host tool implementations into the Client + +Tool packages include Node, filesystem, subprocess, or provider dependencies and cannot enter the browser bundle. The Client consumes only raw JSON and maintains narrow parsers inside its own renderers, so this alternative is rejected. + +### Query presentation from the Host per result + +An on-demand RPC would turn one page read into N network calls and would still require Host lookups, scope restoration, callId recovery, and error coordination, so this alternative is rejected. + +### Allow presentation enhancements + +The Client could produce more rich cards for Code Dispatch subcalls, missing call heads, or history whose Host presenter was unavailable. That would mix an ownership change with product behavior and prevent snapshots from proving equivalence, so this alternative is rejected. + +### Accept temporary Generic degradation + +Stopping view delivery before completing Client cards would temporarily degrade terminal, diff, read, search, web, and Deliverables behavior. Client-equivalent derivation and Host removal must land in the same releasable change. + +## Consequences + +The decision removes presentation work, repeated scans, and duplicate view payloads from Session reads. Its cost is that the retained Host presenter and Client card derivation can evolve independently, so both sides require owner-specific tests and Web equivalence remains an explicit product constraint. + +### Client and Host logic drift + +Each tool may have one Host render intent and one Client card derivation. They serve different consumers and do not share a runtime path. Unrefreshed browser expected outputs pin visual equivalence for the first-party Web experience, while Host presenter tests constrain only the Host API. + +### Same-named providers lack stable identity + +A raw event records the tool name but not the specific ToolDefinition. The Client uses valid event fields to preserve differences between standard and persistent shells. Ambiguous custom or malformed input falls back to Generic; the wire has no extra hint for theoretical extensibility. + +### Metadata is unknown JSON + +Old Sessions may lack fields, and manually edited logs may contain malformed values. Each Client model must narrow locally and cannot pass unknown arrays or objects directly into UI primitives. + +### Two targets must stay synchronized + +Chat and Trajectory have separate Tool Definitions and both carry the raw fields. Card derivation remains only in `ui-tool` and cannot be copied into either Definition. + +### Deliverables has a hidden dependency + +Deliverables is not a visual component, so its mutation parser must remain synchronized with supported first-party write tools. Dedicated tests pin file chips and Markdown links independently of card screenshots. + +### Fixtures can create false confidence + +Fixtures send raw events and metadata rather than handwritten views. Real-Host assembly coverage remains necessary because fixture-only snapshots cannot prove the transport path. + +### Incorrectly refreshing snapshots + +This change promises unchanged user-visible output. A snapshot difference must be fixed in Client derivation. Expected outputs must not be refreshed unless the owner separately approves a specific visual change. + +### Documentation drift + +The Agent Note, package READMEs, cookbook, root rules, and generated references must change together whenever the raw journal or Client presentation owner changes. Host API documentation remains separate. + +### Remote protocol narrowing + +The absence of optional `view` is a prerelease wire-type decision shared by all consumers. There is no compatibility shim, dual-writing, or version negotiation. + +## Relationship to Existing Decisions + +This note partially supersedes the implementation fact in [Client tool presentation ownership](2026-08-08-client-tool-presentation-ownership.md) that “card models receive Host views.” Its core decisions remain: `ui-tool` owns presentation, business plugins use keyed slots, and Conversation owns only lifecycle and topology. + +This note preserves [toolview dissolution](2026-07-23-toolview-dissolution.md): the Client still has one slot registration model and does not restore `ToolViewRegistry`. + +This note narrows the consumer scope of the [render-intent union](2026-07-02-tool-render-intent-union.md). The Host APIs and types remain, while the Session Remote and Web Client do not consume them. This note owns the transport split without rewriting that presenter decision. + +This note updates the entry contract from [Session history and Remote event transport](2026-08-18-session-history-and-event-transport.md): the journal transports only raw events plus an independent projection baseline, not transient tool views. + +This note follows [Conversation Node assembly](2026-08-09-client-conversation-node-assembly.md): the Tool Definition owns event pairing and the call tree, while concrete card models remain in `ui-tool`. + +This note preserves result metadata from the [canonical tool output contract](2026-07-20-canonical-tool-output-contract.md), because it is the lossless, replayable input to Client derivation. + +## Deferred + +- A separate explicit decision may evaluate deleting Host presenters if they remain without production consumers; this decision does not prejudge it. +- Specialized cards for Code Dispatch subcalls require a separate design and visible-snapshot updates; this decision preserves current behavior. +- A third-party mutation tool that joins Deliverables requires a new Client-owned contribution; this decision does not create a registry for an absent consumer. +- Distinct Client presentation for same-named providers first requires a stable, non-presentational identity; it must not restore per-page Host views. +- If Client card-model performance needs measurement, an immutable-block microbenchmark can be added; the shipped architecture already prohibits scanning the Session window. diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md new file mode 100644 index 0000000000..31d3a9f082 --- /dev/null +++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md @@ -0,0 +1,696 @@ +# Agent Note: Client 从原始 Session 工具事件派生展示 + +Status: implemented + +[English](2026-08-23-client-derived-tool-presentation.md) | 中文 + +## Problem + +Session 历史是持久 journal 接口，工具卡片属于 Client 展示。在 `page`／`follow` 中计算卡片 view 会让历史读取依赖 Tools registry、Agent preset、恢复后的 scope、presenter 执行和临时 UI 类型。 + +`tool/result` 不重复记录工具名称和参数。Host 端结果展示因此需要 call index 或按 `callId` 回扫；`maxMessages` 不直接限制事件数量，工具密集页面上的重复扫描可能接近二次方成本。 + +Host 投影还会重复结构化数据。read、diff、search 与 web 结果已在 `tool/result.data.meta` 中持久化有界事实；另一份 view 只增加 Remote payload 与 Client 解码成本，不增加持久语义。 + +Client 已经拥有完整的工具展示入口。`ui-chat` 将 `tool/call`、`tool/result` 与 Code Dispatch 事件组装成稳定的 `ToolCallBlock`；`ui-tool` 拥有递归调用树、按工具名称分发的 `tool.call.toolview` keyed slot、Generic fallback、卡片模型和 details output；业务 Client 插件可以为自己的工具名称注册 renderer。 + +Host presenter 与 Client keyed renderer 分担展示会形成对同一事件的两套解释。keyed renderer 是 Web 扩展点，因此中间 Host view 不提供独立 Web 能力。 + +`ToolDefinition.presentCall`／`presentResult` 仍是保留的 Host API；ACP 采用 automation-only 协议，仓库也没有生产 TUI consumer。是否删除这些定义与 Session 读取是否独立于展示是两个决定。 + +所需结果是一条原始 Session journal 和一个 Client 展示 owner，且不发生可见退化或顺带增强。专用卡片、交互和 Code Dispatch 拓扑保持稳定，transport 不再携带临时 view。 + +## Decision + +Session Remote journal 只下发原始、已验证、可持久化的 Session event。`session.page` 和 `session.follow` 不解析工具参数，不查询 Tools registry，不恢复 presenter scope，不执行 `presentCall`／`presentResult`，也不构造或克隆任何 tool view。 + +Client Conversation 层继续负责工具调用与结果的 identity、配对、生命周期、Code Dispatch 拓扑和稳定 Chat Node。它不解释具体工具名称，也不生成 terminal、diff、read、search 或 web 组件 props。 + +Client `ui-tool` 继续负责 card model 和具体 renderer。每个 card model 改为直接读取 `ToolCallBlock` 中的工具名称、原始参数、结果内容、错误、持久 metadata、Session cwd 与 Host home，并生成与现有页面相同的组件 props。 + +Client 不建立第二套 presenter registry。工具名称分发只使用现有 `tool.call.toolview` keyed slot；Client 中的纯 card-model helper 属于 renderer 实现，不成为 Cordis service、公开 registry 或 wire DTO。 + +Host 的 `ToolDefinition.presentCall`、`ToolDefinition.presentResult`、`ToolCallView`、`ToolResultView` 及现有 presenter 实现全部保留。Session Controller 不调用它们，Client 不导入或消费它们；未来非 Client consumer 是否使用它们不属于本决定。 + +`ToolOutputDefinition.presentationMeta` 与持久 `tool/result.data.meta` 保留。它们携带模型可见结果文本无法无损表达、而现有专用卡片需要的执行结果事实。Client 直接校验并消费 `meta`，不要求 Host 在历史读取时再把它转换成 view。 + +### 目标与非目标 + +| 类别 | 决定 | +|---|---| +| 不存在 | `SessionEventEntry.view`、`SessionToolView`、`SessionToolCallView` | +| 不存在 | `history.ts` 的 `viewFor`、`backscanArgs`、`parseToolCall`、`jsonView` 与 presenter scope lookup | +| 不存在 | follow 中只服务 presentation 的 `openCalls` 与 fallback event scan | +| 不存在 | Client Session 的平行 `views` 数组、Conversation input 的 `view`、Tool block 的 `callView`／`resultView` | +| 派生 | terminal、diff、read、search、web card model 读取 raw block/meta | +| 派生 | Deliverables 读取成功 mutation 的名称与参数 | +| 保留 | Host `ToolDefinition.presentCall`／`presentResult` API、类型、实现与直接测试 | +| 保留 | `output.presentationMeta` 与持久 `tool/result.data.meta` | +| 保留 | Session 日志格式、Remote journal 生命周期与 Conversation identity/topology | +| 保留 | 现有 keyed slot、Generic fallback、Chat、Details 与 Trajectory 结构 | +| 禁止 | 新 Client presenter service、平行 registry 或 wire renderer id | +| 禁止 | 新卡片、视觉改版、交互改版或 Code Dispatch rich-card 增强 | +| 禁止 | 为兼容保留双写、版本协商或旧 `view` 字段 | + +## 术语 + +**原始 Session event**指持久日志中的 `SessionEvent` 事实，包括 `tool/call` 的 `name` 与原始 `arguments` 字符串，以及 `tool/result` 的 `content`、`isError`、结构化错误和可选 `meta`。 + +**持久 metadata**指 `ToolOutputDefinition.presentationMeta` 在工具成功执行时生成并写入 `tool/result.data.meta` 的 JSON 值。它是结果事实的一部分，不是预先排版的 React 或 card DTO。 + +**Host tool view**指 `ToolDefinition.presentCall`／`presentResult` 返回的 `ToolCallView`／`ToolResultView`；Session Remote 不运输它。 + +**Client card model**指 `ui-tool/src/client/tool/models/` 下直接供 `TerminalBlock`、`DiffBlock`、`ReadBlock`、`SearchBlock`、`WebBlock` 或 `ToolRow` 使用的纯 props 数据。 + +**专用卡片**指 terminal、diff、read、search 与 web 的结构化正文；标题、摘要、状态点和普通 IN／OUT 文本仍属于通用工具行。 + +**对等**指同一受支持输入产生由现有组件、组装与浏览器证据固定的用户可见结果和交互，不要求相同的中间 TypeScript 类型或内部函数调用。 + +**无增强**指本决定不让被固定为 Generic fallback 的输入获得新专用卡片，也不扩大已有卡片的数据或交互。 + +## 架构与所有权 + +### 工具执行与持久化 + +1. 工具注册 `output.schema`、`output.render` 和可选 `output.presentationMeta`。 +2. 成功执行产生 canonical JSON value。 +3. Tools runtime 对 value 做快照、schema 校验和冻结。 +4. `output.render(args, value)` 生成模型可见 `ContentBlock[]`。 +5. 顶层调用若声明 `output.presentationMeta`，runtime 同时生成 JSON-safe metadata。 +6. Agent loop 把模型可见结果与 metadata 写入 `tool/result` Session event。 +7. Session log 不保存 `ToolCallView` 或 `ToolResultView`。 + +### Host journal 读取 + +1. `session.page` 取得 attached 或 persisted 事件。 +2. `paginate()` 按 append-origin user／assistant message 边界切页。 +3. tail page 通过已注册 projection 的 snapshot/restore 路径取得 baseline。 +4. 每个 page entry 只包含 `{event}`。 +5. `session.follow` 先建立 listener，再执行 catch-up read、发送 opening cursor 并流式下发连续 `{event}` frame。 +6. 两条路径都不为展示解析 preset／Tools scope、解析工具参数、调用 presenter 或建立 call index。 + +### Client 数据与展示 + +1. Client Session 保存一个连续 raw event window。 +2. `SessionEventSource` 发布只含 event 的 `SessionEventEntry`。 +3. `ui-conversation` 在没有 presentation companion 的情况下 fold 每个事件。 +4. Chat 与 Trajectory Tool Definition 按 callId 配对顶层 call/result，并组装 Code Dispatch 子树。 +5. `RunningToolCall` 与 `ToolResultNode` 保存 raw facts、metadata 与既有 parent identity。 +6. `ToolCallTree` 按 wire tool name 分发 `tool.call.toolview`。 +7. `ui-tool` 在 render site 从 block 派生 card component props。 + +### 生产消费者审计 + +| 对象 | 生产者 | 生产消费者 | 决定 | +|---|---|---|---| +| `presentCall`／`presentResult` | 各 Host 工具 | 可能存在的非 Client caller | 保留在 Session Remote 之外 | +| `SessionEventEntry.view` | 无 | 无 | wire 不存在 | +| `callView`／`resultView` | 无 | 无 | Client model 不存在 | +| `presentationMeta` | Tools runtime | `tool/result`、Client card model 与 Host presenter | 保留的持久输入 | +| fixture presenter mirror | 无 | 无 | fixture 下发 raw metadata | + +ACP 不消费 Session tool view，也不映射 Host render intent。仓库没有生产 TUI consumer；Host presenter 保留，但 Session Remote 不作为其 transport。 + +## 数据流 + +```text +Tool execute + -> canonical value + -> output.render(args, value) + -> model-visible result content + -> output.presentationMeta(args, value), when declared + -> durable tool/result event + +Session page/follow + -> raw Session event envelope + -> no tool lookup + -> no preset lookup for presentation + -> no call backscan + -> no render-intent serialization + +Client SessionEventSource + -> Conversation Tool Definition + -> root call/result pairing + Code Dispatch topology + -> ToolCallBlock(name, argsRaw, content, error, meta) + -> tool.call.toolview keyed dispatch + -> Client card model + -> existing React component +``` + +这条链路保留一次持久 metadata 投影，因为它发生在 canonical result 尚在内存时；删除的是读取历史时的第二次展示投影。 + +### 分层责任 + +| 层 | 负责 | 不负责 | +|---|---|---| +| Tools runtime | 执行、canonical value、模型文本、可重放 metadata | Web 卡片选择和组件 props | +| Session log | 持久事实、顺序、回放 | 临时 card DTO | +| Session Controller | 地址、权限、冷读、分页、follow、projection baseline | tool lookup、presenter、展示 scope | +| Client Session | Remote journal 生命周期与连续窗口 | 工具含义、卡片类型 | +| Conversation Tool Definition | call/result 配对、lifecycle、root/subcall topology | 工具名到组件的解释 | +| `ui-tool` | card model、通用 fallback、Chat/Details 展示 | Session 分页与 Host registry | +| 业务 Client 插件 | 自有 tool name 的 keyed renderer | root/subcall 编排与全局 registry | +| `ui-deliverables` | 当前第一方 mutation 的 produced path | UI card 或 Host render intent | + +## Remote 与持久数据约定 + +### `SessionEventEntry` + +`SessionEventEntry` 保留为 journal entry envelope，只含 `event: SessionWireEvent`。本次不顺带把 page entries 改成裸事件，也不重构 `RemoteJournalStream` 的通用 entry 约定。 + +`SessionPage.events` 仍是 `SessionEventEntry[]`。 + +`SessionFollowFrame` 仍是 opening frame 或带 `event` 的 event frame。 + +删除 `SessionToolCallView`、`SessionToolView` 和 `SessionEventEntry.view`。 + +Client connection 不再从 `dsh-tools/presentation` 转出 `ToolCallView`／`ToolResultView` 供 Session 消费。 + +生成 catalog 与 graph 从各自 source owner 派生已收窄的 Remote 类型和 package dependency。 + +### 持久日志 + +- `tool/call.data.name` 保持原样。 +- `tool/call.data.arguments` 保持模型产生的原始 JSON 字符串。 +- `tool/result.data.message.content` 保持模型可见结果。 +- `tool/result.data.error` 保持结构化失败身份。 +- `tool/result.data.meta` 保持工具私有 JSON 值。 +- Client card model 不写入 Session log。 +- renderer key 与 Host tool implementation id 不写入 Session log。 +- 现有持久 Session 无需迁移，`SESSION_FORMAT_VERSION` 不变。 + +### `presentationMeta` + +`presentationMeta` 不是 Host tool view。它在工具执行完成时读取 canonical value，而该 value 不会持久化；删除它会使下列现有展示无法无损恢复： + +- read 的 path、offset、lines、totalLines 与 lang； +- write/edit 的 applied contextual hunks； +- grep/glob 的分组结果、截断标志与总数； +- web_search 的来源字段与 provider answer； +- web_fetch 的最终 URL、HTTP status 与有效截断标志。 + +Client 对 `meta` 做局部运行时收窄。是否把 `presentationMeta` 改名为更中性的 result metadata 不属于本决定。 + +## Host 端设计 + +`SessionHistoryController.page()` 在取得 source events 后只执行分页与现有 projection baseline 计算。attached Session 使用 projection registry snapshot；detached Session 使用该 registry 对 inspected log 的 restore 路径。history 不通过挂载 preset 改变已注册的 projection 集合。 + +`SessionHistoryController.follow()` 保留 listener-first、opening cursor、gap-free replay、live buffering、取消和 teardown；它不为工具事件维护额外状态。 + +Controller 不存在 `presenterScopeFor()`、`viewFor()`、`backscanArgs()`、`parseToolCall()` 或 `jsonView()` 路径。page state 不含 presenter scope 或参数 resolver；follow state 不含 `openCalls`、`fallbackEvents` 或 presentation 参数 resolver。每个 page/follow event 只包装成 `{event}`，地址、ownership、cursor、seq 与 projection 逻辑保持完整。 + +不可变 event 转换 helper 可以保持窄实现或内联；只要 history 不执行 presentation 工作，其名称没有语义。 + +Session Controller dependency 只在其他 package responsibility 需要时保留；manifest 与 project reference 不含 presentation-only dependency。 + +### 性能约束 + +- `page()` 的工具相关工作为零。 +- 页面增加 tool result 不增加对既有页面事件的重复扫描。 +- `follow()` 不维护展示索引。 +- history 不触发 Cordis `tools` service proxy。 +- history 不等待 presenter standing scope。 +- history 不执行工具参数 JSON parse。 +- history 不执行 tool view JSON clone。 +- Remote payload 不重复携带 `meta` 已表达的结构化数据。 +- Client 不扫描完整 Session event window 生成单个卡片。 +- Client 只在对应 immutable Tool block 变化时重新派生 card model。 + +## Client Session 与 Conversation + +Client Session 不含与 raw event window 平行的私有 `views` 数组。`installWindow()`、`prependWindow()` 和 `appendLive()` 只处理 event entries、cursor/hasMore、queue、projection 与通知。 + +`ConversationEventInput` 只携带 `event`。Conversation assembler 不认识 `SessionToolView`，其 replace/prepend/append、Context identity、Location 与 publication cadence 不变。 + +Chat 和 Trajectory 的 Tool Definition 都不读取 view，而从事件生成以下数据： + +- callId； +- tool name； +- raw arguments； +- turn、step、seq 与 time； +- result content； +- isError 与 structured error； +- result metadata； +- root/subcall parent-child topology； +- interruption synthetic result。 + +`RunningToolCall` 不含 `callView`。 + +`ToolResultNode` 不含 `callView` 与 `resultView`。 + +`ToolCallBlock` 不新增通用 `view`、`card`、`kind` 或 `locations` 字段替代被删除字段。具体展示仍只属于 `ui-tool` 与 keyed renderer。 + +### Root 与 Code Dispatch 子调用 + +Host presenter API 描述顶层 call/result。Code Dispatch 子调用使用 Generic/flattened Client 展示；Client 能识别子调用名称并不赋予它结构化卡片。 + +Code Dispatch start 与 result event 已经携带 `parentCallId`。Conversation 在每个 child `ToolCallBlock` 上保留这项现有事实，root Session call 则不携带它。五类结构化 card model 只接受没有 `parentCallId` 的 block，原本有意支持嵌套调用的 renderer 则继续收到同一个 child block。 + +Details panel 原样委托选中的 block。同一组 card model 读取 `parentCallId`，让选中的 Code Dispatch child 保持现有 raw fallback，因此 Details slot 不需要 placement 字段。 + +keyed slot 仍按每个子调用的真实 tool name 分发；`parentCallId` 只控制本决定覆盖的 terminal/diff/read/search/web 结构化模型。Skill、Cordis 等已经直接读取 raw block 的专用 renderer 保持现状。 + +### 缺失调用头 + +结果节点在当前窗口没有配对 call 时，`ToolResultNode.call` 保持 `null`。Client 不扫描窗口、不发额外 RPC，也不根据 result 文本猜测工具名称。 + +需要名称或参数的专用派生在 `call === null` 时走当前 Generic fallback。只依赖 result metadata 的模型也不借机增强，因为当前 Host `presentResult` 必须先取得配对调用。 + +older page 后续补入调用头时，Conversation Context 按既有 replay 规则重建，届时才允许生成当前已有的专用卡片。 + +### 参数与 metadata 收窄 + +Client 从 `argsRaw` 解析 JSON，解析失败返回 Generic，不抛出 React render 错误。 + +Chat 与 Details 通过纯 helper 复用同一 block 的解析。未来缓存必须使用 immutable block identity，不能按 callId 建立跨 Session 全局状态。 + +每个专用模型只检查它需要的字段。Client 不复制完整 Host tool schema，也不调用 Host `defineTool` validator。 + +合法第一方事件必须与当前 presenter 输出等价。畸形、旧版本或手工修改日志只承诺不崩溃并使用 Generic fallback。 + +## Client card-model 设计 + +现有 `ui-tool/src/client/tool/models/` 继续是 Chat 与 Details 共享派生的唯一位置。helper 直接返回组件 props，不返回 `ToolCallView`／`ToolResultView`，也不创建同构的 `ClientToolView` union。 + +工具名称分支只存在于 `ui-tool` card model、现有 row 分类表，或拥有该工具 keyed renderer 的 Client 插件；不得进入 Session Controller、Client Session、Conversation assembler 或通用 Slot renderer。 + +未知工具继续由 `GenericToolCard` 显示 name、原始 args、结果 content 与错误。 + +### 通用工具行 + +`toolRowModel()` 直接从 `toolName`、`argsRaw`、result content、error、cwd 与 home 派生通用行，并保持以下行为： + +- `search`、`read`、`bash`、`write`、`edit`、`code` 与 `others` 分类； +- 现有标题与工具专用标题； +- summary 字段优先级和单行截断； +- 多 query 的逗号拼接； +- cwd 相对化与 home 缩写； +- file path 点击； +- args pretty JSON 与非 JSON 原文 fallback； +- result content flatten 与 structured error fallback； +- running、ok、error 与 stopped 状态。 + +Generic Host `presentCall` 的 title、kind、rawInput、content 与 locations 当前并不驱动普通 Web 行；Generic `presentResult.content` 也不驱动 Web 输出，因此无需把这些未消费值复制到 Client。 + +### Terminal 卡片 + +Client terminal model 从工具名称、调用参数、结果 content、error、现有 `parentCallId` 与 Session cwd 派生现有 `TerminalBlock` props。 + +| 输入 | 保持的结果 | +|---|---| +| 标准 `bash`／`pwsh` 前台 running | terminal prompt、description、cwd、running 状态 | +| 标准前台 success | terminal output、exit code/signal、成功或失败状态点 | +| `run_in_background:true` | Generic 行与原始结果 | +| 工具执行 error | Generic IN／OUT 与错误摘要 | +| persistent `bash`／`pwsh` running | terminal prompt | +| persistent `bash`／`pwsh` settled | Generic flattened result，不新增 exit card | +| `terminal_send` 前台 | terminal prompt 与 output | +| `terminal_send` background/error | Generic 结果 | +| Code Dispatch child | 当前 flattened Generic 形态 | + +标准 shell 结果继续解析末尾 `[exit code: N]` 与 `[killed by signal: X]`。已解析的 marker 从正文移除；timeout、sandbox denial 与没有 pill 的 marker 留在正文。 + +调用 `description` 继续显示在 card 上方并覆盖折叠摘要。workdir 继续按绝对、相对和缺失三种情况处理；相对路径基于 Session cwd，且保留 `.`、`..`、盘符与 UNC root 的归一化。 + +同名普通与 persistent provider 是特殊兼容点。Client 使用当前有效参数与结果特征保留已交付差异；不足以无歧义识别的输入选择 Generic settled 结果，不增加新表现。 + +TerminalBlock 的 ANSI、光标重放、宽字符、行数上限、展开、复制与辅助技术文本完全不变。 + +### Diff 卡片 + +| 输入 | 保持的结果 | +|---|---| +| running `write` | 从 `file_path` 与 `content` 生成 intended added-only diff | +| running `edit` | 从 `file_path`、`old_string`、`new_string` 生成 intended replacement diff | +| settled `write`／`edit` success | 从 `meta.diffs` 生成 applied contextual hunks | +| write create 或 applied metadata 缺失、畸形、为空 | 当前 args fallback | +| error、畸形 args、edit 的 metadata 畸形、Code Dispatch child | Generic | + +路径、`oldText:null`、`newText`、结果覆盖调用时 diff、Chat 8 行上限、Details 全高显示和文件打开行为不变。 + +### Read 卡片 + +running `read` 继续只有摘要行。成功 settled `read` 从 result meta 读取 path、offset、lines、totalLines 与 lang，并确认结果是单个文本块且符合 read envelope。 + +meta 缺失、字段畸形、result envelope 不匹配、error、缺失 call head 或 Code Dispatch child 都走 Generic。路径 label 的 cwd 相对化、home 缩写、语法语言、总行数、Chat 8 行上限与 Details 全高显示不变。 + +Client 不需要构造 Host `ReadResultView.content`；Generic fallback 始终可直接读取原始 result content。 + +### Search 卡片 + +running `grep`／`glob` 继续只有参数摘要。成功结果分别从 `meta.shape:'matches'` 与 `meta.shape:'paths'` 生成 grouped matches 或 path list。 + +Client 校验 path、lineNumber、line、truncated 与 total。空 matches/paths 是有效卡片；缺失/畸形 meta、未知 shape、error、缺失 call head 与 Code Dispatch child 走 Generic。 + +`truncated:true` 时继续从原始 result content 显示 recovery locator；未截断时不显示。Chat 8 行上限、Details 全高显示和展开行为不变。 + +### Web 卡片 + +running `web_search`／`web_fetch` 继续只有摘要行。成功 search 从 `meta.sources`、`meta.answer`、`meta.truncated` 生成卡片；成功 fetch 从 `meta.url`、`meta.statusCode`、`meta.truncated` 生成卡片。 + +Client 校验每个 source 的 url、title、snippet 与 publishedAt，并继续只把 http/https URL 渲染为链接。meta 缺失或畸形、error、缺失 call head 与 Code Dispatch child 走 Generic。 + +search 的 answer、来源顺序、label fallback 与截断提示不变；fetch 的最终 URL、状态、截断提示与 Details 下方原始正文不变。 + +### 已直接使用 raw block 的 renderer + +- Todo row 继续从 args 计算 completed/active 摘要。 +- Question row 继续从 result content 与 error 计算等待、回答、取消和中止状态。 +- Skill row 继续从 args/result 计算名称与状态。 +- Cordis define/run/action rows 继续从 args/result 与各自 Client service 计算。 +- 这些 renderer 的 props、slot key、注册顺序与可见结果不变。 + +## Deliverables + +`ui-deliverables` 独立于展示意图派生 mutation 业务事实，因此 produced-file 行为不与卡片截图耦合。 + +Deliverables Definition 按 callId 观察 root `tool/call` 与成功 `tool/result`，保存最小的 Client-owned mutation candidate，不扫描 Session window，也不依赖 UI renderer。 + +| 工具 | mutation 判定 | path 来源 | +|---|---|---| +| `write` | 任意成功调用 | `file_path` | +| `edit` | 任意成功调用 | `file_path` | +| `str_replace_editor` | `create`、`str_replace`、`insert` | `path` | +| `str_replace_editor` | `view` | 不产生 path | +| 其他 | 无当前第一方 mutation 语义 | 不产生 path | + +失败、interrupted、orphan result、缺失 path 与畸形 args 不产生 deliverable。同一路径保持 first-seen 去重，closing Assistant seq 之后落定的结果继续排除。 + +本次不新增通用“工具副作用”注册表。Host-only 第三方 presenter 通过 `kind:'edit'`／`locations` 自动加入 Deliverables 的能力被有意移除；未来若有真实第三方 mutation 需求，应由 Client 业务贡献表达，不能恢复 Session view。 + +## Fixture 与测试数据 + +Client fixture 删除手写 `presentCall()`、`presentResult()`、`viewFor()` 与 fixture tool-view 类型。它继续产生与真实日志相同的 raw call、result content 和 result meta。 + +| Fixture | 必须保留的原始事实 | +|---|---| +| terminal | 参数与真实结果 status marker | +| diff | 参数与 result `meta.diffs` | +| read | result meta 的 path/offset/lines/totalLines/lang | +| grep/glob | result meta 的 shape/files 或 paths/truncated/total | +| web | result meta 的 sources/answer 或 url/statusCode/truncated | +| generic/custom | name、argsRaw、content、error | + +fixture 不导入 Host 工具包来计算页面展示，也不保留 presenter 镜像。同一 raw fixture 继续驱动 jsdom、built Web snapshot 与 `?fixture` 浏览器路径。 + +## 展示等价矩阵 + +“当前展示”由已提交的组件测试、组装测试与 Web browser expected 共同定义。transport 或 ownership 重构不能作为 refresh snapshot 的理由；获批产品变化需要独立证据。 + +| 场景 | 必须保持的展示 | +|---|---| +| 未知工具 running | Generic 行，工具名与 args 摘要 | +| 未知工具 settled | Generic 行与原始 output | +| malformed args | 安全 Generic fallback | +| orphan result | callId 标题与 Generic output | +| interrupted call | warning/stopped 状态 | +| bash/pwsh 前台 | 当前 terminal prompt、正文、cwd 与状态 | +| bash/pwsh background/error | 当前 Generic IN／OUT | +| persistent shell | 当前 running terminal、settled Generic | +| terminal_send | 当前前台 terminal、后台/error Generic | +| write/edit | 当前 intended/applied diff 与 error fallback | +| read | 当前 running 摘要、settled ReadBlock 与 error fallback | +| grep/glob | 当前 grouped/path card、截断与 recovery | +| web_search/web_fetch | 当前来源/摘要 card 与原始正文 | +| Todo/Question/Skill/Cordis | 当前专用行 | +| Code Dispatch subcall | 当前 Generic/flattened 形态 | +| Chat 与 Details | 同一调用使用相同 card fields | +| Trajectory | 当前 identity、树、选择和 details | +| Deliverables | 当前成功 mutation chips 与链接 | + +## Client 扩展约定 + +`tool.call.toolview` 继续是唯一工具 UI 注册机制。一个工具若要在 Client 获得专用表现，必须由 Client 插件注册自己的 wire tool name。 + +注册方接收 raw `ToolCallBlock`、Session path 信息和宿主动作，自行校验它认识的 args/meta 字段。注册方不调用 Host tool registry，不依赖 `presentCall`／`presentResult`，也不能要求 `SessionEventEntry.view`。 + +没有 Client renderer 的工具稳定降级为 Generic。同一 tool name 只能有一个生效 keyed registration，重复 key 继续 loud failure。 + +Session-scoped slot 可以表达 Client 侧会话差异，但不从 preset 推断 renderer 变体。Host-only presenter 不自动赋予 Web rich card，这是“Host 描述展示”与“Client 插件拥有展示”的明确边界。 + +## 失败与 fallback + +- Client 把 args 与 meta 当作 wire JSON，在消费点收窄。 +- 参数 JSON 解析失败走 Generic。 +- 已知工具缺少必要字段走 Generic。 +- metadata 缺失或畸形走 Generic；成功 `write` 例外，它按当前 presenter 行为保留由参数派生的整文件 diff。 +- error result 不因 metadata 存在而显示成功卡片。 +- 缺失 call head 不猜测工具名称或参数。 +- 未知 metadata 字段被忽略。 +- 新 metadata variant 在旧 Client 中走 Generic。 +- card-model helper 捕获可预期解析失败，不依赖 React error boundary 完成普通 fallback。 +- keyed renderer 自身的意外异常仍由现有 Slot error isolation 处理。 + +## 同名 Host provider + +Host registry 允许不同 scope 为同一 tool name 提供不同定义；Session view 通过 presenter scope 理论上可以按 preset 选择不同 render intent。删除 view 后，Client keyed slot 只观察 wire name，不能观察 Host definition identity。 + +当前第一方显著实例是普通与 persistent `bash`／`pwsh`。Client 派生使用有效参数与结果特征保持它们的已交付差异，不增加 provider-id wire 字段；无法判别的畸形或自定义同名 provider 输入采用 Generic。 + +本次不承诺保留第三方同名 provider 仅通过 Host presenter 表达的差异。若未来产品确需同名 provider 的不同 Client 展示，必须定义稳定、非展示性的 Client identity；不得恢复按页 Host view 计算。 + +## 已交付范围 + +### Session Controller + +- `SessionEventEntry` 只包含 raw event。 +- 两个 Session tool-view 类型都不存在。 +- history 不含 presentation import、helper 或 page/follow presentation state。 +- 地址、分页、follow 与 projection 逻辑仍由 Session owner 负责。 +- Host 测试固定 raw journal 约定。 + +### Session Controller Client + +- `Session.views` 不存在。 +- EventSource replace/prepend/append delta 保持不变。 +- transport、fixture 与 test-support 类型携带 raw entry。 +- event identity 与引用稳定性保持不变。 + +### UI Conversation、Chat 与 Trajectory + +- Conversation input 与 Tool block 不含 view 字段。 +- Chat/Trajectory Tool Definition 读取 raw event。 +- event pairing、Context replay、树与 target snapshot 保持不变。 +- child Tool block 保留现有 Code Dispatch `parentCallId`；row 与 Details slot owner props 都不增加独立 placement 字段。 + +### UI Tool 与 Deliverables + +- card model 从 raw block/meta 派生。 +- Chat 与 Details 复用相同 helper。 +- Generic fallback 与 keyed dispatch 保持不变。 +- Deliverables 识别第一方 mutation args。 + +### Fixture、文档与生成物 + +- fixture 只发 raw event/meta。 +- Session Controller 与 Client README/JSDoc 描述 raw journal 和 Client presentation owner。 +- 工具 cookbook 记录 Web Client 接入路径。 +- 本文是该决定的 owner；保留的 Host presenter Note 继续拥有各自决定。 +- 手写 Remote 类型、dependency、README、pairing record 与 generated reference 保持同步。 + +## 验证矩阵 + +### Host + +- page 返回连续 raw event entries。 +- follow 返回 opening cursor 与连续 raw event entries。 +- page/follow 在无 Tools service 时行为相同。 +- cold page 不解析或挂载 preset。 +- tail page 通过标准 projection registry 计算 baseline；provider 是否存在由 projection composition 决定，不引入 history 侧 setup 路径。 +- 地址、ownership、message-aligned boundary 与 tail projection 不变。 +- listener-before-read、reconnect catch-up 与 gap repair 不变。 +- 大量 tool results 不触发每结果回扫。 +- wire 结果不含 view。 + +`session-history-journal.host.spec.ts` 负责分页、连续性和 history error 行为，不含 presenter 断言。 + +### Client Conversation + +- replace、prepend 与 append 接受无 view entry。 +- Chat 与 Trajectory root call/result 配对不变。 +- Code Dispatch 树不变。 +- result-only fallback 不变。 +- interruption synthetic result 不复制 view。 +- registry rebuild、older prepend 与 live append 的 Node identity 不变。 + +### Client card model + +- terminal 用 raw args/content 得到已固定的 props。 +- diff 用 args/meta 得到已固定的 diffs。 +- read 用 meta/content 得到已固定的 lines。 +- search 用 meta/content 得到已固定的 grouped/path card 与 recovery。 +- web 用 meta/content 得到已固定的 sources/fetch summary。 +- unknown、malformed、error、missing-call 与 missing-meta 继续 Generic。 +- `parentCallId` 缺失与存在的用例证明结构化展示不会到达 Code Dispatch descendant。 +- Chat 与 Details 对同一 block 得到相同 card fields。 + +### Deliverables + +- write/edit 成功产生 `file_path`。 +- str_replace_editor create/str_replace/insert 产生 `path`。 +- str_replace_editor view 不产生 path。 +- failure、interrupted、malformed 与 orphan 不产生 path。 +- first-seen 去重与 closing seq cut 不变。 + +### 组装与浏览器 + +- terminal、diff、read、search、web browser expected 不刷新并全部通过。 +- tool tree、details、trajectory 与 deliverables 的可见断言不改预期。 +- built Client 通过真实 Remote page/follow 取得 raw events 后仍显示同样卡片。 +- fixture 与真实 Host 使用同一 Client derivation。 +- minimal preset 单独固定 persistent shell 行为。 + +### 静态与文档 + +- 生产代码不存在 `SessionToolView`／`SessionToolCallView`。 +- Session history 不引用 `dsh-tools/presentation`、`ctx.tools`、`presenterScopeFor` 或 `backscanArgs`。 +- Client Conversation 不引用 `ToolCallView`／`ToolResultView`。 +- Client model 不读取 `callView`／`resultView`。 +- fixture 不定义 presenter mirror。 +- Host `presentCall`／`presentResult` 与 `presentationMeta` 仍存在。 +- 没有新增 Client registry 或 Host→Client presentation hint。 +- 受影响的手写类型、README、Agent Note、catalog 与 graph 保持同步。 + +## 验证命令 + +修改本决定时使用 `dsh-pre-push-checks` 按最终 diff 选择命令；所需证据包括： + +- Session Controller history/transport 聚焦测试； +- ui-chat 与 ui-trajectory Tool Definition 测试； +- ui-tool terminal、diff、read、search、web、row、tree 与 details 测试； +- ui-deliverables produced-files 测试； +- connection fixture 与 Client runtime 测试； +- 受影响 Host/Client TypeScript face； +- lint 与 duplication； +- 受影响源文件 per-file 100% coverage； +- `DSH_SNAPSHOT=replay pnpm run test:web`，不得 refresh 现有展示 golden； +- 手写 Remote 类型与 TypeScript 检查； +- `pnpm run doc-sync`； +- `git diff --check`。 + +## 已交付不变量 + +- Session page/follow 不读取 Tools registry 或 presenter scope。 +- Session history 不存在 callId backscan、presentation cache 或 view clone。 +- Remote Session entry 不携带 view。 +- Session 日志与 `SESSION_FORMAT_VERSION` 不变。 +- result meta 逐字节通过日志与 Remote 到达 Client。 +- Conversation 只从 raw event 组装 ToolCallBlock。 +- ToolCallBlock 不含 Host render-intent 字段。 +- 五类结构化 card model 只读 raw block、其现有 `parentCallId` 与 Session path facts。 +- Generic、Todo、Question、Skill 与 Cordis 行行为不变。 +- Deliverables 不依赖 render intent 且保持当前 paths。 +- 所有第一方顶层工具的文本、组件、展开内容、状态、链接与排序不变。 +- malformed、missing-meta、error、orphan 与 unknown-tool 继续安全 fallback。 +- Code Dispatch 子调用保持 Generic/flattened。 +- Chat、Details 与 Trajectory 行为不变。 +- 现有 Web browser expected 无需刷新即可通过。 +- Host presenter API、实现与直接测试不变。 +- ACP 输出不变。 +- 没有新下行展示字段或第二套 Client registry。 +- 分页成本不再随 result 数量乘以页面事件数增长。 +- 下行 payload 不再重复 result meta 的 card DTO。 + +## Alternatives considered + +### 只优化 `backscanArgs`，保留 view + +page 前建立一次 `callId → {name,args}` Map 可以把回扫降为线性，live 已有 `openCalls` 快路径；但 Host lookup、preset scope、presenter、JSON clone、重复 payload 和双重所有权仍存在，因此拒绝。 + +### 在 Client 建 presenter registry + +把 `presentCall`／`presentResult` 接口复制到浏览器会与 `tool.call.toolview` slot 重复注册、生命周期、fallback 和覆盖语义；renderer 仍需把 presenter DTO 转成组件 props，因此拒绝。 + +### 让 Conversation Tool Definition 生成统一 view + +这会把工具名称和 UI card 语义放进 target-neutral Conversation owner，并重建与 Host view 同构的中间 DTO，因此拒绝。 + +### 删除 `presentationMeta` + +read 行结构、applied diff、search 分组、web sources 和有效 truncation 无法从模型文本无损恢复；解析自由文本也会把 UI 绑到输出措辞，因此拒绝。 + +### 持久化 canonical tool result + +这会扩大 Session log、暴露内部结果结构、改变持久格式，并可能保存远超展示所需的大对象；已有 metadata 足够，因此拒绝。 + +### 删除 Host presenter API + +一并删除可以继续收缩代码，但本决定保留 Host `presentCall`／`presentResult`；其 API、实现、测试与类型独立于 Session Remote。 + +### Client 导入 Host 工具实现 + +工具包包含 Node、filesystem、subprocess 或 provider 依赖，不能进入浏览器 bundle；Client 只消费 raw JSON，并在自己的 renderer 内维护窄解析，因此拒绝。 + +### 按结果向 Host 查询 presentation + +按需 RPC 会把一页读取变成 N 次网络调用，仍需 Host lookup、scope、callId 查找与错误协调，因此拒绝。 + +### 允许展示增强 + +Client 可以为 Code Dispatch 子调用、缺失 call head 或 Host presenter 不可用的历史生成更多 rich card，但这会混淆 ownership 变化与产品行为，并使快照无法证明对等，因此拒绝。 + +### 接受临时 Generic 退化 + +先停发 view 再逐步补 Client card 会让 terminal、diff、read、search、web 与 Deliverables 在中间版本退化。Client 对等实现与 Host 删除必须在同一可发布变更中完成。 + +## Consequences + +本决定从 Session 读取中删除 presentation 工作、重复扫描和重复 view payload；代价是保留的 Host presenter 与 Client card derivation 可以独立演进，因此两侧都需要 owner 专属测试，Web 展示对等仍是明确产品约束。 + +### Client 与 Host 逻辑漂移 + +同一工具可以有一份 Host render intent 和一份 Client card derivation。两者面向不同消费方，不共享运行路径；不刷新的 browser expected 固定第一方 Web 视觉对等，Host presenter 测试只约束 Host API。 + +### 同名 provider 无稳定 identity + +raw event 只记录 tool name，不记录具体 ToolDefinition。Client 使用有效事件字段保留普通与 persistent shell 的差异；无法判别的自定义或畸形输入回退 Generic，wire 不为理论扩展性增加 hint。 + +### Metadata 是未知 JSON + +旧 Session 可能缺字段，手工修改日志可能带畸形值。每个 Client model 必须局部收窄，不能把未知数组或对象直接传给 UI primitive。 + +### 双 target 同步 + +Chat 与 Trajectory 各有独立 Tool Definition，两者都携带 raw fields；card derivation 只能留在 `ui-tool`，不能复制进两个 Definition。 + +### Deliverables 隐性依赖 + +Deliverables 不是视觉组件，因此 mutation parser 必须与受支持的第一方写工具保持同步；专用测试独立于卡片截图固定 file chips 与 Markdown links。 + +### Fixture 假绿 + +fixture 下发 raw event/meta，不下发手写 view。真实 Host 组装覆盖仍然必要，因为 fixture-only snapshot 不能证明 transport 路径。 + +### 错误刷新快照 + +本次承诺用户可见输出不变。出现 snapshot diff 时必须修 Client 派生；除非 owner 单独批准具体视觉变化，否则不得 refresh expected。 + +### 文档漂移 + +raw journal 或 Client presentation owner 变化时，Agent Note、package README、cookbook、根规则与 generated reference 必须一起更新；Host API 文档保持独立。 + +### Remote 协议收缩 + +optional `view` 的缺失是所有 consumer 共同遵守的预发布 wire 类型决定；没有兼容 shim、双写或版本协商。 + +## 与现有决策的关系 + +本文部分取代 [Client 工具展示所有权](2026-08-08-client-tool-presentation-ownership.zh.md) 中“card model 接收 Host view”的实现事实；`ui-tool` 拥有展示、业务插件使用 keyed slot、Conversation 只拥有生命周期与拓扑的核心决定保持不变。 + +本文保留 [toolview 溶解](2026-07-23-toolview-dissolution.zh.md) 的决定：Client 仍只有 slot 注册模型，不恢复 `ToolViewRegistry`。 + +本文收窄 [render-intent union](2026-07-02-tool-render-intent-union.zh.md) 的消费范围：Host API 与类型保留，Session Remote 与 Web Client 不消费它。本文独自规定 transport 拆分，不改写该 presenter 决策。 + +本文更新 [Session 历史与 Remote 事件传输](2026-08-18-session-history-and-event-transport.zh.md) 的 entry 约定：journal 只运输原始 event 与独立 projection baseline，不承载临时 tool view。 + +本文遵循 [Conversation Node 组装](2026-08-09-client-conversation-node-assembly.zh.md)：Tool Definition 负责事件配对与调用树，具体 card model 留在 `ui-tool`。 + +本文保留 [规范工具输出约定](2026-07-20-canonical-tool-output-contract.zh.md) 的 result metadata，因为它是无损、可重放 Client 派生的输入。 + +## Deferred + +- Host presenter 若长期没有生产消费者，可由另一项明确决策评估删除；本决定不预判。 +- Code Dispatch 子调用若要专用卡片，需单独设计并更新可见快照；本决定保持现状。 +- 第三方 mutation tool 若要加入 Deliverables，需新增 Client-owned 贡献；本决定不为尚无消费者的扩展性建 registry。 +- 同名 provider 若要不同 Client 展示，需先定义稳定、非展示性的 identity；不得恢复按页 Host view。 +- Client card model 若需量化性能，可以增加 immutable-block 微基准；已交付架构禁止扫描 Session window。 diff --git a/AGENTS.md b/AGENTS.md index 1928b25c31..3fa1ce77e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -124,7 +124,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, - **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)). - **Client UI copy is locale-owned.** Route product text through typed dictionaries and `t` or localized primitive props; `verify-client-ui-i18n` rejects hardcoded copy ([decision](.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)). - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible change updates a keyless runnable-example snapshot; package, e2e-only, and mock-only tests do not substitute. Fixtures replay on macOS/Linux; fix fixtures, not normalizers. -- **A tool's UI render intent is part of its design**, decided up front (`generic`/`terminal`/`diff`, `locations`); presentation methods are pure functions of `args` ([cookbook](docs/cookbook/adding-a-tool.md)). +- **Design each tool's UI presentation up front.** Host presenters stay pure; Web cards derive from raw events and persisted result metadata ([cookbook](docs/cookbook/adding-a-tool.md)). - **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change. - **Both SDKs project the loop.** Agent-loop, session-lifecycle, and `SessionEventMap` changes update the TypeScript and Python SDK expected outputs in the same PR; `pnpm run test` covers neither ([surfaces](docs/testing.md#when-a-snapshot-test-is-required)). - **Choose PR history deliberately.** Split independent changes and fix the introducing PR before propagation. Standalone/stack branches may merge-forward or rebase. Rewrites use `--force-with-lease`, abort on remote movement, never raw `--force`; preserve an in-progress merge-forward checkpoint before taking a newer base ([rationale](.agents/notes/implemented/process/2026-08-02-native-github-stacks-and-optional-rebases.md)). diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index f11b12b5ba..18ce4bd3df 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: 9685f4689a6ebd6994c1fc6dccbae04af1658a15 -config-catalog.zh.md: 51575325b3656487e2fe852a6c8cf0b47b2b6fe8 +config-catalog.md: 8d03e3757388d4f2d317afb4c06537905a9f3688 +config-catalog.zh.md: 81dce53256071fdb3b0059552bca85569c53a3db diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 9685f4689a..8d03e37573 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -269,7 +269,7 @@ Source: [`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/co ## `@deepseek-ai/dsh-api-session-controller` -Requires: `agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionQuery` · `tools` · `typert` · `workspaceRegistry` +Requires: `agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionQuery` · `typert` · `workspaceRegistry` ```ts config-catalog /** Session Controller deployment policy. */ @@ -2990,7 +2990,7 @@ export interface Config { export type ToolPresentationMode = 'native' | 'code' | 'both' ``` -Source: [`packages/core/tools/src/index.ts:654`](../packages/core/tools/src/index.ts) +Source: [`packages/core/tools/src/index.ts:655`](../packages/core/tools/src/index.ts) diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index 51575325b3..81dce53256 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -271,7 +271,7 @@ export interface Config { ## `@deepseek-ai/dsh-api-session-controller` -需要：`agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionQuery` · `tools` · `typert` · `workspaceRegistry` +需要：`agentDefaultModel` · `agents` · `attachments` · `llm` · `sessions` · `sessionQuery` · `typert` · `workspaceRegistry` ```ts config-catalog /** Session Controller deployment policy. */ @@ -2992,7 +2992,7 @@ export interface Config { export type ToolPresentationMode = 'native' | 'code' | 'both' ``` -来源：[`packages/core/tools/src/index.ts:654`](../packages/core/tools/src/index.ts) +来源：[`packages/core/tools/src/index.ts:655`](../packages/core/tools/src/index.ts) diff --git a/docs/cookbook/adding-a-tool.i18n.yaml b/docs/cookbook/adding-a-tool.i18n.yaml index 5920054e1f..bf2d9d4d3f 100644 --- a/docs/cookbook/adding-a-tool.i18n.yaml +++ b/docs/cookbook/adding-a-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 docs/cookbook/adding-a-tool.md -adding-a-tool.md: 37516521de4d00de964003fd6f877831774fdcd3 -adding-a-tool.zh.md: 6a24d5dc303990f9fe13e77c9a92b3a24ca16647 +adding-a-tool.md: 4e07c33dd372ae95391fcad5236832a6f7662e82 +adding-a-tool.zh.md: 17a024a0db0d63ec9ef8c9407e77a471263427c9 diff --git a/docs/cookbook/adding-a-tool.md b/docs/cookbook/adding-a-tool.md index 37516521de..4e07c33dd3 100644 --- a/docs/cookbook/adding-a-tool.md +++ b/docs/cookbook/adding-a-tool.md @@ -87,7 +87,13 @@ Hard rules (they bite if broken): - **UI-only formatting stays out of the model result.** A fenced ` ```console ` block, a diff, a relativized path—none of these belongs in the canonical value or Native content merely to serve a UI. `output.render` owns model-facing prose; `presentationMeta` plus the card presenters own replayable UI state. A `terminal` result view carries raw output and the adapter adds any fallback framing. - **`defineTool` soft-validates the display path.** Malformed or older logged arguments make the wrapper return `undefined` (a generic fallback) rather than throw — display must never crash a replay. -The neutral vocabulary lives in `dsh-tools`; tools never import a UI or transport type. Host/client runtimes map each `card` into their own view. The design and the why are in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); `dsh-tool-fs` (generic/diff) and `dsh-tool-bash` (terminal) are the reference implementations. +The neutral vocabulary lives in `dsh-tools`; tools never import a UI or transport type. Consumers of this API map each `card` into their own view. The design and the why are in [the render-intent-union Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md); `dsh-tool-fs` (generic/diff) and `dsh-tool-bash` (terminal) are the reference implementations. + +## Web Client presentation + +The built-in Web Client does not consume `presentCall` or `presentResult`. Session `page` and `follow` transport raw `tool/call` and `tool/result` events, including persisted `result.meta`. A Client plugin registers its wire tool name in the `tool.call.toolview` keyed slot and derives component props from the `ToolCallBlock` arguments, content, error, metadata, existing Code Dispatch `parentCallId`, and Session path facts. It validates these wire values locally and returns the generic row for malformed or unsupported input. + +Use `output.presentationMeta(args, value)` when an existing Web card needs bounded structured result facts that model-facing content cannot preserve losslessly. Do not store React props or a selected card in metadata, import a Host tool implementation into a browser bundle, or create another Client presenter registry. Defining Host presentation methods alone does not add a specialized Web card. The [Client-derived presentation Agent Note](../../.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md) defines ownership, fallback, and equivalence requirements. ## Verification diff --git a/docs/cookbook/adding-a-tool.zh.md b/docs/cookbook/adding-a-tool.zh.md index 6a24d5dc30..17a024a0db 100644 --- a/docs/cookbook/adding-a-tool.zh.md +++ b/docs/cookbook/adding-a-tool.zh.md @@ -89,7 +89,13 @@ producer 提供同步的 `cancel`、在资源清理后 settle 且不 reject 的 - **UI 格式不进入模型结果。** 围栏 ` ```console ` 块、diff、相对化路径均不应仅为服务 UI 而进入规范值或 Native 内容。`output.render` 负责模型可见的自然语言；`presentationMeta` 和卡片展示器负责可回放的 UI 状态。`terminal` 结果视图携带原始输出，由适配器按需添加回退格式。 - **`defineTool` 对展示路径做软校验。** 格式错误或旧版日志中的参数会使包装器返回 `undefined`（通用回退）而非抛异常——展示绝不能导致回放崩溃。 -中性词汇定义在 `dsh-tools` 中；工具绝不导入 UI 或传输类型。host/client 运行时将每个 `card` 映射到各自的视图。设计与原因见[渲染意图联合体 Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md)；`dsh-tool-fs`（generic/diff）和 `dsh-tool-bash`（terminal）是参考实现。 +中性词汇定义在 `dsh-tools` 中；工具绝不导入 UI 或传输类型。使用该 API 的消费方把每个 `card` 映射到自己的视图。设计与原因见[渲染意图联合体 Agent Note](../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md)；`dsh-tool-fs`（generic/diff）和 `dsh-tool-bash`（terminal）是参考实现。 + +## Web Client 展示 + +内置 Web Client 不消费 `presentCall` 或 `presentResult`。Session `page` 与 `follow` 运输原始 `tool/call` 和 `tool/result` 事件，包括持久化的 `result.meta`。Client 插件在 keyed slot `tool.call.toolview` 中注册自己的 wire 工具名称，并从 `ToolCallBlock` 的参数、内容、错误、metadata、现有 Code Dispatch `parentCallId` 与 Session 路径事实派生组件 props。插件在本地校验这些 wire 值，并让格式错误或不受支持的输入回退到 generic 行。 + +现有 Web 卡片需要模型可见内容无法无损保存的有界结构化结果事实时，使用 `output.presentationMeta(args, value)`。不要在 metadata 中保存 React props 或预选卡片，不要把 Host 工具实现导入浏览器 bundle，也不要建立另一套 Client presenter registry。只定义 Host 展示方法不会增加专用 Web 卡片。[Client 派生展示 Agent Note](../../.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md)规定 owner、fallback 与对等要求。 ## 验证 diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 32599e0510..c9e637910e 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.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/event-producer-consumer.md -event-producer-consumer.md: 8cf11d8be322686c89f8bc57c9f0bc2c4a3aeb74 -event-producer-consumer.zh.md: 6b79a0fded3b5fa6956e9d7b047e78b68ded1f48 +event-producer-consumer.md: 2be5a84969b9f14823abf90cf289a0a41e48dd11 +event-producer-consumer.zh.md: 5bbae1be5d03c3e443d36093ce60dbf7e4b07971 diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 8cf11d8be3..2be5a84969 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -21,11 +21,11 @@ This matrix shows which packages dispatch each harness-owned event and which pac | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:217`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:462`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:442`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:469`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:448`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:455`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:444`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:424`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:451`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:430`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:437`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 6b79a0fded..5bbae1be5d 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -23,11 +23,11 @@ | `agent/session-start` | `emit` | [`packages/core/agent/src/runtime-types.ts:217`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `agent-team`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | | `agent/status` | `emit` | [`packages/core/agent/src/runtime-types.ts:178`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `agent-team`, [`compaction-basic`](../packages/compaction/compaction-basic), [`goal-round-driver`](../packages/goal/goal-round-driver), [`schedule`](../packages/schedule/schedule), `server`, `session-controller` | | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/runtime-types.ts:278`](../packages/core/agent/src/runtime-types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:462`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:442`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:469`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:448`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | -| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:455`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/activity` | `emit` | [`packages/api/session-controller/src/types.ts:444`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/added` | `emit` | [`packages/api/session-controller/src/types.ts:424`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/error` | `emit` | [`packages/api/session-controller/src/types.ts:451`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/removed` | `emit` | [`packages/api/session-controller/src/types.ts:430`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | +| `api-session/status` | `emit` | [`packages/api/session-controller/src/types.ts:437`](../packages/api/session-controller/src/types.ts) | `session-controller` (`emit`) | `remotes` | | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/types.ts:85`](../packages/interaction/user-approval/src/types.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `remotes` | | `authorization/settled` | `emit` | [`packages/credentials/authorization/src/index.ts:57`](../packages/credentials/authorization/src/index.ts) | [`authorization`](../packages/credentials/authorization) (`events.dispatch`) | [`authorization`](../packages/credentials/authorization) | | `commands/change` | `emit` | [`packages/interaction/commands/src/types.ts:80`](../packages/interaction/commands/src/types.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `remotes` | diff --git a/docs/module-graph.i18n.yaml b/docs/module-graph.i18n.yaml index 90fea5010f..b8a9b43bd1 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: 0d26be0a33b6aeca80fd04d9fdabc8f977a714df -module-graph.zh.md: 396d5879e26c8da1446d83323991de13acf0bd61 +module-graph.md: d70aa9a7704a7de5b669928a6cafd8358fb2a3b0 +module-graph.zh.md: 2333d71e61bd935fa482fc766bb7d96bb75d56db diff --git a/docs/module-graph.md b/docs/module-graph.md index 0d26be0a33..d70aa9a770 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -1083,7 +1083,6 @@ flowchart TD pkg_client_connection --> pkg_llm pkg_client_connection --> pkg_session pkg_client_connection --> pkg_tool_todo - pkg_client_connection --> pkg_tools pkg_compaction_tool_result_pruner --> pkg_compaction pkg_compaction_tool_result_pruner --> pkg_invariants pkg_compaction_tool_result_pruner --> pkg_llm @@ -1255,7 +1254,6 @@ flowchart TD pkg_api_session_controller --> pkg_session_query pkg_api_session_controller --> pkg_session_title pkg_api_session_controller --> pkg_subagent - pkg_api_session_controller --> pkg_tools pkg_api_session_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_typert_registry pkg_api_session_controller --> pkg_util_workspace_path @@ -1820,7 +1818,7 @@ flowchart TD | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | | [`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) | | [`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), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools) | +| [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`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) | | [`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), [`subagent`](../packages/subagent/subagent) | | [`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) | @@ -1842,7 +1840,7 @@ flowchart TD | [`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), [`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) | -| [`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), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`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), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | +| [`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), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`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), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`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), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`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-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), [`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) | diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md index 396d5879e2..2333d71e61 100644 --- a/docs/module-graph.zh.md +++ b/docs/module-graph.zh.md @@ -1085,7 +1085,6 @@ flowchart TD pkg_client_connection --> pkg_llm pkg_client_connection --> pkg_session pkg_client_connection --> pkg_tool_todo - pkg_client_connection --> pkg_tools pkg_compaction_tool_result_pruner --> pkg_compaction pkg_compaction_tool_result_pruner --> pkg_invariants pkg_compaction_tool_result_pruner --> pkg_llm @@ -1257,7 +1256,6 @@ flowchart TD pkg_api_session_controller --> pkg_session_query pkg_api_session_controller --> pkg_session_title pkg_api_session_controller --> pkg_subagent - pkg_api_session_controller --> pkg_tools pkg_api_session_controller --> pkg_typert_protocol pkg_api_session_controller --> pkg_typert_registry pkg_api_session_controller --> pkg_util_workspace_path @@ -1822,7 +1820,7 @@ flowchart TD | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title), [`tool-todo`](../packages/todo/tool-todo) | | [`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) | | [`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), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools) | +| [`client-connection`](../packages/client/connection) | `client` | [`attachment`](../packages/attachment/attachment), [`commands`](../packages/interaction/commands), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/runtime-diagnostics/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`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) | | [`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), [`subagent`](../packages/subagent/subagent) | | [`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) | @@ -1844,7 +1842,7 @@ flowchart TD | [`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), [`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) | -| [`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), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`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), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`util-workspace-path`](../packages/util/workspace-path), [`workspace`](../packages/workspace/workspace) | +| [`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), [`invariants`](../packages/runtime-diagnostics/invariants), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`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), [`subagent`](../packages/subagent/subagent), [`typert-protocol`](../packages/typert/protocol), [`typert-registry`](../packages/typert/registry), [`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), [`invariants`](../packages/runtime-diagnostics/invariants), [`session`](../packages/core/session), [`storage-domain`](../packages/storage/storage-domain), [`typert-protocol`](../packages/typert/protocol), [`workspace`](../packages/workspace/workspace) | | [`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-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), [`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) | diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml index 0afa4d58c5..339baa81cc 100644 --- a/docs/subsystems/session.i18n.yaml +++ b/docs/subsystems/session.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/session.md -session.md: edb8f4ebb427bfce6e4def023e65f4697608ceb2 -session.zh.md: 7b3c7a8e50688ba19694d5f45e43d224c2245ef1 +session.md: b7806a4989684be7585d8d42ac215fe1ab1540f0 +session.zh.md: a80a3146b50c4c0fdcf4c3e54e1dc4943eb28642 diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md index edb8f4ebb4..b7806a4989 100644 --- a/docs/subsystems/session.md +++ b/docs/subsystems/session.md @@ -696,7 +696,7 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH /** * Read one cold-safe, message-aligned Session history page. * @param request - durable address, backward cursor, and page budget. - * @param signal - cancellation for persistence and presentation reads. + * @param signal - cancellation for persistence reads. * @returns one chronological page and optional latest projections. */ @Remote('page') page(request: SessionPageRequest, signal: AbortSignal): Promise diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md index 7b3c7a8e50..a80a3146b5 100644 --- a/docs/subsystems/session.zh.md +++ b/docs/subsystems/session.zh.md @@ -700,7 +700,7 @@ inspect( sessionId: SessionId, signal?: AbortSignal, ): Promise<{ meta: SessionH /** * Read one cold-safe, message-aligned Session history page. * @param request - durable address, backward cursor, and page budget. - * @param signal - cancellation for persistence and presentation reads. + * @param signal - cancellation for persistence reads. * @returns one chronological page and optional latest projections. */ @Remote('page') page(request: SessionPageRequest, signal: AbortSignal): Promise diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 51a624d98a..31c76de3e1 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: cda9349e432472a0ed9fd623afef0b689ff72f73 -README.zh.md: 2aaee8f968cf7373110e291c197adbeca21f490e +README.md: 7631e1623f90f9349eca78bc76d46505d13d2e0e +README.zh.md: 7a733b45b1cdbb17096d1e76bb25b54d3bdc0e06 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index cda9349e43..7631e1623f 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -4,6 +4,8 @@ English | [中文](README.zh.md) `@deepseek-ai/dsh-api-session-controller` owns the Host `ctx.sessionController` service and the generated Client `ctx.remote.session` namespace. It serves Session list, search, creation, model selection, rename, fork, prompt, attachment, queue, cancellation, message-aligned history, live log following, and Host-wide control state. +History pages and follow event frames carry only raw `SessionWireEvent` values. Tool arguments, result content, failures, and `tool/result.data.meta` pass through unchanged; the controller does not resolve a Tool definition, run a presenter, or attach UI data. + Each endpoint states its activation policy. List, search, attachment, history pages, and log following can inspect persistence without activating an Agent; queue mutation and cancellation require the corresponding live state; model, rename, and prompt commands may explicitly resume an ordinary Session. Create and fork are the only operations that create a new Agent. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. 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. 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. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 2aaee8f968..7a733b45b1 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -4,6 +4,8 @@ `@deepseek-ai/dsh-api-session-controller` 拥有 Host 的 `ctx.sessionController` 服务和生成的 Client `ctx.remote.session` namespace。它提供 Session 列表、搜索、创建、模型选择、重命名、fork、prompt、附件、queue、取消、按消息对齐的历史、live 日志跟随和 Host 范围 control 状态。 +历史页与 follow event frame 只携带原始 `SessionWireEvent`。工具参数、结果内容、失败信息和 `tool/result.data.meta` 原样通过；controller 不解析 Tool definition、不运行 presenter，也不附加 UI 数据。 + 每个 endpoint 都声明自己的激活策略。列表、搜索、附件、历史页和日志跟随可以在不激活 Agent 的情况下检查 persistence；queue 变更和取消要求对应 live 状态仍然存在；模型、重命名和 prompt 命令可以显式恢复普通 Session。只有 create 和 fork 会创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法，以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。 Client adapter 提供 `SessionEventStream`，即绑定到一个普通 Session 或 direct subagent address 的 Gateway `RemoteJournalStream`。它在读取首个 page 前打开 follow，只发布连续的 `replace`、`prepend` 和 `append` 变更，并通过 tail page 修复重连或 seq 缺口。业务、persistence 或无法恢复的连续性错误会终止 stream，只有物理载体断开才触发自动恢复。`SessionControlStream` 是 Gateway `RemoteSnapshotStream`；每代都以完整的进程本地 baseline 开始，因此重连会替换 queue、jobs 和 projection 状态，而不会把瞬态值当作 durable event。 diff --git a/packages/client/AGENTS.md b/packages/client/AGENTS.md index 2165e19c2a..b45dc60a48 100644 --- a/packages/client/AGENTS.md +++ b/packages/client/AGENTS.md @@ -52,7 +52,7 @@ Non-negotiables across the layers: - **Business data lives in the object layer, never a store.** Entry-declared stores carry shared viewing/interaction state (selection, drafts, panel widths); sessions, frames, and connections stay in the object layer. - **rpcId is strictly bidirectional**: the initiator mints, the responder echoes; business signatures see only `RpcRequest

`, minting stays in the carrier layer ([layering and RPC protocol note](../../.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md)). - **Notifier publication discipline**: `notifyNow` is only the direct echo of a user gesture; structural updates use microtask-batched `markDirty`, while visible streaming chunks use cumulative `markFrameDirty`. See `../api/session-controller/src/client/sessions/notifier.ts`. -- **The web layer is pure presentation.** Nothing that is "how to draw" (tool-card views, queue states) enters the session log; the host computes such data per frame or pushes it live, and replay recomputes it — falling back to the generic form when it can't. A new *model-visible* input still requires a session event (repo-wide rule). +- **The web layer is pure presentation.** Nothing that is only "how to draw" enters the session log. Tool cards derive in the Client from raw call/result events and persisted result metadata; process-local control state uses its own snapshots and frames. Unknown or malformed tool data falls back to the generic form. A new *model-visible* input still requires a session event (repo-wide rule). ## Dependency declaration diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml index ffb66bc995..a6102ddac0 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: 6f47cd87af46cc270d3160482ad047b249aa5053 -README.zh.md: 38e3c626073e9e90a16eebdb91af1e89d4da7c22 +README.md: 4c9665b680fe1922770403d88a04dffc755481ad +README.zh.md: 8bf3db2cb1401427f29016f8dbddcd9d27ec9635 diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md index 6f47cd87af..4c9665b680 100644 --- a/packages/client/ui-conversation/README.md +++ b/packages/client/ui-conversation/README.md @@ -8,7 +8,7 @@ English | [中文](README.zh.md) `UiConversation.events` is the single registry for event Definitions, and `UiConversation.views` is the single registry for target snapshot builders. Both registries reject duplicate keys, preserve registration order, return idempotent disposers, and rebuild existing bindings when their contribution roster changes. `UiConversation.binding(bindingOrSessionId)` returns one identity-stable Conversation binding for the current Session Controller binding. It does not open another event source. -The adapter converts each `SessionEventEntry` to `ConversationEventInput` as `{ event, view? }`: the raw Session event is preserved and the envelope-level tool view is included only when present. Contiguous append and prepend revisions use incremental assembly; replacement windows and revision gaps rebuild from the complete loaded window. The assembler owns Context matching, Turn/Step locations, target node materialization, target activity, and stable target sources. `ConversationSnapshot` contains only target-neutral views and active-target facts; Session lifecycle state remains in `SessionSnapshot`. +The adapter converts each `SessionEventEntry` to a `{ event }` `ConversationEventInput` and preserves the raw Session event, including tool-result metadata. Contiguous append and prepend revisions use incremental assembly; replacement windows and revision gaps rebuild from the complete loaded window. The assembler owns Context matching, Turn/Step locations, target node materialization, target activity, and stable target sources. `ConversationSnapshot` contains only target-neutral views and active-target facts; Session lifecycle state remains in `SessionSnapshot`. Target packages declaration-merge their snapshot and Location data maps, then register with `ctx.uiConversation.events.register(...)` and `ctx.uiConversation.views.register(...)`. A target reads its Session-owned source with `ctx.uiConversation.binding(binding).target(targetId)`. Registrations are Cordis effects and their returned disposers remove the contribution from the same registry. diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md index 38e3c62607..8bf3db2cb1 100644 --- a/packages/client/ui-conversation/README.zh.md +++ b/packages/client/ui-conversation/README.zh.md @@ -8,7 +8,7 @@ `UiConversation.events` 是 event Definition 的唯一 registry，`UiConversation.views` 是 target snapshot builder 的唯一 registry。两者都拒绝重复 key、保持注册顺序、返回幂等 disposer，并在 contribution roster 变化时重建现有 binding。`UiConversation.binding(bindingOrSessionId)` 为当前 Session Controller binding 返回 identity 稳定的 Conversation binding，不会另开 event source。 -adapter 将每个 `SessionEventEntry` 转换成 `{ event, view? }` 形式的 `ConversationEventInput`：原始 Session event 保持不变，仅在 envelope-level tool view 存在时携带 `view`。连续 revision 的 append 和 prepend 使用增量组装；replace window 或 revision 断档从完整已加载窗口重建。assembler 拥有 Context 匹配、Turn/Step location、target node 物化、target activity 和稳定 target source。`ConversationSnapshot` 只包含与 target 无关的 View 与 active-target 事实；Session lifecycle 状态仍属于 `SessionSnapshot`。 +adapter 将每个 `SessionEventEntry` 转换成 `{ event }` 形式的 `ConversationEventInput`，并保留原始 Session event，包括工具结果 metadata。连续 revision 的 append 和 prepend 使用增量组装；replace window 或 revision 断档从完整已加载窗口重建。assembler 拥有 Context 匹配、Turn/Step location、target node 物化、target activity 和稳定 target source。`ConversationSnapshot` 只包含与 target 无关的 View 与 active-target 事实；Session lifecycle 状态仍属于 `SessionSnapshot`。 target package 通过 declaration merge 扩展 snapshot 与 Location data map，再调用 `ctx.uiConversation.events.register(...)` 和 `ctx.uiConversation.views.register(...)`。target 通过 `ctx.uiConversation.binding(binding).target(targetId)` 读取其 Session-owned source。注册属于 Cordis effect，返回的 disposer 从同一个 registry 移除 contribution。 diff --git a/packages/client/ui-deliverables/README.i18n.yaml b/packages/client/ui-deliverables/README.i18n.yaml index c131cc33d9..77799f1afb 100644 --- a/packages/client/ui-deliverables/README.i18n.yaml +++ b/packages/client/ui-deliverables/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-deliverables/README.md -README.md: e7118eac75f31b3ffc3f2434371dba06f029d241 -README.zh.md: 62aa568bb7a14b5f703e60a0c263e851d01734ed +README.md: ace08fae3a001080918973c23aa362080cd69066 +README.zh.md: 9df1664bc42c39012c2eebf397cb368b3b5c6260 diff --git a/packages/client/ui-deliverables/README.md b/packages/client/ui-deliverables/README.md index e7118eac75..ace08fae3a 100644 --- a/packages/client/ui-deliverables/README.md +++ b/packages/client/ui-deliverables/README.md @@ -4,7 +4,7 @@ English | [中文](README.zh.md) Produced-files and clickable-reference feature owner. The Node half registers final-response guidance with the system-prompt registry; the browser half registers the deliverables row a finished turn ends with into the chat view's `conversation.chat.turnTail` hole and links matching inline-code references in the closing prose. The shipped Web patch is the only composition that loads this package. Removing its one cordis.yml entry removes the guidance, row, and prose links together. -`deliverablesDefinition` folds each Turn's successful mutation calls into engine-published `DeliverablesTurnData`; `producedForClosing` reads that data with the closing Assistant seq. The vocabulary is the mutation tools' own follow-along `locations`, never the closing prose: a produced file is listed whether or not the model remembered to name it. A mutation is recognized by render intent, not tool name — a diff card, or a generic card whose `kind` is `edit` (the shape `str_replace_editor`'s insert presents) — so a new mutation tool joins by declaring what it does. Reads, deletes, and failed calls contribute nothing; a path appears once per Turn in first-seen order. The Conversation Location index owns Turn membership, so a Turn that mutates and then ends without content text cannot spill into the next Turn's row. +`deliverablesDefinition` folds each Turn's successful first-party mutation calls into engine-published `DeliverablesTurnData`; `producedForClosing` reads that data with the closing Assistant seq. The source is the validated raw arguments of `write`, `edit`, and the mutating `str_replace_editor` commands (`create`, `str_replace`, and `insert`), never presentation data or closing prose: a produced file is listed whether or not the model remembered to name it. Reads, deletes, unsupported tools, malformed calls, and failed results contribute nothing; a path appears once per Turn in first-seen order. A new mutation tool needs an explicit Client contribution before it joins this list. The Conversation Location index owns Turn membership, so a Turn that mutates and then ends without content text cannot spill into the next Turn's row. `ProducedFiles` renders the row between the closing message's body and its IconActions footer: a quiet label and one measured file lane. It shows the largest leading prefix that fits (up to six chips; basename text, full path as the `title`) while reserving the exact localized `+ N files` width, so the remainder stays visible without wrapping or horizontal scrolling. Each chip opens through the owner-supplied `openFile` — the same Host opener the tool rows use, with the chat view resolving relative paths against the session cwd. When files are hidden, a second-line **Show in folder** action opens the session workspace through that same owner path only while the page is loopback and the current Host handshake reports `canOpenPath`; direct remote Web and headless/container Linux Hosts omit the action by default. Design rationale: the [workspace file links Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md). diff --git a/packages/client/ui-deliverables/README.zh.md b/packages/client/ui-deliverables/README.zh.md index 62aa568bb7..9df1664bc4 100644 --- a/packages/client/ui-deliverables/README.zh.md +++ b/packages/client/ui-deliverables/README.zh.md @@ -4,7 +4,7 @@ 产出文件与可点击文件引用功能的属主。Node 侧向系统提示词 registry 注册最终回复指引；浏览器侧把已完成轮次末尾的产出文件行注册到 chat 视图的 `conversation.chat.turnTail` slot，并将收尾正文中匹配的行内代码引用转换为链接。正式提供的组合中只有 Web patch 加载本包；从 cordis.yml 中删去这一项会同时移除提示词、文件行与正文链接。 -`deliverablesDefinition` 把每个轮次中成功的修改调用折叠进引擎发布的 `DeliverablesTurnData`；`producedForClosing` 结合收尾 Assistant 的 seq 读取这份数据。依据的是修改工具自身附带的 `locations`，而不是收尾正文：无论模型是否记得点名，产出文件都会被列出。修改操作按渲染意图而非工具名识别：diff 卡片，或 `kind` 为 `edit` 的通用卡片（即 `str_replace_editor` 的 insert 操作所呈现的形态）；因此新的修改工具只需声明自身行为即可加入。读取、删除和失败的调用不贡献任何条目；同一路径在一个轮次内按首见顺序只出现一次。Conversation Location 索引负责维护轮次归属关系，因此一个轮次即使先修改文件、随后没有正文内容就结束，也不会溢进下一个轮次的行里。 +`deliverablesDefinition` 把每个轮次中成功的第一方修改调用折叠进引擎发布的 `DeliverablesTurnData`；`producedForClosing` 结合收尾 Assistant 的 seq 读取这份数据。依据的是 `write`、`edit` 和 `str_replace_editor` 修改命令（`create`、`str_replace`、`insert`）经过校验的原始参数，而不是展示数据或收尾正文：无论模型是否记得点名，产出文件都会被列出。读取、删除、不受支持的工具、格式错误的调用和失败结果不贡献任何条目；同一路径在一个轮次内按首见顺序只出现一次。新的修改工具必须先增加显式 Client contribution，才能加入该列表。Conversation Location 索引负责维护轮次归属关系，因此一个轮次即使先修改文件、随后没有正文内容就结束，也不会溢进下一个轮次的行里。 `ProducedFiles` 在收尾消息正文与其 IconActions 之间渲染该行：一个低调的标签和一条经过测量的单行文件 lane。它展示能够放下的最大前缀（至多六个标签项；文本为文件名，完整路径作为 `title`），并为本地化后的精确 `+ N 个文件` 宽度预留空间，因此剩余计数始终可见，既不换行也不横向滚动。每个标签项经由属主提供的 `openFile` 打开——与工具行相同的 Host 打开器，chat 视图会把相对路径按会话 cwd 解析。存在隐藏文件时，第二行的**在文件夹中显示**也经由同一属主路径打开会话 workspace；它只在页面使用 loopback 且当前 Host 握手报告 `canOpenPath` 时出现，直接远程 Web 与 headless／容器 Linux Host 默认均省略该操作。设计原理：[workspace 文件链接 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md)。 diff --git a/packages/client/ui-tool/README.i18n.yaml b/packages/client/ui-tool/README.i18n.yaml index f31167fbde..a9bd41853a 100644 --- a/packages/client/ui-tool/README.i18n.yaml +++ b/packages/client/ui-tool/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-tool/README.md -README.md: 79b1bf27d848f015f132e38a635dd98c05a5dd87 -README.zh.md: 89469445b346dcb58a192a51cacdf9e66af50647 +README.md: 16fd06332d24b265ac7d6b7b000870686262b9c5 +README.zh.md: a21acab8ed6e7b52770a9ee6a63219c11b949c3d diff --git a/packages/client/ui-tool/README.md b/packages/client/ui-tool/README.md index 79b1bf27d8..16fd06332d 100644 --- a/packages/client/ui-tool/README.md +++ b/packages/client/ui-tool/README.md @@ -12,7 +12,7 @@ Business UI packages register only their wire Tool names and atomic views. They Each root and child wrapper preserves the `data-chat-anchor-key="call:"` and `data-chat-call-id` DOM contract used for paging and selection. -The package also fills `conversation.details.tool` with `ToolDetails`. The row and details renderers share the same pure card models for `terminal`, `read`, `diff`, `search`, and `web` render intents. Unknown intent tags and malformed wire card data fall back to flattened Tool result text. +The package also fills `conversation.details.tool` with `ToolDetails`. Row and Details renderers share one pure card model for each terminal, read, diff, search, and web card. These models validate raw call arguments, result content, failure state, persisted metadata, the existing Code Dispatch `parentCallId`, and Session path facts; unsupported or malformed inputs fall back to flattened Tool result text. Generic rows classify known Tool names into search, read, shell, write, edit, code, or generic variants. Running, successful, failed, and interrupted lifecycle states come only from the frozen call/result slice. File paths resolve against the session `cwd` only when the user invokes the Host open-file callback; presentation code does not read Session services. @@ -28,9 +28,9 @@ ctx.slots.inject('tool.call.toolview', () => }, BusinessToolRow)) ``` -The owner payload is `ToolCallOwnerProps`: `callId`, `toolName`, the frozen `block`, optional `cwd` and `home`, and plain `openFile`/`inspect` callbacks. Path summaries relativize to the session cwd first, then replace a leftover POSIX host home with `~`; `filePath` and Host open keep the authored filesystem path. The registration receives the normal session slot runtime share. It does not receive React nodes, Runtime services, or root/subcall knowledge. +The owner payload is `ToolCallOwnerProps`: `callId`, `toolName`, the frozen `block`, optional `cwd` and `home`, and plain `openFile`/`inspect` callbacks. A Code Dispatch block retains its event's `parentCallId`; the field is absent on a root Session call, so row and Details card models preserve the generic flattened form for descendants without another placement flag. Path summaries relativize to the Session cwd first, then replace a leftover POSIX Host home with `~`; `filePath` and Host open keep the authored filesystem path. The registration receives the normal Session slot runtime share but no React node or Runtime service. -This package currently owns the generic fallback and the built-in shell/pwsh, read, write/edit, grep/glob, web, todo, question, and Code Dispatch presentations. `ui-skill` demonstrates a business-owned registration for `skill`. +This package currently owns the generic fallback and the built-in shell/pwsh, read, write/edit, grep/glob, web, todo, question, and Code Dispatch presentations. Structured cards derive directly from first-party raw event fields; Host `presentCall`/`presentResult` values never enter the Client. `ui-skill` demonstrates a business-owned registration for `skill`. Card-specific limits and fallback rules remain in the owning [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md), [diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md), [read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.md), [search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.md), and [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.md) notes. diff --git a/packages/client/ui-tool/README.zh.md b/packages/client/ui-tool/README.zh.md index 89469445b3..a21acab8ed 100644 --- a/packages/client/ui-tool/README.zh.md +++ b/packages/client/ui-tool/README.zh.md @@ -12,7 +12,7 @@ Client 工具展示插件。`ui-conversation` 通过 `conversation.chat.node` 每个 root 和 child 包装层都保留 `data-chat-anchor-key="call:"` 与 `data-chat-call-id` DOM 约定，供分页和 selection 使用。 -本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与详情 renderer 共用同一组面向 `terminal`、`read`、`diff`、`search` 和 `web` render intent 的纯 card model。未知的 intent 标签和格式错误的 wire card 数据都会回退为压平的工具结果文本。 +本包还通过 `ToolDetails` 填充 `conversation.details.tool`。行 renderer 与 Details renderer 分别为 terminal、read、diff、search 和 web 卡片复用同一个纯 card model。这些 model 校验原始调用参数、结果内容、失败状态、持久 metadata、现有 Code Dispatch `parentCallId` 与 Session 路径事实；不受支持或格式错误的输入回退为压平的工具结果文本。 通用行把已知工具名称归类为 search、read、shell、write、edit、code 或 generic 变体。运行中、成功、失败和中断状态只来自冻结的 call/result slice。只有用户调用 Host 打开文件回调时，文件路径才相对会话 `cwd` 解析；展示代码不读取会话服务。 @@ -28,9 +28,9 @@ ctx.slots.inject('tool.call.toolview', () => }, BusinessToolRow)) ``` -owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd` 与 `home`，以及普通的 `openFile`、`inspect` 回调。路径摘要先相对会话 cwd 缩短，再把剩余的 POSIX 宿主家目录写成 `~`；`filePath` 与 Host 打开仍使用作者给出的文件系统路径。注册项会收到常规的会话 slot 运行时共享数据，但不会收到 React node、运行时服务或 root/subcall 知识。 +owner 载荷为 `ToolCallOwnerProps`：`callId`、`toolName`、冻结的 `block`、可选 `cwd` 与 `home`，以及普通的 `openFile`、`inspect` 回调。Code Dispatch block 保留其事件已有的 `parentCallId`；root Session call 没有该字段，因此 row 与 Details card model 无需另一项 placement 标志即可让 descendant 保持 generic 压平形态。路径摘要先相对 Session cwd 缩短，再把剩余的 POSIX Host home 写成 `~`；`filePath` 与 Host 打开仍使用作者给出的文件系统路径。注册项会收到常规 Session slot runtime share，但不会收到 React node 或 runtime service。 -本包当前拥有 generic fallback，以及 shell/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。`ui-skill` 展示了业务包自行拥有的 `skill` 注册项。 +本包当前拥有 generic fallback，以及 shell/pwsh、read、write/edit、grep/glob、web、todo、question 和 Code Dispatch 的内置展示。结构化卡片直接从第一方原始 event 字段派生；Host `presentCall`／`presentResult` 值不会进入 Client。`ui-skill` 展示了业务包自行拥有的 `skill` 注册项。 各类卡片的上限与 fallback 规则仍由对应的 [terminal](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md)、[diff](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md)、[read](../../../.agents/notes/implemented/feature/2026-07-30-web-read-card-frontend.zh.md)、[search](../../../.agents/notes/implemented/feature/2026-07-30-web-search-card.zh.md) 和 [web](../../../.agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md) Agent Note 负责。 diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml index dfeb0e2eb3..571012276f 100644 --- a/packages/core/tools/README.i18n.yaml +++ b/packages/core/tools/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/core/tools/README.md -README.md: 4f67dee611e6f28547ab276bd0884e787aeae0d9 -README.zh.md: 0137f295f2810930212dcb3f45e90af73bcf449c +README.md: a140255a04187d4f2206df0f90c950d7608ee8ac +README.zh.md: f519ba0a364f05ab63967c07ffd6681a5f62a70a diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md index 4f67dee611..a140255a04 100644 --- a/packages/core/tools/README.md +++ b/packages/core/tools/README.md @@ -20,7 +20,7 @@ tools: - `ctx.tools.register(definition: ToolDefinition): () => void` Register a trusted typed same-process definition with a mandatory canonical `output` declaration. The layer is the calling context's scope: a plain plugin context registers globally; an agent's `agent.ctx` registers for that agent alone, shadowing a same-named global tool there. Duplicate names within one layer throw; non-native modes also reject the reserved `run_code` transport name. Missing or unsupported output declarations and a non-positive or non-finite `timeoutMs` fail at registration. The optional synchronous `finalizeContent` callback is snapshotted when a call starts and may replace only final model-facing content after every pipeline outcome is normalized, including an error discovered while materializing another result field. Disposed with the calling fiber. - `ctx.tools.presentAs(mode: ToolPresentationMode): () => void` selects this agent's model-facing presentation, shadowing the `mode` config for that agent alone; it throws from a plain context (a process-wide presentation is the config field) and from a second declaration in the same scope. A code mode also registers that agent's own `tools:sdk` section. The catalog is unchanged — `schemas(agent)` still reports the agent's capabilities; only the assembly's tools collapse. Disposed with the calling fiber. - `ctx.tools.restrict(filter)` applies an agent-scoped allow/deny mask to global tools and throws from a plain context. The filter is snapshotted at registration; multiple masks intersect and scope-local tools merge afterwards. Deny masks admit later unnamed globals, while allow masks exclude later names. Unknown, local, or reserved names and empty filters reject. This is live visibility composition, not an authority boundary; see the [scope security non-goal](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-non-goals). -- `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent) — presenters pass the calling agent so the card matches what executed. +- `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined` Resolution as one scope sees it (shadowing applied; a restricted-away global reads as absent). A Host-local presenter consumer passes the calling agent when it must match the definition that executed. - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]` Schemas of everything the scope can see (without the `execute` functions). The shipped tools' schemas are catalogued in [docs/tool-catalog.md](../../../docs/tool-catalog.md), generated by booting each tool plugin and harvesting this method (see [the tool-schema-catalog Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md)). - `ctx.tools.guard(guard: ToolGuard): () => void` Register a monotonic synchronous execution guard after `tools/pre-execute`: returning a reason denies the call, while `undefined` leaves it unchanged. A plain-context guard applies globally; an `agent.ctx` guard applies only to that agent. Later waterfall listeners cannot turn a guard denial back into permission. Disposed with the calling fiber. - `ctx.tools.execute(exec)` losslessly snapshots and freezes arguments, assigns an opaque token, runs the complete policy/dispatch/result pipeline, then independently snapshots the authoritative outcome before final observation. Invalid arguments use the same result path without reaching policy or the body. Around wrappers may replace only `signal`; the registry re-fuses the original caller signal immediately before the body. @@ -49,7 +49,7 @@ The live registry pipeline has three transformable waterfalls, then the definiti - `PreToolDecision` — `{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`. Input rewrite is deliberately not offered; `ask` is serviced by [`ctx.approval`](../../interaction/user-approval/README.md) when mounted and otherwise degrades to deny. - `PostToolDecision` — accept may replace `content` or `value`, never both, and may attach `additionalContexts`; block turns feedback into a valueless failure. Content replacement preserves the canonical value and metadata. Value replacement is revalidated and rerenders content/metadata. Accept preserves tool-deferred contexts before decision contexts; block discards tool-deferred contexts and exposes only contexts explicitly supplied by the blocking decision. - `ToolGuard` — `(execution) => string | undefined`; the returned string is a final monotonic denial reason evaluated after the reorderable pre-execute waterfall and before dispatch. -- `ToolCallView` / `ToolResultView` — provider-neutral `card`-tagged render intents a tool returns from `presentCall` / `presentResult` to own how a UI renders ITS calls (see "Tool-owned UI presentation"). +- `ToolCallView` / `ToolResultView` — provider-neutral `card`-tagged values returned by the retained Host-side `presentCall` / `presentResult` extension (see "Host presentation descriptors"). The built-in Web Client does not consume these values. ### Extension points @@ -104,14 +104,14 @@ Optional `isConcurrencySafe(args)` receives typed, softly validated arguments. E `JsonSchemaNode` is the raw counterpart shared by tool outputs, Code Mode generation, subagents, and workflows. It permits any JSON root, an annotation-only unconstrained JSON node, and exact-one `oneOf`; annotations must remain lossless JSON. `assertSupportedJsonSchema()` rejects unsupported constructs, while `validateJsonSchemaValue()` returns path-qualified violations. Subagents and workflows retain their caller-defined object-root requirement through `assertObjectJsonSchema()` and `ObjectJsonSchema`, not through a limitation in the shared vocabulary. -### Tool-owned UI presentation +### Host presentation descriptors -Tools optionally own pure `presentCall()` and `presentResult()` render intents, so UIs do not special-case tool names: +Tools may retain pure `presentCall()` and `presentResult()` render intents for Host-local consumers: - Call views are `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`, `{ card: 'terminal', title, description?, cwd? }`, or `{ card: 'diff', title, diffs, locations? }`. - Result views are `{ card: 'generic', title?, content? }`, `{ card: 'terminal', title?, output?, exitCode?, signal? }`, `{ card: 'diff', title?, diffs }`, `{ card: 'search', shape, title?, truncated, total, … }` (a completed discovery search — grouped-by-file matches for `shape: 'matches'` (grep) or a flat path list for `shape: 'paths'` (glob), with `truncated`/`total` so a UI never presents a capped result as complete; the view carries no result text and a search has no `card: 'search'` call-time analogue), `{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }` (a completed file read → a line-numbered, optionally syntax-highlighted code view; `offset` is the 1-based first line the window requested, kept even when `lines` is empty; `lines` is `{ number, text }[]` keeping each file line number, and `content` is the envelope-stripped text a UI without read support falls back to), or `{ card: 'web', kind: 'search' | 'fetch', title?, … }` (a completed web retrieval; the `kind` arms carry the structured search sources or the fetch summary, and a UI without the `web` capability falls back to the raw result content). -Returning `undefined` selects generic fallback. Presenters depend only on their arguments and the durable result because UIs call them during live streaming and log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct top-level calls; that metadata persists with `tool/result` and returns to `presentResult`, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and falls back instead of crashing replay. `dsh-tool-bash` and `dsh-tool-fs` are the reference implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split and the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns card vocabulary. +Returning `undefined` selects generic fallback for a consumer that invokes the presenter. Presenters depend only on their arguments and the durable result so a consumer can use them during live streaming or log replay. `output.presentationMeta(args, value)` derives JSON metadata for direct top-level calls; that metadata persists with `tool/result` and is available both to `presentResult` and to clients that derive their own presentation, while the canonical value itself remains execution-local and is never replayed. Nested Code dispatches do not compute metadata. `defineTool` soft-validates older logged arguments and returns `undefined` on mismatch. Session Remote does not invoke or transport these presenters: the built-in Web Client selects its renderer through `tool.call.toolview` and derives card props from raw call arguments, result content, failure state, and persisted metadata. `dsh-tool-bash` and `dsh-tool-fs` remain reference presenter implementations; the [canonical-output Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md) owns the value/presentation split, the [render-intent Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.md) owns the retained card vocabulary, and the [Client-derived presentation decision](../../../.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md) owns the Web transport split. ### Code Mode diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md index 0137f295f2..f519ba0a36 100644 --- a/packages/core/tools/README.zh.md +++ b/packages/core/tools/README.zh.md @@ -20,7 +20,7 @@ tools: - `ctx.tools.register(definition: ToolDefinition): () => void`：注册一个受信任、带类型的同进程定义，其中必须包含规范的 `output` 声明。所在层由调用上下文的作用域决定：普通插件上下文会全局注册；agent 的 `agent.ctx` 只为该 agent 注册，并在此处遮蔽同名全局工具。同一层内名称重复会抛出；非原生模式还会拒绝保留的 `run_code` 传输名称。缺失或不受支持的输出声明，以及非正数或非有限的 `timeoutMs`，都会使注册失败。可选的同步 `finalizeContent` 回调会在调用开始时纳入快照；在所有流水线结果（包括实体化其他结果字段时发现的错误）规范化之后，它只能替换最终面向模型的内容。该注册会随调用方 fiber 一同 dispose（资源释放）。 - `ctx.tools.presentAs(mode: ToolPresentationMode): () => void`：为本 agent 选择面向模型的呈现方式，仅对该 agent 遮蔽 `mode` 配置；从普通上下文调用会抛出（进程级呈现方式是那个配置字段），同一 scope 内第二次声明也会抛出。code 类模式还会为该 agent 注册它自己的 `tools:sdk` 段。工具目录保持不变：`schemas(agent)` 仍会报告该 agent 的能力；只有组装结果中的工具列表会按所选呈现方式收束。随调用方 fiber dispose。 - `ctx.tools.restrict(filter)`：对全局工具应用 agent 作用域的允许／拒绝掩码；从普通上下文调用会抛出。筛选器在注册时创建快照；多个掩码取交集，随后再合并作用域本地工具。拒绝掩码会接纳后来出现且未点名的全局工具，而允许掩码会排除后来出现的名称。未知、本地或保留名称以及空筛选器都会被拒绝。这是实时可见性组合，不是权限边界；参见[作用域安全非目标](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.zh.md#security-and-authority-are-non-goals)。 -- `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined`：返回指定作用域可见的解析结果，其中已应用名称遮蔽；被作用域限制排除的全局工具会被视为不存在。呈现器会传入发起调用的 agent，使卡片与实际执行内容一致。 +- `ctx.tools.get(name: string, scope?: ScopeKey): ToolDefinition | undefined`：返回指定作用域可见的解析结果，其中已应用名称遮蔽；被作用域限制排除的全局工具会被视为不存在。需要匹配实际执行 definition 的 Host 本地 presenter 消费方会传入发起调用的 agent。 - `ctx.tools.schemas(scope?: ScopeKey): ToolSchema[]`：返回该作用域可见的所有 schema（不含 `execute` 函数）。已交付工具的 schema 收录在 [docs/tool-catalog.md](../../../docs/tool-catalog.zh.md) 中；该目录通过启动每个工具插件并采集此方法的结果生成（参见[工具 schema 目录 Agent Note](../../../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.zh.md)）。 - `ctx.tools.guard(guard: ToolGuard): () => void`：在 `tools/pre-execute` 之后注册单调同步执行守卫：返回理由会拒绝调用，返回 `undefined` 则保持原决定。普通上下文守卫全局生效；`agent.ctx` 守卫只对该 agent 生效。后续 waterfall（瀑布式事件）监听器无法将守卫的拒绝重新变为允许。随调用 fiber dispose。 - `ctx.tools.execute(exec)`：以无损方式快照并冻结参数，分配不透明 token，运行完整的策略／分发／结果流水线，然后在最终观测前独立快照权威结果。无效参数会进入同一结果路径，但不会到达策略或工具主体。环绕包装层只能替换 `signal`；注册表会在进入工具主体之前，立即将调用方的原始信号重新合并到当前信号中。 @@ -49,7 +49,7 @@ tools: - `PreToolDecision`：`{kind:'allow'}` | `{kind:'deny', reason}` | `{kind:'ask', reason?}`。该类型有意不提供输入改写；`ask` 在挂载 [`ctx.approval`](../../interaction/user-approval/README.zh.md) 时由它处理，否则退化为拒绝。 - `PostToolDecision`：接受决定可以替换 `content` 或 `value`（不能同时替换），并可附加 `additionalContexts`；阻止决定会把反馈变成无值失败。替换内容会保留规范值和元数据。替换值会重新验证，并重新呈现内容／元数据。接受决定会先保留工具延迟的上下文，再附加决定上下文；阻止决定会丢弃工具延迟的上下文，只公开阻止决定显式提供的上下文。 - `ToolGuard`：`(execution) => string | undefined`；返回的字符串是最终单调拒绝理由，在可重排的前置执行 waterfall 之后、分发之前求值。 -- `ToolCallView` / `ToolResultView`：提供方无关、带 `card` 标签的呈现意图；工具通过 `presentCall` / `presentResult` 返回该意图，从而拥有 UI 呈现其自身调用的方式（参见「工具拥有的 UI 呈现」）。 +- `ToolCallView` / `ToolResultView`：保留的 Host 侧 `presentCall` / `presentResult` 扩展所返回的、提供方无关且带 `card` 标签的值（参见「Host 展示描述」）。内置 Web Client 不消费这些值。 @@ -106,14 +106,14 @@ ctx.tools.register(defineTool({ `JsonSchemaNode` 是工具输出、Code Mode 生成、subagent 和工作流共享的原始 JSON Schema 对应类型。它允许任意 JSON 根、仅含注解且不施加约束的 JSON 节点，以及恰好匹配一个分支的 `oneOf`；注解必须保持为无损 JSON。`assertSupportedJsonSchema()` 拒绝不受支持的构造，而 `validateJsonSchemaValue()` 返回带路径的违规信息。subagent 和工作流通过 `assertObjectJsonSchema()` 与 `ObjectJsonSchema` 保留调用方定义的对象根要求，而不是依赖共享词汇的限制。 -### 由工具定义的 UI 呈现 +### Host 展示描述 -工具可以选择通过纯函数 `presentCall()` 和 `presentResult()` 定义呈现意图，使 UI 无需针对工具名称编写特殊逻辑： +工具可以为 Host 本地消费方保留纯函数 `presentCall()` 和 `presentResult()` 呈现意图： - 调用视图为 `{ card: 'generic', title, kind?, rawInput?, content?, locations? }`、`{ card: 'terminal', title, description?, cwd? }` 或 `{ card: 'diff', title, diffs, locations? }`。 - 结果视图为 `{ card: 'generic', title?, content? }`、`{ card: 'terminal', title?, output?, exitCode?, signal? }`、`{ card: 'diff', title?, diffs }`、`{ card: 'search', shape, title?, truncated, total, … }`（已完成的发现型搜索——`shape: 'matches'`（grep）为按文件分组的匹配，`shape: 'paths'`（glob）为扁平路径列表，配 `truncated`/`total` 使 UI 永不把被截断的结果当作完整结果呈现；该视图不携带结果文本，且搜索没有 `card: 'search'` 的调用时对应视图）、`{ card: 'read', title?, path, offset, lines, totalLines, lang?, content? }`（已完成的文件读取→带行号、可选语法高亮的代码视图；`offset` 是窗口请求的 1-based 起始行，即使 `lines` 为空也保留；`lines` 是 `{ number, text }[]`，保留每一行的文件行号，`content` 是去除读取结果外层封装后的正文，供不支持读取视图的 UI 回退显示）或 `{ card: 'web', kind: 'search' | 'fetch', title?, … }`（已完成的 web 检索；`kind` 各分支携带结构化的搜索来源或抓取摘要，不具备 `web` 能力的 UI 回退到原始结果内容）。 -返回 `undefined` 会选择通用回退。呈现器只依赖其参数和持久结果，因为 UI 会在实时流式输出和日志回放期间调用它们。`output.presentationMeta(args, value)` 为直接的顶层调用派生 JSON 元数据；该元数据随 `tool/result` 持久化并传回 `presentResult`，而规范值本身仍只存在于执行局部，绝不会回放。嵌套 Code 分发不会计算元数据。`defineTool` 会软验证较旧的日志参数并回退，而不会使回放崩溃。`dsh-tool-bash` 与 `dsh-tool-fs` 是参考实现；[规范输出 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md) 规定值／呈现拆分，[呈现意图 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md) 规定卡片词汇。 +返回 `undefined` 会让调用 presenter 的消费方选择通用回退。presenter 只依赖其参数和持久结果，因此消费方可以在实时流式输出或日志回放期间使用。`output.presentationMeta(args, value)` 为直接顶层调用派生 JSON metadata；该 metadata 随 `tool/result` 持久化，既可供 `presentResult` 使用，也可供自行派生展示的 Client 使用，而规范值本身仍只存在于执行局部，绝不会回放。嵌套 Code 分发不会计算 metadata。`defineTool` 会软验证旧日志参数，并在不匹配时返回 `undefined`。Session Remote 不调用也不运输这些 presenter：内置 Web Client 通过 `tool.call.toolview` 选择 renderer，并从原始调用参数、结果内容、失败状态和持久 metadata 派生 card props。`dsh-tool-bash` 与 `dsh-tool-fs` 仍是 presenter 参考实现；[规范输出 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.zh.md) 规定值／呈现拆分，[呈现意图 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-02-tool-render-intent-union.zh.md) 规定保留的卡片词汇，[Client 派生展示决定](../../../.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md) 规定 Web transport 的拆分。 ### Code Mode diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index e8558ee64d..3901480cb0 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -294,9 +294,10 @@ export interface ToolResult { /** Whether the call failed. */ isError: boolean /** - * The tool-private presentation payload projected by its output declaration - * and threaded verbatim from the `tool/result` event. Absent when the tool - * declared no projector or the call was nested under a composite transport. + * The tool-private presentation payload projected by its output declaration. + * It is persisted verbatim on `tool/result` for Host presenters and Client + * renderers to narrow independently. Absent when the tool declared no + * projector or the call was nested under a composite transport. */ meta?: JsonValue } 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 fce084cf6a..0458ac1704 100644 --- a/packages/extensions/cordis-client-runner/src/client/api-catalog.ts +++ b/packages/extensions/cordis-client-runner/src/client/api-catalog.ts @@ -647,7 +647,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionEventEntry', - declaration: 'export interface SessionEventEntry {\n readonly event: SessionWireEvent;\n readonly view?: SessionToolView;\n}', + declaration: 'export interface SessionEventEntry {\n readonly event: SessionWireEvent;\n}', }, { name: 'SessionEventSource', @@ -685,14 +685,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionStandardProps', declaration: 'export interface SessionStandardProps {\n}', }, - { - name: 'SessionToolCallView', - declaration: 'export type SessionToolCallView = (Omit & {\n readonly rawInput?: JsonValue;\n}) | TerminalCallView | DiffCallView;', - }, - { - name: 'SessionToolView', - declaration: 'export type SessionToolView = {\n readonly for: \'call\';\n readonly view: SessionToolCallView;\n} | {\n readonly for: \'result\';\n readonly view: ToolResultView;\n};', - }, { name: 'SessionWireEvent', declaration: 'export interface SessionWireEvent {\n readonly type: string;\n readonly seq: number;\n readonly time: number;\n readonly data: JsonValue;\n readonly ignorable?: true;\n readonly sourceEventSeqs?: number[];\n readonly surfaceOp?: SurfaceOp;\n}', diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 9d0fc17eb8..6f7d362aa8 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -1275,7 +1275,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ { signature: '@Remote(\'page\') page(request: SessionPageRequest, signal: AbortSignal): Promise', description: 'Read one cold-safe, message-aligned Session history page.', - parameters: [{ name: 'request', description: 'durable address, backward cursor, and page budget.' }, { name: 'signal', description: 'cancellation for persistence and presentation reads.' }], + parameters: [{ name: 'request', description: 'durable address, backward cursor, and page budget.' }, { name: 'signal', description: 'cancellation for persistence reads.' }], returns: 'one chronological page and optional latest projections.', }, { @@ -4415,7 +4415,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionEventEntry', - declaration: 'export interface SessionEventEntry {\n readonly event: SessionWireEvent;\n readonly view?: SessionToolView;\n}', + declaration: 'export interface SessionEventEntry {\n readonly event: SessionWireEvent;\n}', }, { name: 'SessionEventMap', @@ -4753,14 +4753,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'SessionTitleUserMessage', declaration: 'export interface SessionTitleUserMessage {\n readonly seq: number;\n readonly text: string;\n}', }, - { - name: 'SessionToolCallView', - declaration: 'export type SessionToolCallView = (Omit & {\n readonly rawInput?: JsonValue;\n}) | TerminalCallView | DiffCallView;', - }, - { - name: 'SessionToolView', - declaration: 'export type SessionToolView = {\n readonly for: \'call\';\n readonly view: SessionToolCallView;\n} | {\n readonly for: \'result\';\n readonly view: ToolResultView;\n};', - }, { name: 'SessionUpdateQueueRequest', declaration: 'export interface SessionUpdateQueueRequest {\n readonly sessionId: SessionId;\n readonly itemId: MessageId;\n readonly action: QueueAction;\n}',