@wm-coders/dsh-custom-first-control-prompt
English | 中文
Deployment-configured prompt prefix. Ordered system-prompt sections render ahead of the deployment persona, and configured reference user/assistant exchanges are injected into every ordinary conversation request — as real alternating messages prepended on the request path (llm/stream interception, zero session-log writes). Static content renders byte-identically on every request, preserving prefix-cache reuse.
Installation
# From GitHub (recommended — built artifacts committed, no build approval needed)
dsh plugin --profile web add github:WM-CODER/custom-first-control-prompt
# From npm
dsh plugin --profile web add @wm-coders/dsh-custom-first-control-prompt
# From local directory (development)
dsh plugin --profile web add ./path/to/custom-first-control-prompt
After installation, restart the web app (dsh --profile web or run restart-web.ps1 / restart-web.sh).
To uninstall:
dsh plugin --profile web remove @wm-coders/dsh-custom-first-control-prompt
Install / deployment / debugging obstacles and test methods: DEBUG-NOTES.zh.md (in Chinese; web fail-loud root causes, duplicate-id inserts, API verification chains — all paths scrubbed). One-command install: INSTALL.md. Full cross-machine walkthrough: INSTALL-FULL.zh.md (Chinese).
Configuration
- id: custom-first-control-prompt
name: '@wm-coders/dsh-custom-first-control-prompt'
config:
sections:
- name: house-rules
order: -50
text: |
…stable system text…
history:
- user: …
assistant: …
includeSubagents: false
| Key | Default | Meaning |
|---|
sections | — | Ordered system-prompt fragments; absent or empty registers nothing. |
sections[].name | required | Entry name; the registry sees custom-first-control-prompt:<name>. |
sections[].order | required | Render position among all sections. Factory convention: harness identity −100, persona 0, tool guidance 100–199; values below 0 prepend ahead of the persona. |
sections[].enabled | true | false keeps the entry in configuration without registering it. |
sections[].text | required | Static section text; keep it free of volatile values — any change breaks prefix reuse from the first changed token. |
history | — | Ordered user/assistant reference exchanges injected ahead of every ordinary conversation request; both texts must be non-empty and free of reserved tags (case-insensitive: <user>, <assistant>, <exchange>, <custom-history and all closing tags). Absent or empty injects nothing. |
includeSubagents | false | false skips sessions whose header meta marks subagent origin. |
Invalid configuration fails plugin load naming the offending entry: empty text, duplicate section names, or a non-finite order. Per-entry section problems (blank/duplicate name, bad order, empty text) and per-pair history problems (empty text, embedded reserved tags) degrade to skipping that entry with a warning instead of failing the plugin tree.
Injection mechanism
The reference exchanges are built once at plugin activation into alternating real Message objects (deep-frozen, shared by reference across requests), then prepended onto every ordinary conversation request by an llm/stream waterfall listener:
- Clone and redispatch: loop-built requests are deep-frozen and marker-tagged (
markAgentLoopRequest(deepFreeze(...))) and never mutated; the listener clones the request, prepends the seed messages, and redispatches through ctx.llm.stream. The clone carries no loop marker, the agent-loop log-reconstruction invariant does not apply to it, and the discarded original is a pure deriveMessages() projection.
- Zero log writes: seed messages live only on the request path — real turn numbering starts at 1 with no collisions, forks are ordinary copies, and compaction cannot shadow the reference history (every request re-injects it).
- Scope filtering: auxiliary calls (
purpose-stamped, e.g. session-title, compaction) and hand-built requests (no sessionId) pass straight through; subagent-origin sessions are skipped by default (includeSubagents: true opts in).
- Panel verification: not seeing the seed messages in the chat transcript is expected; use the panel's LLM listener to inspect the injected real request (Settings → "Custom first control prompt" → LLM listening, or the dock strip above the composer).
Verifying the injection works: in a fresh session ask a question only the injected history can answer (e.g. "repeat our earliest user message") — the model quoting the configured content proves it. session.history shows no seed messages (a clean log is a feature, not a failure).
Panel save semantics: the panel's config editor writes an id-targeted override into the profile cordis.patch.yml (never an insert, so it cannot collide with the bundle layer's row), updating only this plugin's core row (custom-first-control-prompt) and preserving everything else — other entries, comments, and legacy rows. While the profile patch carries no row, the editor shows the composed config (bundle-layer defaults); saving then creates the override.
System sections
Each enabled entry registers via ctx.systemPrompt.section() at plugin load, so it participates in every assembly exactly like the factory sections: variable interpolation, scope shadowing, and the assembly waterfall all apply. Static configured text renders identically in every assembly, which is what keeps the request prefix reusable.
Model experience
Deployment system sections
What the model sees
Configured section text renders at its configured order position — by default ahead of the persona — alongside the factory sections from dsh-system-prompt.
Token impact
Every section repeats on every request; cost scales with rendered length.
KV-cache impact
Prefixes stay stable while section text, order, and the enabled set render identically. Any change can break reuse from the first changed system-prompt token.
Reference conversation history
What the model sees
Real alternating messages at the head of every ordinary conversation request — one user message per configured user text, one assistant message per configured assistant text:
[user] configured user text 1
[assistant] configured assistant text 1
[user] configured user text 2
[assistant] configured assistant text 2
[user] the real prompt…
Token impact
A fixed single copy of the reference history per request (it never accumulates across turns, and compaction changes nothing — every request re-prepends the same frozen message sequence).
KV-cache impact
The reference history leads the message sequence byte-stably, keeping request prefixes reusable.
Known limitations and deferred work
- The chat UI never shows the reference history — the seeds live only on the request path; neither alternating messages nor framework rows appear in the conversation UI. Reconstructing model-visible content requires the session log plus the deployment config (the framework exposes no plugin event-type registry and
Session.append cannot carry an ignorable envelope) — a deliberate, declared deviation from the harness log-reconstruction default.
- Seed text is model-visible reference material — treat it as prompt text the model reads, not a trusted channel.
- No mid-session edits — configuration changes take effect for new requests after a web restart; a compliant "edit while quiescent" surface-replacement event carrying a source seq reference is deferred.
FAQ: how does the plugin enter the composition?
The package declares dsh.bundle (in-package cordis.patch.yml), and the
reconciliation inside dsh plugin add activates that bundle layer — the
core row custom-first-control-prompt (server logic: system sections,
reference-history injection) appears with no hand-written patch rows. The
browser panel (settings page, dock, LLM listener) is auto-discovered via the
package's dsh.client declaration — no separate patch row for the UI half.
dsh plugin remove drops the dependency and the bundle layer together.
- Customizing: never copy a
- insert: row. Write an id-targeted
(non-insert) patch in the profile cordis.patch.yml to override the bundle
row's config (last write wins) — sample in cordis.patch.yml.template; the
panel's config editor saves exactly this form.
- Offline junction installs skip reconciliation, so the bundle layer never
activates —
install.ps1 -Offline writes the same two rows into the profile
patch instead.
- Duplicate-id warning: once the bundle layer carries the rows, any leftover
- insert: row with the same id in the profile patch (from a manual-era
install) = root-list duplicate → the web fails to boot; uninstall.ps1
strips both shapes surgically.
