Tianyi Cui
a7a5be1703
Run the dsh-archive-agent-notes audit over every active Agent Note on current master, judging each record by whether its rationale still guides work rather than by size or age. - Archive 453 implemented bilingual triplets (417,882 English words): completed UI chrome, narrow adapters, closed bug fixes, implementation walkthroughs whose package READMEs, docs pages, generators, or successor notes now carry the useful behavior, and 51 records fully superseded by a later active note. Keep 201 implemented notes whose ownership rules, negative guarantees, durable or wire semantics, security rules, reintroduction conditions, or still-tempting rejected alternatives remain useful. - Reject 7 proposals whose premise is gone or whose work shipped in amended form under other records; delete 2 rejected notes that no longer prevent a plausible mistake. - Retarget every remaining inbound link to the archived path, and repair active prose that named an archived record as the owner of a live fact: parenthetical citations drop, ownership sentences redirect to the README, docs page, or active note that states the fact, and history citations say so. Chinese files link the English archived path because the pairing gate treats the frozen tree as outside the bilingual corpus. - Seal 1,359 new frozen artifacts; existing seals are unchanged and outbound links from archived notes are neither inspected nor repaired. - Regenerate docs/config-catalog.md after the hook-bridge comment edits shifted two source line numbers.
description, kind
| description | kind |
|---|---|
| Web @file and @session reference source for the composer: candidates, ordering, and atomic inline references (unified file/session picking). | package-reference |
@deepseek-ai/dsh-client-ui-reference
English | 中文
Summary
dsh-client-ui-reference is the unified Web @file and @session reference source: it registers the reference entry in the composer's inline-suggestion machinery so a user typing @ sees file and session candidates in one list. Files order before sessions, sections are labelled with locale-registered terms, and either candidate domain can fail independently without blocking the other. Each row carries only what distinguishes it: a file names its parent directory and nothing at the workspace root, a session names its workspace only when that workspace is not the current one, and a drilled directory listing names none because its breadcrumb already does. A pick inserts an atomic inline reference — file, folder, and session alike — whose hidden serialized and clipboard form is the natural text the shared @path grammar defines; a directory row additionally carries a drill verb (Tab or the row's chevron) that keeps plain editable path text and the menu active at its trailing slash so the user can descend another level. Selecting a session routes through the session-reference service, which validates the mention and captures model context at the pre-step boundary; this package itself registers no prompt or tool.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
The source is active whenever the composition mounts this package and a Host ctx.fileReferences provider is available. Type @ followed by an unquoted token to see files first, then sessions; open @"… to search files only. The candidate list is a completion menu, not a search result page: pick once and keep typing.
What a pick inserts
A file closes completion as an atomic inline reference displayed with a file glyph and business-color filename. A directory row carries two verbs: the settling pick (row click or Enter) resolves the folder itself as the same kind of atomic reference — folder glyph, trailing-slash label, canonical @dir/ mention as its serialized form — while the drill action (Tab or the row's chevron) keeps plain editable path text with a folder glyph and the menu active at its trailing slash, so you can descend another level. Paths containing whitespace use @"path with spaces", and a quote the user opened explicitly remains quoted.
A session pick inserts an atomic inline reference whose hidden ref and clipboard representation is the canonical @[label](dsh-session:…) mention returned by the Host; its visible form is a chat-bubble glyph plus the session title. Sending carries the mention through session.prompt, and the session-reference service validates it and captures model context at agent/pre-step.
Failure behavior
One unavailable or failed candidate domain yields no rows for that domain while the other still lists. A session-reference preparation failure occurs after prompt acceptance and terminates that agent turn.
Understand the implementation
Implementation internals — click to expand
The source keeps candidate encoding internal to the registration effect: the /client export is the plugin body (apply/inject) only.
Candidate flow
For an unquoted token, the browser starts the fileReferences/list and sessionReferenceResolver/candidates Remote calls together, then deterministically orders files before sessions with locale-registered folder/file/session labels. Rows render under non-selectable file and session section headings without a redundant raw reference source title. A session row is dated from the Host session list's updatedAt through the same relative-time bucket that list uses, so one session reads the same age on both surfaces; a session the list does not carry falls back to the candidate's creation time. A drilled query publishes a breadcrumb from the workspace root to the directory being listed; each crumb carries the drill payload a folder row would, so returning to a step and descending into one are one outcome.
Serialization
File picks preserve the natural text defined by the shared @path grammar as the hidden serialized and clipboard form. Session picks use the canonical @[label](dsh-session:…) mention; serialization never reconstructs identity from the visible title.
Further Exploration
These pages cover the suggestion machinery, the reference seams, and the input pipeline.
- ui-input-trigger — the inline suggestion machinery the source registers into.
- file-reference — the
@fileseam and its provider contract. - session-reference — the
@sessionseam and prepared snapshot semantics. - Web input machine and slash pipeline — how references and commands share the input machine.
Model Experience
Indirectly, through Host-owned providers, which own the file guidance and session snapshot preparation this package's reference selection delegates to them.
KV Cache effect
Candidate browsing has no model effect. A selected file or session changes only the new user-message suffix and any Host-prepared session-reference context that follows that message; earlier target history remains unchanged.
Known Limitations and Deferred Work
These limits define when the reference source cannot help; they are current package constraints.
- Candidate failure is intentionally quiet — one unavailable or failed Remote discovery call yields no rows for that domain. A session-reference preparation failure occurs after prompt acceptance and terminates that agent turn.
- No browser-side file scan — Web completion requires a mounted Host
ctx.fileReferencesprovider; the browser cannot fall back to its own filesystem. - Session search remains metadata-only — discovery filters session id, cwd, and the latest log-backed title through
ctx.sessionReferenceResolver; message bodies and full transcripts are not searched.
Dev Note
Working context for maintainers — click to expand
None.
Runtime invariant: No companion is published. A single slash-source registration whose disposal is proven by the HMR-safety spec — it emits no cordis events and owns no cross-plugin mutable state.