dsh-system-prompt-insertion 0.0.1 → 0.2.0

package/lib/index.js

@@ -0,0 +1,902 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
+import Schema from "@deepseek-ai/schemastery";
+import { dshHomeDisplay, dshHomePath, expandHomePath, resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { dirname } from "node:path";
+import { renderPrompt } from "@deepseek-ai/dsh-system-prompt";
+// src/types.ts
+/**
+* The data model this plugin persists.
+*
+* ## One source of truth
+*
+* Everything the model sees comes from one JSON file
+* (`$DSH_HOME/system-prompt-insertion.json`). The profile row's `config` only carries
+* deployment-level switches (master switch, file override, soft size cap) — never
+* prompt text — so there is exactly one place a section can be edited, and the
+* Web editor and a hand-edited file cannot disagree.
+*
+* @module dsh-system-prompt-insertion/types
+*/
+/** Where a section lands inside the assembled system prompt. */
+const POSITIONS = [
+	"head",
+	"body",
+	"tail"
+];
+/** A section id: lowercase alphanumerics and dashes, long enough to be unique. */
+const SECTION_ID = /^[a-z0-9][a-z0-9-]{5,39}$/;
+/** Section-name prefix; also how the preview tells our sections apart. */
+const SECTION_PREFIX = "user:system-prompt-insertion:";
+/** Upper bound on a stored section text, in UTF-8 bytes. */
+const MAX_TEXT_BYTES = 262144;
+/** Upper bound on stored sections; the editor warns instead of silently dropping. */
+const MAX_SECTIONS = 32;
+/** The empty state a fresh install starts from. */
+function emptyState() {
+	return {
+		version: 1,
+		enabled: true,
+		sections: []
+	};
+}
+/** Thrown when a state document cannot be accepted. */
+var StateValidationError = class extends Error {
+	path;
+	constructor(path, message) {
+		super(path === "" ? message : `${path}: ${message}`);
+		this.name = "StateValidationError";
+		this.path = path;
+	}
+};
+function fail(path, message) {
+	throw new StateValidationError(path, message);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readString(value, path) {
+	if (typeof value !== "string") fail(path, "must be a string");
+	return value;
+}
+function readBoolean(value, path, fallback) {
+	if (value === void 0) return fallback;
+	if (typeof value !== "boolean") fail(path, "must be a boolean");
+	return value;
+}
+function readPosition(value, path) {
+	if (value === void 0) return "tail";
+	if (typeof value !== "string" || !POSITIONS.includes(value)) fail(path, `must be one of ${POSITIONS.join(", ")}`);
+	return value;
+}
+function readOrder(value, path) {
+	if (value === void 0 || value === null) return null;
+	if (typeof value !== "number" || !Number.isFinite(value)) fail(path, "must be a finite number or null");
+	return value;
+}
+function readId(value, path) {
+	const id = readString(value, path);
+	if (!SECTION_ID.test(id)) fail(path, "must match [a-z0-9][a-z0-9-]{5,39}");
+	return id;
+}
+/**
+* Validate and normalize one stored state document.
+*
+* Unknown keys inside a section are rejected rather than dropped: a section whose
+* field was renamed by a future version must fail loudly instead of silently
+* losing configuration.
+*
+* @param input - the parsed JSON value.
+* @returns a fresh, fully normalized state.
+* @throws StateValidationError when the document is not acceptable.
+*/
+function normalizeState(input) {
+	if (!isRecord(input)) fail("", "state must be a JSON object");
+	if ((input.version ?? 1) !== 1) fail("version", "unsupported state version (expected 1)");
+	const enabled = readBoolean(input.enabled, "enabled", true);
+	const rawSections = input.sections ?? [];
+	if (!Array.isArray(rawSections)) fail("sections", "must be an array");
+	if (rawSections.length > 32) fail("sections", `holds more than 32 sections`);
+	const seen = /* @__PURE__ */ new Set();
+	return {
+		version: 1,
+		enabled,
+		sections: rawSections.map((raw, index) => {
+			const path = `sections[${index}]`;
+			if (!isRecord(raw)) fail(path, "must be an object");
+			for (const key of Object.keys(raw)) if (![
+				"id",
+				"title",
+				"text",
+				"position",
+				"order",
+				"enabled",
+				"interpolate"
+			].includes(key)) fail(`${path}.${key}`, "unknown field");
+			const id = readId(raw.id, `${path}.id`);
+			if (seen.has(id)) fail(`${path}.id`, `duplicate section id "${id}"`);
+			seen.add(id);
+			const title = readString(raw.title ?? "", `${path}.title`).trim().slice(0, 80);
+			const text = readString(raw.text ?? "", `${path}.text`);
+			const bytes = Buffer.byteLength(text, "utf8");
+			if (bytes > 262144) fail(`${path}.text`, `is ${bytes} bytes; the limit is ${MAX_TEXT_BYTES}`);
+			return {
+				id,
+				title: title === "" ? `Section ${index + 1}` : title,
+				text,
+				position: readPosition(raw.position, `${path}.position`),
+				order: readOrder(raw.order, `${path}.order`),
+				enabled: readBoolean(raw.enabled, `${path}.enabled`, true),
+				interpolate: readBoolean(raw.interpolate, `${path}.interpolate`, false)
+			};
+		})
+	};
+}
+// src/store.ts
+/**
+* The persisted section list: one JSON file, re-read when it changes on disk.
+*
+* ## Why a file rather than the profile entry's `config`
+*
+* The editor writes on every save, and a profile patch is a YAML document shared
+* with every other plugin in the layer — rewriting it from a plugin is a hostile
+* thing to do. A dedicated file also means a hand edit (`vim`) and the Web editor
+* are the same source of truth, and the prompt picks the edit up on the next
+* step, with no reload.
+*
+* ## Change detection
+*
+* `current()` stats the file on every call. A section's text is a provider that
+* runs at each assembly, so this is what makes an out-of-band edit visible
+* without a restart — and the stat is cached by modification time, so the common
+* case is one `statSync` per assembly, not per section.
+*
+* A file that fails to parse is NOT treated as empty: the last good state stays
+* live (wiping someone's prompt because they were mid-save in an editor would be
+* worse than serving a slightly stale one), and the parse error is surfaced to
+* the UI through {@link PromptStore.lastError}.
+*
+* @module dsh-system-prompt-insertion/store
+*/
+function stampOf(path) {
+	try {
+		const stat = statSync(path);
+		return {
+			mtimeMs: stat.mtimeMs,
+			size: stat.size
+		};
+	} catch {
+		return;
+	}
+}
+function sameStamp(a, b) {
+	if (a === void 0 || b === void 0) return a === b;
+	return a.mtimeMs === b.mtimeMs && a.size === b.size;
+}
+/**
+* Render a path for the UI without leaking a machine-specific home directory.
+*
+* @param path - absolute path.
+* @returns `~/.dsh/...` for paths under the default home, `$DSH_HOME/...` for a
+*   configured one, and the path unchanged otherwise.
+*/
+function displayPath(path) {
+	const home = resolveDshHome();
+	const prefix = home.endsWith("/") ? home : `${home}/`;
+	if (path === home) return dshHomeDisplay(home);
+	if (path.startsWith(prefix)) return `${dshHomeDisplay(home)}${path.slice(home.length)}`;
+	return path;
+}
+/** The section store. */
+var PromptStore = class {
+	path;
+	logger;
+	state = emptyState();
+	stamp;
+	source = "missing";
+	error;
+	loaded = false;
+	constructor(options) {
+		this.path = options.path;
+		this.logger = options.logger;
+	}
+	/** Absolute path of the JSON document. */
+	file() {
+		return this.path;
+	}
+	/** Display form of {@link file} for user-facing text. */
+	displayPath() {
+		return displayPath(this.path);
+	}
+	/** Where the current state came from. */
+	origin() {
+		return this.source;
+	}
+	/** The last load or parse error, if the file could not be read. */
+	lastError() {
+		return this.error;
+	}
+	/**
+	* The current state, re-reading the file when it changed on disk.
+	*
+	* @returns a frozen view; callers must not mutate it.
+	*/
+	current() {
+		if (!this.loaded) {
+			this.loaded = true;
+			this.reload(stampOf(this.path));
+			return this.state;
+		}
+		const stamp = stampOf(this.path);
+		if (!sameStamp(stamp, this.stamp)) this.reload(stamp);
+		return this.state;
+	}
+	/**
+	* Validate, persist, and publish a new state.
+	*
+	* @param input - the candidate state (already parsed JSON).
+	* @returns the normalized state that was stored.
+	* @throws StateValidationError when the candidate is not acceptable.
+	*/
+	save(input) {
+		const next = normalizeState(input);
+		mkdirSync(dirname(this.path), {
+			recursive: true,
+			mode: 448
+		});
+		const temporary = `${this.path}.${process.pid}.tmp`;
+		try {
+			writeFileSync(temporary, `${JSON.stringify(next, null, 2)}\n`, {
+				encoding: "utf8",
+				mode: 384
+			});
+			renameSync(temporary, this.path);
+		} catch (error) {
+			try {
+				unlinkSync(temporary);
+			} catch {}
+			throw error;
+		}
+		try {
+			chmodSync(this.path, 384);
+		} catch {}
+		this.state = next;
+		this.stamp = stampOf(this.path);
+		this.source = "memory";
+		this.error = void 0;
+		this.loaded = true;
+		return next;
+	}
+	/** Re-read the file. A failed read keeps the previous state live. */
+	reload(stamp) {
+		if (stamp === void 0) {
+			this.state = emptyState();
+			this.stamp = void 0;
+			this.source = "missing";
+			this.error = void 0;
+			return;
+		}
+		try {
+			const text = readFileSync(this.path, "utf8");
+			this.state = normalizeState(JSON.parse(text));
+			this.stamp = stamp;
+			this.source = "file";
+			this.error = void 0;
+		} catch (error) {
+			this.stamp = stamp;
+			this.source = "unreadable";
+			this.error = error instanceof StateValidationError ? error.message : error instanceof Error ? error.message : String(error);
+			this.logger.warn(`system-prompt-insertion: cannot read ${displayPath(this.path)} (${this.error}); keeping the previous state`);
+		}
+	}
+};
+// src/orders.ts
+/** First order inside the `head` band — right after the persona prefix. */
+const HEAD_BASE = 10;
+/** First order inside the `body` band — after every tool guidance section. */
+const BODY_BASE = 5100;
+/** Distance kept above the host's own last section. */
+const TAIL_GAP = 300;
+/** Spacing between two sections of the same band. */
+const SECTION_STEP = 10;
+/** Fallback for the host's last built-in section order (`DEPLOYMENT_PERSONA_SUFFIX`). */
+const FALLBACK_TAIL_BASE = 10200;
+/**
+* Resolve the concrete order of one section.
+*
+* @param section - the stored section.
+* @param ordinal - its index among ALL sections of the same band, in editor
+*   order. Disabled and empty entries keep their slot, so switching one off does
+*   not renumber its neighbours.
+* @param bases - the band bases for this load.
+* @returns the order to register.
+*/
+function resolveSectionOrder(section, ordinal, bases) {
+	if (section.order !== null) return section.order;
+	switch (section.position) {
+		case "head": return 10 + ordinal * 10;
+		case "body": return BODY_BASE + ordinal * 10;
+		case "tail": return bases.tailBase + 300 + ordinal * 10;
+	}
+}
+/**
+* Plan the registrations for one state: which sections are contributed, under
+* which name and at which order.
+*
+* @param state - the stored state.
+* @param bases - the band bases for this load.
+* @param prefix - registered-name prefix (`user:system-prompt-insertion:` by default).
+* @returns one plan per ENABLED, non-empty section, in editor order.
+*/
+function planRegistrations(state, bases, prefix) {
+	if (!state.enabled) return [];
+	const ordinals = {
+		head: 0,
+		body: 0,
+		tail: 0
+	};
+	const plan = [];
+	for (const section of state.sections) {
+		const ordinal = ordinals[section.position]++;
+		if (!section.enabled || section.text.trim() === "") continue;
+		plan.push({
+			section,
+			name: `${prefix}${section.id}`,
+			order: resolveSectionOrder(section, ordinal, bases)
+		});
+	}
+	return plan;
+}
+// src/register.ts
+/** Read the host's own last built-in section order at runtime. */
+function resolveOrderBases(ctx) {
+	const suffix = ctx.systemPrompt.getSectionOrder("DEPLOYMENT_PERSONA_SUFFIX");
+	return { tailBase: typeof suffix === "number" && Number.isFinite(suffix) ? suffix : FALLBACK_TAIL_BASE };
+}
+/** Owns the registered sections of one plugin instance. */
+var SectionRegistrar = class {
+	ctx;
+	store;
+	logger;
+	prefix;
+	disposers = [];
+	names = [];
+	orderByName = /* @__PURE__ */ new Map();
+	bases;
+	constructor(ctx, store, logger, prefix = SECTION_PREFIX) {
+		this.ctx = ctx;
+		this.store = store;
+		this.logger = logger;
+		this.prefix = prefix;
+		this.bases = resolveOrderBases(ctx);
+	}
+	/** The band bases currently in use (also reported to the preview). */
+	orderBases() {
+		return this.bases;
+	}
+	/** Names of the sections currently registered, for diagnostics and the preview. */
+	registeredNames() {
+		return [...this.names];
+	}
+	/** The concrete order each registered section was placed at. */
+	registeredOrders() {
+		return this.orderByName;
+	}
+	/**
+	* Rebuild the registration plan from the store.
+	*
+	* Registration is idempotent per plan: the previous plan is disposed first, so a
+	* removed section cannot linger. A section whose registration throws (a name
+	* collision with another plugin) is reported and skipped instead of taking the
+	* whole plugin down.
+	*
+	* @returns the state that was planned from.
+	*/
+	sync() {
+		this.dispose();
+		this.bases = resolveOrderBases(this.ctx);
+		const state = this.store.current();
+		const plan = planRegistrations(state, this.bases, this.prefix);
+		for (const entry of plan) {
+			const { section } = entry;
+			try {
+				const dispose = this.ctx.systemPrompt.section({
+					name: entry.name,
+					order: entry.order,
+					text: () => {
+						return this.store.current().sections.find((candidate) => candidate.id === section.id)?.text ?? "";
+					},
+					...section.interpolate ? {} : { interpolate: false }
+				});
+				this.disposers.push(dispose);
+				this.names.push(entry.name);
+				this.orderByName.set(entry.name, entry.order);
+			} catch (error) {
+				this.logger.warn(`system-prompt-insertion: cannot register "${section.id}" at order ${entry.order}: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		return state;
+	}
+	/** Dispose every registration this instance owns. */
+	dispose() {
+		this.names.splice(0);
+		this.orderByName.clear();
+		for (const dispose of this.disposers.splice(0)) try {
+			dispose();
+		} catch {}
+	}
+};
+// src/preview.ts
+/** Normalize a line for duplicate detection: trimmed, whitespace collapsed. */
+function normalizeLine(line) {
+	return line.trim().replace(/\s+/g, " ");
+}
+/** Lines long enough that a repeat is a real repetition rather than boilerplate. */
+const DUPLICATE_LINE_FLOOR = 30;
+/** Complete `{{name}}` references, mirroring the registry's own grammar. */
+const VARIABLE_REFERENCE = /\{\{([^{}]*)\}\}/g;
+/** Lines of one text, indexed for duplicate detection. */
+function longLines(text) {
+	const lines = [];
+	for (const raw of text.split("\n")) {
+		const line = normalizeLine(raw);
+		if (line.length >= DUPLICATE_LINE_FLOOR) lines.push(line);
+	}
+	return lines;
+}
+/** Warnings that depend only on the stored state. */
+function stateWarnings(state, maxSectionBytes) {
+	const warnings = [];
+	for (const section of state.sections) {
+		const bytes = Buffer.byteLength(section.text, "utf8");
+		if (section.enabled && section.text.trim() === "") warnings.push({
+			code: "empty",
+			sectionId: section.id,
+			params: { title: section.title },
+			message: `"${section.title}" is enabled but empty.`
+		});
+		if (bytes > maxSectionBytes) warnings.push({
+			code: "oversize",
+			sectionId: section.id,
+			params: {
+				title: section.title,
+				bytes,
+				cap: maxSectionBytes
+			},
+			message: `"${section.title}" is ${bytes} bytes, above the ${maxSectionBytes}-byte soft cap.`
+		});
+	}
+	return warnings;
+}
+/** Warnings that compare our text with the rest of the assembled prompt. */
+function duplicateWarnings(state, assembly) {
+	const foreign = /* @__PURE__ */ new Map();
+	for (const section of assembly.sections) {
+		if (section.name.startsWith("user:system-prompt-insertion:")) continue;
+		for (const line of longLines(section.text)) if (!foreign.has(line)) foreign.set(line, section.name);
+	}
+	const warnings = [];
+	const reported = /* @__PURE__ */ new Set();
+	for (const section of state.sections) {
+		if (!section.enabled) continue;
+		for (const line of longLines(section.text)) {
+			const owner = foreign.get(line);
+			if (owner === void 0) continue;
+			const key = `${section.id}:${owner}`;
+			if (reported.has(key)) continue;
+			reported.add(key);
+			warnings.push({
+				code: "duplicate",
+				sectionId: section.id,
+				params: {
+					title: section.title,
+					other: owner
+				},
+				message: `"${section.title}" repeats a line already in section "${owner}".`
+			});
+		}
+	}
+	return warnings;
+}
+/** Variables a section references, in first-seen order. */
+function referencedVariables(text) {
+	const names = [];
+	for (const match of text.matchAll(VARIABLE_REFERENCE)) {
+		const name = match[1] ?? "";
+		if (!names.includes(name)) names.push(name);
+	}
+	return names;
+}
+/** Warnings about `{{...}}` references that would fail rendering. */
+function variableWarnings(state, assembly) {
+	const warnings = [];
+	const known = new Set(Object.keys(assembly.variables));
+	for (const section of state.sections) {
+		if (!section.enabled || !section.interpolate) continue;
+		for (const name of referencedVariables(section.text)) {
+			if (known.has(name) && assembly.variables[name] !== void 0) continue;
+			warnings.push({
+				code: "unknown-variable",
+				sectionId: section.id,
+				params: {
+					title: section.title,
+					name,
+					known: [...known].join(", ") || "none"
+				},
+				message: `"${section.title}" references {{${name}}}, which this assembly does not define (known: ${[...known].join(", ") || "none"}). Turn interpolation off to keep it literal.`
+			});
+		}
+	}
+	return warnings;
+}
+/**
+* Render one assembly the way the harness would, except that a reference with no
+* value stays visible as `{{name}}` instead of throwing.
+*
+* A scope-less assembly legitimately has no `{{model}}`: the loop registers that
+* variable per agent. The preview must still show the prompt, so the missing fact
+* is displayed rather than crashing the panel; {@link buildPreview} reports the
+* substitution separately.
+*
+* @param assembly - the assembled prompt.
+* @returns the rendered text, plus the names left unresolved.
+*/
+function renderTolerant(assembly) {
+	const unresolved = /* @__PURE__ */ new Set();
+	const variables = assembly.variables;
+	const parts = [];
+	for (const section of assembly.sections) {
+		let text = section.text;
+		if (section.interpolate !== false) text = text.replace(/\{\{([^{}]*)\}\}/g, (match, name) => {
+			if (!/^[a-z][a-z0-9_]*$/.test(name)) return match;
+			const value = variables[name];
+			if (value === void 0) {
+				unresolved.add(name);
+				return match;
+			}
+			return value;
+		});
+		if (text.length > 0) parts.push(text);
+	}
+	return {
+		text: parts.join("\n\n"),
+		unresolved: [...unresolved]
+	};
+}
+/**
+* Build the preview for the current state.
+*
+* @param host - the store, registrar, host context and soft size cap.
+* @returns the assembled prompt, its sections, and every warning.
+*/
+async function buildPreview(host) {
+	const state = host.store.current();
+	const assembly = await host.ctx.systemPrompt.assemble({});
+	const warnings = [...stateWarnings(state, host.maxSectionBytes), ...duplicateWarnings(state, assembly)];
+	warnings.push(...variableWarnings(state, assembly));
+	const orders = host.registrar.registeredOrders();
+	const sections = assembly.sections.map((section, index) => {
+		const ours = section.name.startsWith(SECTION_PREFIX);
+		const order = ours ? orders.get(section.name) : void 0;
+		return {
+			name: section.name,
+			index,
+			...order === void 0 ? {} : { order },
+			bytes: Buffer.byteLength(section.text, "utf8"),
+			ours,
+			text: section.text
+		};
+	});
+	const complete = sections.length === 1 && !sections[0]?.ours;
+	if (complete) warnings.push({
+		code: "hidden",
+		message: "The active agent preset replaces the whole system prompt with a single section, so these sections are not sent."
+	});
+	else {
+		const present = new Set(sections.map((section) => section.name));
+		for (const name of host.registrar.registeredNames()) {
+			if (present.has(name)) continue;
+			warnings.push({
+				code: "hidden",
+				sectionId: name.slice(29),
+				message: "This section is registered but not part of the current global assembly."
+			});
+		}
+	}
+	if (host.store.origin() === "unreadable") warnings.push({
+		code: "store-error",
+		message: host.store.lastError() ?? "The state file could not be read."
+	});
+	const tolerant = renderTolerant(assembly);
+	const rendered = tolerant.text;
+	let renderError;
+	try {
+		renderPrompt(assembly);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		if (message.includes("user:system-prompt-insertion:")) {
+			renderError = message;
+			warnings.push({
+				code: "render-error",
+				message
+			});
+		} else warnings.push({
+			code: "preview-partial",
+			params: { names: tolerant.unresolved.join(", ") || "—" },
+			message: `Previewed without an agent scope, so per-agent variables were left literal (${tolerant.unresolved.join(", ") || "none"}).`
+		});
+	}
+	return {
+		rendered,
+		bytes: Buffer.byteLength(rendered, "utf8"),
+		sections,
+		variables: Object.keys(assembly.variables),
+		warnings,
+		complete,
+		...renderError === void 0 ? {} : { renderError }
+	};
+}
+// src/routes.ts
+/** URL prefix of every route this plugin owns. */
+const ROUTE_PREFIX = "/dsh-system-prompt-insertion";
+/** Largest accepted request body (the state document is small; 512 KiB is slack). */
+const MAX_BODY_BYTES = 524288;
+function sendJson(res, status, payload) {
+	const body = JSON.stringify(payload);
+	res.statusCode = status;
+	res.setHeader("content-type", "application/json; charset=utf-8");
+	res.setHeader("cache-control", "no-store");
+	res.end(body);
+}
+/** Whether the request's Origin, when sent, is this same origin. */
+function sameOrigin(req) {
+	const origin = req.headers.origin;
+	if (origin === void 0 || origin === "") return true;
+	const host = req.headers.host;
+	if (host === void 0) return false;
+	try {
+		return new URL(origin).host === host;
+	} catch {
+		return false;
+	}
+}
+/** Read a bounded JSON body. */
+async function readJsonBody(req) {
+	const declared = Number(req.headers["content-length"] ?? "0");
+	if (Number.isFinite(declared) && declared > 524288) throw Object.assign(/* @__PURE__ */ new Error("request body is too large"), {
+		status: 413,
+		code: "too-large"
+	});
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+		total += buffer.length;
+		if (total > 524288) throw Object.assign(/* @__PURE__ */ new Error("request body is too large"), {
+			status: 413,
+			code: "too-large"
+		});
+		chunks.push(buffer);
+	}
+	const text = Buffer.concat(chunks).toString("utf8");
+	if (text.trim() === "") return {};
+	try {
+		return JSON.parse(text);
+	} catch {
+		throw Object.assign(/* @__PURE__ */ new Error("request body is not valid JSON"), {
+			status: 400,
+			code: "invalid-json"
+		});
+	}
+}
+/** Answer a request this plugin refuses to serve. */
+function reject(res, status, code, message) {
+	sendJson(res, status, {
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	});
+}
+/** Read the current state as the editor's payload. */
+function statePayload(deps) {
+	const state = deps.store.current();
+	const error = deps.store.lastError();
+	return {
+		state,
+		path: deps.store.displayPath(),
+		origin: deps.store.origin(),
+		...error === void 0 ? {} : { error },
+		orderBases: deps.registrar.orderBases(),
+		registered: deps.registrar.registeredNames()
+	};
+}
+/**
+* Register the three routes on `ctx.webServer` when that service is present.
+*
+* The plugin stays fully functional without it (the host half needs only the
+* prompt registry); a headless profile simply has no editor.
+*
+* @param ctx - the plugin context.
+* @param deps - store, registrar, preview builder and logger.
+*/
+function registerRoutes(ctx, deps) {
+	ctx.inject(["webServer"], (webCtx) => {
+		webCtx.effect(() => webCtx.webServer.register({
+			kind: "exact",
+			path: `${ROUTE_PREFIX}/state`,
+			handler: async (req, res) => {
+				if (!sameOrigin(req)) return reject(res, 403, "cross-origin", "cross-origin request refused");
+				if (req.method === "GET") {
+					sendJson(res, 200, {
+						ok: true,
+						...statePayload(deps)
+					});
+					return;
+				}
+				if (req.method !== "POST") {
+					res.setHeader("allow", "GET, POST");
+					return reject(res, 405, "method-not-allowed", "use GET or POST");
+				}
+				if (!String(req.headers["content-type"] ?? "").toLowerCase().startsWith("application/json")) return reject(res, 415, "unsupported-media-type", "send application/json");
+				try {
+					const body = await readJsonBody(req);
+					const next = deps.store.save(body);
+					deps.registrar.sync();
+					deps.logger.info(`system-prompt-insertion: saved ${next.sections.length} section(s); ${deps.registrar.registeredNames().length} registered`);
+					sendJson(res, 200, {
+						ok: true,
+						...statePayload(deps)
+					});
+				} catch (error) {
+					if (error instanceof StateValidationError) return reject(res, 422, "invalid-state", error.message);
+					const status = typeof error.status === "number" ? error.status : 500;
+					const code = typeof error.code === "string" ? error.code : "write-failed";
+					deps.logger.warn(`system-prompt-insertion: save failed (${code}): ${error instanceof Error ? error.message : String(error)}`);
+					reject(res, status, code, error instanceof Error ? error.message : String(error));
+				}
+			}
+		}), `system-prompt-insertion: ${ROUTE_PREFIX}/state`);
+		webCtx.effect(() => webCtx.webServer.register({
+			kind: "exact",
+			path: `${ROUTE_PREFIX}/preview`,
+			handler: async (req, res) => {
+				if (!sameOrigin(req)) return reject(res, 403, "cross-origin", "cross-origin request refused");
+				if (req.method !== "GET") {
+					res.setHeader("allow", "GET");
+					return reject(res, 405, "method-not-allowed", "use GET");
+				}
+				try {
+					sendJson(res, 200, {
+						ok: true,
+						...await deps.preview()
+					});
+				} catch (error) {
+					deps.logger.warn(`system-prompt-insertion: preview failed: ${error instanceof Error ? error.message : String(error)}`);
+					reject(res, 500, "preview-failed", error instanceof Error ? error.message : String(error));
+				}
+			}
+		}), `system-prompt-insertion: ${ROUTE_PREFIX}/preview`);
+	});
+}
+// src/index.ts
+/**
+* `dsh-system-prompt-insertion` — user-owned text injected into the DeepSeek
+* Harness system prompt.
+*
+* ## What it adds
+*
+* The harness assembles one system prompt per model step from ordered sections
+* contributed by plugins. This plugin lets the USER inject their own text as
+* those sections: written in the Web editor (or a JSON file), placed at the head,
+* the middle, or the very tail of that prompt, and rendered on every step with
+* no restart.
+*
+* A "section" is the harness's own unit of prompt composition, so user text lands
+* in the same layer as the platform's own instructions — unlike `AGENTS.md`, which
+* arrives as a *user-role* message whose frame explicitly says it does not
+* override system instructions.
+*
+* ## Composition
+*
+* One profile row mounts both halves:
+*
+* 1. the host half loads the state file, registers one prompt section per enabled
+*    entry, and (when `ctx.webServer` exists) serves the editor's JSON routes;
+* 2. the browser half registered by this package's `./client` export draws a
+*    left-column sidebar panel and talks to those routes.
+*
+* Nothing here is coupled to a specific agent preset: registration happens on the
+* host context, so the global layer covers Web sessions, subagents and workflow
+* children. A preset that takes over the whole prompt (`complete: true`, e.g. the
+* built-in `minimal`) cannot be appended to, and the editor says so.
+*
+* ## Configuration
+*
+* The row's `config` holds deployment switches only — never prompt text — so the
+* editor and a hand-edited file cannot disagree about what is live.
+*
+* @module dsh-system-prompt-insertion
+*/
+/** Cordis plugin name. */
+const name = "system-prompt-insertion";
+/** The prompt registry must exist before a section can be registered. */
+const inject = ["systemPrompt"];
+/** How long to coalesce filesystem change notifications. */
+const WATCH_DEBOUNCE_MS = 60;
+/** How often the state file is polled for out-of-band edits. */
+const WATCH_INTERVAL_MS = 1e3;
+/** Schema for {@link Config}. */
+const Config = Schema.object({
+	enabled: Schema.boolean().default(true).description("Add the stored text to the system prompt as sections."),
+	storeFile: Schema.string().default("").description("Path of the state file. Empty uses $DSH_HOME/system-prompt-insertion.json."),
+	maxSectionBytes: Schema.number().default(8192).description("Soft per-section size cap the editor reports; nothing is truncated.")
+});
+/**
+* Resolve the row configuration into absolute options.
+*
+* @param config - the row configuration.
+* @returns the paths and limits the plugin runs with.
+*/
+function resolveOptions(config) {
+	const configured = config.storeFile.trim();
+	return {
+		storeFile: configured === "" ? dshHomePath("system-prompt-insertion.json") : expandHomePath(configured),
+		maxSectionBytes: Number.isFinite(config.maxSectionBytes) && config.maxSectionBytes > 0 ? config.maxSectionBytes : 8192
+	};
+}
+/**
+* Mount the user-owned system-prompt text and its editor.
+*
+* @param ctx - the profile row's context.
+* @param config - the validated row configuration.
+*/
+function apply(ctx, config) {
+	const logger = ctx.logger;
+	if (!config.enabled) {
+		logger.info("system-prompt-insertion: disabled by configuration");
+		return;
+	}
+	const options = resolveOptions(config);
+	const store = new PromptStore({
+		path: options.storeFile,
+		logger
+	});
+	const registrar = new SectionRegistrar(ctx, store, logger);
+	ctx.effect(() => () => registrar.dispose(), "system-prompt-insertion: registrations");
+	ctx.effect(() => {
+		let timer;
+		const onChange = () => {
+			if (timer !== void 0) clearTimeout(timer);
+			timer = setTimeout(() => {
+				timer = void 0;
+				try {
+					registrar.sync();
+					logger.info(`system-prompt-insertion: reloaded ${registrar.registeredNames().length} section(s) after a file change`);
+				} catch (error) {
+					logger.warn(`system-prompt-insertion: reload failed: ${error instanceof Error ? error.message : String(error)}`);
+				}
+			}, WATCH_DEBOUNCE_MS);
+			timer.unref?.();
+		};
+		watchFile(options.storeFile, { interval: WATCH_INTERVAL_MS }, onChange);
+		return () => {
+			if (timer !== void 0) clearTimeout(timer);
+			unwatchFile(options.storeFile, onChange);
+		};
+	}, "system-prompt-insertion: state watcher");
+	registerRoutes(ctx, {
+		store,
+		registrar,
+		logger,
+		preview: () => buildPreview({
+			ctx,
+			store,
+			registrar,
+			maxSectionBytes: options.maxSectionBytes
+		})
+	});
+	const state = registrar.sync();
+	logger.info(`system-prompt-insertion: ${registrar.registeredNames().length} of ${state.sections.length} section(s) registered from ${store.displayPath()}`);
+}
+export { BODY_BASE, Config, FALLBACK_TAIL_BASE, HEAD_BASE, MAX_BODY_BYTES, MAX_SECTIONS, MAX_TEXT_BYTES, POSITIONS, PromptStore, ROUTE_PREFIX, SECTION_ID, SECTION_PREFIX, SECTION_STEP, SectionRegistrar, StateValidationError, TAIL_GAP, apply, buildPreview, displayPath, emptyState, inject, name, normalizeState, planRegistrations, registerRoutes, resolveOptions, resolveOrderBases, resolveSectionOrder };