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. A pick inserts an atomic inline reference — a file closes completion with an editable path text, a session inserts a canonical mention — so the sent text is the same natural text the shared grammar defines. 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.

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 remains plain editable path text with a folder glyph and keeps 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.

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 @file seam and its provider contract.
session-reference — the @session seam 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.fileReferences provider; 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.

README.md