@khorsheed/dsh-context-guard 0.1.0

package/lib/types/client/CompactGuardButton.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { IconWarningOutline16 } from '@deepseek-ai/dsh-client-ui-primitives';
+import { guardReading } from './guard.js';
+import css from './CompactGuardButton.module.css';
+/**
+ * Composer-tool-row compact button. Renders nothing until the context
+ * occupancy (`projectedTokens / contextWindow` — the same number the
+ * composer's context ring shows) crosses the threshold; then it appears
+ * automatically in the amber warning tint. The threshold comes from the
+ * shared `context-guard` settings section (live), falling back to the
+ * composition-time value while the settings surface is absent. Clicking
+ * executes the official `/compact` command through the injected face.
+ */
+export function CompactGuardButton({ useProjection, useConfig, t, thresholdRatio, compactNow, }) {
+    const pressure = useProjection('contextPressure');
+    const config = useConfig(value => value);
+    const effective = config.status === 'ready' && config.value !== undefined
+        ? config.value
+        : { thresholdRatio };
+    const reading = useMemo(() => guardReading({
+        projectedTokens: pressure?.projectedTokens ?? pressure?.pressureTokens ?? Number.NaN,
+        contextWindow: pressure?.contextWindow,
+        thresholdRatio: effective.thresholdRatio,
+    }), [pressure, effective.thresholdRatio]);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const aliveRef = useRef(true);
+    useEffect(() => {
+        aliveRef.current = true;
+        return () => {
+            aliveRef.current = false;
+        };
+    }, []);
+    if (reading === null || reading.level === 'ok')
+        return null;
+    const run = () => {
+        setBusy(true);
+        setError(null);
+        void compactNow().then((failure) => {
+            if (!aliveRef.current)
+                return;
+            setBusy(false);
+            setError(failure);
+        }, (reason) => {
+            if (!aliveRef.current)
+                return;
+            setBusy(false);
+            setError(reason instanceof Error ? reason.message : String(reason));
+        });
+    };
+    return (_jsxs("span", { className: css.wrap, children: [_jsxs("button", { type: "button", className: `${css.button} ${css.warning}`, "aria-label": t('button.aria', { percent: String(reading.percent) }), disabled: busy, onClick: run, children: [_jsx("span", { className: css.icon, "aria-hidden": true, children: _jsx(IconWarningOutline16, { size: 14 }) }), t('button.label')] }), error !== null && (_jsx("span", { className: css.error, role: "status", title: error, children: t('button.error') }))] }));
+}

package/lib/types/client/SettingsCard.d.ts

@@ -0,0 +1,12 @@
+import type { ContextGuardSettingsCardProps } from './slots.ts';
+/**
+ * The context-guard settings card in the plugin configuration tab: the same
+ * collapsible chrome the official plugin cards use (a header naming the
+ * plugin and what its settings govern, disclosing the controls in place),
+ * re-implemented here because the client bundle-purity gate forbids
+ * value-importing the official card chrome. Two staged number fields write
+ * through the shared settingsScope on save; per-field reset reverts a field
+ * to the composition layer.
+ */
+export declare function ContextGuardSettingsCard({ useConfig, scope, t }: ContextGuardSettingsCardProps): import("react").JSX.Element | null;
+//# sourceMappingURL=SettingsCard.d.ts.map

package/lib/types/client/SettingsCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SettingsCard.d.ts","sourceRoot":"","sources":["../../../src/client/SettingsCard.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAA;AAuB/D;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,6BAA6B,sCAqI9F"}

package/lib/types/client/SettingsCard.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { IconChevronDownOutline14 } from '@deepseek-ai/dsh-client-ui-primitives';
+import css from './SettingsCard.module.css';
+/** Parse a draft into a number, or NaN when it is not one. */
+function parseNumber(text) {
+    const value = Number(text.trim());
+    return Number.isFinite(value) ? value : Number.NaN;
+}
+/** Whether the user layer carries a field (presence marks an override). */
+function overridden(snapshot, field) {
+    return snapshot.user !== undefined
+        && typeof snapshot.user === 'object'
+        && snapshot.user !== null
+        && field in snapshot.user;
+}
+/**
+ * The context-guard settings card in the plugin configuration tab: the same
+ * collapsible chrome the official plugin cards use (a header naming the
+ * plugin and what its settings govern, disclosing the controls in place),
+ * re-implemented here because the client bundle-purity gate forbids
+ * value-importing the official card chrome. Two staged number fields write
+ * through the shared settingsScope on save; per-field reset reverts a field
+ * to the composition layer.
+ */
+export function ContextGuardSettingsCard({ useConfig, scope, t }) {
+    const snapshot = useConfig(value => value);
+    const value = snapshot.status === 'ready' ? snapshot.value : undefined;
+    const [open, setOpen] = useState(false);
+    const [threshold, setThreshold] = useState({ text: '', invalid: false });
+    const [saved, setSaved] = useState(false);
+    const [error, setError] = useState(false);
+    const aliveRef = useRef(true);
+    /** The section revision the drafts were last seeded from; re-seed only on a committed change. */
+    const seededRevision = useRef(null);
+    // Re-seed the drafts whenever the section VALUE changes (first load, a save
+    // settling, an external reset). Keyed on the snapshot revision rather than
+    // the value's object identity: a save settling publishes a new snapshot
+    // (revision bump), while an unrelated re-render must not discard a draft in
+    // flight — the staged model promises the screen shows exactly what a save
+    // would store.
+    useEffect(() => {
+        aliveRef.current = true;
+        if (value === undefined)
+            return;
+        if (seededRevision.current === snapshot.revision)
+            return;
+        seededRevision.current = snapshot.revision ?? null;
+        setThreshold({ text: String(value.thresholdRatio), invalid: false });
+        setSaved(false);
+        setError(false);
+        return () => {
+            aliveRef.current = false;
+        };
+    }, [value, snapshot.revision]);
+    if (snapshot.status === 'unavailable')
+        return null;
+    const write = (draft, min, max) => {
+        const parsed = parseNumber(draft.text);
+        setThreshold({ text: draft.text, invalid: !Number.isFinite(parsed) || parsed < min || parsed > max });
+    };
+    const save = () => {
+        if (threshold.invalid || snapshot.writable !== true)
+            return;
+        const ratio = parseNumber(threshold.text);
+        if (!Number.isFinite(ratio))
+            return;
+        setError(false);
+        setSaved(false);
+        void scope.set('thresholdRatio', ratio).then(() => {
+            if (!aliveRef.current)
+                return;
+            setSaved(true);
+        }, () => {
+            if (!aliveRef.current)
+                return;
+            setError(true);
+        });
+    };
+    const reset = () => {
+        setError(false);
+        setSaved(false);
+        void scope.unset('thresholdRatio').catch(() => {
+            if (aliveRef.current)
+                setError(true);
+        });
+    };
+    const title = t('settings.title');
+    const dirty = threshold.text !== String(value?.thresholdRatio ?? '');
+    return (_jsxs("li", { className: open ? `${css.card} ${css.cardOpen}` : css.card, children: [_jsxs("button", { type: "button", className: css.header, "aria-expanded": open, "aria-label": `${t(open ? 'settings.collapse' : 'settings.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('settings.description') })] }), _jsx(IconChevronDownOutline14, { className: open ? `${css.chevron} ${css.chevronOpen}` : css.chevron })] }), open && value !== undefined && (_jsxs("div", { className: css.body, children: [_jsxs("label", { className: css.field, children: [_jsxs("span", { className: css.fieldHead, children: [_jsx("span", { className: css.fieldName, children: t('settings.field.threshold') }), overridden(snapshot, 'thresholdRatio') && _jsx("span", { className: css.badge, children: t('settings.overridden') })] }), _jsxs("span", { className: css.inputRow, children: [_jsx("input", { className: threshold.invalid ? `${css.input} ${css.inputInvalid}` : css.input, type: "number", step: "0.01", min: "0.01", max: "1", value: threshold.text, "aria-label": t('settings.field.threshold'), onChange: (event) => { write({ text: event.target.value, invalid: false }, 0.01, 1); } }), _jsx("button", { type: "button", className: css.reset, onClick: reset, children: t('settings.reset') })] }), _jsx("span", { className: css.hint, children: t('settings.field.threshold.hint') })] }), _jsxs("span", { className: css.footer, children: [_jsxs("span", { className: css.status, children: [saved ? _jsx("span", { className: css.saved, children: t('settings.saved') }) : null, error ? _jsx("span", { className: css.errorText, children: t('settings.error') }) : null] }), _jsx("button", { type: "button", className: css.secondary, disabled: !dirty, onClick: () => {
+                                    if (value === undefined)
+                                        return;
+                                    setThreshold({ text: String(value.thresholdRatio), invalid: false });
+                                    setSaved(false);
+                                    setError(false);
+                                }, children: t('settings.discard') }), _jsx("button", { type: "button", className: css.save, disabled: !dirty || threshold.invalid || snapshot.writable !== true, onClick: save, children: t('settings.save') })] })] }))] }));
+}

package/lib/types/client/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Browser-half configuration of the context-guard plugin. The runner hands
+ * the plugin its validated entry config through the apply second parameter;
+ * this module supplies the defaults and clamps, so a composition that does
+ * not pass config still renders with the documented values and out-of-range
+ * input lands inside the legal bounds.
+ *
+ * Once the settings surface is composed, these values arrive through the
+ * `context-guard` settings section instead: the composition entry becomes the
+ * section's base layer, and the settings card overrides it per field. The
+ * fallback path here only serves deployments without the settings surface.
+ */
+/**
+ * Deployment-tunable guard behavior.
+ *
+ * The guard is a reminder: when the context OCCUPANCY (the same
+ * `projectedTokens / contextWindow` number the composer's context ring shows)
+ * crosses `thresholdRatio`, the compact button appears. The official
+ * compaction engine auto-compacts at 80% of the window on its own; the real
+ * provider rejection wall is `window − maxTokens` (the request reserves
+ * output), so a request can fail before occupancy alone reaches 80% — set a
+ * lower threshold for an earlier reminder. The field tunes ONLY when the
+ * button appears; real compaction timing (compaction-basic's own config) is
+ * never affected.
+ */
+export interface ContextGuardConfig {
+    /**
+     * Context occupancy fraction at which the button appears (clamped to
+     * (0, 1]; default 0.8, matching compaction-basic's default pressure
+     * threshold).
+     */
+    thresholdRatio: number;
+}
+/**
+ * Normalize the entry config into the full {@link ContextGuardConfig}: every
+ * omitted field takes its documented default and every numeric field is
+ * clamped into its legal range.
+ * @param config - the unvalidated entry config, when the runner passes one.
+ * @returns the effective guard behavior.
+ */
+export declare function resolveConfig(config: Partial<ContextGuardConfig> | undefined): ContextGuardConfig;
+//# sourceMappingURL=config.d.ts.map

package/lib/types/client/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/client/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB;AAUD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,SAAS,GAAG,kBAAkB,CAQjG"}

package/lib/types/client/config.js

@@ -0,0 +1,30 @@
+/**
+ * Browser-half configuration of the context-guard plugin. The runner hands
+ * the plugin its validated entry config through the apply second parameter;
+ * this module supplies the defaults and clamps, so a composition that does
+ * not pass config still renders with the documented values and out-of-range
+ * input lands inside the legal bounds.
+ *
+ * Once the settings surface is composed, these values arrive through the
+ * `context-guard` settings section instead: the composition entry becomes the
+ * section's base layer, and the settings card overrides it per field. The
+ * fallback path here only serves deployments without the settings surface.
+ */
+/** Bounds of the deployment-tunable number (clamped in resolveConfig). */
+const THRESHOLD_RATIO_MIN = 0.01;
+const THRESHOLD_RATIO_MAX = 1;
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Normalize the entry config into the full {@link ContextGuardConfig}: every
+ * omitted field takes its documented default and every numeric field is
+ * clamped into its legal range.
+ * @param config - the unvalidated entry config, when the runner passes one.
+ * @returns the effective guard behavior.
+ */
+export function resolveConfig(config) {
+    return {
+        thresholdRatio: clamp(config?.thresholdRatio ?? 0.8, THRESHOLD_RATIO_MIN, THRESHOLD_RATIO_MAX),
+    };
+}

package/lib/types/client/guard.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure guard decision math: whether the next request's prompt-plus-output
+ * budget is about to overflow the model's context window, mirroring the
+ * provider-side rejection rule (`prompt + max_tokens > context_length`).
+ *
+ * The numerator rides the official `contextPressure` projection so it answers
+ * for the NEXT request rather than the last one: `projectedTokens` is the
+ * provider-reported prompt sample carried forward over the surface's signed
+ * movement since (compaction included), with the bare sample as the fallback
+ * for logs whose projection predates that field. The occupancy is the SAME
+ * number the composer's context ring shows — the guard is a reminder on top
+ * of that ring, not a second figure.
+ */
+/** The three guard states: nothing to show, about to overflow, already over. */
+export type GuardLevel = 'ok' | 'warning' | 'overdue';
+/** Inputs to the guard decision; both come from the session's contextPressure projection plus config. */
+export interface GuardInput {
+    /** Current projected context tokens (projectedTokens ?? pressureTokens). */
+    projectedTokens: number;
+    /** The routed model's advertised context window; absent until a route reports one. */
+    contextWindow: number | undefined;
+    /** The occupancy fraction at which the guard turns on (clamped (0, 1] by config). */
+    thresholdRatio: number;
+}
+/** One guard reading: the level plus the occupancy figure behind it. */
+export interface GuardReading {
+    level: GuardLevel;
+    /** `projectedTokens / contextWindow`, rounded, clamped to 0–100 — the same occupancy the context ring shows. */
+    percent: number;
+    /** The routed model's advertised context window. */
+    contextWindow: number;
+}
+/**
+ * Decide the guard level for one request budget.
+ *
+ * `overdue` means the occupancy already reached the whole window — the
+ * provider will have rejected requests before this point, so it is a
+ * defensive floor rather than a reachable state.
+ *
+ * @param input - the projection figures plus config.
+ * @returns the reading, or null when either the window or the context is unknown.
+ */
+export declare function guardReading(input: GuardInput): GuardReading | null;
+//# sourceMappingURL=guard.d.ts.map

package/lib/types/client/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../src/client/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,gFAAgF;AAChF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,SAAS,CAAA;AAErD,yGAAyG;AACzG,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,eAAe,EAAE,MAAM,CAAA;IACvB,sFAAsF;IACtF,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,qFAAqF;IACrF,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,CAAA;IACjB,gHAAgH;IAChH,OAAO,EAAE,MAAM,CAAA;IACf,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,GAAG,IAAI,CAiBnE"}

package/lib/types/client/guard.js

@@ -0,0 +1,42 @@
+/**
+ * Pure guard decision math: whether the next request's prompt-plus-output
+ * budget is about to overflow the model's context window, mirroring the
+ * provider-side rejection rule (`prompt + max_tokens > context_length`).
+ *
+ * The numerator rides the official `contextPressure` projection so it answers
+ * for the NEXT request rather than the last one: `projectedTokens` is the
+ * provider-reported prompt sample carried forward over the surface's signed
+ * movement since (compaction included), with the bare sample as the fallback
+ * for logs whose projection predates that field. The occupancy is the SAME
+ * number the composer's context ring shows — the guard is a reminder on top
+ * of that ring, not a second figure.
+ */
+/**
+ * Decide the guard level for one request budget.
+ *
+ * `overdue` means the occupancy already reached the whole window — the
+ * provider will have rejected requests before this point, so it is a
+ * defensive floor rather than a reachable state.
+ *
+ * @param input - the projection figures plus config.
+ * @returns the reading, or null when either the window or the context is unknown.
+ */
+export function guardReading(input) {
+    const { contextWindow, projectedTokens, thresholdRatio } = input;
+    if (contextWindow === undefined || !Number.isFinite(contextWindow) || contextWindow <= 0) {
+        return null;
+    }
+    if (!Number.isFinite(projectedTokens) || projectedTokens < 0)
+        return null;
+    const ratio = projectedTokens / contextWindow;
+    const level = ratio >= 1
+        ? 'overdue'
+        : ratio >= thresholdRatio
+            ? 'warning'
+            : 'ok';
+    return {
+        level,
+        percent: Math.min(100, Math.round(ratio * 100)),
+        contextWindow,
+    };
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Context-guard plugin, browser half: contributes one
+ * `conversation.input.right` entry — a compact button inside the composer's
+ * tool row that appears automatically when the next request's budget
+ * (`contextPressure.projectedTokens` + the output budget) crosses
+ * `thresholdRatio` of the routed model's context window — plus one
+ * `settings.plugin.item` card in the plugin configuration tab that edits the
+ * same two numbers live. The action rides the official `/compact` command
+ * channel (`remote.commands.execute` → host `ctx.commands` →
+ * `ctx.compaction.compactNow`); the config rides the official settings
+ * surface (host half registers the namespace, this half binds its
+ * `settingsScope`), so neither needs a new RPC or any edit to core packages;
+ * composing this plugin out of cordis.yml removes every surface it adds.
+ *
+ * Why this exists: the official auto-compaction fires at `agent/pre-step`
+ * when the meter's context estimate crosses 80% of the window — a check that
+ * excludes the request's own output budget and rides a heuristic that
+ * deliberately underprices CJK/JSON. A long request can therefore push
+ * context + maxTokens past the window while the estimate still sits below
+ * 80%, so the provider rejects the request (CONTEXT_WINDOW_EXCEEDED). The
+ * guard surfaces the danger while a manual compaction still fits — the
+ * summarization call reserves only its own small output cap, so it keeps
+ * running after the main request is rejected.
+ * @module @khorsheed/dsh-context-guard/client
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type ContextGuardConfig } from './config.ts';
+import { NS } from './locales.ts';
+export type { ContextGuardConfig } from './config.ts';
+export { resolveConfig } from './config.ts';
+export type { ContextGuardKey } from './locales.ts';
+export { guardReading } from './guard.ts';
+export type { GuardInput, GuardLevel, GuardReading } from './guard.ts';
+export type { CompactGuardButtonProps, ContextGuardInjected, ContextGuardSettingsCardInjected, ContextGuardSettingsCardProps, } from './slots.ts';
+/** Dictionary namespace owned by this plugin. */
+export { NS };
+/** Required services: the slot ledger, the command Remote, the settings scope, and the copy. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the composer-tool-row compact button and the
+ * settings card over the shared `context-guard` section.
+ * @param ctx - client root context.
+ * @param config - entry config (the section's composition base layer); defaults apply when the runner passes none.
+ */
+export declare function apply(ctx: ClientContext, config?: Partial<ContextGuardConfig>): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,EAAE,aAAa,EAAa,MAAM,wCAAwC,CAAA;AAiBtF,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAM,EAAE,EAAM,MAAM,cAAc,CAAA;AAKzC,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACtE,YAAY,EACV,uBAAuB,EAAE,oBAAoB,EAAE,gCAAgC,EAAE,6BAA6B,GAC/G,MAAM,YAAY,CAAA;AAEnB,iDAAiD;AACjD,OAAO,EAAE,EAAE,EAAE,CAAA;AAEb,gGAAgG;AAChG,eAAO,MAAM,MAAM,UAAoE,CAAA;AAEvF;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CA4CpF"}

package/lib/types/client/index.js

@@ -0,0 +1,61 @@
+import { CONTEXT_GUARD_NS } from '../namespace.js';
+import { resolveConfig } from './config.js';
+import { en, NS, zh } from './locales.js';
+import { CompactGuardButton } from './CompactGuardButton.js';
+import { ContextGuardSettingsCard } from './SettingsCard.js';
+export { resolveConfig } from './config.js';
+export { guardReading } from './guard.js';
+/** Dictionary namespace owned by this plugin. */
+export { NS };
+/** Required services: the slot ledger, the command Remote, the settings scope, and the copy. */
+export const inject = ['slots', 'remote', 'remote.commands', 'locale', 'settingsScope'];
+/**
+ * Client plugin body: register the composer-tool-row compact button and the
+ * settings card over the shared `context-guard` section.
+ * @param ctx - client root context.
+ * @param config - entry config (the section's composition base layer); defaults apply when the runner passes none.
+ */
+export function apply(ctx, config) {
+    const fallback = resolveConfig(config);
+    ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'context-guard: dictionaries');
+    // One shared live section: the settings card writes it, the button reads
+    // it. While the settings surface is absent, the button falls back to the
+    // composition-time values above.
+    const scope = ctx.settingsScope.bind({ namespace: CONTEXT_GUARD_NS });
+    // The slot is declared by ui-conversation, whose apply order relative to
+    // this plugin is unconstrained: register through slots.inject so the entry
+    // waits for the declaration instead of crashing the loader at boot.
+    ctx.slots.inject('conversation.input.right', () => ctx.slots.register({
+        name: 'conversation.input.right',
+        id: 'context-guard',
+        // Sit before the primary send button; the seat currently has no other
+        // occupants, and a leading position keeps the danger visible.
+        order: -10,
+        locale: NS,
+        inject: (sessionId) => ({
+            thresholdRatio: fallback.thresholdRatio,
+            // Failure strings stay English (error-surface policy: not localized).
+            compactNow: async () => {
+                const result = await ctx.remote.commands.execute(sessionId, '/compact', []);
+                if (!result.ok)
+                    return `${result.error.message} (${result.error.code})`;
+                if (result.value === undefined)
+                    return 'unknown command: /compact';
+                return null;
+            },
+            hooks: { config: scope },
+        }),
+    }, CompactGuardButton));
+    // The plugin configuration tab keys its cards on the settings namespace, so
+    // the compact-timing card registers under CONTEXT_GUARD_NS and renders
+    // wherever the tab dispatches that key.
+    ctx.slots.inject('settings.plugin.item', () => ctx.slots.register({
+        name: 'settings.plugin.item',
+        key: CONTEXT_GUARD_NS,
+        locale: NS,
+        inject: () => ({
+            scope,
+            hooks: { config: scope },
+        }),
+    }, ContextGuardSettingsCard));
+}

package/lib/types/client/locales.d.ts

@@ -0,0 +1,48 @@
+/** `context-guard` namespace dictionaries. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'button.label': string;
+    'button.aria': string;
+    'button.error': string;
+    'settings.title': string;
+    'settings.description': string;
+    'settings.expand': string;
+    'settings.collapse': string;
+    'settings.field.threshold': string;
+    'settings.field.threshold.hint': string;
+    'settings.overridden': string;
+    'settings.reset': string;
+    'settings.save': string;
+    'settings.discard': string;
+    'settings.saved': string;
+    'settings.error': string;
+};
+/** The context-guard namespace key union. */
+export type ContextGuardKey = keyof typeof zh;
+/** The dictionary namespace owned by this plugin. */
+export declare const NS = "context-guard";
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The context-guard compact button's copy. */
+        'context-guard': ContextGuardKey;
+    }
+}
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'button.label': string;
+    'button.aria': string;
+    'button.error': string;
+    'settings.title': string;
+    'settings.description': string;
+    'settings.expand': string;
+    'settings.collapse': string;
+    'settings.field.threshold': string;
+    'settings.field.threshold.hint': string;
+    'settings.overridden': string;
+    'settings.reset': string;
+    'settings.save': string;
+    'settings.discard': string;
+    'settings.saved': string;
+    'settings.error': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/locales.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locales.d.ts","sourceRoot":"","sources":["../../../src/client/locales.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAE9C,mEAAmE;AACnE,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;CAgBmB,CAAA;AAElC,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,EAAE,CAAA;AAE7C,qDAAqD;AACrD,eAAO,MAAM,EAAE,kBAAkB,CAAA;AAEjC,OAAO,QAAQ,kCAAkC,CAAC;IAChD,UAAU,kBAAkB;QAC1B,+CAA+C;QAC/C,eAAe,EAAE,eAAe,CAAA;KACjC;CACF;AAED,mEAAmE;AACnE,eAAO,MAAM,EAAE;;;;;;;;;;;;;;;;CAgBmB,CAAA"}

package/lib/types/client/locales.js

@@ -0,0 +1,39 @@
+/** `context-guard` namespace dictionaries. */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export const zh = {
+    'button.label': '压缩',
+    'button.aria': '上下文已用 {percent}%，点击压缩历史',
+    'button.error': '压缩未执行',
+    'settings.title': '压缩提醒时机',
+    'settings.description': '上下文占用达到设定比例时，输入框出现压缩按钮',
+    'settings.expand': '展开',
+    'settings.collapse': '收起',
+    'settings.field.threshold': '提醒比例',
+    'settings.field.threshold.hint': '上下文占用达到窗口的该比例时显示压缩按钮；可配置范围 0.01–1，按自己的偏好调整即可',
+    'settings.overridden': '已自定义',
+    'settings.reset': '重置',
+    'settings.save': '保存',
+    'settings.discard': '放弃',
+    'settings.saved': '已保存',
+    'settings.error': '保存失败，请重试',
+};
+/** The dictionary namespace owned by this plugin. */
+export const NS = 'context-guard';
+/** English dictionary, checked complete against the zh key set. */
+export const en = {
+    'button.label': 'compact',
+    'button.aria': 'Context at {percent}%, click to compact history',
+    'button.error': 'Compaction was not executed',
+    'settings.title': 'Compaction reminder timing',
+    'settings.description': 'Shows the compact button in the composer once context occupancy reaches the configured fraction',
+    'settings.expand': 'Expand',
+    'settings.collapse': 'Collapse',
+    'settings.field.threshold': 'Reminder ratio',
+    'settings.field.threshold.hint': 'Show the compact button once context occupancy reaches this fraction of the window; configurable from 0.01 to 1 — tune it to your preference',
+    'settings.overridden': 'Overridden',
+    'settings.reset': 'Reset',
+    'settings.save': 'Save',
+    'settings.discard': 'Discard',
+    'settings.saved': 'Saved',
+    'settings.error': 'Save failed, please retry',
+};

package/lib/types/client/slots.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Slot-facing types of the context-guard client half: the injected faces of
+ * the composer-tool-row compact button and the settings card, both carrying
+ * the shared `context-guard` settings scope as a hooks source so the button
+ * and the card react to the same live section.
+ */
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import type { ContextGuardConfig } from './config.ts';
+/** Injected action face of the composer-tool-row entry. */
+export interface ContextGuardInjected {
+    /** Resolved context-occupancy fraction at which the guard turns on; the boot-time fallback. */
+    thresholdRatio: number;
+    /**
+     * Run the official `/compact` command against this session's agent —
+     * the same command the user would type, so the host owns the lifecycle
+     * (idle-gating, the compaction lock, and the flow node presentation).
+     * @returns null on admitted execution; a user-visible failure line otherwise.
+     */
+    compactNow: () => Promise<string | null>;
+    hooks: {
+        /** The shared `context-guard` settings section; the button binds `useConfig` to it. */
+        config: SettingsScope<ContextGuardConfig>;
+    };
+}
+/** Full props of the composer-tool-row compact entry. */
+export type CompactGuardButtonProps = PropsRuntime<'conversation.input.right'> & InjectFace<ContextGuardInjected> & PropsLocale<'context-guard'>;
+/** Injected face of the settings card: the same shared section, read and written here. */
+export interface ContextGuardSettingsCardInjected {
+    /** The live section handle; the card stages edits and writes through it on save. */
+    scope: SettingsScope<ContextGuardConfig>;
+    hooks: {
+        /** The shared `context-guard` settings section; the card binds `useConfig` to it. */
+        config: SettingsScope<ContextGuardConfig>;
+    };
+}
+/** Full props of the settings.plugin.item card entry. */
+export type ContextGuardSettingsCardProps = PropsRuntime<'settings.plugin.item'> & InjectFace<ContextGuardSettingsCardInjected> & PropsLocale<'context-guard'>;
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/slots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slots.d.ts","sourceRoot":"","sources":["../../../src/client/slots.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAC7F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAA;AAS3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErD,2DAA2D;AAC3D,MAAM,WAAW,oBAAoB;IACnC,+FAA+F;IAC/F,cAAc,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,KAAK,EAAE;QACL,uFAAuF;QACvF,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;KAC1C,CAAA;CACF;AAED,yDAAyD;AACzD,MAAM,MAAM,uBAAuB,GACjC,YAAY,CAAC,0BAA0B,CAAC,GACtC,UAAU,CAAC,oBAAoB,CAAC,GAChC,WAAW,CAAC,eAAe,CAAC,CAAA;AAEhC,0FAA0F;AAC1F,MAAM,WAAW,gCAAgC;IAC/C,oFAAoF;IACpF,KAAK,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;IACxC,KAAK,EAAE;QACL,qFAAqF;QACrF,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAA;KAC1C,CAAA;CACF;AAED,yDAAyD;AACzD,MAAM,MAAM,6BAA6B,GACvC,YAAY,CAAC,sBAAsB,CAAC,GAClC,UAAU,CAAC,gCAAgC,CAAC,GAC5C,WAAW,CAAC,eAAe,CAAC,CAAA"}

package/lib/types/client/slots.js

@@ -0,0 +1 @@
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Context-guard plugin, node half. Registers the `context-guard` settings
+ * namespace so the web settings page can render the compact-timing card and
+ * the browser half can bind its `settingsScope` to the same section. The
+ * plugin's own runtime behavior is purely client-side (the composer compact
+ * button); this registration only exists to make the two tunables
+ * (`thresholdRatio`, `maxTokens`) editable from the GUI instead of YAML.
+ * @module @khorsheed/dsh-context-guard
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { CONTEXT_GUARD_NS } from './namespace.ts';
+export { ContextGuardSettingsSchema } from './settings.ts';
+/**
+ * Register the compact-timing section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ * @param config - the plugin's composition entry, used as the section's base layer.
+ */
+export declare function apply(ctx: Context, config?: Record<string, unknown>): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA;AAE1D;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI,CAQ9E"}

package/lib/types/index.js

@@ -0,0 +1,24 @@
+/**
+ * Context-guard plugin, node half. Registers the `context-guard` settings
+ * namespace so the web settings page can render the compact-timing card and
+ * the browser half can bind its `settingsScope` to the same section. The
+ * plugin's own runtime behavior is purely client-side (the composer compact
+ * button); this registration only exists to make the two tunables
+ * (`thresholdRatio`, `maxTokens`) editable from the GUI instead of YAML.
+ * @module @khorsheed/dsh-context-guard
+ */
+import { settingsNamespace } from '@deepseek-ai/dsh-settings';
+import { CONTEXT_GUARD_NS } from './namespace.js';
+import { ContextGuardSettingsSchema } from './settings.js';
+export { CONTEXT_GUARD_NS } from './namespace.js';
+export { ContextGuardSettingsSchema } from './settings.js';
+/**
+ * Register the compact-timing section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ * @param config - the plugin's composition entry, used as the section's base layer.
+ */
+export function apply(ctx, config = {}) {
+    ctx.inject(['settings'], (settingsCtx) => {
+        settingsCtx.settings.register(settingsNamespace(CONTEXT_GUARD_NS), ContextGuardSettingsSchema, { base: config });
+    });
+}