dsh-composer-predictions 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-composer-predictions contributors
+
+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/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# dsh-composer-predictions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI ghost text for the message box in the DeepSeek Harness Web GUI.
+
+- **Next message** — after the agent replies, the empty composer shows a
+  streamed suggestion for your likely next message. **Tab** accepts it as an
+  editable draft.
+- **Inline continuation** — while you pause mid-draft with the caret at the end,
+  the composer completes that sentence where the caret is. **Tab** accepts the
+  completion without sending anything.
+
+Up to three candidates are requested per call. **Alt+Down / Alt+Up** cycle them,
+**Escape** dismisses one, and typing aborts any in-flight request and hides the
+ghost.
+
+## Install
+
+Inside the DeepSeek Harness Web GUI: **Plugins → Install**, then enter
+
+```
+dsh-composer-predictions
+```
+
+Or from a terminal with a DSH profile:
+
+```bash
+dsh plugin --profile <name> add dsh-composer-predictions
+```
+
+Then restart the Harness (a profile addition is applied at boot). A linked
+source checkout is picked up again when the profile recomposes.
+
+## Use
+
+1. Send a message and let the agent finish — a dimmed next-message suggestion
+   streams in with a `Tab` keycap.
+2. Or type anything and pause with the caret at the end of the draft — a
+   continuation ghost appears right after the caret.
+3. **Tab** turns the current candidate into an editable draft.
+   **Alt+Down** shows the next candidate, **Alt+Up** the previous one.
+   **Escape** dismisses, and typing hides the ghost without sending anything.
+4. Accepting never submits the message; edit it or press Enter yourself.
+
+![Next-message ghost](docs/next-message-ghost.png)
+
+![Inline continuation ghost](docs/continuation-ghost.png)
+
+## How it works
+
+- The **Host half** registers two routes on the Harness web server:
+  - `POST /composer-prediction` — JSON (`suggestion` plus `suggestions`), kept
+    for compatibility with older clients.
+  - `POST /composer-prediction/v2` — Server-Sent Events: `meta`, `delta`
+    (streamed text), then `done` with the final candidate list.
+- A request carries `{ sessionId, mode, draft }`, where `mode` is `next` or
+  `continue`. The Host reads the Session tail (`deriveMessages()`), adds a short
+  list of recent tool calls and their outcomes, and renders one bounded prompt.
+  `next` declines when the agent has not produced a reply; `continue` includes
+  the draft text that ends at the caret.
+- One small auxiliary model call runs through `ctx.llm` over that prompt. The
+  suggestion uses the Session's own provider/model at the model's lowest
+  reasoning effort unless `provider`/`model` are configured. Model output is
+  split into up to `maxSuggestions` clean one-line candidates: numbering,
+  bullets and quotes are stripped, `NONE` produces no suggestion, and drafts the
+  model restated are trimmed. A continuation keeps the model's leading
+  separator space; the Client adds one only when a non-CJK draft and
+  continuation would otherwise glue two words together.
+- Results are cached per Session sequence (and per draft for continuations), so
+  a repeated request for unchanged context costs no model call.
+- The **Client half** registers into `conversation.input.overlay`, debounces
+  requests (600 ms after a turn settles, 500 ms after a typing pause), aborts
+  superseded requests, and renders the ghost over the empty composer or at the
+  caret. It measures the resident editor, so the ghost follows its padding,
+  line height, and scroll position.
+- Nothing is written to the Session log, and predictions are not counted as
+  conversation turns.
+
+## Configuration
+
+Override the row in your profile's `cordis.patch.yml`:
+
+```yaml
+- id: composer-predictions
+  name: dsh-composer-predictions
+  config:
+    maxOutputTokens: 220   # 16..4096
+    timeoutMs: 20000       # 1000..120000
+    maxMessages: 10        # 2..40 messages of transcript
+    maxChars: 8000         # 500..40000 characters of transcript
+    maxSuggestions: 3      # 1..5 candidates per request
+    maxToolNotes: 6        # 0..20 recent tool calls in the prompt
+    provider: deepseek-account   # optional fixed route; both keys or neither
+    model: deepseek-flash
+    reasoningEffort: off   # off | low | high | max; omitted = model's lowest
+```
+
+A route override is a pair: half a pair is ignored and the Session route wins.
+A suggestion longer than 240 characters is cut at a word boundary.
+
+## Privacy and limits
+
+- The conversation tail, recent tool activity and (in continuation mode) the
+  draft are sent to the configured model route, just like a normal turn.
+  Nothing else leaves the machine.
+- Predictions are suggestions only; they never run tools or change the Session.
+- Accepting a suggestion and then editing it is a normal draft: it is only sent
+  when you submit it.
+- Prediction calls do not appear in the Session log or its token meter.
+- Requires a Harness build that provides `conversation.input.overlay`,
+  `ctx.llm`, and `sessions.deriveMessages()`.
+
+## Test
+
+```bash
+node --test
+```
+
+Probe a running GUI to watch the stream and cache timing:
+
+```bash
+node tools/live-probe.mjs <sessionId> continue "Can you also"
+```
+
+The 22 cases drive both Host endpoints against a fake Session and LLM service:
+prompt contents (including tool activity), candidate normalization and spacing,
+streaming events, per-turn and per-draft caching, route and effort selection,
+failure reporting, and request validation. Client helpers (continuation
+joining, SSE parsing, streaming candidates) are unit-tested through the bundle's
+internal `__testing` export.
+
+## Uninstall
+
+Disable **Composer predictions** in **Plugins → Installed**, or remove it with
+`dsh plugin --profile <name> remove dsh-composer-predictions`.
+
+## License
+
+MIT