dsh-reference-anything 0.4.4 → 0.5.1

package/NOTICE.md

@@ -1,5 +1,24 @@
 # Third-party notices
 
+## Lucide action icons
+
+The Import, Summary, and Undo 2 SVG paths in `src/client/provider-icons.tsx`
+are from https://github.com/lucide-icons/lucide and are licensed under ISC:
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
 The OpenCLI provider adapters in `opencli-plugin/` are derived in part from
 `pinguarmy/ai-chat-exporter` at commit
 `9f0f9e21d818316d45c0a13c98d288a80bb8174e`.
@@ -46,7 +65,46 @@ redistributed by this package.
 
 ## DeepSeek Harness reference services
 
+`src/client/native-reference-text.tsx` adapts `user-text-rules.ts` and
+`FileReference.tsx` from `packages/client/ui-reference/src/client/` at
+https://github.com/deepseek-ai/deepseek-harness/tree/687f282e8625c6b8d11ff58211a90524be2e4317.
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 File candidate formatting and cross-session candidate types use the official
 DeepSeek Harness packages `@deepseek-ai/dsh-file-reference` and
 `@deepseek-ai/dsh-session-reference`. Those packages remain external package
 dependencies and are used under the DeepSeek Harness project's MIT license.
+
+## dsh-chat-import agent icons
+
+Settings icons in images/agents are copied from Nwflower/dsh-chat-import (dbd03e1dfeaffea980458df1afc4ef899af9a2a4).
+Copyright (c) 2026 Nwflower; Copyright (c) 2026 Scarlett.
+Distributed under the MIT License; the full license is included in images/agents/LICENSE.
+
+## Bundled conversation scanners and readers
+
+`vendor/chat-import-reader/parsers.mjs` and `scanners.mjs` contain adapted
+read-only discovery, database summary, parser and preview code from Nwflower/dsh-chat-import npm 0.26.1, plus its fzstd decoder.
+Copyright (c) 2026 Nwflower and Scarlett; fzstd copyright (c) 2020 Arjun Barrett.
+Both are MIT licensed. Full licenses are shipped in
+`vendor/chat-import-reader/LICENSE` and `LICENSE.fzstd`; source hashes and
+regeneration instructions accompany the snapshot in the repository.

package/README.md

@@ -35,25 +35,27 @@ One `@` for them all.
 
 </div>
 
-**Reference Anything is an enhancement for the DeepSeek Harness (DSH) `@` menu.** It brings multiple reference sources into one searchable menu, so you can mention the context you need without switching tools or copying content manually.
+**Reference Anything is an enhancement for the DeepSeek Harness (DSH) `@` menu.** It brings files, sessions, local agents, web chats, cloud drives, and local plugins into one searchable menu, so you can mention the context you need without switching tools or copying content manually.
 
-After typing `@`, you can browse and click items in the menu with your mouse, or use the keyboard to enter text, search, and narrow down the results.
+After typing `@`, you can browse and click items in the menu with your mouse, or use the keyboard to enter text, search, and narrow down the results. When a folder is selected, press `Tab` to enter it and continue browsing, or `Enter` to insert the folder reference.
 
 Use one `@` menu to reference:
 
 - 🧩 DSH commands and Skills
 - 📁 Workspace files and folders
 - 💬 DSH session history
-- 🖥️ **NEW: Transcripts left on disk by other local agent CLIs (Claude Code, Codex, Cursor, and eleven more)**
-- ✨ **NEW: Historical conversations from online chatbots like ChatGPT, Claude, Gemini, DeepSeek, Grok, and Kimi**
-- ☁️ **NEW: Files from cloud drives connected through OpenList**
+- 🖥️ **Local Agent conversations:** bundled scanning and read-only parsers for 29 source formats, including Claude Code, Codex and Cursor; optional import into DSH through Chat Import. Live acceptance coverage is recorded separately.
+- ✨ **Added by this plugin — highlight: Historical conversations from web chatbots including ChatGPT, Claude, Gemini, DeepSeek, Grok, and Kimi**
+- ☁️ **Added by this plugin: Files from cloud drives connected through OpenList**
+- 🧩 **Added by this plugin: Installed and configured local DSH plugins, without repeatedly hunting through directories**
 
 Beyond extending what `@` can reference, Reference Anything also enhances the `@` menu itself:
 
-- Customize visible groups: enable or hide `Commands`, `Skills`, files, DSH sessions, local agent conversations, external conversations, and cloud-drive files, then arrange them in any order
+- Customize visible groups: enable or hide `Commands`, `Skills`, files, DSH sessions, local agent conversations, external conversations, cloud-drive files, and local plugins, then arrange them in any order
+- Customize shortcuts: assign your own shortcuts to source groups, web providers, local agents, and cloud-drive mounts
 - Customize result counts: set each group's collapsed row count and hard candidate cap independently
 - Choose how to browse: expand or collapse individual groups, or use DSH's native scrolling list
-- Enhanced visual icons: distinguish reference sources with type icons and platform logos, making menu items easier to identify
+- Enhanced visual icons and commands: distinguish reference sources with type icons and platform logos
 
 <table>
   <tr>
@@ -75,6 +77,59 @@ Type `@`, search across enabled sources, and insert the selected reference into
 
 ## 📰 News
 
+### 0.5.0 Preview · Feature Demos
+
+This update also adds unified local pagination, resumable long-text reads and message/tool search, rechecks source switches on every read, and moves non-local tools to external_reference_list/read. See the [release and migration guide](./docs/release-v0.5.0.md). See also the [v0.5.1 compatibility fixes](./docs/release-v0.5.1.md).
+
+#### Import Past Conversations into DSH and Pick Up Where You Left Off
+
+Want to continue an existing local session without copying and pasting chat logs or treating old threads purely as static context?
+
+Now, when you find a local session in the `@` menu, you have two ways to use it:
+- **Reference as context (`Enter`)**: Insert the session directly as a reference;
+- **Import and continue chatting (`Tab`)**: Open the action menu, select **Import**, and confirm to bring the entire conversation history into DSH and keep chatting seamlessly! (Prefer a faster workflow? You can disable the confirmation prompt in Settings.)
+
+> 💡 **Note**: Importing requires `dsh-chat-import` v0.26.1 or a compatible newer version to be installed and enabled.
+
+![Press Enter to reference a session, or Tab to open the action menu and import history; uses mock data.](./release-notes/0.5.0/demos/agent-import.gif)
+
+#### One-Click Upgrade for `dsh-chat-import` Right from the Menu
+
+If an outdated version of `dsh-chat-import` prevents you from using chat import or handoff summaries, you no longer need to update it manually.
+
+Simply click the **upgrade prompt** right inside the menu to update to v0.26.1 or later. If prompted after the upgrade, restart DSH to apply the changes.
+
+![Upgrade dsh-chat-import from the menu and view the simulated restart prompt in settings.](./release-notes/0.5.0/demos/chat-import-upgrade.gif)
+
+#### Type `@plugin:` to Reference Installed Plugins Directly
+
+Want your Agent to troubleshoot a plugin issue or inspect its source code? Digging through deep system folders just to find the installation path is a hassle.
+
+Now you can simply type `@plugin:`, search for the plugin name, and press `Enter` to pass its installation directory straight to the Agent (supports all plugins currently installed in your DSH environment).
+
+![Filter local plugins in the @plugin: menu and press Enter to insert the plugin directory reference.](./release-notes/0.5.0/demos/local-plugins.gif)
+
+#### Custom Shortcuts to Narrow Down Your Search Scope Instantly
+
+Tired of scrolling through a cluttered `@` menu full of files, folders, and different sources just to find a past conversation?
+
+You can now assign **custom shortcuts** to different chat sources in Settings (multiple shortcuts can be separated by commas), allowing you to filter by category and narrow down your search scope right as you type:
+- **Search across a combined group**: Not sure where a conversation happened? Assign the same shortcut (e.g., `chat`) to both Local Agents and Web Chats, then type `@chat:` to narrow your search exclusively to those sources;
+- **Target a specific source**: When you know exactly where to look, use a dedicated shortcut like `@codex:` to filter exclusively for Codex sessions.
+
+![Configure shared shortcuts in settings, then search sessions using both shared and source-specific shortcuts.](./release-notes/0.5.0/demos/shortcuts.gif)
+
+#### Browse Folders Directly in the `@` Menu — No Need to Type Full Paths
+
+Want to reference a deeply nested folder without memorizing or typing out its full path?
+
+You can now navigate folder hierarchies directly inside the `@` file menu:
+- **Open subfolder**: Select a folder and press `Tab` to step inside;
+- **Go back**: Use the breadcrumb navigation bar at the top of the menu;
+- **Insert reference**: Press `Enter` on your target folder to insert it directly into your chat.
+
+![Press Tab in the file menu to enter subdirectories, navigate back, and press Enter to reference a folder.](./release-notes/0.5.0/demos/folders.gif)
+
 - **2026-10-12 · v0.4.4** — Added local plugin discovery to the `@` menu, configurable source and provider shortcuts, improved picker icons and folder insertion, and added the `model` command entry.
 
 - **2026-10-06 · v0.4.3** — Reference Anything now supports DSH Desktop! Enjoy a refreshed and optimized settings page!
@@ -88,7 +143,7 @@ Type `@`, search across enabled sources, and insert the selected reference into
 ## 🧭 Roadmap
 
 - [x] Support referencing historical conversations from other local agents
-- [ ] Support continuing referenced local-agent sessions
+- [x] Support continuing referenced local-agent sessions (Continue Session)
 - [x] Reference cloud-drive files through OpenList
 - [ ] Manage cloud-drive files inside the plugin (in progress; current access is read-only)
 - [ ] Support more keyword matching rules, including blacklists and whitelists, especially for file search
@@ -103,72 +158,82 @@ Type `@`, search across enabled sources, and insert the selected reference into
 
 ## 📦 Installation
 
-Prerequisites:
+The released version is **v0.5.1**, with a declared minimum DSH SDK version of **`0.2.0-rc.2`**.
 
-- `dsh` is installed and running; automatic OpenCLI installation requires the `npm` bundled with Node.js.
-- The target platforms are already logged in under the selected Chrome Profile.
+### Official desktop app
 
-Install the stable `0.3.x` line for the current stable DSH SDK:
+Reference Anything handles native references by default. If you explicitly enable the official `ui-reference` plugin in your profile, restart DSH and reload the page: the official plugin handles native references, and RA hides its duplicate file and DSH session candidates. Previously inserted RA file/session references still work; other RA sources are unaffected.
 
-```powershell
-dsh plugin --profile web add dsh-reference-anything@latest
-```
+Official file and session sections follow RA's visibility switches and independent ordering, and retain its collapsed item counts and expand/collapse actions, including arrow-key, Enter, and Tab navigation. The official plugin still handles reference insertion, copying, and previews. Select “No collapse (native)” to show the full list; unsupported candidate formats also fall back to the full list.
 
-Install `v0.4.4` on DSH `>=0.2.0-rc.2`:
+After Tab enters a file directory, RA pauses searches in other sources and the menu shows only files. Returning to the root restores other sources. Expand/collapse actions use gray text.
 
-```powershell
-dsh plugin --profile web add dsh-reference-anything@alpha
-```
+Download the official desktop app from the [DeepSeek Harness website](https://www.deepseek.com/en/harness/), open **Plugins → Add plugin**, enter `dsh-reference-anything`, and follow the prompts to install and enable it. Restart DSH if asked, then open **Settings → Reference Anything**.
 
-After the DSH alpha API stabilizes and the migration is verified, the `alpha` line will be promoted to `latest` and become the default installation.
+Desktop uses a separate plugin profile; plugins installed in the Web profile are not automatically enabled in Desktop. See the [official desktop documentation](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/desktop/README.md).
 
-To install the stable source locally with DSH `v0.1.0-rc.8 ~ v0.1.1-rc.2`:
+### DSH Market
+
+Open [Reference Anything on DSH Market](https://dshmarket.com/p/Chael-Chael/dsh-reference-anything/), or search for `dsh-reference-anything` in the in-app market. If the market is not installed, use **Add plugin** with `dshmarket` in Desktop; for Web, run:
 
 ```powershell
-git switch main
-pnpm install
-npm run check
-dsh plugin --profile web add .
+dsh plugin --profile web add dshmarket
 ```
 
-To install the alpha source locally with DSH `v0.2.0-rc.2` or newer:
+### Web CLI
 
 ```powershell
-git switch alpha
-pnpm install
-npm run check
-dsh plugin --profile web add .
+dsh plugin --profile web add dsh-reference-anything
 ```
 
-> [!NOTE]
-> To restore DSH's original `@` menu appearance, simply uninstall this plugin.
+The installed version depends on the selected channel; this README describes v0.5.1.
+
+### Optional: Connect web AI chats
+
+Only web chats need this step. Local sources work without it. Sign into the desired platforms in your browser. OpenCLI is installed with this plugin; adapter setup still needs npm.
 
-After installing the DSH plugin, open `Settings → Reference Anything → Availability check` in DSH Web (restart DSH first if this settings entry is not yet visible), then click **One-click setup**. It discovers OpenCLI; installs or upgrades it globally through npm when it is missing or older than `1.8.6`; installs the bundled adapters for all six platforms; starts or refreshes Browser Bridge; and opens the OpenCLI Browser Bridge page in the [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk). Confirm the extension installation, then return and click **Recheck setup**. Any remaining failed check displays its own recovery action.
+After installing the DSH plugin, open `Settings → Reference Anything → Availability check` in DSH (restart DSH first if this settings entry is not yet visible), then click **One-click setup**. It uses OpenCLI 2.0.0 installed as a runtime dependency and updated together with this plugin; installs the bundled adapters for all six platforms; starts or refreshes Browser Bridge; and opens the OpenCLI Browser Bridge page in the [Chrome Web Store](https://chromewebstore.google.com/detail/opencli/ildkmabpimmkaediidaifkhjpohdnifk). Confirm the extension installation, then return and click **Recheck setup**. Any remaining failed check displays its own recovery action.
 
-You can also install OpenCLI and the conversation adapter manually, then start Browser Bridge:
+For a custom global OpenCLI, install it manually and enter its full executable path in settings. The default opencli always uses the plugin dependency:
 
 ```powershell
-npm install --global "@jackwener/opencli@>=1.8.6"
+npm install --global "@jackwener/opencli@2.0.0"
 opencli plugin install file:///C:/path/to/dsh-reference-anything/opencli-plugin
 opencli daemon restart
 ```
 
-Replace `C:/path/to/dsh-reference-anything` with the repository location. Browser extensions cannot be silently installed from a webpage; confirm the installation in the Chrome Web Store, or download an extension package from [OpenCLI Releases](https://github.com/jackwener/opencli/releases) and use “Load unpacked.” If the browser blocks the store popup, the settings page keeps a normal fallback link. When multiple browser profiles are connected, select and apply one directly in the failed check. Global npm installation remains subject to OS permissions; failures retain their original diagnostic in the settings page.
+Replace `C:/path/to/dsh-reference-anything` with the repository location. Browser extensions cannot be silently installed from a webpage; confirm the installation in the Chrome Web Store, or download an extension package from [OpenCLI Releases](https://github.com/jackwener/opencli/releases) and use “Load unpacked.” If the browser blocks the store popup, the settings page keeps a normal fallback link. When multiple browser profiles are connected, select and apply one directly in the failed check. OpenCLI updates with this plugin; the browser store updates the extension separately.
 
 ## 🚀 Usage
 
 Reference Anything registers eight sources in the native DSH `@` menu rather than introducing a separate search interface. Settings let you choose which groups appear, their order, their collapsed row count, their hard candidate cap, and whether groups use plugin-owned collapse actions or the native scrolling list. A separate one-click control switches the visible picker back to DSH's official file/session list without stopping the plugin, synchronization service, local data, or model-facing tools; the same control restores the Reference Anything picker at any time.
 
-1. Open `Settings → Reference Anything` in DSH Web.
-2. Under **Availability check**, confirm that OpenCLI, Browser Bridge, the browser extension, and the conversation adapter are ready.
-3. Under **Web AI conversation sync settings**, choose a browser profile, storage mode, sync mode, and history range, then start syncing.
-4. Type `@` in the input box and choose from the `Commands`, `Skills`, `Files and folders`, `DSH sessions`, `Local agent conversations`, `External conversations`, `Cloud drive files`, or `All local plugins` groups.
-5. Type a keyword to filter candidates, for example `@cache-design`.
+1. Type `@` to browse sources, or enter a keyword such as `@cache-design`.
+2. Click a result, or select it with the arrow keys and press `Enter`. For workspace folders, `Tab` opens the folder and `Enter` inserts a reference.
+3. Add your request and send it: “Use this Codex conversation and project folder to check whether the earlier plan has been implemented.”
+
+For web chats, complete the connection steps above, then choose platforms, browser profile, storage mode, and history range under **Settings → Reference Anything → Web AI conversation sync settings** and start syncing. For cloud files, connect OpenList and add a mount in Settings.
 
 The default **Read bodies on demand** mode stores only the title index locally and uses the browser when an agent needs the conversation. Choose **Store full bodies locally** for offline reading and full-text search. The plugin checks for new versions when it loads; release notes are available in Settings, and installed updates take effect after restarting DSH.
 
-> [!WARNING]
-> To protect your account and conversation data, external conversations are imported and synchronized through OpenCLI using your existing logged-in browser session. A browser window may temporarily open during use or synchronization. In most cases, leave it open in the background: the plugin will reuse it without interrupting your work. The window may also display OpenCLI debugging information. This is expected—please do not be alarmed or close it manually; wait for the operation to finish. Due to current OpenCLI limitations, we temporarily use slower serial synchronization to reduce how often browser windows open. Once the upstream OpenCLI repository is updated, we will switch to faster parallel synchronization.
+> [!NOTE]
+> OpenCLI may open or reuse browser windows while syncing web chats or reading bodies. Keep them available until the operation finishes. Sync speed depends on the platform, history size, and browser connection.
+
+### Shortcut examples
+
+These examples use the current defaults. After changing shortcuts, use the values shown in Settings.
+
+| Input | What it finds |
+| --- | --- |
+| `@file:README` | Workspace files and folders |
+| `@session:` | DSH session history |
+| `@agent:` / `@codex:` | Local agent history / Codex only |
+| `@chat:` / `@chatgpt:cache` | Web chats / matching ChatGPT chats |
+| `@drive:` | Connected cloud drives |
+| `@plugin:` | Local DSH plugins |
+| `@command:` / `@skill:` | Commands / Skills |
+
+Under **General**, set shortcuts for groups, web providers, local agents, and cloud mounts. Separate multiple shortcuts with commas: set the file group to `file,f`, then use `@f:README`. A shortcut can target multiple sources. Full-width colons (`：`) are also supported.
 
 ### 🧩 One `@` menu, multiple sources
 
@@ -176,30 +241,30 @@ The `@` menu contains eight groups: `Commands`, `Skills`, `Files and folders`, `
 
 #### ⌨️ @Commands — DSH native commands
 
-To browse commands, use `@commands`; selecting one hands `/command` back to DSH's native slash pipeline.
+To browse commands, use `@command:`; selecting one hands `/command` back to DSH's native slash pipeline.
 
 <p align="center"><img src="./images/at-commands.png" alt="Browse DSH commands from the @ menu" width="800" /></p>
 
 #### 🛠️ @Skills — DSH skill library
 
-To browse skills, use `@skills:`; selecting one inserts `/skill` for DSH's native skill handling.
+To browse skills, use `@skill:`; selecting one inserts `/skill` for DSH's native skill handling.
 
 <p align="center"><img src="./images/at-skills.png" alt="Browse DSH skills from the @ menu" width="800" /></p>
 
 #### 📁 @Files and folders — workspace files and directories
 
-Type `@files:` in the input box to browse files and folders through DSH's official file-reference Remote.
+Type `@file:` in the input box to browse files and folders through DSH's official file-reference Remote.
 
 <p align="center"><img src="./images/at-files.png" alt="Browse workspace files and folders from the @ menu" width="800" /></p>
 
 **Features:**
+
 - Uses the official `@path` / `@"path with spaces"` grammar and canonical file candidate service
-- Files become native atomic references; selecting a directory keeps the path editable and continues completion
-- The plugin no longer creates or parses a custom `dsh-file:` scheme
+- Files and folders become native references; press `Tab` on a folder to browse inside it, or `Enter` to insert it
 
 #### 💬 @DSH sessions — DSH session history
 
-Type `@sessions:` to browse DSH sessions through the official session-reference Remote.
+Type `@session:` to browse DSH sessions through the official session-reference Remote.
 
 <p align="center"><img src="./images/at-sessions.png" alt="Browse DSH sessions from the @ menu" width="800" /></p>
 
@@ -207,23 +272,39 @@ Selected sessions use DSH's canonical `dsh-session:` mention and native session
 
 #### 🖥️ @Local agent conversations — transcripts from local agent CLIs
 
-Type `@agents:` to search and reference conversations saved by other local agent tools.
+Type `@agent:` to search and reference conversations saved by other local agent tools.
+
+All 29 sources use bundled read-only scanners and parsers derived from dsh-chat-import. Scanning and references work without installing Chat Import. Source switches, additional directories and workspace scope still apply; settings show source paths, counts and scan errors. Enter inserts a reference, including recoverable images through DSH attachments; viewing images requires a vision-capable model. Confirmed empty conversations are hidden; read errors remain visible. Local references now store a readable source, path and session ID; reselect references created with the old local URI protocol.
+
+When you send local references, the plugin appends one aggregated background after each user message. The model reads `ref: {source, path, sessionId}` with a content `revision`. `reference_list` discovers local sessions; `reference_read` reads `messages`, `tools` or `images`; `reference_search` searches message/tool text; `reference_image` returns actual pixels.
+
+Use `from` for both scope and starting position: `messages` uses `messageId`; `tools` uses `toolId` with an optional owning `messageId`; `images` uses `imageId` with an optional owning `messageId`. Copy the complete `next` object into `from` to continue. Long text uses a Unicode code-point `textOffset`, preserving every remaining character rather than keeping only the head and tail. Source-provided summaries use `role: "summary"`; source limitations use an English `notice`. Source content is never translated.
+
+`reference-mention.maxTextBytes` caps all new reference contexts in one pre-step batch at 16 KiB by default; estimated remaining context can reduce it. `reference-tool.maxTextBytes` separately caps each local tool text result at 16 KiB. Unknown capacity leaves only bounded metadata and a notice; metadata that cannot fit fails explicitly. Previews contain a continuous recent suffix, with a continuation for an oversized final message. Images have a separate 10 MiB limit.
+
+Every new read checks the enabled source, allowed real path and session identity; no per-session grant is needed for local references. After a version change, restart `reference_read` with the same `ref`, `part: "messages"`, and omit both `revision` and `from`. No full-text snapshots or cross-call parsed-body caches are saved. Other sources retain their existing URI-based protocol under `external_reference_list` and `external_reference_read`.
+
+Import status, session import and handoff summaries use the optional Chat Import API. Install or upgrade the independent plugin from settings when needed; Reference Anything does not install it on startup. An unavailable API leaves import status unknown and does not stop local scanning or reference reading. Tab retains the configured import and summary actions and confirmation flow.
+
+The scanner runs in a separate process and caches metadata for 30 seconds. Parsing a reference may still read its complete source before returning a page. Source code and icons retain their MIT licenses (see `vendor/chat-import-reader/` and `images/agents/LICENSE`). Maintainers update both snapshots with `npm run vendor:sync -- <built-dsh-chat-import-directory>`; see the vendor README for checks before shipping.
 
 <p align="center"><img src="./images/at-local-agents.png" alt="Browse other local agents' transcripts from the @ menu" width="800" /></p>
 
-**Supported agents:** Claude Code, Codex, Cursor, Qoder, Reasonix, OpenClaw, Kimi, Grok Build, Hermes, Gemini CLI, Pi, opencode, mimocode, and zcode.
+**Supported sources:** Claude Code, Codex, Cursor, Gemini CLI, Antigravity, Reasonix, opencode, mimocode, zcode, Grok Build, OpenClaw, Pi, Hermes, Kimi, Kilo Code, Qoder, ChatGPT exports, WorkBuddy, Qwen Code, Continue, Cline, Goose, DSH 4, Zed, Crush, Teleagent, Trae Work, Vibe, and DSH.
 
 **Features:**
 
 - Automatically detects conversation history and shows the number found for each agent
 - Lets you enable agents independently or choose a custom history folder
 - Searches all detected conversations by default, with an option to limit results to the current workspace
-- Reads conversation content on demand; tool names are concise by default, with full details available when needed
+- Automatically previews recent body text; reads numbered messages, associated tool details and images on demand
 - Supports agent-specific prefixes such as `@codex:`, `@claude-code:`, and `@gemini-cli:`
 
+References read local history without modifying it. Import and handoff-summary actions are separate operations through Chat Import. Claude Code and Codex adapters have been checked against real transcripts; other formats are primarily fixture-tested and may vary by tool version. Database reads for opencode, mimocode, and zcode require `node:sqlite` in the DSH host runtime.
+
 #### 🧩 @Local plugins — installed and configured plugins
 
-Use `@plugin:`, `@plugins:`, `@插件:`, or `@本地插件:` to find plugins. Under **Settings → Reference Anything → General**, the **All local plugins** switch enables or disables this group immediately; the choice is saved. It is enabled by default, with six collapsed rows and a candidate cap of 50.
+Use `@plugin:` to find plugins. Settings can also show only running plugins or hide official DeepSeek plugins. Under **Settings → Reference Anything → General**, the **All local plugins** switch enables or disables this group immediately; the choice is saved. It is enabled by default, with six collapsed rows and a candidate cap of 50.
 
 The list uses the active DSH loader's composed entries and lifecycle state, supplemented by declared profile bundles and installed packages with DSH bundle/client metadata. Ordinary dependencies are excluded. Running, disabled, and not-running states describe host entries; packages without a host entry are shown as not running. Selecting a plugin inserts its name and, when available, a native reference to its real local directory. File access still uses DSH's existing tools and permissions.
 
@@ -233,15 +314,22 @@ Supports historical conversations from ChatGPT, Claude, Gemini, DeepSeek, Grok,
 
 <p align="center"><img src="./images/at-external-conversations.png" alt="Browse external conversations from the @ menu" width="800" /></p>
 
+**Store full bodies locally** enables offline reading of synchronized text; it does not mean attachments are saved offline. Automatic and startup sync are off by default and can be enabled in Settings.
+
 **Platform filtering:**
+
 - Use `@chatgpt:cache` or `@claude:refactor` to filter a specific platform
 - Short aliases are also accepted, such as `@gpt:` and `@ds:`
 - Entering `@claude` alone lists recent conversations for that platform
 
 **Search capabilities:**
+
 - **Title match:** fuzzy search on conversation titles
+
 - **Content search:** available only in **Store full bodies locally** mode; if title matches are insufficient, synchronized bodies are searched and matching excerpts are shown in the candidate list
+
 - **Provider and account isolation:** history is maintained separately by Provider and account scope
+
 - `@` search uses the account scope cached by the latest sync and never probes the browser; after a sync observes an account switch, it exposes only that account while older rows remain available in conversation management for cleanup
 
 **Reference display:** after selection, the draft shows a native removable DSH reference with the Provider logo. Its stable serialized form is:
@@ -249,11 +337,11 @@ Supports historical conversations from ChatGPT, Claude, Gemini, DeepSeek, Grok,
 @[ChatGPT·Conversation title](dsh-ref:<opaque-base64url>)
 ```
 
-Opening the source URL happens only in the UI; the URL is never injected into model context. The initial reference contains only a safe pointer; if the model needs the body, it calls `reference_read` on demand.
+Opening the source URL happens only in the UI; the URL is never injected into model context. A Web conversation reference initially contains only a safe pointer; if the model needs the body, it calls `external_reference_read` on demand.
 
 #### ☁️ @Cloud drive files — files connected through OpenList
 
-Type `@drive:`, `@cloud:`, `@netdisk:`, or `@网盘` to browse folders and reference files from cloud drives connected through OpenList.
+Type `@drive:` to browse folders and reference files from cloud drives connected through OpenList.
 
 Common providers include OneDrive, Aliyun Drive, Baidu Netdisk, Quark, 115, 123, Dropbox, Google Drive/Photos, and Yandex. Other providers available in OpenList can be configured from the same settings page.
 
@@ -270,25 +358,24 @@ Common providers include OneDrive, Aliyun Drive, Baidu Netdisk, Quark, 115, 123,
 ---
 
 **General notes:**
-- Use `:` or `/` as the separator instead of a space: the `@` candidate token ends at a space, so `@chatgpt keyword` closes the menu as soon as you press the space. For multi-word searches, write `@cachedesign` or `@cache-design`.
+
+- Use `:` after a group shortcut instead of a space: the `@` candidate token ends at a space, so `@chatgpt keyword` closes the menu as soon as you press the space. For multi-word searches, write `@cachedesign` or `@cache-design`.
 - Without a type prefix, all groups are searched at once.
 - Commands and Skills are handed back to DSH's native slash-command handling after selection; the native `/` panel remains available.
-- Switching the picker back to DSH's official file/session list hides every plugin-owned group, including `Local agent conversations` and `Cloud drive files`. The host source stays registered, so an already-inserted reference still expands and `reference_read` still works; only the menu entry is gone until you switch back.
+- Switching the picker back to DSH's official file/session list hides every plugin-owned group, including `Local agent conversations` and `Cloud drive files`. The host source stays registered, so an already-inserted reference still expands and `external_reference_read` still works; only the menu entry is gone until you switch back.
 
 ## 🔄 How External Conversation References Work
 
 ```text
-DSH Web @Conversations
+DSH Web / Desktop @chat:
         ↕ Host Remote
-DSH Host + reference_anything local mirror
+DSH Host + reference_anything index / optional body mirror
         ↕ execFile(opencli, argv)
 opencli-plugin-dsh-chat-history
         ↕ OpenCLI daemon + official Browser Bridge
 ChatGPT / Claude / Gemini / DeepSeek / Grok / Kimi
 ```
 
-This does not include the legacy standalone DeepSeek CDP / `--remote-debugging-port` collector. All six platforms use the OpenCLI Provider adapter path, avoiding duplicate browser-reading implementations.
-
 ### 🤖 Model-facing Protocol
 
 A reference produces an untrusted-data envelope alongside the current user request. The initial envelope contains only pointers and never the conversation body:
@@ -315,11 +402,11 @@ A reference produces an untrusted-data envelope alongside the current user reque
 }
 ```
 
-- The agent calls `reference_read({ uri, limit, cursor })` only when it needs the body. Turns in each page are in chronological order, and pagination moves from newer pages toward older ones.
+- The agent calls `external_reference_read({ uri, limit, cursor })` only when it needs the body. Turns in each page are in chronological order, and pagination moves from newer pages toward older ones.
 - For the initial `deferred=true` item, the first call passes only `uri` and does not send an empty `nextCursor`.
-- In offline-mirror mode, `reference_read` paginates over the current revision. In metadata-only mode, each read requests content from the Provider again and validates the cached account scope inside that same browser operation. Missing, account-mismatch, and fetch errors instruct the agent to ask for a Provider sync before retrying.
+- In offline-mirror mode, `external_reference_read` paginates over the current revision. In metadata-only mode, each read requests content from the Provider again and validates the cached account scope inside that same browser operation. Missing, account-mismatch, and fetch errors instruct the agent to ask for a Provider sync before retrying.
 - `before` is kept only as a deprecated compatibility parameter and cannot be combined with `cursor`.
-- A mention or `reference_list` grants the current task permission to read that URI; unauthorized URIs are rejected.
+- A mention or `external_reference_list` grants the current task permission to read that URI; unauthorized URIs are rejected.
 - Each conversation keeps only the latest revision. Cursors for older revisions expire after content changes.
 - `reference_attachment_read` validates the task grant and, for Web conversations, verifies that the active provider account still matches the account scope captured by sync. A mismatch is rejected with guidance to sync that provider and reselect the conversation.
 - Attachments are capped at 25 MiB while streaming. PNG, JPEG, WebP, and GIF may render inline; every other format, including SVG, is returned as an ordinary temporary file. Successful files expire after one hour, and failures or plugin disposal remove them immediately.

package/cordis.patch.yml

@@ -6,20 +6,25 @@
 - id: ui-reference
   # Reference Anything re-registers Files and DSH sessions as two independent
   # sources over the same official Remotes.  Disabling only this Client source
-  # keeps the official file/session services and canonical mention semantics.
+  # keeps the official file/session services. RA also owns the native
+  # "reference" codec and the newer Host's file/folder message renderers.
+  # If a profile explicitly enables ui-reference, RA defers those registrations
+  # and hides its duplicate file/session candidates (saved RA chips still work).
   disabled: true
 
 - insert:
+    - id: reference-chat-import-runtime
+      name: 'dsh-reference-anything/chat-import-runtime'
+
     # The registry every source registers into.
     - id: references
       name: 'dsh-reference-anything'
       config:
         listLimit: 20
 
-    # Expands plugin-owned `@[label](dsh-ref:…)` mentions into untrusted
-    # metadata on every surface. Native file and `dsh-session:` references stay
-    # with DSH's official services. External transcripts are not prefetched;
-    # the agent calls reference_read only when the current task needs one.
+    # Local Agent mentions receive bounded body previews before the model runs.
+    # Other external sources retain deferred reading. Native file and
+    # `dsh-session:` references stay with DSH's official services.
     - id: reference-mention
       name: 'dsh-reference-anything/reference'
       config:
@@ -76,9 +81,9 @@
         # OpenList is inert until a connection is configured in the Cloud
         # drives settings section; no account secret is stored in this patch.
         drives: ['openlist']
-        # Where OpenList listing starts when `roots` has no explicit entry.
-        # Keep it empty to show the OpenList root.
-        root: ''
+        # Where OpenList listing starts when `roots` has no explicit entry.
+        # Keep it empty to show the OpenList root.
+        root: ''
         # Optional OpenList root, for example {openlist: '/notes'}.
         roots: {}
         listTtlMs: 30000
@@ -90,9 +95,8 @@
         maxReadTurns: 20
         blockChars: 4000
 
-    # Transcripts other coding agents leave on disk, listed by title and read a
-    # window at a time. Reading one needs a per-task grant: these are other
-    # sessions' conversations, so the model may only open what its user named.
+    # Local transcripts are read only from enabled sources and allowed roots;
+    # no per-task grant. Every read rechecks the current source policy.
     - id: reference-local-agent
       name: 'dsh-reference-anything/local-agent'
       config:
@@ -106,9 +110,9 @@
                  'kimi', 'grokbuild', 'hermes', 'gemini-cli', 'pi',
                  'opencode', 'mimocode', 'zcode']
         extraRoots: []
-        # The @ menu is a cross-project history picker; the per-Agent enable
-        # switches remain the explicit visibility boundary.
-        scope: 'all'
+        # The @ menu is a cross-project history picker; the per-Agent enable
+        # switches remain the explicit visibility boundary.
+        scope: 'all'
         maxTranscripts: 200
         maxReadTurns: 20
         maxScanBytes: 33554432
@@ -118,7 +122,7 @@
         maxLineBytes: 1048576
         directoryTtlMs: 5000
         includeThinking: false
-        toolCalls: 'full'
+        toolCalls: 'full'
         includeSidechains: false
         stripEnvironmentPreamble: true
         # The last three formats keep every conversation in one SQLite database

package/images/agents/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Nwflower
+Copyright (c) 2026 Scarlett
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/images/agents/README.md

@@ -0,0 +1,3 @@
+Agent icons copied unchanged from https://github.com/Nwflower/dsh-chat-import/tree/dbd03e1dfeaffea980458df1afc4ef899af9a2a4/assets/agents.
+
+MIT license: see LICENSE in this directory. DSH4 reuses dsh.svg.

package/images/agents/antigravity.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><path d="M12 3.2 2.6 21.9h3.2l2.03-4.1h8.34l2.03 4.1h3.2L12 3.2zm0 4.6 2.72 5.5H9.28L12 7.8z" fill="#1A73E8"/></svg>

package/images/agents/chatgpt.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><g fill="#000000"><path d="M9.205 8.658v-2.26c0-.19.072-.333.238-.428l4.543-2.616c.619-.357 1.356-.523 2.117-.523 2.854 0 4.662 2.212 4.662 4.566 0 .167 0 .357-.024.547l-4.71-2.759a.797.797 0 00-.856 0l-5.97 3.473zm10.609 8.8V12.06c0-.333-.143-.57-.429-.737l-5.97-3.473 1.95-1.118a.433.433 0 01.476 0l4.543 2.617c1.309.76 2.189 2.378 2.189 3.948 0 1.808-1.07 3.473-2.76 4.163zM7.802 12.703l-1.95-1.142c-.167-.095-.239-.238-.239-.428V5.899c0-2.545 1.95-4.472 4.591-4.472 1 0 1.927.333 2.712.928L8.23 5.067c-.285.166-.428.404-.428.737v6.898zM12 15.128l-2.795-1.57v-3.33L12 8.658l2.795 1.57v3.33L12 15.128zm1.796 7.23c-1 0-1.927-.332-2.712-.927l4.686-2.712c.285-.166.428-.404.428-.737v-6.898l1.974 1.142c.167.095.238.238.238.428v5.233c0 2.545-1.974 4.472-4.614 4.472zm-5.637-5.303l-4.544-2.617c-1.308-.761-2.188-2.378-2.188-3.948A4.482 4.482 0 014.21 6.327v5.423c0 .333.143.571.428.738l5.947 3.449-1.95 1.118a.432.432 0 01-.476 0zm-.262 3.9c-2.688 0-4.662-2.021-4.662-4.519 0-.19.024-.38.047-.57l4.686 2.71c.286.167.571.167.856 0l5.97-3.448v2.26c0 .19-.07.333-.237.428l-4.543 2.616c-.619.357-1.356.523-2.117.523zm5.899 2.83a5.947 5.947 0 005.827-4.756C22.287 18.339 24 15.84 24 13.296c0-1.665-.713-3.282-1.998-4.448.119-.5.19-.999.19-1.498 0-3.401-2.759-5.947-5.946-5.947-.642 0-1.26.095-1.88.31A5.962 5.962 0 0010.205 0a5.947 5.947 0 00-5.827 4.757C1.713 5.447 0 7.945 0 10.49c0 1.666.713 3.283 1.998 4.448-.119.5-.19 1-.19 1.499 0 3.401 2.759 5.946 5.946 5.946.642 0 1.26-.095 1.88-.309a5.96 5.96 0 004.162 1.713z"></path></g></svg>

package/images/agents/claude.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><path clip-rule="evenodd" d="M20.998 10.949H24v3.102h-3v3.028h-1.487V20H18v-2.921h-1.487V20H15v-2.921H9V20H7.488v-2.921H6V20H4.487v-2.921H3V14.05H0V10.95h3V5h17.998v5.949zM6 10.949h1.488V8.102H6v2.847zm10.51 0H18V8.102h-1.49v2.847z" fill="#D97757" fill-rule="evenodd"/></svg>

package/images/agents/cline.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><text x="12" y="12" text-anchor="middle" dominant-baseline="central" font-family="sans-serif" font-size="13" font-weight="700" letter-spacing="-0.02em" fill="#0E1116">Cl</text></svg>

package/images/agents/codex.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><path d="M9.064 3.344a4.578 4.578 0 012.285-.312c1 .115 1.891.54 2.673 1.275.01.01.024.017.037.021a.09.09 0 00.043 0 4.55 4.55 0 013.046.275l.047.022.116.057a4.581 4.581 0 012.188 2.399c.209.51.313 1.041.315 1.595a4.24 4.24 0 01-.134 1.223.123.123 0 00.03.115c.594.607.988 1.33 1.183 2.17.289 1.425-.007 2.71-.887 3.854l-.136.166a4.548 4.548 0 01-2.201 1.388.123.123 0 00-.081.076c-.191.551-.383 1.023-.74 1.494-.9 1.187-2.222 1.846-3.711 1.838-1.187-.006-2.239-.44-3.157-1.302a.107.107 0 00-.105-.024c-.388.125-.78.143-1.204.138a4.441 4.441 0 01-1.945-.466 4.544 4.544 0 01-1.61-1.335c-.152-.202-.303-.392-.414-.617a5.81 5.81 0 01-.37-.961 4.582 4.582 0 01-.014-2.298.124.124 0 00.006-.056.085.085 0 00-.027-.048 4.467 4.467 0 01-1.034-1.651 3.896 3.896 0 01-.251-1.192 5.189 5.189 0 01.141-1.6c.337-1.112.982-1.985 1.933-2.618.212-.141.413-.251.601-.33.215-.089.43-.164.646-.227a.098.098 0 00.065-.066 4.51 4.51 0 01.829-1.615 4.535 4.535 0 011.837-1.388zm3.482 10.565a.637.637 0 000 1.272h3.636a.637.637 0 100-1.272h-3.636zM8.462 9.23a.637.637 0 00-1.106.631l1.272 2.224-1.266 2.136a.636.636 0 101.095.649l1.454-2.455a.636.636 0 00.005-.64L8.462 9.23z" fill="url(#dsh-import-grad-codex)"/><defs><linearGradient id="dsh-import-grad-codex" x1="12" x2="12" y1="3" y2="21" gradientUnits="userSpaceOnUse"><stop stop-color="#B1A7FF"/><stop offset=".5" stop-color="#7A9DFF"/><stop offset="1" stop-color="#3941FF"/></linearGradient></defs></svg>

package/images/agents/continue.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><text x="12" y="12" text-anchor="middle" dominant-baseline="central" font-family="sans-serif" font-size="15" font-weight="700" letter-spacing="-0.02em" fill="#0E1116">C</text></svg>

package/images/agents/crush.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><text x="12" y="12" text-anchor="middle" dominant-baseline="central" font-family="sans-serif" font-size="13" font-weight="700" letter-spacing="-0.02em" fill="#5A56E0">Cr</text></svg>

package/images/agents/cursor.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="-4 -4 32 32" width="48" height="48"><rect x="-4" y="-4" width="32" height="32" rx="6" fill="#fff"/><path d="M22.106 5.68L12.5.135a.998.998 0 00-.998 0L1.893 5.68a.84.84 0 00-.419.726v11.186c0 .3.16.577.42.727l9.607 5.547a.999.999 0 00.998 0l9.608-5.547a.84.84 0 00.42-.727V6.407a.84.84 0 00-.42-.726zm-.603 1.176L12.228 22.92c-.063.108-.228.064-.228-.061V12.34a.59.59 0 00-.295-.51l-9.11-5.26c-.107-.062-.063-.228.062-.228h18.55c.264 0 .428.286.296.514z" fill="#111216"/></svg>