dsh-agent-plugins-market 0.9.0 → 0.9.2

package/lib/packages/market-translation/src/application/translation/service.js

@@ -0,0 +1,113 @@
+import { chunkDocument, translateMarkdownDocument } from './document.js';
+import { TranslationLocalizer } from './localizer.js';
+import { collectUnits } from './unit.js';
+export class TranslationService {
+    localizer;
+    constructor(options) {
+        this.localizer = new TranslationLocalizer(options);
+    }
+    /** Read the persisted cache once, before the first {@link translateFields} read. */
+    load() {
+        return this.localizer.load();
+    }
+    /** Cancel timers and drop queued work; in-flight calls finish and are persisted. */
+    dispose() {
+        this.localizer.dispose();
+    }
+    /** Drop every cached translation, in memory and on disk. */
+    clear() {
+        return this.localizer.clear();
+    }
+    /** Apply a live display-preference change: off cancels unfinished work, on forgets failures. */
+    onEnabledChanged() {
+        this.localizer.onEnabledChanged();
+    }
+    /** Wait until the queue drains or the deadline passes. */
+    settle(deadlineMs) {
+        return this.localizer.settle(deadlineMs);
+    }
+    /**
+     * Translate one entity's description for a surface.
+     *
+     * Only the description is a translatable field: a name is an identity the user
+     * types, greps, and matches against upstream documentation, so the collector
+     * hands back no unit for one. Nothing here waits on a provider: an uncached
+     * field answers with the upstream text and reports itself pending.
+     *
+     * A description longer than one chunk travels in chunks, exactly as a
+     * document body does ({@link localizeText}), so the size of an upstream field
+     * is never a reason for a provider call to be cut off.
+     *
+     * Exposed for the panel and status surfaces that build their own rows; it is
+     * not part of the HTTP route surface.
+     * @param surface - the surface the entity belongs to.
+     * @param id - the entity's stable identity inside that surface.
+     * @param fields - the entity's upstream name and description.
+     * @param locale - the host locale this read resolved once; there is no
+     * default, because a default would re-read the host preference per entity and
+     * make a read's cost scale with its row count.
+     * @returns the translated fields and how many of them are still pending.
+     */
+    translateFields(surface, id, fields, locale) {
+        const translated = {};
+        let pending = 0;
+        for (const unit of collectUnits(surface, id, fields)) {
+            const result = this.localizeText(unit.surface, unit.id, unit.role ?? 'description', unit.text, locale);
+            pending += result.pending;
+            if (result.text !== unit.text)
+                translated.translatedDescription = result.text;
+        }
+        return { fields: translated, pending };
+    }
+    /**
+     * Translate one authored text, chunk by chunk, and reassemble it exactly.
+     *
+     * Every text the layer sends travels the way a document does: split on blank
+     * lines into chunks one request may carry, fenced code passed through
+     * verbatim, and the authored text between chunks re-emitted rather than
+     * synthesized — so a text nothing was translated for comes back byte for
+     * byte, and a translated one keeps the author's own blank lines. A
+     * description is chunked for the same reason a document is: the model hop
+     * sizes one call's output from the source it carries, and a text that exceeds
+     * that budget is cut off mid-generation, which fails the batch and retires the
+     * provider for the rest of the session.
+     * @param surface - the surface the entity belongs to.
+     * @param id - the entity's stable identity inside that surface.
+     * @param role - which text of the entity this is; the cache key's role slot.
+     * @param text - the authored text.
+     * @param locale - the interface language this read resolved once.
+     * @returns the reassembled text and how many of its chunks are still in flight.
+     */
+    localizeText(surface, id, role, text, locale) {
+        const chunks = chunkDocument(text);
+        if (chunks.length === 0)
+            return { text, pending: 0 };
+        let pending = 0;
+        const parts = [];
+        for (const chunk of chunks) {
+            if (!chunk.translatable) {
+                parts.push(chunk.text, chunk.separator);
+                continue;
+            }
+            const result = this.localizer.localize({ surface, id, role, text: chunk.text }, locale);
+            if (result.pending)
+                pending += 1;
+            parts.push(result.text, chunk.separator);
+        }
+        return { text: parts.join(''), pending };
+    }
+    /**
+     * Translate paragraphs in one complete Markdown tree. The provider receives
+     * prose only. Links, code, math, references and nested containers remain local.
+     * The result includes a translated document and paragraph-paired Markdown.
+     * Unchanged output preserves the source bytes. Changed output preserves the
+     * parsed structure and uses canonical Markdown formatting. Pending paragraphs
+     * remain authored until complete. The retry flag resets only this document
+     * failure budgets and the provider breaker, without clearing cached successes.
+     */
+    translateDocument(surface, id, text, locale, retry = false) {
+        if (retry)
+            this.localizer.retryDocument(surface, id);
+        return translateMarkdownDocument(text, (paragraph, parts) => this.localizer.localizeParagraph({ surface, id, role: 'document', text: paragraph }, parts, locale));
+    }
+}

package/lib/packages/market-translation/src/application/translation/unit.js

@@ -0,0 +1,19 @@
+/**
+ * Collect units for one entity, skipping empty or undefined text.
+ *
+ * Descriptions only: a name is an identifier the user types and matches against
+ * upstream documentation, and translating one made it harder to recognize than
+ * the original. The text is carried verbatim — the emptiness check trims, but
+ * the unit does not, so the cache key stays tied to what upstream authored.
+ * @param surface - the surface the entity belongs to.
+ * @param id - the entity's stable identity inside that surface.
+ * @param fields - the entity's upstream name and description.
+ * @returns the units to translate.
+ */
+export function collectUnits(surface, id, fields) {
+    return isTranslatable(fields.description) ? [{ surface, id, text: fields.description }] : [];
+}
+/** Whether a field holds text worth sending to a translation backend. */
+function isTranslatable(text) {
+    return typeof text === 'string' && text.trim() !== '';
+}

package/lib/packages/market-translation/src/index.js

@@ -0,0 +1,4 @@
+/** Explicit cross-domain entry surface. Internal modules are not import targets for siblings. */
+export { TranslationService } from './application/translation/service.js';
+export { createLlmTranslator } from './runtime/host/llm-translator.js';
+export { createTranslationProviders } from './runtime/host/translation-providers.js';

package/lib/packages/market-translation/src/runtime/host/llm-translator.js

@@ -0,0 +1,278 @@
+/**
+ * Translate a batch of texts through the host's own LLM service.
+ *
+ * This is the only place the translation layer talks to a model. It follows the
+ * harness auxiliary-call shape (packages/session/session-title-llm): resolve a
+ * route, stream through ctx.llm.stream, assemble the chunks with
+ * BlockAssembler, and reject on a terminal finish reason.
+ *
+ * The route is the user default model, read at call time from
+ * agentDefaultModel -- the same selection the harness uses for its own
+ * auxiliary calls, so the market never invents a model the deployment did not
+ * configure. purpose is deliberately omitted: the published
+ * GenerateOptions.purpose accepts only compaction and session-title, and
+ * neither describes a translation. Omitting it keeps the call on the ordinary
+ * route with no model-hidden transport metadata.
+ * @module runtime/host/llm-translator
+ */
+import { BlockAssembler, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { pluginMarketSource } from '../../../../market-contracts/src/host/plugin-message-source.js';
+/** Bound the call: a stalled model must not pin a translation slot forever. */
+const TRANSLATE_TIMEOUT_MS = 30_000;
+/**
+ * Conservative output allowances, not tokenizer measurements. English output
+ * can expand Chinese source substantially; its 1.5 allowance is paired with
+ * the localizer's smaller English-target batches. Chinese retains the 0.6
+ * estimate. Both remain bounded by MAX_OUTPUT_TOKENS_CAP.
+ */
+const OUTPUT_TOKENS_PER_SOURCE_CHAR = { zh: 0.6, en: 1.5 };
+/** Floor for one call, so a short text still has room for its own output. */
+const MIN_OUTPUT_TOKENS = 512;
+/** Ceiling for one call, so a large one cannot ask for an unbounded generation. */
+export const MAX_OUTPUT_TOKENS_CAP = 4_096;
+/**
+ * The output budget for one call carrying this much source text.
+ *
+ * Sized from the source rather than from the text count: what a call has to
+ * answer is the expansion of the text it was handed, so a batch of one long
+ * text and a batch of twenty short ones are budgeted by the same rule.
+ * @param sourceChars - characters in the user turn this call will send.
+ * @param locale - target language; English uses the larger expansion allowance.
+ * @returns the output token ceiling to ask the route for.
+ */
+export function outputTokenBudget(sourceChars, locale = 'zh') {
+    const ratio = locale.toLowerCase().startsWith('en') ? OUTPUT_TOKENS_PER_SOURCE_CHAR.en : OUTPUT_TOKENS_PER_SOURCE_CHAR.zh;
+    return Math.min(Math.max(Math.ceil(sourceChars * ratio), MIN_OUTPUT_TOKENS), MAX_OUTPUT_TOKENS_CAP);
+}
+/**
+ * Batch separator: a line holding only two percent signs.
+ *
+ * A model asked to translate several segments at once needs an unambiguous
+ * boundary, and this one cannot appear inside ordinary prose.
+ */
+const BATCH_SEPARATOR = '\n\n%%\n\n';
+const BATCH_SEPARATOR_PATTERN = /\r?\n[ \t]*%%[ \t]*\r?\n/;
+/**
+ * The language name a target tag is asked for in.
+ *
+ * A model reads a language name, not a tag: `zh` alone is answered in
+ * Traditional as often as in Simplified. The layer resolves the interface
+ * preference to the language the market actually renders ({@link
+ * resolveTranslationTarget}) before the chain is called, so the tags that reach
+ * here are few; the table names the spellings a caller may still hand in,
+ * because a tag that names a script should be answered in that script rather
+ * than left for the model to interpret.
+ */
+const TARGET_LANGUAGE_NAMES = {
+    zh: 'Simplified Chinese',
+    'zh-hans': 'Simplified Chinese',
+    'zh-cn': 'Simplified Chinese',
+    'zh-sg': 'Simplified Chinese',
+    'zh-hant': 'Traditional Chinese',
+    'zh-tw': 'Traditional Chinese',
+    'zh-hk': 'Traditional Chinese',
+    en: 'English'
+};
+/** The language to translate into, named for the prompt. */
+function targetLanguageName(locale) {
+    return TARGET_LANGUAGE_NAMES[locale.toLowerCase()] ?? locale;
+}
+/**
+ * Stable instruction; the target language and the batch flag are the variables.
+ * @param locale - target locale id.
+ * @param batched - whether the user turn carries several segments.
+ * @returns the system prompt for this call.
+ */
+function systemPrompt(locale, batched) {
+    const lines = [
+        'You translate plugin marketplace text for a developer tool.',
+        'Translate the user text into ' + targetLanguageName(locale) + '.',
+        'Preserve product names, package names, acronyms (MCP, LSP, DSH, CLI), and URLs exactly as written.',
+        'Keep the tone factual and concise. Output the translation alone: no quotes, no notes, no alternatives.'
+    ];
+    if (batched) {
+        lines.push('The input holds several segments separated by a line containing only two percent signs.', 'Return the same number of segments in the same order, separated the same way.', 'Never use that separator for anything else, and never merge or split segments.');
+    }
+    return lines.join(' ');
+}
+/**
+ * The user turn carrying the text.
+ *
+ * Built through the host factory rather than as a literal: a UserMessage
+ * carries a stable id and a source tag, and hand-writing one would fabricate
+ * both. The source is this plugin declared producer identity -- the turn is an
+ * instruction this plugin sends, not text the user typed.
+ * @param text - the masked text to translate.
+ * @returns the user message to send.
+ */
+function userMessage(text) {
+    return createUserMessage({ content: [{ type: 'text', text }], source: pluginMarketSource() });
+}
+/**
+ * Read the route the deployment selected, or undefined.
+ * @param host - the plugin context, read structurally.
+ * @returns the resolved route, or undefined when no model is configured.
+ */
+function readRoute(host) {
+    try {
+        const service = host.get?.('agentDefaultModel');
+        const selection = service?.currentSelection();
+        if (selection === undefined)
+            return undefined;
+        if (typeof selection.provider !== 'string' || typeof selection.model !== 'string')
+            return undefined;
+        if (selection.provider.length === 0 || selection.model.length === 0)
+            return undefined;
+        const effort = typeof selection.reasoningEffort === 'string' && selection.reasoningEffort.length > 0 ? selection.reasoningEffort : undefined;
+        return { provider: selection.provider, model: selection.model, ...(effort === undefined ? {} : { reasoningEffort: effort }) };
+    }
+    catch {
+        // A half-provisioned service is indistinguishable from an absent one.
+        return undefined;
+    }
+}
+/**
+ * Choose the reasoning effort for one translation call.
+ *
+ * Translating a sentence is mechanical, and the DeepSeek adapter default is
+ * high -- leaving the effort unset would spend reasoning tokens on every one of
+ * hundreds of texts. So the call asks for off first and keeps the user own
+ * selection only if the route refuses it: an unsupported effort rejects at
+ * validation rather than reaching the provider, and a model that genuinely
+ * requires reasoning still gets a working call instead of a failure.
+ *
+ * The user selection is forwarded rather than overridden when it is already
+ * explicit, because that is a choice they made for this deployment.
+ * @param llm - live LLM runtime owning effort validation, when it exposes it.
+ * @param route - the resolved provider/model route.
+ * @param signal - cancellation for the capability lookup.
+ * @returns the effort to send, or undefined to accept the adapter default.
+ */
+async function chooseEffort(llm, route, signal) {
+    if (route.reasoningEffort !== undefined)
+        return route.reasoningEffort;
+    if (llm.resolveCallConfig === undefined)
+        return undefined;
+    try {
+        await llm.resolveCallConfig({ provider: route.provider, model: route.model, reasoningEffort: 'off' }, signal);
+        return 'off';
+    }
+    catch {
+        // The route does not accept off; fall back to its own default.
+        return undefined;
+    }
+}
+/**
+ * Translate a terminal finish reason into an auxiliary-call failure.
+ * @param finish - the assembled finish reason.
+ * @returns the error to throw, or undefined when the stream ended normally.
+ */
+function finishError(finish) {
+    switch (finish.kind) {
+        case 'stop':
+            return undefined;
+        case 'error':
+        case 'aborted': {
+            const error = new Error(finish.failure.message);
+            error.code = finish.failure.code;
+            return error;
+        }
+        case 'max-tokens':
+            return new Error('translation reached the output token limit');
+        case 'tool-calls':
+            return new Error('translation unexpectedly requested a tool');
+        default:
+            return new Error('translation stopped for an unsupported reason: ' + String(finish.kind));
+    }
+}
+/**
+ * Collect the assistant text from one stream, rejecting on a terminal failure.
+ * @param stream - the chunk stream from the LLM service.
+ * @param signal - cancellation, checked between chunks.
+ * @returns the assembled assistant text.
+ */
+async function collectText(stream, signal) {
+    const assembler = new BlockAssembler();
+    for await (const chunk of stream) {
+        signal.throwIfAborted();
+        assembler.push(chunk);
+    }
+    signal.throwIfAborted();
+    const terminal = finishError(assembler.finish);
+    if (terminal !== undefined)
+        throw terminal;
+    const blocks = assembler.blocks();
+    const text = blocks
+        .filter((block) => block.type === 'text')
+        .map(block => block.text)
+        .join(' ')
+        .trim();
+    if (text.length === 0)
+        throw new Error('the model returned no text');
+    return text;
+}
+/**
+ * Build the model-backed provider over one plugin context.
+ *
+ * Every read is deferred to the call, because the LLM and default-model
+ * services provision after apply() returns; a value captured here would stay
+ * undefined for the life of the process. available() therefore re-resolves the
+ * route on each question, and a deployment with no model configured never
+ * queues work nothing can complete.
+ * @param host - the plugin context, read structurally so tests can pass a stub.
+ * @returns a provider bound to this context.
+ */
+export function createLlmTranslator(host) {
+    return {
+        id: 'llm',
+        available: () => readRoute(host) !== undefined && host.get?.('llm') !== undefined,
+        async translate(request) {
+            request.signal.throwIfAborted();
+            const llm = host.get?.('llm');
+            const route = readRoute(host);
+            if (llm === undefined || route === undefined)
+                throw new Error('the DSH model service is unavailable');
+            const texts = request.texts;
+            if (texts.length === 0)
+                return [];
+            const batched = texts.length > 1;
+            // One controller merges caller cancellation with the call deadline, so a
+            // stalled provider cannot hold a translation slot open.
+            const controller = new AbortController();
+            const onAbort = () => controller.abort();
+            request.signal.addEventListener('abort', onAbort, { once: true });
+            const timeout = setTimeout(onAbort, TRANSLATE_TIMEOUT_MS);
+            timeout.unref?.();
+            try {
+                const effort = await chooseEffort(llm, route, controller.signal);
+                controller.signal.throwIfAborted();
+                // The budget is sized from what this call actually carries: the batch
+                // separator is part of the turn, and a text longer than any earlier
+                // batch is what the response has to cover.
+                const source = batched ? texts.join(BATCH_SEPARATOR) : (texts[0] ?? '');
+                const options = {
+                    provider: route.provider,
+                    model: route.model,
+                    system: systemPrompt(request.locale, batched),
+                    messages: [userMessage(source)],
+                    maxTokens: outputTokenBudget(source.length, request.locale),
+                    temperature: 0,
+                    ...(effort === undefined ? {} : { reasoningEffort: effort }),
+                    signal: controller.signal
+                };
+                const answer = await collectText(llm.stream(options), controller.signal);
+                if (!batched)
+                    return [answer];
+                const segments = answer.split(BATCH_SEPARATOR_PATTERN).map(segment => segment.trim());
+                if (segments.length !== texts.length) {
+                    throw new Error('the model returned ' + String(segments.length) + ' of ' + String(texts.length) + ' segments');
+                }
+                return segments;
+            }
+            finally {
+                clearTimeout(timeout);
+                request.signal.removeEventListener('abort', onAbort);
+            }
+        }
+    };
+}

package/lib/packages/market-translation/src/runtime/host/machine-translator.js

@@ -0,0 +1,152 @@
+/** Google's public web-translation endpoint, the one the Translate widget calls. */
+const GOOGLE_ENDPOINT = 'https://translate-pa.googleapis.com/v1/translateHtml';
+/**
+ * The key the endpoint above expects. It is a public, browser-embedded key
+ * rather than a credential issued to this plugin — the same value ships inside
+ * every page that renders Google's translate widget, so it identifies the
+ * calling application and grants nothing.
+ */
+const GOOGLE_API_KEY = 'AIzaSyATBXajvzQLTDHEQbcpq0Ihe0vWDHmO520';
+/** Microsoft's consumer endpoint, the one Edge's translate feature calls. */
+const MICROSOFT_ENDPOINT = 'https://edge.microsoft.com/translate/translatetext';
+/** Auto-detect each request item; user-authored text can be Chinese or English. */
+const SOURCE_LANGUAGE = 'auto';
+/** How much of an error body to quote before it stops being diagnostic. */
+const ERROR_BODY_LIMIT = 200;
+/**
+ * Google's target language id.
+ *
+ * Google reads a bare `zh` as Simplified Chinese already, so the host's own
+ * value needs no qualification. A tag that names a script or region more
+ * precisely than the host does — `zh-Hant`, `ja` — is forwarded as authored
+ * rather than flattened to its primary subtag, which would silently answer in
+ * the wrong script.
+ */
+function googleTargetLanguage(locale) {
+    return locale.toLowerCase() === 'zh' ? 'zh' : locale;
+}
+/**
+ * Microsoft's target language id.
+ *
+ * This endpoint picks the script from the tag itself, so the host's bare `zh`
+ * — which names no script — has to be qualified to reach Simplified Chinese.
+ * A tag that already names one is forwarded as authored, so `zh-Hant` still
+ * answers in Traditional.
+ */
+function microsoftTargetLanguage(locale) {
+    return locale.toLowerCase() === 'zh' ? 'zh-Hans' : locale;
+}
+/** One error's message, whatever was thrown. */
+function reason(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * POST a JSON body and read the JSON answer, with the endpoint named in every
+ * failure so a chain log says which hop broke.
+ */
+async function postJson(provider, url, init) {
+    let response;
+    try {
+        response = await fetch(url, init);
+    }
+    catch (error) {
+        throw new Error(`${provider} translate: ${reason(error)}`, { cause: error });
+    }
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new Error(`${provider} translate: HTTP ${String(response.status)}${detail === '' ? '' : `: ${detail.slice(0, ERROR_BODY_LIMIT)}`}`);
+    }
+    try {
+        const payload = await response.json();
+        return payload;
+    }
+    catch (error) {
+        throw new Error(`${provider} translate: unreadable response body: ${reason(error)}`, { cause: error });
+    }
+}
+/** Read the first translation out of one Microsoft answer entry, or undefined. */
+function microsoftEntryText(entry) {
+    if (typeof entry !== 'object' || entry === null)
+        return undefined;
+    const translations = entry['translations'];
+    if (!Array.isArray(translations))
+        return undefined;
+    const first = translations[0];
+    if (typeof first !== 'object' || first === null)
+        return undefined;
+    const text = first['text'];
+    return typeof text === 'string' ? text : undefined;
+}
+/**
+ * Accept one answer batch only when it lines up with the request.
+ *
+ * A batch endpoint that answers short has dropped a unit somewhere, and a
+ * positionally aligned result would silently pair translations with the wrong
+ * entity. Rejecting the whole batch costs one fallback hop and keeps every
+ * answer attached to its own text.
+ */
+function requireBatch(provider, value, expected) {
+    const expectedText = `${provider} translate: expected ${String(expected)} results`;
+    if (!Array.isArray(value))
+        throw new Error(`${expectedText}, got not an array`);
+    if (value.length !== expected)
+        throw new Error(`${expectedText}, got ${String(value.length)}`);
+    // A well-sized batch whose entries carry no text is a different fault from a
+    // short batch, and the two need different words to be diagnosable.
+    const unreadable = value.filter(item => typeof item !== 'string').length;
+    if (unreadable > 0)
+        throw new Error(`${expectedText}, but ${String(unreadable)} carried no text`);
+    return value;
+}
+/**
+ * Translate one batch through Google's public endpoint.
+ *
+ * The body is the endpoint's own protobuf-JSON envelope: a single triple of
+ * texts, source language and target language, tagged `wt_lib` so the answer
+ * comes back as a plain array rather than as the widget's HTML payload.
+ * @param request - the batch, its target locale and cancellation.
+ * @returns the translations and the provider id.
+ * @throws when the request fails, the endpoint refuses it, or the answer does not line up.
+ */
+export async function googleTranslate(request) {
+    if (request.texts.length === 0)
+        return { texts: [], provider: 'google' };
+    const payload = await postJson('google', GOOGLE_ENDPOINT, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json+protobuf',
+            'x-goog-api-key': GOOGLE_API_KEY
+        },
+        body: JSON.stringify([[request.texts, SOURCE_LANGUAGE, googleTargetLanguage(request.locale)], 'wt_lib']),
+        signal: request.signal
+    });
+    // The answer is one array of arrays; the outer one carries the batch.
+    const batch = Array.isArray(payload) ? payload[0] : undefined;
+    return { texts: requireBatch('google', batch, request.texts.length), provider: 'google' };
+}
+/**
+ * Translate one batch through Microsoft's public endpoint.
+ *
+ * The body is the bare string array, and the languages ride the query string.
+ * `isEnterpriseClient=false` selects the consumer backend, which is the one
+ * that answers without authentication.
+ * @param request - the batch, its target locale and cancellation.
+ * @returns the translations and the provider id.
+ * @throws when the request fails, the endpoint refuses it, or the answer does not line up.
+ */
+export async function microsoftTranslate(request) {
+    if (request.texts.length === 0)
+        return { texts: [], provider: 'microsoft' };
+    const query = new URLSearchParams({
+        to: microsoftTargetLanguage(request.locale),
+        isEnterpriseClient: 'false'
+    });
+    const payload = await postJson('microsoft', `${MICROSOFT_ENDPOINT}?${query.toString()}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(request.texts),
+        signal: request.signal
+    });
+    const texts = Array.isArray(payload) ? payload.map(microsoftEntryText) : payload;
+    return { texts: requireBatch('microsoft', texts, request.texts.length), provider: 'microsoft' };
+}

package/lib/packages/market-translation/src/runtime/host/text-masking.js

@@ -0,0 +1,96 @@
+/**
+ * Mask the spans a machine engine corrupts, then restore them from its answer.
+ *
+ * Neither keyless endpoint leaves technical text alone: Google's HTML aligner
+ * escapes a bare `<`, and Microsoft folds angle brackets into pseudo-tags. The
+ * spans those engines damage — inline code, URLs, tag fragments and `${VAR}`
+ * paths — are exactly what a catalog description is made of, and the fixed terms
+ * are the ones an engine likes to paraphrase. Sending a bracketed token instead
+ * keeps the payload plain, and the restore table puts the original text back.
+ *
+ * The same table is the integrity check. An answer is accepted only when every
+ * placeholder it recorded comes back exactly once and nothing placeholder-shaped
+ * was invented, so a truncated or rewritten answer is discarded rather than
+ * rendered with a stray `⟦C1⟧` in it.
+ * @module runtime/host/text-masking
+ */
+/**
+ * The masking passes, widest span first.
+ *
+ * Order is load-bearing, in two places. Inline code runs first because its body
+ * may contain every other span, and angle-bracket fragments run before URLs
+ * because a markdown autolink is one fragment: masking the URL first would
+ * leave its bare `<` behind for the engine to escape, while masking the
+ * fragment first keeps the whole span intact.
+ */
+const MASK_RULES = [
+    { letter: 'D', pattern: /⟪d\d+⟫/g },
+    { letter: 'C', pattern: /`[^`]*`/g },
+    { letter: 'T', pattern: /<[^>]{0,200}>/g },
+    { letter: 'U', pattern: /https?:\/\/\S+/g },
+    { letter: 'V', pattern: /\$\{[A-Z_][A-Z0-9_]*\}/g },
+    { letter: 'H', pattern: /[<>&]/g },
+    { letter: 'K', pattern: /\b(?:MCP|LSP|DSH|CLI|API|JSON|HTTP|URL|SDK)\b/g }
+];
+/** The placeholder shape: a category letter and a 1-based index between U+27E6 and U+27E7. */
+const PLACEHOLDER_PATTERN = '⟦[A-Z]\\d+⟧';
+/** Every placeholder-shaped token in one string, in order of appearance. */
+function placeholderTokens(text) {
+    return text.match(new RegExp(PLACEHOLDER_PATTERN, 'g')) ?? [];
+}
+/**
+ * Replace every span the engines damage with a numbered placeholder.
+ * @param input - the upstream text, exactly as authored.
+ * @returns the text to send, and the table that restores it.
+ */
+export function maskText(input) {
+    const placeholders = new Map();
+    let text = input;
+    for (const rule of MASK_RULES) {
+        let index = 0;
+        text = text
+            .split(/(⟦[A-Z]\d+⟧)/g)
+            .map(part => {
+            if (/^⟦[A-Z]\d+⟧$/.test(part))
+                return part;
+            return part.replace(rule.pattern, match => {
+                index += 1;
+                const placeholder = `⟦${rule.letter}${index}⟧`;
+                placeholders.set(placeholder, match);
+                return placeholder;
+            });
+        })
+            .join('');
+    }
+    return { text, placeholders };
+}
+/**
+ * Put every masked span back, or reject the answer.
+ *
+ * An answer is rejected — `undefined`, so the caller discards the item instead
+ * of caching it — when a placeholder is missing, arrives twice, or when the
+ * engine invented one of its own. A short answer that dropped a placeholder
+ * would otherwise restore a sentence with a hole in it, and an invented one
+ * would render as literal brackets.
+ * @param masked - the text the engine returned.
+ * @param placeholders - the table {@link maskText} produced for that text.
+ * @returns the restored text, or `undefined` when the answer cannot be trusted.
+ */
+export function unmaskText(masked, placeholders) {
+    const seen = new Map();
+    for (const token of placeholderTokens(masked))
+        seen.set(token, (seen.get(token) ?? 0) + 1);
+    // Counting both directions rejects a dropped, duplicated and invented
+    // placeholder with one comparison: the answer carries exactly the table's
+    // keys, each of them once.
+    if (seen.size !== placeholders.size)
+        return undefined;
+    for (const [token, count] of seen) {
+        if (count !== 1 || !placeholders.has(token))
+            return undefined;
+    }
+    let restored = masked;
+    for (const [placeholder, original] of placeholders)
+        restored = restored.split(placeholder).join(original);
+    return restored;
+}