@maci0/dsh-ponytail 0.0.0-stage → 0.18.2

package/lib/frontmatter.js

@@ -0,0 +1,285 @@
+/**
+ * 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
+ */
+const FRONTMATTER_BLOCK = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/**
+ * A mapping key this reader can prove `yaml` resolves to the same string: a
+ * letter or underscore first, because a leading digit or sign could resolve to
+ * a number, and none of the indicator characters that would open a tag,
+ * anchor, alias, flow node, or quoted key.
+ */
+const PLAIN_KEY = /^([A-Za-z_][A-Za-z0-9_.-]*):(?:[ \t](.*))?$/;
+/**
+ * Code points JavaScript's `trim`/`trimStart` strip but YAML counts as content:
+ * a block scalar's indentation is measured from them here, so a block holding
+ * one cannot be read line by line and goes to `yaml`.
+ */
+const JS_ONLY_SPACE = /[\u000B\u000C\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000\uFEFF]/;
+/**
+ * The plain-scalar spellings `yaml` resolves to something other than their own
+ * text. Only the YAML 1.2 core schema spellings: `yes`, `on`, `y`, and `no`
+ * are plain strings there, and every numeric, timestamp, and `.inf`/`.nan`
+ * form starts with a character this pattern excludes.
+ */
+const TYPED_WORDS = new Map([
+    ['null', null],
+    ['Null', null],
+    ['NULL', null],
+    ['true', true],
+    ['True', true],
+    ['TRUE', true],
+    ['false', false],
+    ['False', false],
+    ['FALSE', false],
+]);
+/**
+ * Plain scalars this reader returns verbatim. The leading character rules out
+ * every typed form above; the character set excludes the indicators that change
+ * how the line is read (`:` opening a nested value, `#` after a space opening
+ * a comment, tabs, quotes, and flow brackets), so a match is always literal
+ * text.
+ */
+const PLAIN_TEXT = /^[A-Za-z_][A-Za-z0-9 _.'()/,-]*$/;
+/**
+ * Block scalar header: the style indicator and the optional strip flag. The
+ * keep indicator (`+`, and any explicit indentation digit) is left out on
+ * purpose: a header this pattern rejects falls through to `yaml`, which is the
+ * only way to prove what a keep-chomped body keeps.
+ */
+const BLOCK_HEADER = /^([|>])(-)?$/;
+/** A complete single-line single-quoted scalar, with `''` as the only escape. */
+const SINGLE_QUOTED = /^'((?:[^']|'')*)'$/;
+/** A complete single-line double-quoted scalar with no escape to decode. */
+const DOUBLE_QUOTED = /^"([^"\\]*)"$/;
+/**
+ * The real parser, loaded by the first document this reader cannot prove.
+ * Cached after the first load: a rejected load is dropped so a later document
+ * can try again instead of inheriting one transient failure.
+ */
+let yaml;
+function loadYaml() {
+    yaml ??= import('yaml').catch((error) => {
+        yaml = undefined;
+        throw error;
+    });
+    return yaml;
+}
+/**
+ * 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 function splitFrontmatter(source) {
+    const text = source.replace(/^\uFEFF/, '');
+    const match = FRONTMATTER_BLOCK.exec(text);
+    if (match === null)
+        return { block: '', body: text };
+    // The body keeps its own bytes apart from line terminators, which are
+    // normalized to `\n`.
+    return { block: match[1] ?? '', body: text.slice(match[0].length).replace(/\r\n/g, '\n') };
+}
+/**
+ * Parse leading YAML frontmatter from a markdown document.
+ * @param source - full file contents.
+ * @returns the parsed keys and the remaining body.
+ */
+export async function parseFrontmatter(source) {
+    const { block, body } = splitFrontmatter(source);
+    return { data: await parseBlock(block), body };
+}
+/**
+ * Parse one frontmatter block, tolerating a malformed or non-mapping one.
+ * @returns the parsed mapping, or an empty one.
+ */
+async function parseBlock(block) {
+    if (block.trim() === '')
+        return {};
+    const flat = readFlatBlock(block);
+    if (flat !== undefined)
+        return flat;
+    try {
+        const { parse } = await loadYaml();
+        const data = parse(block);
+        if (data !== null && typeof data === 'object' && !Array.isArray(data)) {
+            return data;
+        }
+    }
+    catch {
+        // A malformed block is a skipped skill, not a failed mount.
+    }
+    return {};
+}
+/**
+ * Read the flat-mapping shape this module understands.
+ *
+ * Every construct that is not a top-level `key: value` entry with a scalar
+ * value (an indented line, an unindented scalar, a duplicate key (which
+ * `yaml` rejects), a `__proto__` key (which would set a prototype), a carriage
+ * return anywhere (a line break to `yaml`, and one the delimiter regex never
+ * promised to place), or a value shape below)
+ * returns `undefined` so the caller hands the whole block to `yaml`.
+ */
+function readFlatBlock(block) {
+    // Refused even for `\r\n`: the reader can prove where it splits the block,
+    // but not that `yaml` breaks every carriage return in the same place.
+    if (block.includes('\r'))
+        return undefined;
+    // `trimStart` would measure a block scalar's indentation through these, and
+    // YAML would not: any of them means the real parser decides.
+    if (JS_ONLY_SPACE.test(block))
+        return undefined;
+    // A tab is never indentation, and inside a folded body YAML treats a
+    // tab-leading content line as more indented: not this reader's to fold.
+    if (block.includes('\t'))
+        return undefined;
+    const lines = block.split(/\r\n|\n/);
+    const data = {};
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (line === '')
+            continue;
+        if (line.startsWith(' ') || line.startsWith('\t'))
+            return undefined;
+        const entry = PLAIN_KEY.exec(line);
+        if (entry === null)
+            return undefined;
+        const key = entry[1] ?? '';
+        // `yaml` rejects a repeated key, resolves a typed word to something other
+        // than its own text, and would set a prototype on `__proto__`; the real
+        // parser has to say so for all three.
+        if (key === '__proto__' || TYPED_WORDS.has(key) || Object.hasOwn(data, key))
+            return undefined;
+        // Trailing white space is separation, not content.
+        const value = (entry[2] ?? '').replace(/[ \t]+$/, '');
+        if (value === '') {
+            data[key] = null;
+            continue;
+        }
+        const header = BLOCK_HEADER.exec(value);
+        if (header !== null) {
+            const scalar = readBlockScalar(lines, index + 1, header[1] === '|', header[2] === '-');
+            if (scalar === undefined)
+                return undefined;
+            data[key] = scalar.text;
+            index = scalar.next - 1;
+            continue;
+        }
+        if (value.startsWith("'")) {
+            const quoted = SINGLE_QUOTED.exec(value);
+            if (quoted === null)
+                return undefined;
+            data[key] = (quoted[1] ?? '').replace(/''/g, "'");
+            continue;
+        }
+        if (value.startsWith('"')) {
+            const quoted = DOUBLE_QUOTED.exec(value);
+            if (quoted === null)
+                return undefined;
+            data[key] = quoted[1] ?? '';
+            continue;
+        }
+        if (TYPED_WORDS.has(value)) {
+            data[key] = TYPED_WORDS.get(value);
+            continue;
+        }
+        if (!PLAIN_TEXT.test(value))
+            return undefined;
+        data[key] = value;
+    }
+    return data;
+}
+/**
+ * Count the spaces a line starts with. YAML indentation is spaces; a tab or a
+ * code point JS would treat as blank is not this reader's to interpret.
+ */
+function leadingSpaces(line) {
+    let count = 0;
+    while (count < line.length && line.charCodeAt(count) === 32)
+        count += 1;
+    return count;
+}
+/**
+ * Read one block scalar body.
+ *
+ * Only the shape `yaml` folds without surprises is accepted: every content line
+ * indented by the same positive number of spaces, no leading blank line, no
+ * tab in the indentation, and no line that is only white space (which keeps its
+ * own bytes instead of folding). Trailing blank lines are chomped away by both
+ * `|` and `>` without the `+` indicator, so they are dropped here.
+ * @param literal - `true` for `|`, `false` for `>`.
+ * @param stripped - `true` for the `-` chomping indicator.
+ * @returns the scalar text and the index after its body, or `undefined` when
+ * `yaml` must decide.
+ */
+function readBlockScalar(lines, start, literal, stripped) {
+    let next = start;
+    while (next < lines.length) {
+        const line = lines[next] ?? '';
+        if (line !== '' && !line.startsWith(' '))
+            break;
+        next += 1;
+    }
+    const body = lines.slice(start, next);
+    while (body.length > 0 && body[body.length - 1] === '')
+        body.pop();
+    const first = body[0];
+    if (first === undefined)
+        return { text: '', next };
+    // Indentation is spaces only: a tab, or anything `yaml` counts as content,
+    // means this reader cannot prove where the body starts.
+    const indent = leadingSpaces(first);
+    if (indent === 0)
+        return undefined;
+    const content = [];
+    for (const line of body) {
+        if (line === '') {
+            content.push('');
+            continue;
+        }
+        const lead = leadingSpaces(line);
+        if (lead !== indent || line.length === indent)
+            return undefined;
+        content.push(line.slice(indent));
+    }
+    let text = '';
+    if (literal)
+        text = content.join('\n');
+    else {
+        // Folding replaces the break between two content lines with a space, and
+        // every run of `blank` blank lines between them with that many newlines.
+        let blanks = 0;
+        for (const line of content) {
+            if (line === '') {
+                blanks += 1;
+                continue;
+            }
+            if (text !== '')
+                text += blanks === 0 ? ' ' : '\n'.repeat(blanks);
+            blanks = 0;
+            text += line;
+        }
+    }
+    if (text !== '' && !stripped)
+        text += '\n';
+    return { text, next };
+}

package/lib/host.js

@@ -0,0 +1,12 @@
+/**
+ * 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
+ */
+export {};

package/lib/index.js

@@ -0,0 +1,375 @@
+/**
+ * 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 { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import z from '@deepseek-ai/schemastery';
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { buildModeInstructions, DEFAULT_MODE, isDeactivationCommand, normalizeCommandMode, normalizeMode, resolveDefaultMode, RUNTIME_MODES, VALID_MODES, } from './modes.js';
+import { createSkillProvider } from './skills.js';
+import { splitFrontmatter } from './frontmatter.js';
+/** Plugin name as it appears in the loader. */
+export 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 const LEVEL_ROUTE = '/ponytail/level';
+/** Row schema: an absent level is filled by the loader before `apply`. */
+export const Config = z.object({
+    defaultMode: z.union([...RUNTIME_MODES]).default(DEFAULT_MODE).volatile(),
+});
+/**
+ * Mount the plugin.
+ * @param ctx - the host context.
+ * @param config - the schema-resolved row; the loader always passes one.
+ */
+export function apply(ctx, config) {
+    // `<package>/skills`, resolved from this module's own location.
+    const skillsDir = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills');
+    const startup = resolveDefaultMode(config.defaultMode.get());
+    // Parsed once, at load: the ruleset is filtered per assembly, so the
+    // frontmatter must not have to be re-read for every request. A missing body
+    // means a broken install: fail while loading rather than injecting a silently
+    // truncated ruleset.
+    const skillBody = splitFrontmatter(readFileSync(join(skillsDir, 'ponytail', 'SKILL.md'), 'utf8')).body.trimStart();
+    /**
+     * The mode-filtered ruleset, keyed by level.
+     *
+     * The body above is parsed once and never re-read, so the filter's result is
+     * a pure function of the level: at most one entry per accepted level, filled
+     * on first use and never invalidated, because nothing that feeds it can
+     * change while the plugin is mounted.
+     */
+    const instructionsByMode = new Map();
+    const modeInstructions = (mode) => {
+        let text = instructionsByMode.get(mode);
+        if (text === undefined) {
+            text = buildModeInstructions({ mode, skillBody });
+            instructionsByMode.set(mode, text);
+        }
+        return text;
+    };
+    const warn = (message) => {
+        console.warn(`[ponytail] ${message}`);
+    };
+    /** Session-local level, used when the profile write cannot hold the level. */
+    let override;
+    let modeGeneration = 0;
+    /** The row's live level; updates are committed into the same reference. */
+    const configuredMode = () => normalizeMode(config.defaultMode.get());
+    const activeMode = () => override ?? configuredMode() ?? startup;
+    /** The mounted settings service, or `undefined` while none is attached. */
+    const settingsService = () => {
+        const service = ctx.get('settings');
+        return service === undefined || service === null ? undefined : service;
+    };
+    /**
+     * Persist a level through the settings document; false when it cannot hold it.
+     *
+     * The service is queried at the use site rather than captured from the
+     * `inject` callback: the callback's fiber disposes when the settings service
+     * unloads, and a captured reference would then let a later write reach a
+     * detached service.
+     * @param next - the level to commit.
+     * @param signal - caller cancellation; an abort during the write stops the
+     * wait, and the write itself still lands.
+     * @returns whether the document accepted the level.
+     */
+    const persist = async (next, signal) => {
+        signal?.throwIfAborted();
+        const settings = settingsService();
+        const id = entryId(ctx);
+        if (settings === undefined || id === undefined || normalizeMode(next) === undefined)
+            return false;
+        try {
+            await abortable(settings.update(id, { defaultMode: next }), signal);
+            signal?.throwIfAborted();
+            return true;
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            warn(`could not persist level "${next}": ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    };
+    const setMode = async (next, signal) => {
+        signal?.throwIfAborted();
+        const started = ++modeGeneration;
+        const previous = activeMode();
+        const persisted = await persist(next, signal);
+        // A refused older request cannot restore a level the human already ended.
+        if (started === modeGeneration)
+            override = persisted ? undefined : next;
+        const mode = activeMode();
+        return { previous, mode, changed: mode !== previous };
+    };
+    /**
+     * Turn the level off because the human's own message was a deactivation
+     * command.
+     *
+     * The override is set before the settings write is awaited: the durable
+     * `user/message` event arrives before the turn's prompt is assembled, and
+     * awaiting the document would let that same turn assemble with the ruleset
+     * still injected: the one turn the user just asked to end. A committed
+     * document then becomes the source of truth again, so the card and the
+     * prompt cannot disagree.
+     */
+    const deactivateFromMessage = () => {
+        if (activeMode() === 'off')
+            return;
+        const started = ++modeGeneration;
+        override = 'off';
+        void persist('off').then((persisted) => {
+            if (persisted && started === modeGeneration)
+                override = undefined;
+        });
+    };
+    ctx.on('loader/volatile-update', () => {
+        modeGeneration += 1;
+        override = undefined;
+    });
+    ctx.inject(['systemPrompt'], (scope) => {
+        scope.systemPrompt.section({
+            name: 'ponytail',
+            order: 700, // after the persona prefix, before tool guidance
+            // Evaluated at each assembly, so a level change lands on the next request.
+            // `off` returns empty text, which assembly drops.
+            text: () => modeInstructions(activeMode()),
+        });
+    });
+    ctx.inject(['skills'], (scope) => {
+        scope.skills.registerProvider(() => createSkillProvider({ skillsDir, onWarn: warn }));
+    });
+    ctx.inject(['tools'], (scope) => {
+        scope.tools.register(createModeTool(activeMode, setMode));
+    });
+    ctx.inject(['commands'], (scope) => {
+        scope.commands.register({
+            name: 'ponytail',
+            description: '✂ Set the ponytail level (lite, full, ultra, review, off) or report the current one.',
+            input: { hint: 'lite | full | ultra | review | off' },
+            handler: async (invocation) => handleModeCommand(invocation, activeMode, setMode),
+        });
+    });
+    ctx.inject(['webServer', 'connection'], (scope) => {
+        scope.effect(() => scope.webServer.register({
+            kind: 'exact',
+            path: LEVEL_ROUTE,
+            handler: (req, res) => {
+                const rejection = scope.connection.requestRejection(req);
+                if (rejection !== undefined) {
+                    res.statusCode = rejection;
+                    res.end();
+                    return;
+                }
+                if (req.method !== undefined && req.method !== 'GET') {
+                    res.statusCode = 405;
+                    res.setHeader('allow', 'GET');
+                    res.end();
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader('content-type', 'application/json; charset=utf-8');
+                res.setHeader('cache-control', 'no-store');
+                res.end(JSON.stringify({ mode: activeMode(), source: override === undefined ? 'settings' : 'session' }));
+            },
+        }), `ponytail: GET ${LEVEL_ROUTE}`);
+    });
+    // "stop ponytail" / "normal mode" typed as an ordinary message, given the
+    // same effect as `/ponytail off`. The command path is unaffected: this only
+    // claims messages that are exactly the command and come from the human.
+    ctx.on('session/event', (_session, event) => {
+        if (event.type !== 'user/message')
+            return;
+        const text = userMessageText(event.data);
+        if (text === undefined || !isDeactivationCommand(text))
+            return;
+        deactivateFromMessage();
+    });
+}
+/**
+ * Read the plain text of a genuine user message.
+ *
+ * Injected context (skill bodies, file references, replayed history) rides the
+ * same event stream, so a message only counts when the harness marks it as the
+ * user's own; an injected instruction that happened to read "normal mode" must
+ * never toggle the level.
+ * @param data - the `user/message` event payload.
+ * @returns the concatenated text blocks, or `undefined` when this is not the
+ * human's own text.
+ */
+function userMessageText(data) {
+    if (data === null || typeof data !== 'object')
+        return undefined;
+    const message = data;
+    if (message.source?.kind !== 'user')
+        return undefined;
+    if (!Array.isArray(message.content))
+        return undefined;
+    const text = message.content
+        .map((block) => (block.type === 'text' && typeof block.text === 'string' ? block.text : ''))
+        .join('\n');
+    return text.trim() === '' ? undefined : text;
+}
+/**
+ * Await `work`, settling early when `signal` aborts.
+ *
+ * The settings write is not interruptible from here, so the abandoned promise
+ * still settles on its own; only its rejection is absorbed, and the tool call
+ * returns before the write it no longer waits for.
+ * @param work - the in-flight write.
+ * @param signal - caller cancellation.
+ * @returns the write's result once it settles.
+ */
+function abortable(work, signal) {
+    if (signal === undefined || signal.aborted)
+        return work;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new Error('aborted'));
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+    });
+}
+/**
+ * Build the model-facing level tool.
+ * @param getMode - reads the active level.
+ * @param setMode - applies and persists a level.
+ * @returns the registered tool definition.
+ */
+function createModeTool(getMode, setMode) {
+    return defineTool({
+        name: 'ponytail',
+        // The `enum` below already names every level, and the injected ruleset
+        // explains what each one does; repeating both here only costs tokens.
+        description: 'Set or report the ponytail level, which governs how much code is written. '
+            + 'The level persists in the user settings document. '
+            + 'Call with no arguments to report the current level.',
+        parameters: {
+            mode: {
+                type: 'string',
+                enum: [...VALID_MODES],
+                description: 'Level to activate. Omit to report the current level.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    mode: { type: 'string', enum: [...VALID_MODES], required: true },
+                    previous: { type: 'string', enum: [...VALID_MODES], required: true },
+                    changed: { type: 'boolean', required: true },
+                    active: { type: 'boolean', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: renderModeResult(value) }],
+        },
+        async execute(args, exec) {
+            const requested = readModeArgument(args);
+            const previous = getMode();
+            if (requested === undefined) {
+                return { mode: previous, previous, changed: false, active: previous !== 'off' };
+            }
+            const applied = await setMode(requested, exec.signal);
+            return {
+                mode: applied.mode,
+                previous: applied.previous,
+                changed: applied.changed,
+                active: applied.mode !== 'off',
+            };
+        },
+    });
+}
+/**
+ * Read the optional `mode` argument.
+ *
+ * `defineTool` already rejected a value outside the enum, so an unrecognized
+ * value never reaches the body and reads as a status query.
+ * @param args - losslessly snapshotted model arguments.
+ * @returns the requested level, or `undefined` for a status query.
+ */
+function readModeArgument(args) {
+    if (args === null || typeof args !== 'object')
+        return undefined;
+    const raw = args['mode'];
+    if (raw === undefined || raw === null || raw === '')
+        return undefined;
+    return normalizeCommandMode(raw);
+}
+/**
+ * Phrase one level outcome. Shared by the model-facing tool and the human
+ * command, which report the same three transitions.
+ * @param mode - the level now active.
+ * @param previous - the level before the call.
+ * @param changed - whether the call moved the level.
+ * @returns the sentence both surfaces start from.
+ */
+function modeSentence(mode, previous, changed) {
+    if (!changed)
+        return `Ponytail level: ${mode}.`;
+    return mode === 'off'
+        ? `Ponytail off (was ${previous}). Normal behavior.`
+        : `Ponytail level: ${mode} (was ${previous}).`;
+}
+/**
+ * Render the canonical tool value for the model.
+ * @param value - the canonical value returned by `execute`.
+ * @returns model-facing prose.
+ */
+function renderModeResult(value) {
+    const record = (value ?? {});
+    const mode = typeof record['mode'] === 'string' ? record['mode'] : 'unknown';
+    const previous = typeof record['previous'] === 'string' ? record['previous'] : mode;
+    const changed = record['changed'] === true;
+    const active = record['active'] === true;
+    if (!changed && !active)
+        return 'Ponytail is off. Normal behavior.';
+    const sentence = modeSentence(mode, previous, changed);
+    return active ? `${sentence} The ruleset is injected into every request.` : sentence;
+}
+/**
+ * Handle the human `/ponytail [level]` command.
+ * @param invocation - the command invocation.
+ * @param getMode - reads the active level.
+ * @param setMode - applies and persists a level.
+ * @returns the direct-UI result.
+ */
+async function handleModeCommand(invocation, getMode, setMode) {
+    const input = invocation.rawInput.trim().toLowerCase();
+    if (input === '')
+        return { kind: 'success', text: modeSentence(getMode(), getMode(), false) };
+    const requested = isDeactivationCommand(input) ? 'off' : normalizeCommandMode(input);
+    if (requested === undefined) {
+        return {
+            kind: 'error',
+            text: `Unknown ponytail level "${invocation.rawInput.trim()}". Use one of: ${VALID_MODES.join(', ')}.`,
+        };
+    }
+    const { previous, mode, changed } = await setMode(requested);
+    return { kind: 'success', text: modeSentence(mode, previous, changed) };
+}
+/** Profile entry id of this plugin, when the loader mounted it. */
+function entryId(ctx) {
+    const id = ctx.fiber?.entry?.options?.id;
+    return typeof id === 'string' ? id : undefined;
+}