@huanlin/dsh-plugin-preface-context 0.1.0

package/lib/types/client/preface-card.css.js

@@ -0,0 +1,327 @@
+/**
+ * Card styles + runtime style injection for the preface-context settings
+ * card.
+ *
+ * The DSH client loader never serves `.css` artifacts — every style must be
+ * injected inside the bundle's factory closure (the same contract the
+ * upstream tsdown.client preset implements with lightningcss). A plain
+ * template-string stylesheet installed once at plugin activation is the slim
+ * equivalent for a hand-rolled bundle: static, prefixed class names
+ * (`dsh-pfc-*`, unique in the document) replace the hashed CSS-modules map,
+ * and the `<style data-plugin-css>` tag is removed when the plugin unloads.
+ *
+ * Colors resolve through `--dsw-alias-*` tokens so the card adapts to the
+ * light/dark theme.
+ *
+ * @module @huanlin/dsh-plugin-preface-context/client/preface-card.css
+ */
+/** Class-name map consumed by the card component (CSS-modules replacement). */
+export const css = {
+    card: 'dsh-pfc-card',
+    cardOpen: 'dsh-pfc-card--open',
+    header: 'dsh-pfc-header',
+    headText: 'dsh-pfc-head-text',
+    name: 'dsh-pfc-name',
+    description: 'dsh-pfc-description',
+    pending: 'dsh-pfc-pending',
+    chevron: 'dsh-pfc-chevron',
+    chevronOpen: 'dsh-pfc-chevron--open',
+    body: 'dsh-pfc-body',
+    readOnly: 'dsh-pfc-readonly',
+    field: 'dsh-pfc-field',
+    head: 'dsh-pfc-field-head',
+    label: 'dsh-pfc-label',
+    badges: 'dsh-pfc-badges',
+    badge: 'dsh-pfc-badge',
+    reset: 'dsh-pfc-reset',
+    textarea: 'dsh-pfc-textarea',
+    toggleRow: 'dsh-pfc-toggle-row',
+    toggle: 'dsh-pfc-toggle',
+    toggleOn: 'dsh-pfc-toggle--on',
+    knob: 'dsh-pfc-knob',
+    knobOn: 'dsh-pfc-knob--on',
+    hint: 'dsh-pfc-hint',
+    footer: 'dsh-pfc-footer',
+    failed: 'dsh-pfc-failed',
+    discard: 'dsh-pfc-discard',
+    save: 'dsh-pfc-save',
+};
+/** `data-plugin-css` tag id of the injected stylesheet. */
+const STYLE_TAG_ID = '@huanlin/dsh-plugin-preface-context/preface-card.css';
+/** The card stylesheet (injected as one tagged `<style>` at activation). */
+const CSS = `
+.dsh-pfc-card {
+  list-style: none;
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.22));
+  background: var(--dsw-alias-bg-layer-3, transparent);
+  border-radius: 12px;
+  transition: border-color 0.16s, background 0.16s;
+  overflow: hidden;
+}
+
+.dsh-pfc-card--open {
+  border-color: var(--dsw-alias-border-l3, rgba(128, 128, 128, 0.35));
+}
+
+.dsh-pfc-header {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  gap: 12px;
+  padding: 14px 16px;
+  font: inherit;
+  color: inherit;
+  text-align: left;
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+}
+
+.dsh-pfc-head-text {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+
+.dsh-pfc-name {
+  font-size: 15px;
+  font-weight: 600;
+  line-height: 1.4;
+  color: var(--dsw-alias-label-primary, inherit);
+}
+
+.dsh-pfc-description {
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary, rgba(128, 128, 128, 0.7));
+}
+
+.dsh-pfc-pending {
+  flex: none;
+  white-space: nowrap;
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 17px;
+  padding: 1px 8px;
+  border-radius: 999px;
+  color: var(--dsw-alias-label-secondary, inherit);
+  background: var(--dsw-alias-bg-module-platform, rgba(128, 128, 128, 0.12));
+}
+
+.dsh-pfc-chevron {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  color: var(--dsw-alias-label-tertiary, inherit);
+  transition: transform 0.16s;
+}
+
+.dsh-pfc-chevron--open {
+  transform: rotate(180deg);
+}
+
+.dsh-pfc-body {
+  margin: 0 16px;
+  padding: 12px 0 4px;
+  border-top: 1px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.22));
+}
+
+.dsh-pfc-readonly {
+  margin: 0 0 8px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary, rgba(128, 128, 128, 0.7));
+}
+
+.dsh-pfc-field {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin: 0 0 12px;
+}
+
+.dsh-pfc-field-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.dsh-pfc-label {
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-primary, inherit);
+}
+
+.dsh-pfc-badges {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin-left: auto;
+}
+
+.dsh-pfc-badge {
+  font-size: 11px;
+  font-weight: 500;
+  line-height: 17px;
+  padding: 1px 8px;
+  border-radius: 999px;
+  color: var(--dsw-alias-label-secondary, inherit);
+  background: var(--dsw-alias-bg-module-platform, rgba(128, 128, 128, 0.12));
+}
+
+.dsh-pfc-reset {
+  appearance: none;
+  font: inherit;
+  font-size: 12px;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  color: var(--dsw-alias-brand-primary, #0a84ff);
+}
+
+.dsh-pfc-reset:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.dsh-pfc-textarea {
+  width: 100%;
+  box-sizing: border-box;
+  min-height: 96px;
+  resize: vertical;
+  padding: 6px 10px;
+  font-family: var(--dsw-font-mono, ui-monospace, monospace);
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary, inherit);
+  background: var(--dsw-alias-bg-layer-3, transparent);
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.3));
+  border-radius: 8px;
+}
+
+.dsh-pfc-textarea:focus {
+  outline: none;
+  border-color: var(--dsw-alias-brand-primary, #0a84ff);
+}
+
+.dsh-pfc-textarea:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.dsh-pfc-toggle-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.dsh-pfc-toggle {
+  position: relative;
+  width: 40px;
+  height: 22px;
+  flex: none;
+  padding: 0;
+  background: var(--dsw-alias-bg-module-platform, rgba(128, 128, 128, 0.12));
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.3));
+  border-radius: 999px;
+  cursor: pointer;
+  transition: background 0.16s, border-color 0.16s;
+}
+
+.dsh-pfc-toggle--on {
+  background: var(--dsw-alias-brand-primary, #0a84ff);
+  border-color: var(--dsw-alias-brand-primary, #0a84ff);
+}
+
+.dsh-pfc-knob {
+  position: absolute;
+  top: 2px;
+  left: 2px;
+  width: 16px;
+  height: 16px;
+  background: var(--dsw-alias-bg-layer-1, #fff);
+  border-radius: 50%;
+  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
+  transition: transform 0.16s;
+}
+
+.dsh-pfc-knob--on {
+  transform: translateX(18px);
+}
+
+.dsh-pfc-toggle:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.dsh-pfc-hint {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary, rgba(128, 128, 128, 0.6));
+}
+
+.dsh-pfc-footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 12px 0 4px;
+  border-top: 1px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.22));
+}
+
+.dsh-pfc-failed {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-error, #ff453a);
+}
+
+.dsh-pfc-discard,
+.dsh-pfc-save {
+  appearance: none;
+  font: inherit;
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 20px;
+  padding: 5px 14px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  cursor: pointer;
+  color: var(--dsw-alias-label-primary, inherit);
+  background: var(--dsw-alias-bg-module-platform, rgba(128, 128, 128, 0.12));
+  transition: background 0.16s, opacity 0.16s;
+}
+
+.dsh-pfc-save {
+  background: var(--dsw-alias-brand-primary, #0a84ff);
+  color: var(--dsw-alias-bg-layer-1, #fff);
+}
+
+.dsh-pfc-discard:disabled,
+.dsh-pfc-save:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+`;
+/**
+ * Install the card stylesheet as one tagged `<style>` element.
+ * @returns the disposer removing the tag (idempotent outside a document).
+ */
+export function installPrefaceCardStyles() {
+    if (typeof document === 'undefined')
+        return () => { };
+    if (document.querySelector(`style[data-plugin-css='${STYLE_TAG_ID}']`) !== null)
+        return () => { };
+    const style = document.createElement('style');
+    style.dataset.plugin = '@huanlin/dsh-plugin-preface-context';
+    style.dataset.pluginCss = STYLE_TAG_ID;
+    style.textContent = CSS;
+    document.head.appendChild(style);
+    return () => { style.remove(); };
+}

package/lib/types/client/preface-card.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The preface-context settings card: a collapsible card on the "插件配置"
+ * settings page. Renders an enable toggle and a multiline textarea for the
+ * context text. Stages edits locally and writes them on save through the
+ * bound {@link PrefaceCardController}.
+ *
+ * The chrome mirrors the upstream `PluginCard` shape (a header button
+ * stacking name over description, a dirty pill, a rotating chevron; a body
+ * with the form controls and a footer with Discard/Save) because the
+ * upstream client value face exports no reusable card. Styles come from the
+ * statically injected `preface-card.css` stylesheet (the loader never serves
+ * `.css` artifacts); every color resolves through a `--dsw-alias-*` token so
+ * the card adapts to the light/dark theme.
+ */
+import { type ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { PrefaceCardFace, PrefaceCardActions } from './preface-card-controller.ts';
+/** Injected dependencies of the card (slot `inject`). */
+export type PrefaceCardInjected = PrefaceCardFace & PrefaceCardActions;
+/** Props the renderer binds for the card. */
+export type PrefaceCardProps = PropsRuntime<'settings.plugin.item'> & PropsLocale<'settings.preface-context'> & InjectFace<PrefaceCardInjected>;
+/**
+ * Render the preface-context card.
+ * @param props - locale copy, the card snapshot, and its form actions.
+ * @returns the card, or nothing when the namespace is unavailable.
+ */
+export declare function PrefaceCard(props: PrefaceCardProps): ReactNode;

package/lib/types/client/preface-card.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The preface-context settings card: a collapsible card on the "插件配置"
+ * settings page. Renders an enable toggle and a multiline textarea for the
+ * context text. Stages edits locally and writes them on save through the
+ * bound {@link PrefaceCardController}.
+ *
+ * The chrome mirrors the upstream `PluginCard` shape (a header button
+ * stacking name over description, a dirty pill, a rotating chevron; a body
+ * with the form controls and a footer with Discard/Save) because the
+ * upstream client value face exports no reusable card. Styles come from the
+ * statically injected `preface-card.css` stylesheet (the loader never serves
+ * `.css` artifacts); every color resolves through a `--dsw-alias-*` token so
+ * the card adapts to the light/dark theme.
+ */
+import { useState } from 'react';
+import clsx from 'clsx';
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives';
+import { css } from "./preface-card.css.js";
+/**
+ * Render the preface-context card.
+ * @param props - locale copy, the card snapshot, and its form actions.
+ * @returns the card, or nothing when the namespace is unavailable.
+ */
+export function PrefaceCard(props) {
+    const [open, setOpen] = useState(false);
+    const { t } = props;
+    const state = props.usePrefaceCard(snapshot => snapshot);
+    if (!state.available)
+        return null;
+    const title = t('title');
+    const blocked = !state.dirty || state.saving;
+    const enabledOn = state.enabled.text === 'true';
+    return (_jsxs("li", { className: clsx(css.card, open && css.cardOpen), children: [_jsxs("button", { type: "button", className: css.header, "aria-expanded": open, "aria-label": `${t(open ? 'collapse' : 'expand')}: ${title}`, onClick: () => { setOpen(!open); }, children: [_jsxs("span", { className: css.headText, children: [_jsx("span", { className: css.name, children: title }), _jsx("span", { className: css.description, children: t('description') })] }), state.dirty ? _jsx("span", { className: css.pending, children: t('unsaved') }) : null, _jsx(IconChevronDownOutline14, { className: clsx(css.chevron, open && css.chevronOpen) })] }), open
+                ? (_jsxs("div", { className: css.body, children: [!state.writable ? _jsx("p", { className: css.readOnly, role: "status", children: t('readOnly') }) : null, _jsxs("div", { className: css.field, children: [_jsxs("div", { className: css.head, children: [_jsx("label", { className: css.label, children: t('enabled') }), state.enabled.overridden
+                                            ? (_jsxs("span", { className: css.badges, children: [_jsx("span", { className: css.badge, children: t('overridden') }), _jsx("button", { type: "button", className: css.reset, disabled: !state.writable, onClick: () => { props.resetField('enabled'); }, children: t('reset') })] }))
+                                            : null] }), _jsx("div", { className: css.toggleRow, children: _jsx("button", { type: "button", role: "switch", "aria-checked": enabledOn, className: clsx(css.toggle, enabledOn && css.toggleOn), disabled: !state.writable, onClick: () => { props.edit('enabled', enabledOn ? 'false' : 'true'); }, children: _jsx("span", { className: clsx(css.knob, enabledOn && css.knobOn) }) }) }), _jsx("p", { className: css.hint, children: t('enabledHint') })] }), _jsxs("div", { className: css.field, children: [_jsxs("div", { className: css.head, children: [_jsx("label", { className: css.label, children: t('contextText') }), state.contextText.overridden
+                                            ? (_jsxs("span", { className: css.badges, children: [_jsx("span", { className: css.badge, children: t('overridden') }), _jsx("button", { type: "button", className: css.reset, disabled: !state.writable, onClick: () => { props.resetField('contextText'); }, children: t('reset') })] }))
+                                            : null] }), _jsx("textarea", { id: "plugin-config-preface-context-text", className: css.textarea, value: state.contextText.text, placeholder: t('contextTextPlaceholder'), disabled: !state.writable, onChange: (event) => { props.edit('contextText', event.target.value); } }), _jsx("p", { className: css.hint, children: t('contextTextHint') })] }), _jsxs("div", { className: css.footer, children: [state.failed ? _jsx("p", { className: css.failed, role: "status", children: t('saveFailed') }) : null, _jsx("button", { type: "button", className: css.discard, disabled: !state.dirty || state.saving, onClick: props.discard, children: t('discard') }), _jsx("button", { type: "button", className: css.save, disabled: blocked, onClick: props.save, children: t(state.saving ? 'saving' : 'save') })] })] }))
+                : null] }));
+}

package/lib/types/config.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Config schema for the preface-context plugin (Schemastery, strict).
+ *
+ * The plugin-row config (the `entry` passed to `apply`) is the composition
+ * BASE of the `preface-context` settings namespace. The settings user layer
+ * is layered on top (schema defaults → base → user layer) when a settings
+ * service is mounted; without one, the entry is the sole source.
+ *
+ * @module @huanlin/dsh-plugin-preface-context/config
+ */
+/** User-editable configuration for the preface-context plugin. */
+export interface PrefaceConfig {
+    /** Master switch: when false, no context is injected at session start. */
+    enabled: boolean;
+    /** The text block injected as model-visible instructions context. */
+    contextText: string;
+}
+/**
+ * Schemastery schema for the `preface-context` settings namespace.
+ *
+ * Strict by construction: unknown keys fail validation here, even though the
+ * settings service itself is non-strict and would otherwise accept them.
+ */
+export declare const Config: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types").default<Schemastery.ObjectS<{
+    enabled: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types").default<boolean, boolean>;
+    contextText: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types").default<string, string>;
+}>, Schemastery.ObjectT<{
+    enabled: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types").default<boolean, boolean>;
+    contextText: import("C:/Users/Administrator/.dsh/source/current/vendor/schemastery/lib/types").default<string, string>;
+}>>;
+/**
+ * Resolve a raw config patch through the schema, returning a full
+ * {@link PrefaceConfig} with defaults applied. Unknown keys are rejected
+ * here (the settings service itself is non-strict and would otherwise accept
+ * them), matching the Loader's strict validation.
+ * @param input - a partial or complete config object.
+ * @returns the schema-resolved config.
+ * @throws when the input carries an unknown key or a value the schema rejects.
+ */
+export declare function resolvePrefaceConfig(input: Partial<PrefaceConfig>): PrefaceConfig;

package/lib/types/config.js

@@ -0,0 +1,42 @@
+/**
+ * Config schema for the preface-context plugin (Schemastery, strict).
+ *
+ * The plugin-row config (the `entry` passed to `apply`) is the composition
+ * BASE of the `preface-context` settings namespace. The settings user layer
+ * is layered on top (schema defaults → base → user layer) when a settings
+ * service is mounted; without one, the entry is the sole source.
+ *
+ * @module @huanlin/dsh-plugin-preface-context/config
+ */
+import z from 'schemastery';
+/**
+ * Schemastery schema for the `preface-context` settings namespace.
+ *
+ * Strict by construction: unknown keys fail validation here, even though the
+ * settings service itself is non-strict and would otherwise accept them.
+ */
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+    contextText: z.string().default(''),
+});
+/** Known config keys (for strict unknown-key rejection). */
+const CONFIG_KEYS = new Set(['enabled', 'contextText']);
+/**
+ * Resolve a raw config patch through the schema, returning a full
+ * {@link PrefaceConfig} with defaults applied. Unknown keys are rejected
+ * here (the settings service itself is non-strict and would otherwise accept
+ * them), matching the Loader's strict validation.
+ * @param input - a partial or complete config object.
+ * @returns the schema-resolved config.
+ * @throws when the input carries an unknown key or a value the schema rejects.
+ */
+export function resolvePrefaceConfig(input) {
+    if (input !== null && typeof input === 'object' && !Array.isArray(input)) {
+        for (const key of Object.keys(input)) {
+            if (!CONFIG_KEYS.has(key)) {
+                throw new Error(`preface-context: unknown config key "${key}"`);
+            }
+        }
+    }
+    return Config(input);
+}

package/lib/types/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * dsh-plugin-preface-context — injects a user-configured text block as
+ * model-visible instructions context at the start of every session.
+ *
+ * The plugin listens to `agent/session-start` and, when enabled and the
+ * context text is non-empty, calls `agent.inject()` with a plugin-sourced
+ * `user/message` carrying the text as a single text block. The message
+ * enters the session inbox and is claimed by the first `agent/pre-step`,
+ * reaching the model as instructions context closest to its first answer.
+ *
+ * The text and the enable switch are editable on the "插件配置" settings
+ * page: the host registers the `preface-context` settings namespace (the
+ * plugin-row config is the composition base), and the client half binds a
+ * card to that namespace through `ctx.settingsScope.bind()`. The runtime
+ * reads the LIVE composed value through the bridge source, so a settings
+ * edit takes effect on the next session start without a restart.
+ *
+ * @module @huanlin/dsh-plugin-preface-context
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import type { PrefaceConfig } from './config.ts';
+export declare const name = "dsh-plugin-preface-context";
+/** Services the plugin consumes; the row loads once all are available. */
+export declare const inject: string[];
+/** Loader schema (schemastery, strict) — validated by the cordis Loader. */
+export { Config } from './config.ts';
+export type { PrefaceConfig } from './config.ts';
+/**
+ * Build the user-message to inject for one session start.
+ *
+ * The message carries the context text as a single text block and is tagged
+ * `source.kind: 'plugin'` with `form: 'instructions'` so the model and UI
+ * can present it as workspace instructions rather than a user prompt.
+ * @param config - the live composed config.
+ * @returns the message to inject, or `undefined` when injection is disabled
+ *   or the text is empty/whitespace.
+ */
+export declare function buildPrefaceMessage(config: PrefaceConfig): ReturnType<typeof createUserMessage> | undefined;
+/**
+ * Plugin entry: install the settings bridge, then inject the preface text on
+ * every session start.
+ * @param ctx - the plugin's cordis context.
+ * @param config - the composition entry config (base layer of the settings namespace).
+ */
+export declare function apply(ctx: Context, config: PrefaceConfig): void;

package/lib/types/index.js

@@ -0,0 +1,64 @@
+/**
+ * dsh-plugin-preface-context — injects a user-configured text block as
+ * model-visible instructions context at the start of every session.
+ *
+ * The plugin listens to `agent/session-start` and, when enabled and the
+ * context text is non-empty, calls `agent.inject()` with a plugin-sourced
+ * `user/message` carrying the text as a single text block. The message
+ * enters the session inbox and is claimed by the first `agent/pre-step`,
+ * reaching the model as instructions context closest to its first answer.
+ *
+ * The text and the enable switch are editable on the "插件配置" settings
+ * page: the host registers the `preface-context` settings namespace (the
+ * plugin-row config is the composition base), and the client half binds a
+ * card to that namespace through `ctx.settingsScope.bind()`. The runtime
+ * reads the LIVE composed value through the bridge source, so a settings
+ * edit takes effect on the next session start without a restart.
+ *
+ * @module @huanlin/dsh-plugin-preface-context
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { installPrefaceSettings } from "./settings.js";
+export const name = 'dsh-plugin-preface-context';
+/** Services the plugin consumes; the row loads once all are available. */
+export const inject = ['agents', 'llm'];
+/** Loader schema (schemastery, strict) — validated by the cordis Loader. */
+export { Config } from "./config.js";
+/** Plugin source tag carried by every injected message. */
+const PLUGIN_SOURCE = { kind: 'plugin', plugin: 'dsh-plugin-preface-context', form: 'instructions' };
+/**
+ * Build the user-message to inject for one session start.
+ *
+ * The message carries the context text as a single text block and is tagged
+ * `source.kind: 'plugin'` with `form: 'instructions'` so the model and UI
+ * can present it as workspace instructions rather than a user prompt.
+ * @param config - the live composed config.
+ * @returns the message to inject, or `undefined` when injection is disabled
+ *   or the text is empty/whitespace.
+ */
+export function buildPrefaceMessage(config) {
+    if (!config.enabled)
+        return undefined;
+    const text = config.contextText.trim();
+    if (text === '')
+        return undefined;
+    return createUserMessage({
+        content: [{ type: 'text', text: config.contextText }],
+        source: PLUGIN_SOURCE,
+    });
+}
+/**
+ * Plugin entry: install the settings bridge, then inject the preface text on
+ * every session start.
+ * @param ctx - the plugin's cordis context.
+ * @param config - the composition entry config (base layer of the settings namespace).
+ */
+export function apply(ctx, config) {
+    const bridge = installPrefaceSettings(ctx, config);
+    ctx.on('agent/session-start', ({ agent }) => {
+        const message = buildPrefaceMessage(bridge.source());
+        if (message === undefined)
+            return;
+        agent.inject(message);
+    });
+}

package/lib/types/settings.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Host-side `preface-context` settings namespace + live source wiring.
+ *
+ * The plugin-row config (the `entry` passed to the plugin's `apply`) is the
+ * composition BASE of the `preface-context` settings namespace: when a dsh
+ * settings service is mounted, its user layer is layered on top (schema
+ * defaults → base → user layer) and the runtime reads the live resolved
+ * value through the bridge's `source` thunk. Without a settings service the
+ * conditional `ctx.inject(['settings'], ...)` child never activates and the
+ * source is exactly the entry: behavior identical to a no-settings build.
+ *
+ * The namespace reaches the web configuration boundary directly: the
+ * apiproxy `settings.mutate` / `settings.describe` RPCs accept any
+ * registered namespace (no allowlist gate in current upstream dsh), so the
+ * client card reads/writes through `ctx.settingsScope.bind({ namespace })`
+ * — no gateway channel is needed.
+ *
+ * @module @huanlin/dsh-plugin-preface-context/settings
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { PrefaceConfig } from './config.ts';
+/** The `preface-context` settings namespace (registered when a settings service exists). */
+export declare const PREFACE_SETTINGS_NAMESPACE = "preface-context";
+/**
+ * The live configuration source for the runtime.
+ *
+ * `source()` returns the composed config (schema defaults → plugin-row base
+ * → settings user layer). `onChange` registers a callback that fires at
+ * attach, on committed changes, and at detach back to the entry.
+ */
+export interface PrefaceSettingsBridge {
+    /** Read the currently authoritative config. */
+    source(): PrefaceConfig;
+    /** Register a change callback (fires at attach, on change, at detach). */
+    onChange(callback: () => void): void;
+}
+/**
+ * Install the `preface-context` settings namespace and wire the live source.
+ *
+ * Mirrors the dsh `installSettingsSection` pattern. The registration rides a
+ * conditional `ctx.inject(['settings'], ...)` child, so with no settings
+ * service the source stays the entry config. Multi-fiber dedupe: the host
+ * may compose several preface-context fibers, and `settings.register` fails
+ * loud on a duplicate namespace — the catch lets the first registration own
+ * the live namespace while later instances fall back to the entry source.
+ * @param ctx - consumer plugin context owning the wiring.
+ * @param entry - the composition entry config, used as `base`.
+ * @returns the bridge the runtime and gateway read through.
+ */
+export declare function installPrefaceSettings(ctx: Context, entry: PrefaceConfig): PrefaceSettingsBridge;