@poco-ai/agentero-dsh-host 0.0.0-stage → 0.1.1

package/lib/tools.js

@@ -0,0 +1,204 @@
+import { discoverArxiv, importId } from './catalog.js';
+import { cliFailure, runAgentero } from './cli-run.js';
+import { listVaultNotes, readVaultFile } from './notes-files.js';
+/** How many catalog rows a tool result may carry. */
+const PAPER_CAP = 40;
+/** How many note files a search may open. */
+const SEARCH_CAP = 40;
+/** How many search hits to return. */
+const HIT_CAP = 20;
+/** Note text returned to the model, in characters. */
+const TEXT_CAP = 12_000;
+const objectSchema = {
+    type: 'object',
+    additionalProperties: true,
+};
+/**
+ * Render a tool result. The tools API calls `render(arguments, value)`, so the
+ * value to serialize is the second parameter — declaring only one would
+ * stringify the arguments and hand the model an echo of its own call.
+ */
+function textResult(_arguments, value) {
+    return [{ type: 'text', text: JSON.stringify(value) }];
+}
+function record(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function stringArg(args, key) {
+    const row = record(args);
+    const value = row?.[key];
+    return typeof value === 'string' ? value.trim() : '';
+}
+async function paperList(settings, query, children) {
+    const args = [
+        '--vault', settings.vault,
+        '--json',
+        'paper', 'list',
+        '--fields', 'year,authors,tags,date',
+    ];
+    if (query !== '')
+        args.push('--query', query);
+    const result = await runAgentero(settings.agenteroBin, args, 20_000, children);
+    if (result.timedOut || result.spawnError !== undefined || result.code !== 0) {
+        throw new Error(cliFailure(result, 'agentero paper list'));
+    }
+    const parsed = JSON.parse(result.stdout);
+    const data = record(parsed)?.data;
+    const rows = Array.isArray(data) ? data : [];
+    return {
+        papers: rows.slice(0, PAPER_CAP),
+        truncated: rows.length > PAPER_CAP,
+    };
+}
+/**
+ * Register model tools that read and import the same vault as the panels.
+ * @returns Disposer that unregisters every tool.
+ */
+export function registerTools(ctx, settings, children) {
+    const tools = ctx.tools;
+    const dispose = [];
+    dispose.push(tools.register({
+        name: 'agentero_list_papers',
+        description: 'List papers already in the Agentero vault. Paths are vault-relative, such as papers/<id>. Do not invent a second catalog.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                query: { type: 'string', description: 'Optional substring matched by the Agentero CLI against title, authors, id, path, and tags.' },
+            },
+        },
+        output: { schema: { ...objectSchema }, render: textResult },
+        async execute(args) {
+            if (settings.vault === '')
+                throw new Error('vault is not configured');
+            return paperList(settings, stringArg(args, 'query'), children);
+        },
+    }));
+    dispose.push(tools.register({
+        name: 'agentero_import_paper',
+        description: 'Import one paper into the Agentero vault by arXiv id, DOI, or URL. Dedupes against papers already in the vault.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['text'],
+            properties: {
+                text: { type: 'string', description: 'arXiv id, DOI, or paper URL.' },
+            },
+        },
+        output: { schema: { ...objectSchema }, render: textResult },
+        async execute(args) {
+            if (settings.vault === '')
+                throw new Error('vault is not configured');
+            const text = stringArg(args, 'text');
+            if (text === '')
+                throw new Error('text is required');
+            const result = await importId(settings, text, children);
+            if (result.status !== 200)
+                throw new Error(result.error);
+            return JSON.parse(result.raw);
+        },
+    }));
+    dispose.push(tools.register({
+        name: 'agentero_read_note',
+        description: 'Read one Markdown file inside the vault. Use notes/<file>.md for the notes library, or papers/<id>/NOTES.md for the note beside a paper. Paths are vault-relative. This does not return PDF page text.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['path'],
+            properties: {
+                path: { type: 'string', description: 'Vault-relative path using / separators.' },
+            },
+        },
+        output: { schema: { ...objectSchema }, render: textResult },
+        async execute(args) {
+            if (settings.vault === '')
+                throw new Error('vault is not configured');
+            const path = stringArg(args, 'path');
+            if (path === '')
+                throw new Error('path is required');
+            const file = await readVaultFile(settings.vault, path);
+            if (file.status !== 200)
+                throw new Error(file.error);
+            const truncated = file.text.length > TEXT_CAP;
+            return {
+                path: file.path,
+                text: truncated ? file.text.slice(0, TEXT_CAP) : file.text,
+                truncated,
+            };
+        },
+    }));
+    dispose.push(tools.register({
+        name: 'agentero_search_notes',
+        description: 'Search Markdown files under the vault notes/ directory by title or body. Does not list per-paper NOTES.md files.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['query'],
+            properties: {
+                query: { type: 'string', description: 'Substring matched against the note title, path, and body.' },
+            },
+        },
+        output: { schema: { ...objectSchema }, render: textResult },
+        async execute(args) {
+            if (settings.vault === '')
+                throw new Error('vault is not configured');
+            const query = stringArg(args, 'query').toLowerCase();
+            if (query === '')
+                throw new Error('query is required');
+            const notes = await listVaultNotes(settings.vault);
+            const hits = [];
+            let scanned = 0;
+            for (const note of notes) {
+                if (hits.length >= HIT_CAP || scanned >= SEARCH_CAP)
+                    break;
+                const titleHit = note.title.toLowerCase().includes(query) || note.path.toLowerCase().includes(query);
+                scanned += 1;
+                const file = await readVaultFile(settings.vault, note.path);
+                if (file.status !== 200)
+                    continue;
+                const body = file.text;
+                const at = body.toLowerCase().indexOf(query);
+                if (!titleHit && at < 0)
+                    continue;
+                const start = at < 0 ? 0 : Math.max(0, at - 80);
+                hits.push({
+                    path: note.path,
+                    title: note.title,
+                    excerpt: body.slice(start, start + 240),
+                });
+            }
+            return { notes: hits };
+        },
+    }));
+    dispose.push(tools.register({
+        name: 'agentero_discover_arxiv',
+        description: 'Rank a short arXiv list for one keyword. Papers already in the vault are omitted. Import a chosen id with agentero_import_paper.',
+        parameters: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['keyword'],
+            properties: {
+                keyword: { type: 'string', description: 'Topic term or phrase.' },
+            },
+        },
+        output: { schema: { ...objectSchema }, render: textResult },
+        async execute(args) {
+            if (settings.vault === '')
+                throw new Error('vault is not configured');
+            const keyword = stringArg(args, 'keyword');
+            if (keyword === '')
+                throw new Error('keyword is required');
+            const result = await discoverArxiv(settings, keyword, children);
+            if (result.status !== 200)
+                throw new Error(result.error);
+            return JSON.parse(result.raw);
+        },
+    }));
+    return () => {
+        for (const remove of dispose)
+            remove();
+    };
+}
+//# sourceMappingURL=tools.js.map

package/lib/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/lib/translate.d.ts

@@ -0,0 +1,70 @@
+/** One-shot PDF translation through the Harness model registry. No session or tools are used. */
+export interface TranslationSettings {
+    translationProvider: string;
+    translationModel: string;
+    translationSystemPrompt?: string;
+    translationUserPrompt?: string;
+}
+interface CallControls {
+    temperature?: number;
+    maxTokens?: number;
+    reasoningEffort?: string;
+}
+interface CallConfig extends CallControls {
+    provider: string;
+    model: string;
+}
+/** Minimal public dsh-llm seam, like the host's other injected service faces. */
+export interface TranslationLlm {
+    prepareCall(config: CallConfig, signal: AbortSignal, configure: (controls: CallControls, model: {
+        reasoning?: {
+            efforts: readonly {
+                id: string;
+            }[];
+        };
+    }) => CallControls): Promise<{
+        config: CallConfig;
+        stream(options: CallConfig & {
+            system: string;
+            messages: {
+                role: 'user';
+                content: {
+                    type: 'text';
+                    text: string;
+                }[];
+            }[];
+            signal: AbortSignal;
+        }): AsyncIterable<{
+            type: string;
+            index?: number;
+            block?: {
+                type: string;
+                text?: string;
+            };
+            reason?: {
+                kind: string;
+                failure?: {
+                    message: string;
+                    status?: number;
+                    statusCode?: number;
+                    code?: string;
+                };
+            };
+        }>;
+    }>;
+}
+export interface DefaultTranslationModel {
+    currentSelection(): {
+        provider: string;
+        model: string;
+    };
+}
+export type TranslateText = (text: string, target: string, signal: AbortSignal) => Promise<string>;
+export declare function translationTarget(value: unknown): string;
+/** The prompt rules and customization semantics are shared with motif. */
+export declare function translationMessages(text: string, target: string, settings: TranslationSettings): {
+    system: string;
+    user: string;
+};
+export declare function createTranslator(settings: TranslationSettings, getLlm: () => TranslationLlm | undefined, getDefault: () => DefaultTranslationModel | undefined): TranslateText;
+export {};

package/lib/translate.js

@@ -0,0 +1,80 @@
+/** One-shot PDF translation through the Harness model registry. No session or tools are used. */
+import { retryTranslation } from './translation/retry.js';
+import { buildTranslateMessages } from './translation/prompt.js';
+import { translateDocumentText } from './translation/pipeline.js';
+export function translationTarget(value) {
+    const target = typeof value === 'string' ? value.trim() : '';
+    return /^[a-zA-Z]{2,3}(?:-[a-zA-Z0-9]{2,8})?$/.test(target) ? target : 'zh-CN';
+}
+/** The prompt rules and customization semantics are shared with motif. */
+export function translationMessages(text, target, settings) {
+    const language = /^zh(?:-CN)?$/i.test(target) ? 'Simplified Chinese'
+        : /^zh-(TW|HK)$/i.test(target) ? 'Traditional Chinese'
+            : /^en(?:-|$)/i.test(target) ? 'English' : target;
+    return buildTranslateMessages({ text, targetLangName: language,
+        customSystem: settings.translationSystemPrompt, customUser: settings.translationUserPrompt });
+}
+export function createTranslator(settings, getLlm, getDefault) {
+    return async (input, target, parentSignal) => {
+        const text = input.trim();
+        if (text === '' || text.length > 20_000)
+            throw new Error('Translation requires 1–20000 characters.');
+        const provider = settings.translationProvider.trim();
+        const model = settings.translationModel.trim();
+        if ((provider === '') !== (model === '')) {
+            throw new Error('Configure translationProvider and translationModel together in agentero-host.');
+        }
+        const route = provider === '' ? getDefault()?.currentSelection() : { provider, model };
+        if (route === undefined || route.provider === '' || route.model === '') {
+            throw new Error('Select a default model in Harness, or configure translationProvider and translationModel in agentero-host.');
+        }
+        const llm = getLlm();
+        if (llm === undefined)
+            throw new Error('Harness LLM service is unavailable. Enable a model provider for PDF translation.');
+        const operationSignal = AbortSignal.any([parentSignal, AbortSignal.timeout(300_000)]);
+        const translateChunk = (source) => retryTranslation(async () => {
+            const signal = AbortSignal.any([operationSignal, AbortSignal.timeout(90_000)]);
+            signal.throwIfAborted();
+            const call = await llm.prepareCall({ provider: route.provider, model: route.model, temperature: 0.2, maxTokens: 8192 }, signal, (controls, info) => {
+                // Effort IDs belong to the adapter. Its catalog orders them least to greatest.
+                const effort = info.reasoning?.efforts[0]?.id;
+                return { ...controls, ...(effort === undefined ? {} : { reasoningEffort: effort }) };
+            });
+            signal.throwIfAborted();
+            const messages = translationMessages(source, translationTarget(target), settings);
+            const blocks = new Map();
+            let complete = false;
+            for await (const chunk of call.stream({
+                ...call.config,
+                system: messages.system,
+                messages: [{ role: 'user', content: [{ type: 'text', text: messages.user }] }],
+                signal,
+            })) {
+                signal.throwIfAborted();
+                // block-end is authoritative; accumulating deltas as well would duplicate text.
+                if (chunk.type === 'block-end' && chunk.block?.type === 'text' && typeof chunk.block.text === 'string' && typeof chunk.index === 'number') {
+                    blocks.set(chunk.index, chunk.block.text);
+                }
+                if (chunk.type === 'finish') {
+                    if (chunk.reason?.kind !== 'stop') {
+                        const error = new Error(chunk.reason?.failure?.message ?? `Translation incomplete (${chunk.reason?.kind ?? 'unknown'}). Try a smaller selection.`);
+                        Object.assign(error, chunk.reason?.failure);
+                        if (chunk.reason?.kind === 'max-tokens')
+                            Object.assign(error, { code: 'TRANSLATION_INCOMPLETE' });
+                        throw error;
+                    }
+                    complete = true;
+                }
+            }
+            signal.throwIfAborted();
+            if (!complete)
+                throw new Error('Translation stream ended before completion. Please retry.');
+            const result = [...blocks].sort(([a], [b]) => a - b).map(([, value]) => value).join('\n').trim();
+            if (result === '')
+                throw new Error('The model returned no translation. Please retry or select another model.');
+            return result;
+        }, operationSignal);
+        return translateDocumentText(text, translationTarget(target), translateChunk, operationSignal);
+    };
+}
+//# sourceMappingURL=translate.js.map

package/lib/translate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translate.js","sourceRoot":"","sources":["../src/translate.ts"],"names":[],"mappings":"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"}

package/lib/translation/batches.d.ts

@@ -0,0 +1,21 @@
+export declare const TRANSLATE_BATCH_CHARS = 4500;
+/** Anything batchable: a single region or a joined paragraph chain. */
+type TranslateUnit = {
+    source: string;
+};
+/**
+ * Group units (already in reading order) into batches whose combined payload
+ * stays under {@link TRANSLATE_BATCH_CHARS}. Oversized units are kept
+ * alone and split by the transport. Batches may span adjacent pages; results are mapped
+ * back per unit, so positions are unaffected.
+ */
+export declare function buildTranslateBatches<T extends TranslateUnit>(units: readonly T[]): T[][];
+/** Join a batch into one numbered payload; a lone unit is sent as-is. */
+export declare function buildNumberedPayload(batch: readonly TranslateUnit[]): string;
+/**
+ * Split a numbered translation back into `expected` segments by `[[n]]` markers.
+ * Returns null when markers are missing/out of order or any segment is empty, so
+ * the caller can fall back to translating each sentence individually.
+ */
+export declare function parseNumberedTranslation(result: string, expected: number): string[] | null;
+export {};

package/lib/translation/batches.js

@@ -0,0 +1,88 @@
+// Ported from motif (Copyright (c) 2026 poco-ai, MIT). See MOTIF-LICENSE.txt.
+export const TRANSLATE_BATCH_CHARS = 4500;
+const TRANSLATE_BATCH_MARKER_RE = /(\[{2}|［{2})\s*(\d+)\s*(\]{2}|］{2})/g;
+/** Projected payload length of a batch (matches {@link buildNumberedPayload}). */
+function batchPayloadLength(batch) {
+    if (batch.length === 0)
+        return 0;
+    if (batch.length === 1)
+        return batch[0]?.source.length ?? 0;
+    let total = 0;
+    batch.forEach((unit, i) => {
+        total += `[[${i + 1}]] `.length + unit.source.length;
+        if (i > 0)
+            total += 2; // "\n\n"
+    });
+    return total;
+}
+/**
+ * Group units (already in reading order) into batches whose combined payload
+ * stays under {@link TRANSLATE_BATCH_CHARS}. Oversized units are kept
+ * alone and split by the transport. Batches may span adjacent pages; results are mapped
+ * back per unit, so positions are unaffected.
+ */
+export function buildTranslateBatches(units) {
+    const batches = [];
+    let current = [];
+    for (const unit of units) {
+        const candidate = [...current, unit];
+        if (current.length > 0 &&
+            batchPayloadLength(candidate) > TRANSLATE_BATCH_CHARS) {
+            batches.push(current);
+            current = [unit];
+        }
+        else {
+            current = candidate;
+        }
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/** Join a batch into one numbered payload; a lone unit is sent as-is. */
+export function buildNumberedPayload(batch) {
+    if (batch.length === 1)
+        return batch[0]?.source ?? "";
+    return batch.map((unit, i) => `[[${i + 1}]] ${unit.source}`).join("\n\n");
+}
+/**
+ * Split a numbered translation back into `expected` segments by `[[n]]` markers.
+ * Returns null when markers are missing/out of order or any segment is empty, so
+ * the caller can fall back to translating each sentence individually.
+ */
+export function parseNumberedTranslation(result, expected) {
+    const trimmed = result.trim();
+    if (expected <= 1)
+        return trimmed ? [trimmed] : null;
+    const markers = [];
+    const re = new RegExp(TRANSLATE_BATCH_MARKER_RE.source, "g");
+    let m = re.exec(trimmed);
+    while (m !== null) {
+        markers.push({
+            n: Number(m[2]),
+            start: m.index,
+            end: m.index + m[0].length,
+        });
+        m = re.exec(trimmed);
+    }
+    if (markers.length !== expected || trimmed.slice(0, markers[0]?.start).trim())
+        return null;
+    const chosen = markers.slice(0, expected);
+    for (let i = 0; i < expected; i++) {
+        if (chosen[i]?.n !== i + 1)
+            return null;
+    }
+    const segments = [];
+    for (let i = 0; i < expected; i++) {
+        const cur = chosen[i];
+        if (!cur)
+            return null;
+        const nextStart = i + 1 < expected ? chosen[i + 1]?.start : trimmed.length;
+        const seg = trimmed.slice(cur.end, nextStart ?? trimmed.length).trim();
+        if (!seg)
+            return null;
+        segments.push(seg);
+    }
+    return segments;
+}
+//# sourceMappingURL=batches.js.map

package/lib/translation/batches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batches.js","sourceRoot":"","sources":["../../src/translation/batches.ts"],"names":[],"mappings":"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"}

package/lib/translation/chunks.d.ts

@@ -0,0 +1,2 @@
+/** Lossless transport splitting. Geometry and sentence anchors stay upstream. */
+export declare function splitTranslationChunks(text: string, limit: number): string[];

package/lib/translation/chunks.js

@@ -0,0 +1,36 @@
+// Ported from motif (Copyright (c) 2026 poco-ai, MIT). See MOTIF-LICENSE.txt.
+/** Lossless transport splitting. Geometry and sentence anchors stay upstream. */
+export function splitTranslationChunks(text, limit) {
+    if (!Number.isInteger(limit) || limit < 32)
+        throw new Error("Invalid chunk limit");
+    const chunks = [];
+    let start = 0;
+    while (start < text.length) {
+        let end = Math.min(text.length, start + limit);
+        if (end < text.length) {
+            // Prefer a word/clause boundary in the latter half of the budget.
+            const floor = start + Math.floor(limit / 2);
+            for (let i = end; i > floor; i--) {
+                if (/[\s，。；！？]/u.test(text[i - 1] ?? "")) {
+                    end = i;
+                    break;
+                }
+            }
+            // Never tear an opaque placeholder or UTF-16 surrogate pair apart.
+            const open = text.lastIndexOf("⟦", end - 1);
+            const close = text.indexOf("⟧", open);
+            if (open >= start && open < end && close >= end) {
+                if (open === start)
+                    throw new Error("Translation token exceeds request budget");
+                end = open;
+            }
+            const code = text.charCodeAt(end - 1);
+            if (code >= 0xd800 && code <= 0xdbff)
+                end--;
+        }
+        chunks.push(text.slice(start, end));
+        start = end;
+    }
+    return chunks;
+}
+//# sourceMappingURL=chunks.js.map

package/lib/translation/chunks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunks.js","sourceRoot":"","sources":["../../src/translation/chunks.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,iFAAiF;AACjF,MAAM,UAAU,sBAAsB,CAAC,IAAY,EAAE,KAAa;IACjE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,EAAE;QACzC,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACxC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,IAAI,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;QAC/C,IAAI,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvB,kEAAkE;YAClE,MAAM,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YAC5C,KAAK,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;gBAClC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;oBAC1C,GAAG,GAAG,CAAC,CAAC;oBACR,MAAM;gBACP,CAAC;YACF,CAAC;YACD,mEAAmE;YACnE,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;YAC5C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACtC,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,GAAG,GAAG,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;gBACjD,IAAI,IAAI,KAAK,KAAK;oBACjB,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;gBAC7D,GAAG,GAAG,IAAI,CAAC;YACZ,CAAC;YACD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YACtC,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM;gBAAE,GAAG,EAAE,CAAC;QAC7C,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;QACpC,KAAK,GAAG,GAAG,CAAC;IACb,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC"}

package/lib/translation/mask.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Protect tokens that MT engines mangle (inline math, LaTeX commands, URLs,
+ * DOIs, citation markers, cross-references, and Markdown links) by swapping
+ * them for opaque placeholders before the request and restoring them afterwards.
+ */
+export type MaskedToken = {
+    placeholder: string;
+    original: string;
+};
+export type MaskedText = {
+    text: string;
+    tokens: MaskedToken[];
+};
+export type RestoredText = {
+    text: string;
+    /** Placeholders the engine dropped or rewrote; caller decides retry policy. */
+    missing: number;
+    /** Duplicated or invented placeholders invalidate structural restoration. */
+    invalid?: boolean;
+};
+export declare function maskInlineTokens(text: string): MaskedText;
+export declare function restoreInlineTokens(text: string, tokens: readonly MaskedToken[]): RestoredText;

package/lib/translation/mask.js

@@ -0,0 +1,69 @@
+// Ported from motif (Copyright (c) 2026 poco-ai, MIT). See MOTIF-LICENSE.txt.
+/**
+ * Protect tokens that MT engines mangle (inline math, LaTeX commands, URLs,
+ * DOIs, citation markers, cross-references, and Markdown links) by swapping
+ * them for opaque placeholders before the request and restoring them afterwards.
+ */
+import { findPreservedLinkSpans } from "./preserved-links.js";
+/**
+ * Mathematical white square brackets: absent from paper prose, and left alone
+ * by MT engines far more reliably than ASCII brackets, which collide with
+ * citation markers and with the `[[n]]` batch numbering.
+ */
+function placeholderFor(index) {
+    return `⟦${index}⟧`;
+}
+const MASK_PATTERNS = [
+    /⟪(?:F|\/?S)\d+⟫/gu,
+    // Display / inline TeX math (present when the source came from LaTeX).
+    /\$\$[^$]{1,400}\$\$/g,
+    /\$[^$\n]{1,200}\$/g,
+    /\\\((?:[^\\]|\\[^)]){1,200}?\\\)/g,
+    // LaTeX commands with or without a braced argument.
+    /\\[A-Za-z]+(?:\{[^{}]{0,120}\})?/g,
+    // Links and identifiers.
+    /https?:\/\/[^\s、，。]+/g,
+    /\bdoi:\s*10\.\d{4,9}\/\S+/gi,
+    /\b10\.\d{4,9}\/[^\s、，。]+/g,
+];
+export function maskInlineTokens(text) {
+    // Match the original string once; overlapping patterns must not nest placeholders.
+    const spans = findPreservedLinkSpans(text).map(({ start, end, text }) => ({ start, end, text }));
+    for (const pattern of [...MASK_PATTERNS, /`[^`\n]+`/g, /⟦\s*\d+\s*⟧/g, /\[\[\d+\]\]/g]) {
+        for (const match of text.matchAll(new RegExp(pattern.source, pattern.flags))) {
+            spans.push({ start: match.index, end: match.index + match[0].length, text: match[0] });
+        }
+    }
+    spans.sort((a, b) => a.start - b.start || b.end - a.end);
+    const tokens = [];
+    let cursor = 0;
+    let masked = '';
+    let index = 0;
+    for (const span of spans) {
+        if (span.start < cursor)
+            continue;
+        let placeholder = placeholderFor(index++);
+        while (text.includes(placeholder))
+            placeholder = placeholderFor(index++);
+        tokens.push({ placeholder, original: span.text });
+        masked += text.slice(cursor, span.start) + placeholder;
+        cursor = span.end;
+    }
+    return { text: masked + text.slice(cursor), tokens };
+}
+export function restoreInlineTokens(text, tokens) {
+    const originals = new Map(tokens.map(token => [token.placeholder.slice(1, -1), token.original]));
+    const counts = new Map();
+    let invalid = false;
+    // One pass also prevents a literal placeholder in an original formula from being restored twice.
+    const out = text.replace(/⟦\s*(\d+)\s*⟧/g, (full, id) => {
+        counts.set(id, (counts.get(id) ?? 0) + 1);
+        const original = originals.get(id);
+        if (original === undefined || (counts.get(id) ?? 0) > 1)
+            invalid = true;
+        return original ?? full;
+    });
+    const missing = [...originals.keys()].filter(id => !counts.has(id)).length;
+    return { text: out, missing, ...(invalid ? { invalid: true } : {}) };
+}
+//# sourceMappingURL=mask.js.map

package/lib/translation/mask.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mask.js","sourceRoot":"","sources":["../../src/translation/mask.ts"],"names":[],"mappings":"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"}

package/lib/translation/pipeline.d.ts

@@ -0,0 +1,3 @@
+/** Heal PDF ligatures and wrapped words without deleting unclassified page content. */
+export declare function normalizeTranslationSource(raw: string): string;
+export declare function translateDocumentText(input: string, target: string, translate: (text: string) => Promise<string>, signal: AbortSignal): Promise<string>;