@maci0/dsh-ponytail 0.0.0-stage → 0.18.3

package/lib/modes.js

@@ -0,0 +1,158 @@
+/**
+ * Ponytail's level model: the accepted levels, their normalization, the
+ * mode-specific filter over the `ponytail` skill body, and the instruction
+ * block the plugin injects into the system prompt.
+ *
+ * Ported from the reference implementation's `hooks/ponytail-config.js` and
+ * `hooks/ponytail-instructions.js` (MIT, © DietrichGebert) so the DSH port
+ * speaks the same lite/full/ultra/review vocabulary and filters the same rows.
+ * The one addition is `resolveDefaultMode`'s `configured` source, which lets a
+ * deployment set the default from this plugin's own config field.
+ *
+ * @module dsh-ponytail/modes
+ */
+/** Levels that change the always-on ruleset and may be persisted as a default. */
+export const RUNTIME_MODES = ['off', 'lite', 'full', 'ultra'];
+/** Every accepted level; `review` is session-only and never a valid default. */
+export const VALID_MODES = ['off', 'lite', 'full', 'ultra', 'review'];
+/** Level used when neither config nor environment sets one. */
+export const DEFAULT_MODE = 'full';
+/**
+ * Normalize a value to one of `values`, case- and whitespace-insensitively.
+ * @param values - the accepted levels.
+ * @param value - candidate level from a config field or a command.
+ * @returns the canonical level, or `undefined` when unrecognized.
+ */
+function normalize(values, value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    return values.find((mode) => mode === normalized);
+}
+/** Normalize a value to a level that may be persisted as a default. */
+export function normalizeMode(value) {
+    return normalize(RUNTIME_MODES, value);
+}
+/** Normalize a value to any accepted level, including the session-only `review`. */
+export function normalizeCommandMode(value) {
+    return normalize(VALID_MODES, value);
+}
+/**
+ * Whether a whole message is a deactivation command.
+ *
+ * "stop ponytail" / "normal mode" turn ponytail off, but only as a standalone
+ * command: matching the phrase anywhere in a message turned it off mid-task for
+ * ordinary requests like "add a normal mode toggle", so the whole trimmed
+ * message must be the command, ignoring case and trailing punctuation.
+ * @param text - user message text.
+ * @returns whether the message is the deactivation command.
+ */
+export function isDeactivationCommand(text) {
+    const normalized = String(text ?? '').trim().toLowerCase().replace(/[.!?\s]+$/, '');
+    return normalized === 'stop ponytail' || normalized === 'normal mode';
+}
+/**
+ * Resolve the level a fresh process starts in.
+ *
+ * Only runtime levels count, so a stray `review` can never become the default.
+ * @param configured - the row's `defaultMode` field, when the row carries one.
+ * @returns the resolved startup level.
+ */
+export function resolveDefaultMode(configured) {
+    return normalizeMode(configured) ?? DEFAULT_MODE;
+}
+/** The two mode-keyed line shapes, hoisted so the filter does not recompile them. */
+const TABLE_LABEL = /^\|\s*\*\*(.+?)\*\*\s*\|/;
+const EXAMPLE_LABEL = /^-\s*([^:]+):\s*"/;
+/** Opening or closing marker of a fenced code block, with its run of backticks or tildes. */
+const FENCE = /^\s*(`{3,}|~{3,})/;
+/**
+ * Mark every line that belongs to a fenced code block.
+ *
+ * Fenced text is literal, so a mode-shaped line inside it is an example of the
+ * syntax, not a ruleset row: the filter must leave it alone. Fences nest by
+ * length, so a run closes only on the same character with an equal or longer
+ * run; an unterminated fence runs to the end of the body, as CommonMark reads
+ * it.
+ * @param lines - the body, split into lines.
+ * @returns one flag per line, `true` inside a fence.
+ */
+function fencedLines(lines) {
+    const inside = lines.map(() => false);
+    let open;
+    for (let index = 0; index < lines.length; index += 1) {
+        const marker = FENCE.exec(lines[index] ?? '')?.[1];
+        if (marker === undefined) {
+            inside[index] = open !== undefined;
+            continue;
+        }
+        // A marker that matches the opening run closes it; a shorter or
+        // differently-charactered one is content inside the open fence.
+        if (open === undefined)
+            open = marker;
+        else if (marker[0] === open[0] && marker.length >= open.length)
+            open = undefined;
+        inside[index] = true;
+    }
+    return inside;
+}
+/**
+ * Drop the intensity-table rows and worked examples that belong to other
+ * levels.
+ *
+ * Only the intensity table rows and worked examples are mode-specific, and both
+ * are keyed by a level name. A bullet whose label is not a level (e.g.
+ * "No unrequested abstractions: ...") is a normal rule and stays verbatim; the
+ * quoted-value requirement on examples is what keeps a rule that merely starts
+ * with a level word from being dropped in every other mode. A fenced code block
+ * is literal text, so nothing in it is dropped either.
+ * @param body - markdown of the `ponytail` skill, frontmatter already removed.
+ * @param mode - the level to keep.
+ * @returns the body with other levels' rows and examples removed.
+ */
+export function filterSkillBodyForMode(body, mode) {
+    const effective = normalizeMode(mode) ?? DEFAULT_MODE;
+    const lines = String(body ?? '').split(/\r?\n/);
+    const fenced = fencedLines(lines);
+    return lines
+        .filter((line, index) => {
+        if (fenced[index] === true)
+            return true;
+        // Both labels start their line, so one character rules out the common
+        // prose line before either regex runs. Same rows, same output.
+        const head = line.charCodeAt(0);
+        if (head !== 0x7c && head !== 0x2d)
+            return true;
+        const tableLabel = TABLE_LABEL.exec(line);
+        if (tableLabel?.[1] !== undefined) {
+            const labelMode = normalizeMode(tableLabel[1].trim());
+            if (labelMode !== undefined)
+                return labelMode === effective;
+        }
+        const exampleLabel = EXAMPLE_LABEL.exec(line);
+        if (exampleLabel?.[1] !== undefined) {
+            const labelMode = normalizeMode(exampleLabel[1].trim());
+            if (labelMode !== undefined)
+                return labelMode === effective;
+        }
+        return true;
+    })
+        .join('\n');
+}
+/**
+ * Build the exact text the system prompt carries for one level.
+ * @param input - the active level and the skill body.
+ * @returns the instruction block, or `''` when the level is `off`.
+ */
+export function buildModeInstructions(input) {
+    const { mode } = input;
+    if (mode === 'off')
+        return '';
+    if (mode === 'review') {
+        return ('PONYTAIL MODE ACTIVE — level: review. Behavior defined by the `ponytail-review`' +
+            ' skill; load it with the skill tool.');
+    }
+    const effective = normalizeMode(mode) ?? DEFAULT_MODE;
+    return 'PONYTAIL MODE ACTIVE — level: ' + effective + '\n\n' +
+        filterSkillBodyForMode(input.skillBody, effective);
+}

package/lib/skills.js

@@ -0,0 +1,209 @@
+/**
+ * The bundled ponytail skills as a `ctx.skills` provider.
+ *
+ * Skills are read from this package's `skills/<name>/SKILL.md`, so the same
+ * files stay the single source of truth for both the always-on ruleset (which
+ * filters the `ponytail` body per level) and the on-demand skills.
+ *
+ * @module dsh-ponytail/skills
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { BUNDLED_SKILL_RANK, isSkillName, } from '@deepseek-ai/dsh-skill';
+import { parseFrontmatter } from './frontmatter.js';
+/** Provider name inside the skill registry. */
+const PROVIDER_NAME = 'ponytail';
+/** Instruction file every skill directory must carry. */
+const INSTRUCTION_FILE = 'SKILL.md';
+/**
+ * Frontmatter keys that project onto a summary field rather than provider
+ * metadata. `disable-model-invocation`/`user-invocable` resolve into
+ * `invocation`, so they never ride along as provider-specific keys.
+ */
+const INVOCATION_KEYS = new Set([
+    'name',
+    'description',
+    'whenToUse',
+    'disable-model-invocation',
+    'user-invocable',
+]);
+/**
+ * Read one frontmatter value as a trimmed string.
+ * @param value - YAML-parsed value, of any shape.
+ * @returns the trimmed string, or `undefined` when the value is missing or a collection.
+ */
+function scalar(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    return undefined;
+}
+/**
+ * Read and parse one skill file. Shared by discovery and direct loads so a
+ * single file enforces the name/description/frontmatter rules everywhere.
+ * @param path - absolute path of the `SKILL.md` file.
+ * @param entryName - directory name fallback when frontmatter omits `name`.
+ * @param onWarn - optional non-fatal problem sink.
+ * @returns the parsed skill, or `undefined` with a warning when invalid.
+ */
+async function readSkillFile(path, onWarn, entryName) {
+    let source;
+    try {
+        source = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        // A directory without an instruction file is a broken skill, not an empty
+        // one: `discoverSkills` promises this reaches the same sink as every other
+        // skipped skill, so the install can say why a skill is missing.
+        onWarn?.(`cannot read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    // `parseFrontmatter` surfaces a malformed block as empty data, never a throw.
+    const parsed = await parseFrontmatter(source);
+    const fallback = entryName ?? basename(path);
+    const name = scalar(parsed.data['name']) ?? fallback;
+    const description = scalar(parsed.data['description']) ?? '';
+    const whenToUse = scalar(parsed.data['whenToUse']);
+    if (!isSkillName(name)) {
+        onWarn?.(`skipping ${path}: "${name}" is not a valid kebab-case skill name`);
+        return undefined;
+    }
+    if (description === '') {
+        onWarn?.(`skipping ${path}: frontmatter has no description`);
+        return undefined;
+    }
+    const metadata = {};
+    for (const [key, value] of Object.entries(parsed.data)) {
+        if (INVOCATION_KEYS.has(key))
+            continue;
+        metadata[key] = value;
+    }
+    return {
+        name,
+        ...(whenToUse === undefined ? {} : { whenToUse }),
+        description,
+        // Only the literal `true` disables the model surface and only the literal
+        // `false` disables the human one: an absent or malformed flag keeps the
+        // permissive default, so a typo advertises a skill instead of hiding it.
+        invocation: {
+            modelInvocable: parsed.data['disable-model-invocation'] !== true,
+            userInvocable: parsed.data['user-invocable'] !== false,
+        },
+        content: parsed.body.trim(),
+        metadata,
+        path,
+        directory: dirname(path),
+    };
+}
+/**
+ * Read every valid skill directory under `skillsDir`.
+ *
+ * A missing directory, a directory without `SKILL.md`, a file with unreadable
+ * frontmatter, and a file with a missing description are reported through
+ * `onWarn` and skipped: one broken file must not cost the catalog its other
+ * skills.
+ * @param skillsDir - directory holding one subdirectory per skill.
+ * @param onWarn - optional non-fatal problem sink.
+ * @returns the parsed skills, sorted by name.
+ */
+export async function discoverSkills(skillsDir, onWarn) {
+    let entries;
+    try {
+        entries = await readdir(skillsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        onWarn?.(`cannot read skills directory ${skillsDir}: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const path = join(skillsDir, entry.name, INSTRUCTION_FILE);
+        const skill = await readSkillFile(path, onWarn, entry.name);
+        if (skill !== undefined)
+            skills.push(skill);
+    }
+    return skills.sort((left, right) => left.name.localeCompare(right.name));
+}
+/**
+ * Build the provider the skill registry mounts.
+ * @param options - skills directory and the non-fatal problem sink.
+ * @returns a provider whose candidates are summaries and whose bodies come from disk.
+ */
+export function createSkillProvider(options) {
+    const summaryOf = (skill) => ({
+        path: skill.path,
+        name: skill.name,
+        description: skill.description,
+        ...(skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse }),
+        invocation: skill.invocation,
+        source: 'bundled',
+        provider: PROVIDER_NAME,
+        resourceBase: { kind: 'directory', path: skill.directory },
+    });
+    /**
+     * Discovery result per skills directory, keyed by directory.
+     *
+     * A packaged `skills/` tree is immutable in place, so a discovery that
+     * completed has nothing that could invalidate it: the entry is bounded by the
+     * number of directories this provider was built for, which is one. A call
+     * that was aborted is never stored, so it keeps re-reading the tree.
+     */
+    const catalogs = new Map();
+    const discoverOnce = (signal) => {
+        const cached = catalogs.get(options.skillsDir);
+        if (cached !== undefined)
+            return cached;
+        let complete = true;
+        const pending = discoverSkills(options.skillsDir, (message) => {
+            complete = false;
+            options.onWarn?.(message);
+        }).then((skills) => ({ skills, complete }));
+        // Store after the read settles, and only while the caller still wants it:
+        // an aborted call must read the tree on its next attempt.
+        pending.then(({ complete }) => { if (complete && signal?.aborted !== true)
+            catalogs.set(options.skillsDir, pending); }, () => { });
+        return pending;
+    };
+    return {
+        name: PROVIDER_NAME,
+        // The packaged skills are immutable in place, so there is nothing to
+        // invalidate and no watcher to own. `list`/`get` honor the caller's abort
+        // signal only at their own await boundaries: a caller that aborts mid-read
+        // gets no candidates rather than a later answer it stopped waiting for.
+        async list(lookup = {}) {
+            if (lookup.signal?.aborted)
+                return [];
+            const { skills, complete } = await discoverOnce(lookup.signal);
+            if (lookup.signal?.aborted)
+                return [];
+            const candidates = skills.map((skill) => ({
+                ...summaryOf(skill),
+                rank: BUNDLED_SKILL_RANK,
+                locator: skill.path,
+                metadata: skill.metadata,
+            }));
+            return complete ? candidates : { candidates, complete: false };
+        },
+        async get(candidate, lookup = {}) {
+            if (typeof candidate.locator !== 'string')
+                return undefined;
+            if (lookup.signal?.aborted)
+                return undefined;
+            // Read the locator directly: one file instead of a full re-discovery.
+            // The directory name is the same fallback discovery used, so a skill
+            // whose frontmatter omits `name` loads under the name `list` reported.
+            // The name check keeps a stale candidate (path reused by another skill)
+            // from loading under the wrong identity.
+            const skill = await readSkillFile(candidate.locator, options.onWarn, basename(dirname(candidate.locator)));
+            if (lookup.signal?.aborted)
+                return undefined;
+            if (skill === undefined || skill.name !== candidate.name)
+                return undefined;
+            return { ...summaryOf(skill), content: skill.content, metadata: skill.metadata };
+        },
+    };
+}

package/lib/types/frontmatter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * YAML-frontmatter reader for the bundled `SKILL.md` files.
+ *
+ * A frontmatter block is dominated by one shape: a flat mapping of
+ * `key: value` entries carrying plain, quoted, or block scalars. This module
+ * reads that shape by hand, because the alternative (handing every block to
+ * `yaml`) pulls the whole parser into the boot path of the plugin, where it is
+ * the single largest cost of mounting. Anything the reader cannot prove it
+ * would transcribe exactly is handed to `yaml`, the same parser the upstream
+ * filesystem provider uses, through a dynamic `import`, so this reader accepts
+ * exactly what the registry accepts and the parser is loaded only by a document
+ * that actually needs it: plain scalars, quoted scalars, folded (`>`, `>-`) and
+ * literal (`|`, `|-`) block scalars, and nested maps. A missing or malformed
+ * block yields no keys and leaves the whole source as the body rather than
+ * throwing: `discoverSkills` reports the consequence (no description) and
+ * keeps every other skill.
+ *
+ * @module dsh-ponytail/frontmatter
+ */
+/** Parsed frontmatter plus the markdown body that follows it. */
+interface Frontmatter {
+    readonly data: Readonly<Record<string, unknown>>;
+    /** Everything after the closing delimiter, or the whole source when absent. */
+    readonly body: string;
+}
+/**
+ * Split a document into its frontmatter block and the body that follows it.
+ *
+ * Pure text, no parsing: the body is the same either way, so a caller that
+ * needs only the body (the always-on ruleset, read once at mount) never
+ * touches a parser at all.
+ * @param source - full file contents.
+ * @returns the block's lines and the remaining body.
+ */
+export declare function splitFrontmatter(source: string): {
+    readonly block: string;
+    readonly body: string;
+};
+/**
+ * Parse leading YAML frontmatter from a markdown document.
+ * @param source - full file contents.
+ * @returns the parsed keys and the remaining body.
+ */
+export declare function parseFrontmatter(source: string): Promise<Frontmatter>;
+export {};

package/lib/types/host.d.ts

@@ -0,0 +1,159 @@
+/**
+ * The slice of the DeepSeek Harness host surface this plugin uses, declared
+ * structurally.
+ *
+ * These interfaces describe the exact contracts the plugin calls; the host
+ * types remain authoritative, and every service is reached through
+ * `ctx.inject([...])`, so a composition that does not mount one simply omits
+ * that capability.
+ *
+ * @module dsh-ponytail/host
+ */
+import type { SkillCandidate, SkillDefinition, SkillLookupOptions, SkillProvider, SkillProviderObservation } from '@deepseek-ai/dsh-skill';
+import type { ToolDefinition } from '@deepseek-ai/dsh-tools';
+/** Disposer returned by every host registration. */
+type Disposable = () => void;
+/** One contributed system-prompt section. */
+export interface PromptSectionContribution {
+    /** Unique section name across the composition. */
+    readonly name: string;
+    /** Ascending concatenation position. */
+    readonly order: number;
+    /** Static text, or a provider evaluated at each assembly (empty text is dropped). */
+    readonly text: string | ((context: unknown) => string);
+}
+/**
+ * A {@link SkillProvider} whose lookup may be omitted by direct callers.
+ */
+export type SkillProviderLike = Omit<SkillProvider, 'list' | 'get'> & {
+    list(options?: SkillLookupOptions): Promise<readonly SkillCandidate[] | SkillProviderObservation>;
+    get(candidate: SkillCandidate, options?: SkillLookupOptions): Promise<SkillDefinition | undefined>;
+};
+/** Invocation handed to a registered human command. */
+export interface CommandInvocationLike {
+    /** Text following the command name, including separator whitespace. */
+    readonly rawInput: string;
+}
+/** Direct-UI outcome of a human command. */
+export type CommandResultLike = {
+    readonly kind: 'success';
+    readonly text?: string;
+} | {
+    readonly kind: 'error';
+    readonly text: string;
+};
+/** A plugin-owned human command. */
+export interface CommandDefinitionLike {
+    /** Lowercase command name without the leading slash. */
+    readonly name: string;
+    /** Summary used in discovery UI. */
+    readonly description: string;
+    /** Optional free-form input hint. */
+    readonly input?: {
+        readonly hint: string;
+    };
+    /** Execute against the receiving agent without a model message. */
+    handler(invocation: CommandInvocationLike): CommandResultLike | Promise<CommandResultLike>;
+}
+/**
+ * The slice of a durable session message the deactivation watcher reads.
+ *
+ * `source.kind === 'user'` is what separates the human's own words from the
+ * context the harness injects into the same event stream (skill bodies,
+ * references, replayed history).
+ */
+export interface SessionMessageLike {
+    /** Content blocks; only `text` blocks carry words. */
+    readonly content?: readonly {
+        readonly type?: string;
+        readonly text?: string;
+    }[] | undefined;
+    /** Provenance of the message. */
+    readonly source?: {
+        readonly kind?: string;
+    } | undefined;
+}
+/** One durable session event, as `session/event` delivers it. */
+export interface SessionEventLike {
+    /** Event discriminator, e.g. `user/message`. */
+    readonly type?: string;
+    /** Event payload; a {@link SessionMessageLike} for `user/message`. */
+    readonly data?: unknown;
+}
+/**
+ * Structural view of the Cordis context the plugin uses.
+ *
+ * Members are only reached inside the matching `inject` callback, where the
+ * host guarantees the service is present, or through {@link HostContext.get}
+ * at the use site.
+ */
+export interface HostContext {
+    /** Run `callback` once the named services are available; the return is a fiber. */
+    inject(dependencies: readonly string[], callback: (scope: HostContext) => void): unknown;
+    /** Bind a registration's disposer to the calling fiber. */
+    effect(callback: () => Disposable, label?: string): unknown;
+    /** Query a mounted service, or `undefined` while none is mounted. */
+    get(service: string): unknown;
+    /** Subscribe to a host event; the returned disposer removes the listener. */
+    on(event: 'session/event', listener: (session: unknown, event: SessionEventLike) => void): Disposable;
+    on(event: 'loader/volatile-update', listener: () => void): Disposable;
+    /** Owning fiber, present once the loader mounted this plugin. */
+    readonly fiber?: {
+        readonly entry?: {
+            readonly options?: {
+                readonly id?: string;
+            };
+        };
+    };
+    readonly systemPrompt: {
+        section(section: PromptSectionContribution): Disposable;
+    };
+    readonly skills: {
+        registerProvider(create: () => SkillProviderLike): Disposable;
+    };
+    readonly tools: {
+        register(definition: ToolDefinition): Disposable;
+    };
+    readonly commands: {
+        register(definition: CommandDefinitionLike): Disposable;
+    };
+    readonly webServer: WebServerLike;
+    readonly connection: ConnectionLike;
+}
+/** The slice of an incoming HTTP request the level route reads. */
+export interface RequestLike {
+    readonly method?: string | undefined;
+    readonly headers: object | undefined;
+}
+/** The slice of an HTTP response the level route writes. */
+export interface ResponseLike {
+    statusCode: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/** The slice of the `webServer` service this plugin registers on. */
+export interface WebServerLike {
+    /** Register one route; a duplicate path throws. */
+    register(route: {
+        readonly kind: 'exact';
+        readonly path: string;
+        handler(req: RequestLike, res: ResponseLike): void | Promise<void>;
+    }): Disposable;
+}
+/** The composition's trust fence for HTTP requests. */
+export interface ConnectionLike {
+    /** The rejection status for an untrusted or unauthenticated request, else `undefined`. */
+    requestRejection(request: {
+        readonly headers: object | undefined;
+    }): 401 | 403 | undefined;
+}
+/** The slice of the settings service this plugin uses. */
+export interface SettingsServiceLike {
+    /**
+     * Merge fields into one profile entry. `ns` is the entry id.
+     * @param ns - profile entry id.
+     * @param patch - fields to write.
+     */
+    update(ns: string, patch: Record<string, unknown>): Promise<void>;
+}
+export {};

package/lib/types/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * dsh-ponytail: Ponytail, lazy senior dev mode, as a DeepSeek Harness plugin.
+ *
+ * Four capabilities, all mounted through public Cordis extension points:
+ *
+ * - the bundled skills (`ponytail`, `-review`, `-audit`, `-debt`, `-gain`,
+ *   `-help`) become one `ctx.skills` provider;
+ * - while a level other than `off` is active, the mode-filtered ruleset is
+ *   contributed to the system prompt on every assembly;
+ * - the level is switchable from the model (`ponytail` tool) and the human
+ *   (`/ponytail` command);
+ * - the `ponytail` settings namespace makes the level persistent and pairs with
+ *   this package's browser half, which renders the card in the Web client's
+ *   Plugins page, on the ponytail row's Configure control.
+ *
+ * Skill content is adapted from the reference implementation
+ * (https://github.com/DietrichGebert/ponytail, MIT, © DietrichGebert).
+ *
+ * @module dsh-ponytail
+ */
+import type { Volatile } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { type RuntimeMode } from './modes.ts';
+import type { HostContext } from './host.ts';
+/** Plugin name as it appears in the loader. */
+export declare const name = "ponytail";
+/**
+ * Route the browser half reads for the level in use and its source. The card
+ * and the chip cannot see a session-local level (`review`, or one the settings
+ * document refused), so they ask the host instead of the settings document.
+ */
+export declare const LEVEL_ROUTE = "/ponytail/level";
+/**
+ * Configuration accepted from this plugin's row in a profile patch.
+ *
+ * The level is defaulted in the schema below, so the loader fills an absent
+ * `defaultMode` with `full` before {@link apply} runs; an invalid value still
+ * fails at load, because the union rejects it. The field is volatile, so the
+ * value arrives as a stable reference the plugin reads with `.get()`.
+ */
+export interface Config {
+    /** Startup level. The schema default fills `full`. */
+    readonly defaultMode: Volatile<RuntimeMode>;
+}
+/** Row schema: an absent level is filled by the loader before `apply`. */
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    defaultMode: z<"full" | "lite" | "off" | "ultra", "full" | "lite" | "off" | "ultra", "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    defaultMode: z<"full" | "lite" | "off" | "ultra", "full" | "lite" | "off" | "ultra", "volatile-defined">;
+}>>, "plain">;
+/**
+ * Mount the plugin.
+ * @param ctx - the host context.
+ * @param config - the schema-resolved row; the loader always passes one.
+ */
+export declare function apply(ctx: HostContext, config: Config): void;