@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/agents/language-directive.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+    buildContentLanguageDirective,
+    buildMigrationLanguageDirective,
+    buildPrimaryLanguageDirective,
+    isValidLanguageCode,
+    resolveLanguageName,
+    withContentLanguageDirective,
+    withMigrationLanguageDirective,
+} from "./language-directive";
+
+const EXHAUSTIVE_STRUCTURAL_TOKENS = [
+    "summary",
+    "symptom",
+    "model_or_provider_involved",
+    "ord_span",
+    "provider_sdk",
+    "model_behavior",
+    "tool_protocol",
+    "host_integration",
+    "historian_pipeline",
+    "edit_pipeline",
+    "environment",
+    "undocumented_internal",
+    "other",
+    "fixed",
+    "workaround",
+    "external_blocker",
+    "contained_failure",
+    "deferred",
+    "unknown_but_bounded",
+    "user",
+    "test_result",
+    "tool_result",
+    "self_review",
+    "unprocessed_from",
+    "verified",
+    "update",
+    "archive",
+    "candidate_ids",
+    "update_existing",
+    "memory_id",
+    "dismiss_existing",
+    "consume_candidate_ids",
+    "migrated",
+    "answer",
+] as const;
+
+describe("resolveLanguageName", () => {
+    it("maps a 2-letter ISO 639-1 code to 'English (Endonym)'", () => {
+        expect(resolveLanguageName("tr")).toBe("Turkish (Türkçe)");
+        expect(resolveLanguageName("es")).toBe("Spanish (Español)");
+        expect(resolveLanguageName("ja")).toBe("Japanese (日本語)");
+    });
+    it("normalizes case and surrounding whitespace", () => {
+        expect(resolveLanguageName("  TR ")).toBe("Turkish (Türkçe)");
+    });
+    it("returns the bare English name when the endonym matches it", () => {
+        expect(resolveLanguageName("en")).toBe("English");
+    });
+    it("returns '' for unset, blank, non-codes, and unknown codes", () => {
+        expect(resolveLanguageName()).toBe("");
+        expect(resolveLanguageName("   ")).toBe("");
+        expect(resolveLanguageName("Turkish")).toBe(""); // full name rejected
+        expect(resolveLanguageName("tur")).toBe(""); // 3-letter rejected
+        expect(resolveLanguageName("zz")).toBe(""); // not a real language
+        expect(resolveLanguageName("e1")).toBe("");
+    });
+    it("isValidLanguageCode mirrors resolveLanguageName", () => {
+        expect(isValidLanguageCode("tr")).toBe(true);
+        expect(isValidLanguageCode("zz")).toBe(false);
+        expect(isValidLanguageCode("Español")).toBe(false);
+    });
+});
+
+describe("language directives", () => {
+    it("emits the content directive with the resolved name and structural rule", () => {
+        const directive = buildContentLanguageDirective("tr");
+        expect(directive).toContain("Write human-readable prose you author in: Turkish (Türkçe).");
+        expect(directive).toContain("Copy required output schemas exactly");
+        expect(directive).toContain("No relevant memories found");
+    });
+
+    it("emits the preserve-user-quotes variant", () => {
+        const directive = buildContentLanguageDirective("es", {
+            preserveUserQuotes: true,
+        });
+        expect(directive).toContain(
+            "Preserve U: lines and directly quoted user text in their original source language; write the surrounding summary prose in Spanish (Español).",
+        );
+    });
+
+    it("emits the migration preserve-language variant", () => {
+        const directive = buildMigrationLanguageDirective("pt");
+        expect(directive).toContain("Preserve each migrated memory's existing language");
+        expect(directive).toContain(
+            "do NOT translate a memory just because an output language is set",
+        );
+        expect(directive).not.toContain("Write human-readable prose you author");
+    });
+
+    it("emits the primary one-liner with the resolved name", () => {
+        expect(buildPrimaryLanguageDirective("zh")).toBe(
+            "Use Chinese (中文) for your natural-language replies to the user unless the user explicitly asks for another language. Keep code, identifiers, file paths, commands, logs, and quoted text verbatim.",
+        );
+    });
+
+    it("returns empty or unchanged for blank or invalid language", () => {
+        expect(buildContentLanguageDirective()).toBe("");
+        expect(buildContentLanguageDirective("   ")).toBe("");
+        expect(buildContentLanguageDirective("Turkish")).toBe(""); // full name not a code
+        expect(buildMigrationLanguageDirective()).toBe("");
+        expect(buildPrimaryLanguageDirective()).toBe("");
+        expect(withContentLanguageDirective("base", "")).toBe("base");
+        expect(withMigrationLanguageDirective("base", " ")).toBe("base");
+        expect(withContentLanguageDirective("base", "zz")).toBe("base"); // unknown code
+    });
+
+    it("does not inline the exhaustive structural token inventory", () => {
+        const directive = buildContentLanguageDirective("tr");
+        for (const token of EXHAUSTIVE_STRUCTURAL_TOKENS) {
+            const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            expect(directive, token).not.toMatch(
+                new RegExp(`(^|[^A-Za-z0-9_])${escaped}([^A-Za-z0-9_]|$)`),
+            );
+        }
+    });
+});

package/src/agents/language-directive.ts

@@ -0,0 +1,113 @@
+interface ContentLanguageDirectiveOptions {
+    preserveUserQuotes?: boolean;
+}
+
+const ENGLISH_LANGUAGE_NAMES = new Intl.DisplayNames(["en"], {
+    type: "language",
+    fallback: "none",
+});
+
+/**
+ * Resolve a 2-letter ISO 639-1 code to the model-facing name string we validated
+ * against weak models: "English (Endonym)", e.g. "tr" -> "Turkish (Türkçe)",
+ * "es" -> "Spanish (Español)". A name (not a bare code) is what makes a weak
+ * model reliably write in-language. Built from Intl.DisplayNames, so there is no
+ * hardcoded language table to maintain. Returns "" for anything that is not a
+ * resolvable 2-letter code, so an unset OR invalid value emits no directive.
+ */
+export function resolveLanguageName(language?: string): string {
+    const code = typeof language === "string" ? language.trim().toLowerCase() : "";
+    if (!/^[a-z]{2}$/.test(code)) return "";
+    let english: string | undefined;
+    try {
+        english = ENGLISH_LANGUAGE_NAMES.of(code) ?? undefined;
+    } catch {
+        return "";
+    }
+    if (!english) return "";
+    let endonym: string | undefined;
+    try {
+        endonym =
+            new Intl.DisplayNames([code], { type: "language", fallback: "none" }).of(code) ??
+            undefined;
+    } catch {
+        endonym = undefined;
+    }
+    // english === endonym for self-named languages (e.g. "en" -> "English").
+    return endonym && endonym !== english ? `${english} (${endonym})` : english;
+}
+
+/** True when `language` is a resolvable 2-letter ISO 639-1 code. */
+export function isValidLanguageCode(language?: string): boolean {
+    return resolveLanguageName(language) !== "";
+}
+
+/** Build guidance for hidden agents that author prose. Returns "" when unset. */
+export function buildContentLanguageDirective(
+    language?: string,
+    options: ContentLanguageDirectiveOptions = {},
+): string {
+    const target = resolveLanguageName(language);
+    if (!target) return "";
+
+    const lines = [
+        "## Output language",
+        "",
+        `Write human-readable prose you author in: ${target}.`,
+        "",
+        "Do not translate or rename structural tokens. Copy required output schemas exactly:",
+        "- XML tag names, XML attribute names, JSON keys, tool names, tool-call argument keys, enum values, booleans/null, and required sentinel strings stay in English exactly as shown.",
+        "- Keep code identifiers, file paths, commands, config keys, CLI flags, URLs, commit hashes, model/provider IDs, stack traces, diagnostics, and transcript role markers such as U:, A:, and TC: verbatim.",
+        "- Localize only free-text prose values/content: summaries, memory text, explanations, titles, observations, and answers — unless the prompt says to preserve original wording.",
+        "",
+        "These literal values must remain English when used:",
+        "PROJECT_RULES, ARCHITECTURE, CONSTRAINTS, CONFIG_VALUES, NAMING;",
+        "causal_incident, trajectory_correction;",
+        "feature, design, docs, release, investigation, bug, refactor, infra;",
+        "memory, observation; true, false; No relevant memories found.",
+        "",
+        "Preserve the required output shape. Do not add commentary outside the requested XML/JSON/tool output.",
+    ];
+
+    if (options.preserveUserQuotes) {
+        lines.push(
+            "",
+            `Preserve U: lines and directly quoted user text in their original source language; write the surrounding summary prose in ${target}.`,
+        );
+    }
+    return lines.join("\n");
+}
+
+/** Append content-language guidance to a hidden-agent system prompt. */
+export function withContentLanguageDirective(
+    systemPrompt: string,
+    language?: string,
+    options: ContentLanguageDirectiveOptions = {},
+): string {
+    const directive = buildContentLanguageDirective(language, options);
+    return directive ? `${systemPrompt}\n\n${directive}` : systemPrompt;
+}
+
+/** Build migration-specific guidance. Returns "" when unset. */
+export function buildMigrationLanguageDirective(language?: string): string {
+    const target = resolveLanguageName(language);
+    if (!target) return "";
+    return [
+        "## Output language",
+        "",
+        "Preserve each migrated memory's existing language — do NOT translate a memory just because an output language is set. When merging memories written in different languages, use the language of the clearest / source-majority memory; otherwise keep the source phrasing. Only the category re-mapping changes.",
+    ].join("\n");
+}
+
+/** Append migration-specific language guidance to a system prompt. */
+export function withMigrationLanguageDirective(systemPrompt: string, language?: string): string {
+    const directive = buildMigrationLanguageDirective(language);
+    return directive ? `${systemPrompt}\n\n${directive}` : systemPrompt;
+}
+
+/** Build the primary-agent reply directive. Returns "" when unset. */
+export function buildPrimaryLanguageDirective(language?: string): string {
+    const target = resolveLanguageName(language);
+    if (!target) return "";
+    return `Use ${target} for your natural-language replies to the user unless the user explicitly asks for another language. Keep code, identifiers, file paths, commands, logs, and quoted text verbatim.`;
+}

package/src/agents/magic-context-prompt.language.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "bun:test";
+
+import { COMPARTMENT_AGENT_SYSTEM_PROMPT } from "../hooks/magic-context/compartment-prompt";
+import { withContentLanguageDirective } from "./language-directive";
+import { buildMagicContextSection, SELF_TAG_GUIDANCE } from "./magic-context-prompt";
+
+describe("Magic Context language guidance", () => {
+    it("keeps guidance bytes unchanged when language is unset or blank", () => {
+        const baseline = buildMagicContextSection(null, 20, true, false, false, false);
+        expect(buildMagicContextSection(null, 20, true, false, false, false, undefined)).toBe(
+            baseline,
+        );
+        expect(buildMagicContextSection(null, 20, true, false, false, false, "   ")).toBe(baseline);
+    });
+
+    it("keeps historian prompt bytes unchanged when language is unset", () => {
+        expect(
+            withContentLanguageDirective(COMPARTMENT_AGENT_SYSTEM_PROMPT, undefined, {
+                preserveUserQuotes: true,
+            }),
+        ).toBe(COMPARTMENT_AGENT_SYSTEM_PROMPT);
+    });
+
+    it("adds deterministic primary language guidance when set", () => {
+        const first = buildMagicContextSection(null, 20, true, false, false, false, "tr");
+        const second = buildMagicContextSection(null, 20, true, false, false, false, "tr");
+        const baseline = buildMagicContextSection(null, 20, true, false, false, false);
+
+        expect(first).toBe(second);
+        expect(first).toContain("Use Turkish (Türkçe) for your natural-language replies");
+        // 语言指令已移到段尾（上游 port）：无语言基线是输出前缀，指令追加在
+        // SELF_TAG 收尾块之后。
+        expect(first.startsWith(baseline)).toBe(true);
+        expect(baseline.endsWith(SELF_TAG_GUIDANCE)).toBe(true);
+        expect(first.indexOf("Use Turkish")).toBeGreaterThan(first.indexOf(SELF_TAG_GUIDANCE));
+    });
+});