rlmh-dsh 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rishi Jain
+
+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,113 @@
-# Temporary Holding Version
+# rlmh-dsh: RLM mode for DeepSeek Harness
 
-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.
+`rlmh-dsh` adds **RLM mode** to [DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh) (dsh). RLM mode is the Recursive Language Model method from [rlm-harness](https://github.com/RishiJain905/rlm-harness), running inside dsh.
+
+The model doesn't read long inputs. It works through a persistent Python REPL, the `run_code` tool:
+- loading files into variables;
+- measuring and slicing them with code;
+- handing the reading to **sub-calls** (`llm`, `llm_batch`, `scan`, `ask_files`), which are separate model calls that each read one piece and answer briefly;
+- doing exact counting, filtering and arithmetic in Python.
+
+The model's own context stays small and its prompt cache stays warm, even on inputs far larger than its context window.
+
+## Install
+
+**dsh desktop:**
+1. Open **Plugins** → **Add plugin** → **Install a third-party plugin**.
+2. Enter `rlmh-dsh`, then click **Install** and **Enable now**.
+
+There is no restart and no terminal. RLM mode needs Python, and the desktop app ships one.
+
+**dsh CLI or web:**
+
+```bash
+dsh plugin --profile web add rlmh-dsh
+```
+
+Use your own profile's name in place of `web`.
+
+Needs dsh 0.2.2-rc.1 or later, below 0.3.0.
+
+## Use it
+
+Start a session with the **RLM mode** agent preset. The model gets `run_code` and the REPL, plus these helpers:
+
+| In the REPL | What it does |
+|---|---|
+| `llm(prompt)` | One sub-call; returns the answer as text |
+| `llm_batch(prompts, shared=…, over=…)` | Several sub-calls in parallel. `shared=` and `over=` put a fixed prefix first, so sub-calls hit the provider's cache |
+| `segments(text, size)` | Cuts text at line breaks into pieces sized for one sub-call |
+| `scan(text, question)` | Asks a question of every segment of a text |
+| `ask_files(paths, question)` | Asks a question of files, without loading them into the model's prompt |
+| `rlm(task, context=None)` | A child agent in RLM mode, with its own REPL, run as a dsh subagent |
+
+Each sub-call shows up as an `llm` row in the Trajectory view, with a `[sub-call tokens: …]` line.
+
+## Settings
+
+Go to **Plugins** → **Built-in plugin settings** → **RLM mode**.
+
+| Setting | Default |
+|---|---|
+| Sub-call provider and model | The session's own model |
+| Sub-call reasoning effort | The session's own effort |
+| Characters one `run_code` result shows | 8,000 |
+| Sub-calls per `run_code` call | 200 |
+| Parallel sub-calls | 8 |
+
+Sub-calls cost tokens, mostly output tokens. A cheaper sub-call model or a lower effort cuts that cost.
+
+## Python
+
+RLM mode looks for Python 3.10 or later, in this order:
+1. the runtime's `pythonBin` option, if you set one in the profile;
+2. the Python bundled with dsh desktop;
+3. an installed rlm-harness's Python;
+4. a Python 3.12 that uv already has;
+5. `python` or `python3` on PATH.
+
+If none is found, the agent says so. Install the desktop app, or install Python 3.12 from python.org or with `uv python install 3.12`, then start a new session. RLM mode never downloads anything itself.
+
+## Caching
+
+RLM mode follows dsh's caching rules:
+- its instructions and tool list are fixed for the session;
+- it never rewrites requests;
+- compaction is dsh's own;
+- sub-calls put their fixed prefix first and use their own session affinity key, `<session>:sub`.
+
+In tests on DeepSeek Flash through OpenRouter, long RLM sessions read 94% to 98% of their input from cache, about the same as Standard mode. Two settings outside the plugin matter:
+
+- **OpenRouter host switching.** OpenRouter serves many open models from several hosts and may move a request to a host without your cache. Each move is one full miss. Two ways to keep requests on one host:
+  - use dsh's own DeepSeek provider with a DeepSeek key;
+  - on OpenRouter, create a preset with a provider **order** and use a model id ending in `@preset/<slug>`.
+- **A huge output cap starts compaction early.** dsh compacts at about `context window − output cap − 65,536` tokens. Some imported OpenRouter models declare an output cap close to their context window, for example DeepSeek Flash Latest's 943,718. On those, every session compacts at about 39k tokens, and each compaction misses the cache. Set a smaller output cap, such as 65,536, on that model in dsh's model settings.
+
+## Permissions
+
+The REPL runs under dsh's file policy, through dsh's sandbox service, in the same way as dsh's own code runtime:
+- **read-only** and **plan** mode: the REPL and everything it starts can't write;
+- **workspace-write**: writes outside the workspace are denied;
+- if the sandbox is unavailable, a confined mode fails closed;
+- dsh's one-time escalation prompt still works.
+
+How strongly writes are blocked depends on dsh's backend for your OS. On Windows, dsh reports enforcement as `partial`. Treat it as protection against accidents, not against a hostile program.
+
+## Privacy
+
+- **The plugin holds no keys.** Sub-calls go through dsh's model service, so dsh holds the key.
+- **No key-like variables reach the REPL.** Environment variables whose names look like keys (`KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `AUTH`, `HEADERS`) are removed before it starts.
+- **Nothing contacts the network except your model provider.** It is contacted only through dsh.
+
+## Development
+
+The source is on the `dsh-plugin` branch of [rlm-harness](https://github.com/RishiJain905/rlm-harness/tree/dsh-plugin/dsh-plugin):
+- Node tests: `npm test`.
+- Python tests: `python -m unittest discover -s test -p "test_*.py"`.
+- Cache guard, which runs a real dsh against a fake model server: `node test/e2e/cache-guard.mjs`.
+
+The design and its test results are in `documentation/v1.1/dsh-plugin-plan.md`.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,119 @@
+# KV cache: every text here (the persona, the preset) is fixed, so dsh's cached prompt prefix stays byte-identical.
+# rlmh for DeepSeek Harness (D-264): the user's settings (`rlmh-settings`) and the "RLM mode" agent preset. The
+# top-level `rlm-runtime`, `rlm-subcall-tool` and `rlm-rlm-tool` rows are off by default and exist for headless tests (an overlay
+# turns them on for the whole deployment); the preset mounts its own copies.
+- insert:
+    # The package root is the settings service (lib/index.js). It must be the only active top-level entry from this
+    # package, because the package has a browser half (the settings page); the rows below are off by default.
+    - id: rlmh-settings
+      name: 'rlmh-dsh'
+    - id: rlm-runtime
+      name: './lib/rlm-runtime.js'
+      disabled: true
+    - id: rlm-subcall-tool
+      name: './lib/subcall-tool.js'
+      disabled: true
+    - id: rlm-rlm-tool
+      name: './lib/rlm-tool.js'
+      disabled: true
+    - id: preset-rlm
+      name: '@deepseek-ai/dsh-agent-preset'
+      config:
+        id: rlm
+        name: RLM mode
+        description: Recursive Language Model mode. The agent works in a persistent Python REPL and hands reading to sub-calls (llm, llm_batch, scan, ask_files).
+        order: 5
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              # rlmh's `default` prompt (engine/rlm_engine/profiles/default/system.md and guidance.md), adapted to
+              # run_code. The function list itself is in run_code's description (lib/rlm-runtime.js INSTRUCTIONS).
+              prefix: |-
+                You are a coding agent powered by the {{model}} model, working as a Recursive Language Model.
+
+                Your only tool is run_code: a persistent Python REPL. Variables, functions and imports persist between calls, and you see what a call prints, cut at a few thousand characters. The harness's tools are functions inside the REPL (`await tools.read({...})`, `await tools.grep({...})`, `await tools.edit({...})` and the rest), and so are the RLM functions: llm, llm_batch, segments, scan, ask_files and rlm.
+
+                How to work: your own view is small, and sub-calls are where the reading happens. A sub-call is another model call that reads a large piece of text (up to about 60,000 characters) and answers in a few thousand tokens. You are the orchestrator: look at the input's structure first with code (sizes, headings, line counts), decide how to split the work (which pieces, which question for each, how you will combine the answers), send independent pieces out together, ask each for a short answer you can parse, combine the answers with code, and check anything surprising with another sub-call. Use code for exact filtering, counting and arithmetic, and sub-calls for reading and judgment. Your sub-call budget is there to be spent.
+
+                Reading a large text (a long file, a log, a document):
+                - Load it into a variable with Python and never print it whole.
+                - Searching it with re or str.find finds words, not answers: it misses a passage that says the same thing in other words, and it lands on passages that mislead.
+                - So start with a scan: `found = scan(text, "<the question, with what it depends on>")`. Print the passages, then read around the offsets that matter (`text[at - 500:at + 500]`).
+                - When the answer takes several steps (one fact leads to the next), scan for the first step, then scan for each next step with what a passage named. Put nothing you have not read into a scan's question.
+                - For lists, counts and totals, ask with schema= (`scan(text, q, schema=list[str])`, or `llm_batch(prompts, over=segments(text), schema=...)`) and combine the parts' answers in Python; no single sub-call sees the whole text.
+                - Use thinking="off" for lookups and extraction; keep thinking for judgment.
+
+                Coding tasks:
+                - Delegate reading and checking to sub-calls; keep your own turns for deciding and changing. When a question covers more than three files, or a file over 300 lines, use ask_files instead of reading it yourself. For a job of several steps of its own (investigate one part, draft one module), start a child run with rlm(task, context=None), with a clear task and what its answer should contain.
+                - Change files with the harness's edit and write tools (`await tools.edit({...})`), so the user's approvals apply, and run commands and tests with its shell tool.
+
+                Rules:
+                - Explore with code and print summaries, never whole files or pages.
+                - Answer the user in a plain reply once what you have read supports each part of it; where passages disagree, read both in place first.
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+            config:
+              applyPatch: false
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: compaction-basic
+                name: '@deepseek-ai/dsh-compaction-basic'
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  # KV cache: pruning rewrites an earlier result, which misses the cache from there on. run_code
+                  # results are capped at 8,000 characters (outputMaxChars) plus a note, so 12,000 never prunes them.
+                  thresholdChars: 12000
+                  headChars: 4096
+                  tailChars: 1024
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: rlm-execution
+            name: cordis:group
+            group: true
+            isolate:
+              ptcRuntime: true
+            config:
+              - id: rlm-runtime
+                name: 'rlmh-dsh/lib/rlm-runtime.js'
+              - id: rlm-subcall-tool
+                name: 'rlmh-dsh/lib/subcall-tool.js'
+              - id: rlm-rlm-tool
+                name: 'rlmh-dsh/lib/rlm-tool.js'
+              - id: tool-executor-ptc
+                name: '@deepseek-ai/dsh-tool-executor-ptc'
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'

package/lib/blobs.js

@@ -0,0 +1,45 @@
+// KV cache: none (this holds sub-call prefixes by content; the bytes sent are the stored text, unchanged)
+// Shared sub-call prefixes (a segment for over=, a batch's shared= text), stored once per process by the SHA-256 of
+// their text. The REPL sends each distinct prefix once; the `llm` tool's arguments carry its id, so dsh's session log
+// records a short reference instead of up to 60,000 characters per sub-call. Ids are checked against the text, so one
+// session's code can't plant different text under an id another session uses. Least recently used goes first past
+// the size cap; a miss tells the REPL to send the prefix again.
+import { createHash } from 'node:crypto'
+
+export const MAX_CHARS = 256 * 1024 * 1024
+const store = new Map() // id -> text, oldest first
+let held = 0
+
+export function blobId(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+/** Store `text` under `id`; false (and nothing stored) when the id is not the text's SHA-256. */
+export function putBlob(id, text) {
+  if (typeof id !== 'string' || typeof text !== 'string' || blobId(text) !== id) return false
+  if (store.has(id)) {
+    store.delete(id)
+    store.set(id, text)
+    return true
+  }
+  store.set(id, text)
+  held += text.length
+  for (const [old, oldText] of store) {
+    if (held <= MAX_CHARS || old === id) break
+    store.delete(old)
+    held -= oldText.length
+  }
+  return true
+}
+
+/** The text stored under `id`, refreshed as recently used; undefined when unknown. */
+export function getBlob(id) {
+  const text = store.get(id)
+  if (text !== undefined) {
+    store.delete(id)
+    store.set(id, text)
+  }
+  return text
+}
+
+export const MISSING_PREFIX = 'unknown prefix_id'

package/lib/client.js

@@ -0,0 +1,115 @@
+// KV cache: none (a settings page in the browser; it changes settings, never prompt or tool text)
+// RLM mode's settings page, the browser half of rlmh-dsh (step 4c). It edits the volatile fields of the
+// `rlmh-settings` profile entry (lib/settings.js) through dsh's shared settings form: values are staged until Save,
+// an overridden field carries a badge and a reset, and an empty field saves as a reset. The page sits in the Plugins
+// page (`plugins.item` slot) while the Host serves that entry's form. dsh supplies React and the UI primitives, so
+// this file is loaded as-is (no build step), in the module format dsh's client loader expects.
+window.__ModuleLoader__.load({
+  id: 'rlmh-dsh',
+  factory: (require) => {
+    const { jsx, jsxs } = require('react/jsx-runtime')
+    const P = require('@deepseek-ai/dsh-client-ui-primitives')
+
+    /** The profile entry whose volatile fields this page edits (cordis.patch.yml `rlmh-settings`). */
+    const ENTRY = 'rlmh-settings'
+    const NS = 'settings.rlmh'
+
+    const en = {
+      title: 'RLM mode',
+      description: 'Choose the model and effort for RLM mode\'s sub-calls, and how much one run_code result shows.',
+      subProvider: 'Sub-call provider',
+      subProviderHint: 'The provider route for sub-calls, as in the model picker (for example openrouter). Leave blank to use the agent\'s own.',
+      subModel: 'Sub-call model',
+      subModelHint: 'The model id for sub-calls (for example ~deepseek/deepseek-flash-latest). Leave blank to use the agent\'s own model.',
+      subReasoningEffort: 'Sub-call reasoning effort',
+      subReasoningEffortHint: 'An effort the sub-call model offers, such as low, medium or high. Leave blank to use the agent\'s effort. Lower effort costs less output.',
+      outputMaxChars: 'Result size (characters)',
+      outputMaxCharsHint: 'How much of one run_code result the agent sees; the rest is cut so it reads through sub-calls. Default 8000.',
+      maxSubcallsPerRun: 'Sub-calls per run_code call',
+      maxSubcallsPerRunHint: 'The most sub-calls one run_code call may make. Default 200.',
+      maxParallelSubcalls: 'Sub-calls at once (fallback)',
+      maxParallelSubcallsHint: 'Only used when the session has no sub-call tool. Default 8.',
+      overridden: 'Overridden',
+      reset: 'Reset to default',
+      readOnly: 'This deployment stores settings read-only.',
+      unavailable: 'RLM mode\'s settings plugin is not loaded, so it cannot be configured right now.',
+      save: 'Save',
+      saving: 'Saving…',
+      saveFailed: 'The deployment did not accept these values; they were left for you to correct.',
+      invalidNumber: 'Enter a number, or leave blank to use the default.',
+    }
+
+    const TEXT = ['subProvider', 'subModel', 'subReasoningEffort']
+    const NUMBERS = ['outputMaxChars', 'maxSubcallsPerRun', 'maxParallelSubcalls']
+
+    /** Bridges the `rlmh-settings` entry's form onto the page's staged form. */
+    class RlmhCardController {
+      constructor(scope) {
+        this.form = new P.SettingsFormModel(scope, [...TEXT.map((f) => P.settingsTextField(f)), ...NUMBERS.map((f) => P.settingsNumberField(f))])
+        this.store = this.form.bind(() => this.projection())
+      }
+
+      projection() {
+        const out = { ...this.form.shell() }
+        for (const f of [...TEXT, ...NUMBERS]) out[f] = this.form.field(f)
+        return out
+      }
+
+      inject() {
+        return { hooks: { rlmhCard: this.store }, ...this.form.actions() }
+      }
+
+      dispose() {
+        this.form.dispose()
+      }
+    }
+
+    /** The one-liner on the Plugins page, or the settings form when the page is open. */
+    function RlmhCard(props) {
+      const { t } = props
+      const state = props.useRlmhCard((snapshot) => snapshot)
+      if (props.view === 'summary') return t('description')
+      const disabled = !state.writable
+      const field = (name, numeric) => jsx(P.SettingsValueField, {
+        id: `plugin-config-rlmh-${name}`,
+        label: t(name),
+        hint: t(`${name}Hint`),
+        overriddenLabel: t('overridden'),
+        resetLabel: t('reset'),
+        invalidLabel: t('invalidNumber'),
+        numeric,
+        disabled,
+        ...state[name],
+        onEdit: (text) => { props.edit(name, text) },
+        onReset: () => { props.resetField(name) },
+      }, name)
+      return jsxs(P.SettingsForm, {
+        labels: { unavailable: t('unavailable'), readOnly: t('readOnly'), saveFailed: t('saveFailed'), save: t('save'), saving: t('saving') },
+        state,
+        onSave: props.save,
+        onDiscard: props.discard,
+        children: [...TEXT.map((f) => field(f, false)), ...NUMBERS.map((f) => field(f, true))],
+      })
+    }
+
+    const inject = ['slots', 'locale', 'configForms']
+
+    function apply(ctx) {
+      const t = ctx.locale.bind(NS)
+      // English only for now; every language dsh ships reads the same copy.
+      ctx.effect(() => ctx.locale.register(NS, { en, zh: en, ja: en, es: en, fr: en, de: en, ru: en, pt: en }), 'rlmh-dsh: dictionaries')
+      const card = new RlmhCardController(ctx.configForms.get(ENTRY))
+      ctx.effect(() => () => { card.dispose() }, 'rlmh-dsh: form subscription')
+      ctx.effect(() => ctx.configForms.whileServed([ENTRY], () => ctx.slots.inject('plugins.item', () => ctx.slots.register({
+        name: 'plugins.item',
+        id: 'rlmh',
+        order: 60,
+        label: () => t('title'),
+        locale: NS,
+        inject: () => card.inject(),
+      }, RlmhCard))), 'rlmh-dsh: page')
+    }
+
+    return { NS, inject, apply }
+  },
+})

package/lib/index.js

@@ -0,0 +1,5 @@
+// KV cache: none
+// rlmh-dsh's one top-level entry (cordis.patch.yml `rlmh-settings`, named by the package): the user's settings
+// service (lib/settings.js). Because package.json declares a browser half under `dsh.client` (lib/client.js, the
+// settings page), dsh allows only one active deployment entry from this package, so the settings service is it.
+export { default, name, SETTING_DEFAULTS, effective } from './settings.js'