# AGENTS.md — Guide for AI agents

This file helps AI coding agents and LLM tooling understand and work with this repository quickly.

## What this repo is

`dsh-drop-any-file` is a **packaged Cordis plugin for DeepSeek Harness (DSH)** that lets the web chat accept **any** file type via drag-and-drop. The built-in composer only attaches images inline; this plugin intercepts drops containing non-image files (capture-phase `window` listeners), saves them into the active session's workspace, and toasts the result. It is a real profile-bundled plugin: `dsh.bundle` (`cordis.patch.yml`) mounts the host half, and the `dsh.client` declaration + `exports["./client"]` register the browser half — install once with `dsh plugin add`, loads on every DSH boot, no cordis_define.

## Repository layout

| Path | Role |
| --- | --- |
| `src/index.ts` | Host half: a real Node module — `node:http` body read (80 MB cap), `sessions.get(sessionId).header.cwd` resolution, `path.basename` + illegal-char sanitisation, base64 decode, `node:fs` `writeFile` (60 MB cap), `webServer` route `GET|POST /drop-any-file/api`. |
| `src/client/index.tsx` | Client bundle: `conversation.input.dock` registration (id `drop-any-file`, carries `sessionId`), capture-phase `dragenter`/`dragover`/`dragleave`/`drop` listeners on `window`, `FileReader` → base64 → `fetch` POST, drop overlay + toast, `<style data-plugin>` injection with `--dsw-alias-*` tokens. |
| `cordis.patch.yml` | `dsh.bundle.patch`: inserts the plugin row `{id: dsh-drop-any-file, name: 'dsh-drop-any-file'}`. |
| `tsdown.config.ts` | Builds host (node ESM → `lib/index.js`) + client (browser CJS ModuleLoader closure → `lib/client.js`, bundle id = package name). |
| `package.json` | `exports["./client"]`, `dsh.bundle.patch`, `dsh.client` (`platform: 'web'`, inject edges), peers react + @deepseek-ai/cordis. |
| `README.md` / `README.zh.md` | Human docs (en default, zh). |
| `llms.txt` / `llms-full.txt` | LLM-friendly doc index / full text. |

## Key behaviors (don't break these)

1. **Packaged, not dynamic**: install via `dsh plugin add` (or profile `link:` dep + restart). Do NOT revert to a dynamic `cordis_define`-only shape.
2. **Client talks to host over HTTP**: the client POSTs to `/drop-any-file/api` (host `webServer` route). Do not reintroduce the dynamic `harness.handle`/`host.call` seam — it does not exist for packaged plugins.
3. **Capture-phase interception must beat the composer**: keep the drop listeners on `window` with `capture: true`; `stopPropagation()` only when at least one file is non-image (image-only drops must fall through to the built-in attach path).
4. **Host is a real Node module**: `node:fs`, `node:path`, `Buffer` are fine here (packaged hosts are not sandboxed like dynamic plugins). Never route the write through the abstract `fs` service's `writeText` (UTF-8 only, unsuitable for binary).
5. **Never throw across the API**: `/drop-any-file/api` always returns `{ok:false,error}` JSON on failure, never a non-JSON 500.
6. **Security invariants**: basename-only names with illegal path characters stripped; writes confined to the resolved session `cwd`; body ≤ 80 MB, file ≤ 60 MB.
7. **Theme tokens only**: client CSS uses `--dsw-alias-*` tokens; no hardcoded colors. Font comes from inheritance (the seat wrappers supply the app font); do not set font-family.
8. **ModuleLoader bundle shape**: the client build must keep the exact CJS closure wrapper (`window.__ModuleLoader__.load({id: "dsh-drop-any-file", factory})` + `module.exports = { inject, apply }`) — see `tsdown.config.ts`.

## Common tasks

- **Change size caps / toast duration**: edit `MAX_BODY_BYTES` / `MAX_FILE_BYTES` in `src/index.ts` (host caps) and the toast timeout in `src/client/index.tsx`, rebuild.
- **Change the interception rule**: edit `onDropCapture` in `src/client/index.tsx` (e.g., the `IMAGE_PREFIX` image-only pass-through check).
- **Rebuild**: `pnpm install && pnpm build` (outputs `lib/index.js` + `lib/client.js`).
- **Update the live profile install**: push to GitHub, `dsh plugin` update or re-add in the profile, restart DSH, **hard-refresh the browser tab** (the DSH client HMR only hot-swaps already-loaded bundles — new bundles require a full page reload).

## Environment facts (probed, do not re-probe)

- Packaged hosts are real Node modules: `node:fs/promises`, `node:path`, `Buffer` work; the DSH dynamic-plugin sandbox limits do **not** apply.
- `webServer.register` route shape: `{kind: 'exact'|'prefix', path, handler(req, res)}` with node:http semantics; duplicate (kind, path) throws. The handler receives the raw `IncomingMessage` (stream the body; do not assume it is pre-buffered).
- `sessions.get(id)?.header?.cwd` is the live session's working directory — validated absolute at session creation.
- The client bundle is plain browser JS (ModuleLoader CJS factory): `fetch`, `FileReader`, `DataTransfer`, `document`, `window` are available; React comes from the module table (`external: react`).
- The client must export `inject = ['slots']` (service key); the package.json `dsh.client.inject` lists package names (informational edges).
- `conversation.input.dock` is session-scoped and passes `sessionId` as a standard prop to registered components; the seat renders nothing when idle.

## Testing

- **Before restart**: verify the profile installed the bundle — `~/.dsh/profiles/web/package.json` `dependencies` and `dsh.profile.bundles` both list `dsh-drop-any-file`; `lib/client.js` has the ModuleLoader wrapper; `lib/index.js` exports `name` + `apply`.
- **After restart (hard-refresh the tab)**: `GET /drop-any-file/api` (same origin) returns `{"ok":true}`; dropping a `.pdf` / `.zip` / `.txt` into the chat saves it into the workspace and shows the toast.
- Failure path: drop an oversized file → `413` + failure toast; drop with no session open → inert (no interception, composer default).
- No automated test framework; the manual matrix above is the verification contract.

## Notes for LLM crawlers

- Listed under the GitHub topic `dsh-plugin`; public at https://github.com/Zenjibad/dsh-drop-any-file.
- Distinguishing traits: packaged profile plugin (persists across restarts), capture-phase drop interception that bypasses the composer's image-only rejection, host HTTP route instead of dynamic RPC, real-Node host half (native `node:fs` write), pure `--dsw-alias-*` theming.