open-multi-agent-kit 0.97.0 → 0.98.1

package/dist/core/completion-sound-io.js

@@ -0,0 +1,64 @@
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+const SPAWN_KILL_TIMEOUT_MS = 1000;
+const SOUND_ENV_KEYS = [
+    "DBUS_SESSION_BUS_ADDRESS",
+    "DISPLAY",
+    "LANG",
+    "LC_ALL",
+    "PULSE_SERVER",
+    "SystemRoot",
+    "TEMP",
+    "TMP",
+    "WAYLAND_DISPLAY",
+    "WINDIR",
+    "XDG_RUNTIME_DIR",
+];
+/** Process boundary for sound backends: no inherited PATH, credentials, or workspace cwd. */
+export function completionSoundProcessOptions(sourceEnv = process.env) {
+    const env = {};
+    for (const key of SOUND_ENV_KEYS) {
+        const value = sourceEnv[key];
+        if (value !== undefined)
+            env[key] = value;
+    }
+    return { cwd: tmpdir(), env, shell: false, stdio: "ignore", windowsHide: true };
+}
+/** Default IO: bounded fire-and-forget spawn with terminal BEL fallback. */
+export function defaultCompletionSoundIo() {
+    return {
+        spawnBackend: (argv) => new Promise((resolve) => {
+            try {
+                const [executable, ...args] = argv;
+                const child = spawn(executable, args, completionSoundProcessOptions());
+                const killTimer = setTimeout(() => {
+                    try {
+                        child.kill();
+                    }
+                    catch {
+                        // Best effort only.
+                    }
+                }, SPAWN_KILL_TIMEOUT_MS);
+                killTimer.unref();
+                child.once("error", (error) => resolve({ ok: false, diagnostic: error.code ?? "spawn_error" }));
+                child.once("spawn", () => {
+                    child.unref();
+                    resolve({ ok: true });
+                });
+            }
+            catch {
+                resolve({ ok: false, diagnostic: "spawn_error" });
+            }
+        }),
+        writeBell: () => {
+            try {
+                process.stdout.write("\u0007");
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+//# sourceMappingURL=completion-sound-io.js.map

package/dist/core/completion-sound-io.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-sound-io.js","sourceRoot":"","sources":["../../src/core/completion-sound-io.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,MAAM,qBAAqB,GAAG,IAAI,CAAC;AACnC,MAAM,cAAc,GAAG;IACtB,0BAA0B;IAC1B,SAAS;IACT,MAAM;IACN,QAAQ;IACR,cAAc;IACd,YAAY;IACZ,MAAM;IACN,KAAK;IACL,iBAAiB;IACjB,QAAQ;IACR,iBAAiB;CACR,CAAC;AAQX,6FAA6F;AAC7F,MAAM,UAAU,6BAA6B,CAAC,SAAS,GAAsB,OAAO,CAAC,GAAG,EAAgB;IACvG,MAAM,GAAG,GAAsB,EAAE,CAAC;IAClC,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC3C,CAAC;IACD,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAAA,CAChF;AAED,4EAA4E;AAC5E,MAAM,UAAU,wBAAwB,GAAsB;IAC7D,OAAO;QACN,YAAY,EAAE,CAAC,IAAI,EAAE,EAAE,CACtB,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACxB,IAAI,CAAC;gBACJ,MAAM,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;gBACnC,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,6BAA6B,EAAE,CAAC,CAAC;gBACvE,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC;oBAClC,IAAI,CAAC;wBACJ,KAAK,CAAC,IAAI,EAAE,CAAC;oBACd,CAAC;oBAAC,MAAM,CAAC;wBACR,oBAAoB;oBACrB,CAAC;gBAAA,CACD,EAAE,qBAAqB,CAAC,CAAC;gBAC1B,SAAS,CAAC,KAAK,EAAE,CAAC;gBAClB,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAA4B,EAAE,EAAE,CACpD,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,IAAI,IAAI,aAAa,EAAE,CAAC,CAC/D,CAAC;gBACF,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC;oBACzB,KAAK,CAAC,KAAK,EAAE,CAAC;oBACd,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBAAA,CACtB,CAAC,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,CAAC,CAAC;YACnD,CAAC;QAAA,CACD,CAAC;QACH,SAAS,EAAE,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC;gBACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBAC/B,OAAO,IAAI,CAAC;YACb,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,KAAK,CAAC;YACd,CAAC;QAAA,CACD;KACD,CAAC;AAAA,CACF","sourcesContent":["import { type SpawnOptions, spawn } from \"node:child_process\";\nimport { tmpdir } from \"node:os\";\n\nconst SPAWN_KILL_TIMEOUT_MS = 1000;\nconst SOUND_ENV_KEYS = [\n\t\"DBUS_SESSION_BUS_ADDRESS\",\n\t\"DISPLAY\",\n\t\"LANG\",\n\t\"LC_ALL\",\n\t\"PULSE_SERVER\",\n\t\"SystemRoot\",\n\t\"TEMP\",\n\t\"TMP\",\n\t\"WAYLAND_DISPLAY\",\n\t\"WINDIR\",\n\t\"XDG_RUNTIME_DIR\",\n] as const;\n\nexport interface CompletionSoundIo {\n\t/** Spawn a fixed absolute argv; resolve success/failure. */\n\treadonly spawnBackend: (argv: readonly string[]) => Promise<{ readonly ok: boolean; readonly diagnostic?: string }>;\n\treadonly writeBell: () => boolean;\n}\n\n/** Process boundary for sound backends: no inherited PATH, credentials, or workspace cwd. */\nexport function completionSoundProcessOptions(sourceEnv: NodeJS.ProcessEnv = process.env): SpawnOptions {\n\tconst env: NodeJS.ProcessEnv = {};\n\tfor (const key of SOUND_ENV_KEYS) {\n\t\tconst value = sourceEnv[key];\n\t\tif (value !== undefined) env[key] = value;\n\t}\n\treturn { cwd: tmpdir(), env, shell: false, stdio: \"ignore\", windowsHide: true };\n}\n\n/** Default IO: bounded fire-and-forget spawn with terminal BEL fallback. */\nexport function defaultCompletionSoundIo(): CompletionSoundIo {\n\treturn {\n\t\tspawnBackend: (argv) =>\n\t\t\tnew Promise((resolve) => {\n\t\t\t\ttry {\n\t\t\t\t\tconst [executable, ...args] = argv;\n\t\t\t\t\tconst child = spawn(executable, args, completionSoundProcessOptions());\n\t\t\t\t\tconst killTimer = setTimeout(() => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tchild.kill();\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Best effort only.\n\t\t\t\t\t\t}\n\t\t\t\t\t}, SPAWN_KILL_TIMEOUT_MS);\n\t\t\t\t\tkillTimer.unref();\n\t\t\t\t\tchild.once(\"error\", (error: NodeJS.ErrnoException) =>\n\t\t\t\t\t\tresolve({ ok: false, diagnostic: error.code ?? \"spawn_error\" }),\n\t\t\t\t\t);\n\t\t\t\t\tchild.once(\"spawn\", () => {\n\t\t\t\t\t\tchild.unref();\n\t\t\t\t\t\tresolve({ ok: true });\n\t\t\t\t\t});\n\t\t\t\t} catch {\n\t\t\t\t\tresolve({ ok: false, diagnostic: \"spawn_error\" });\n\t\t\t\t}\n\t\t\t}),\n\t\twriteBell: () => {\n\t\t\ttry {\n\t\t\t\tprocess.stdout.write(\"\\u0007\");\n\t\t\t\treturn true;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/completion-sound.d.ts

@@ -1,4 +1,6 @@
+import { type CompletionSoundIo } from "./completion-sound-io.ts";
 import type { PromptSettledEvent } from "./prompt-settlement.ts";
+export { type CompletionSoundIo, completionSoundProcessOptions, defaultCompletionSoundIo, } from "./completion-sound-io.ts";
 /**
  * Cross-platform completion sound service (OMK v0.97.x roadmap §17, M4/PR7).
  *
@@ -19,6 +21,7 @@ export interface CompletionSoundSettings {
     minDurationMs?: number;
     onSuccess?: boolean;
     onFailure?: boolean;
+    onAbort?: boolean;
     terminalBellFallback?: boolean;
 }
 export interface NotificationSettings {
@@ -42,6 +45,7 @@ export interface ResolvedCompletionSoundSettings {
     readonly minDurationMs: number;
     readonly onSuccess: boolean;
     readonly onFailure: boolean;
+    readonly onAbort?: boolean;
     readonly terminalBellFallback: boolean;
 }
 /** Defaults per §17.1; `OMK_COMPLETION_SOUND=0|1` (§18.2) overrides `enabled`. */
@@ -72,16 +76,6 @@ export declare function selectCompletionSoundCandidates(input: {
     readonly isWsl: boolean;
     readonly terminalBellFallback: boolean;
 }): readonly CompletionSoundCandidate[];
-export interface CompletionSoundIo {
-    /** Spawn a fixed argv; resolve success/failure. Must never throw synchronously into the caller. */
-    readonly spawnBackend: (argv: readonly string[]) => Promise<{
-        readonly ok: boolean;
-        readonly diagnostic?: string;
-    }>;
-    readonly writeBell: () => boolean;
-}
-/** Default IO: detached-ish fire-and-forget spawn per §17.4. */
-export declare function defaultCompletionSoundIo(): CompletionSoundIo;
 /**
  * Stateful service: once per promptRunId (§17.4), deterministic candidate
  * walk, all failures downgraded to diagnostics. `handleSettled` is fire and

package/dist/core/completion-sound.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"completion-sound.d.ts","sourceRoot":"","sources":["../../src/core/completion-sound.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"node:child_process\";\nimport type { PromptSettledEvent } from \"./prompt-settlement.ts\";\n\n/**\n * Cross-platform completion sound service (OMK v0.97.x roadmap §17, M4/PR7).\n *\n * Consumes `prompt_settled` only (§16.1: never `agent_end`) and is a pure UX\n * signal — it must never influence run outcome, block the event loop, or\n * delay process exit (§17.4: spawn with `stdio: \"ignore\"`, `shell: false`,\n * `unref()`, bounded kill timer, never awaited by the prompt path).\n *\n * Security (§22.1): every backend uses a fixed executable and fixed argv;\n * no user text, paths, or model output is ever interpolated.\n *\n * Backend selection is a deterministic candidate chain per platform\n * (§17.3); a spawn failure falls through to the next candidate and finally\n * to the terminal BEL. All failures are diagnostics only (§4.6).\n */\n\nexport interface CompletionSoundSettings {\n\tenabled?: boolean; // default: false (§17.1: backward compat, CI/headless surprise, accessibility)\n\tminDurationMs?: number; // default: 5000\n\tonSuccess?: boolean; // default: true\n\tonFailure?: boolean; // default: true\n\tterminalBellFallback?: boolean; // default: true\n}\n\nexport interface NotificationSettings {\n\tcompletionSound?: CompletionSoundSettings;\n}\n\nexport type CompletionSoundBackend =\n\t| \"macos-afplay\"\n\t| \"windows-system-sound\"\n\t| \"linux-canberra\"\n\t| \"linux-paplay\"\n\t| \"linux-aplay\"\n\t| \"terminal-bell\"\n\t| \"none\";\n\nexport interface CompletionSoundRequest {\n\treadonly promptRunId: string;\n\treadonly outcome: \"completed\" | \"failed\" | \"aborted\";\n\treadonly durationMs: number;\n}\n\nexport interface CompletionSoundResult {\n\treadonly backend: CompletionSoundBackend;\n\treadonly attempted: boolean;\n\treadonly success: boolean;\n\treadonly diagnostic?: string;\n}\n\nexport const COMPLETION_SOUND_ENV = \"OMK_COMPLETION_SOUND\";\nconst SPAWN_KILL_TIMEOUT_MS = 1000;\n\nexport interface ResolvedCompletionSoundSettings {\n\treadonly enabled: boolean;\n\treadonly minDurationMs: number;\n\treadonly onSuccess: boolean;\n\treadonly onFailure: boolean;\n\treadonly terminalBellFallback: boolean;\n}\n\n/** Defaults per §17.1; `OMK_COMPLETION_SOUND=0|1` (§18.2) overrides `enabled`. */\nexport function resolveCompletionSoundSettings(\n\tsettings?: CompletionSoundSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedCompletionSoundSettings {\n\tlet enabled = settings?.enabled ?? false;\n\tconst envValue = env[COMPLETION_SOUND_ENV]?.trim();\n\tif (envValue === \"0\") {\n\t\tenabled = false;\n\t} else if (envValue === \"1\") {\n\t\tenabled = true;\n\t}\n\treturn {\n\t\tenabled,\n\t\tminDurationMs:\n\t\t\ttypeof settings?.minDurationMs === \"number\" && settings.minDurationMs >= 0 ? settings.minDurationMs : 5000,\n\t\tonSuccess: settings?.onSuccess ?? true,\n\t\tonFailure: settings?.onFailure ?? true,\n\t\tterminalBellFallback: settings?.terminalBellFallback ?? true,\n\t};\n}\n\nexport interface CompletionSoundSurface {\n\t/** Only the interactive TUI plays sounds by default (§17.4). */\n\treadonly isTui: boolean;\n\treadonly isTty: boolean;\n\treadonly isCi: boolean;\n}\n\n/** §17.1/§17.4 gate: settings, outcome mapping, duration floor, and surface. */\nexport function shouldPlayCompletionSound(input: {\n\treadonly settings: ResolvedCompletionSoundSettings;\n\treadonly event: PromptSettledEvent;\n\treadonly surface: CompletionSoundSurface;\n}): boolean {\n\tconst { settings, event, surface } = input;\n\tif (!settings.enabled || !surface.isTui || !surface.isTty || surface.isCi) {\n\t\treturn false;\n\t}\n\tif (event.durationMs < settings.minDurationMs) {\n\t\treturn false;\n\t}\n\tif (event.outcome === \"completed\") {\n\t\treturn settings.onSuccess;\n\t}\n\tif (event.outcome === \"failed\") {\n\t\treturn settings.onFailure;\n\t}\n\t// User-initiated aborts never chime: the user is already at the keyboard.\n\treturn false;\n}\n\nexport interface CompletionSoundCandidate {\n\treadonly backend: CompletionSoundBackend;\n\t/** Fixed argv (§22.1); empty for terminal-bell (written, not spawned). */\n\treadonly argv: readonly string[];\n}\n\n/**\n * Deterministic backend candidate chain per platform (§17.3, §23.2 property\n * 14). The runner tries candidates in order on spawn failure.\n */\nexport function selectCompletionSoundCandidates(input: {\n\treadonly platform: NodeJS.Platform;\n\treadonly isWsl: boolean;\n\treadonly terminalBellFallback: boolean;\n}): readonly CompletionSoundCandidate[] {\n\tconst bell: CompletionSoundCandidate[] = input.terminalBellFallback ? [{ backend: \"terminal-bell\", argv: [] }] : [];\n\tif (input.platform === \"darwin\") {\n\t\treturn [{ backend: \"macos-afplay\", argv: [\"afplay\", \"/System/Library/Sounds/Glass.aiff\"] }, ...bell];\n\t}\n\tif (input.platform === \"win32\") {\n\t\treturn [{ backend: \"windows-system-sound\", argv: windowsSystemSoundArgv(\"powershell.exe\") }, ...bell];\n\t}\n\tif (input.platform === \"linux\" && input.isWsl) {\n\t\t// §17.3 WSL: Windows PowerShell first, then the terminal BEL.\n\t\treturn [{ backend: \"windows-system-sound\", argv: windowsSystemSoundArgv(\"powershell.exe\") }, ...bell];\n\t}\n\tif (input.platform === \"linux\") {\n\t\treturn [\n\t\t\t{ backend: \"linux-canberra\", argv: [\"canberra-gtk-play\", \"-i\", \"complete\"] },\n\t\t\t{ backend: \"linux-paplay\", argv: [\"paplay\", \"/usr/share/sounds/freedesktop/stereo/complete.oga\"] },\n\t\t\t{ backend: \"linux-aplay\", argv: [\"aplay\", \"-q\", \"/usr/share/sounds/alsa/Front_Center.wav\"] },\n\t\t\t...bell,\n\t\t];\n\t}\n\treturn [...bell];\n}\n\n/** Fixed expression only (§17.3 Windows): no user text ever enters the command. */\nfunction windowsSystemSoundArgv(executable: string): readonly string[] {\n\treturn [executable, \"-NoProfile\", \"-NonInteractive\", \"-Command\", \"[System.Media.SystemSounds]::Asterisk.Play()\"];\n}\n\nexport interface CompletionSoundIo {\n\t/** Spawn a fixed argv; resolve success/failure. Must never throw synchronously into the caller. */\n\treadonly spawnBackend: (argv: readonly string[]) => Promise<{ readonly ok: boolean; readonly diagnostic?: string }>;\n\treadonly writeBell: () => boolean;\n}\n\n/** Default IO: detached-ish fire-and-forget spawn per §17.4. */\nexport function defaultCompletionSoundIo(): CompletionSoundIo {\n\treturn {\n\t\tspawnBackend: (argv) =>\n\t\t\tnew Promise((resolve) => {\n\t\t\t\ttry {\n\t\t\t\t\tconst [executable, ...args] = argv;\n\t\t\t\t\tconst child = spawn(executable, args, { stdio: \"ignore\", shell: false, windowsHide: true });\n\t\t\t\t\tconst killTimer = setTimeout(() => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tchild.kill();\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Best effort only.\n\t\t\t\t\t\t}\n\t\t\t\t\t}, SPAWN_KILL_TIMEOUT_MS);\n\t\t\t\t\tkillTimer.unref();\n\t\t\t\t\tchild.once(\"error\", (error: NodeJS.ErrnoException) =>\n\t\t\t\t\t\tresolve({ ok: false, diagnostic: error.code ?? \"spawn_error\" }),\n\t\t\t\t\t);\n\t\t\t\t\t// Success means \"spawned\"; playback is not awaited (§17.4).\n\t\t\t\t\tchild.once(\"spawn\", () => {\n\t\t\t\t\t\tchild.unref();\n\t\t\t\t\t\tresolve({ ok: true });\n\t\t\t\t\t});\n\t\t\t\t} catch {\n\t\t\t\t\tresolve({ ok: false, diagnostic: \"spawn_error\" });\n\t\t\t\t}\n\t\t\t}),\n\t\twriteBell: () => {\n\t\t\ttry {\n\t\t\t\tprocess.stdout.write(\"\\u0007\");\n\t\t\t\treturn true;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Stateful service: once per promptRunId (§17.4), deterministic candidate\n * walk, all failures downgraded to diagnostics. `handleSettled` is fire and\n * forget — callers must not await it on the prompt path.\n */\nexport interface CompletionSoundServiceDeps {\n\treadonly getSettings: () => CompletionSoundSettings | undefined;\n\treadonly surface: () => CompletionSoundSurface;\n\treadonly candidates: () => readonly CompletionSoundCandidate[];\n\treadonly io?: CompletionSoundIo;\n\treadonly env?: NodeJS.ProcessEnv;\n\t/** §20.2 observability hook; fail-open, never affects the result. */\n\treadonly onResult?: (result: CompletionSoundResult) => void;\n}\n\nexport class CompletionSoundService {\n\tprivate readonly playedRunIds = new Set<string>();\n\tprivate lastResult: CompletionSoundResult | null = null;\n\tprivate readonly deps: CompletionSoundServiceDeps;\n\n\tconstructor(deps: CompletionSoundServiceDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/** Most recent attempt, for diagnostics/tests. */\n\tget lastPlaybackResult(): CompletionSoundResult | null {\n\t\treturn this.lastResult;\n\t}\n\n\tasync handleSettled(event: PromptSettledEvent): Promise<CompletionSoundResult> {\n\t\ttry {\n\t\t\tconst settings = resolveCompletionSoundSettings(this.deps.getSettings(), this.deps.env ?? process.env);\n\t\t\tif (this.playedRunIds.has(event.promptRunId)) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: false, diagnostic: \"already_played\" });\n\t\t\t}\n\t\t\tif (!shouldPlayCompletionSound({ settings, event, surface: this.deps.surface() })) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: true });\n\t\t\t}\n\t\t\tthis.playedRunIds.add(event.promptRunId);\n\t\t\tconst io = this.deps.io ?? defaultCompletionSoundIo();\n\t\t\tconst diagnostics: string[] = [];\n\t\t\tfor (const candidate of this.deps.candidates()) {\n\t\t\t\tif (candidate.backend === \"terminal-bell\") {\n\t\t\t\t\tconst ok = io.writeBell();\n\t\t\t\t\treturn this.finish({\n\t\t\t\t\t\tbackend: \"terminal-bell\",\n\t\t\t\t\t\tattempted: true,\n\t\t\t\t\t\tsuccess: ok,\n\t\t\t\t\t\tdiagnostic: diagnostics.length > 0 ? diagnostics.join(\", \") : undefined,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tconst spawned = await io.spawnBackend(candidate.argv);\n\t\t\t\tif (spawned.ok) {\n\t\t\t\t\treturn this.finish({ backend: candidate.backend, attempted: true, success: true });\n\t\t\t\t}\n\t\t\t\tdiagnostics.push(`${candidate.backend}: ${spawned.diagnostic ?? \"failed\"}`);\n\t\t\t}\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: diagnostics.join(\", \") });\n\t\t} catch (error) {\n\t\t\t// §23.2 property 13: sound failure never changes the prompt outcome.\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: String(error) });\n\t\t}\n\t}\n\n\tprivate finish(result: CompletionSoundResult): CompletionSoundResult {\n\t\tthis.lastResult = result;\n\t\ttry {\n\t\t\tthis.deps.onResult?.(result);\n\t\t} catch {\n\t\t\t// Observability must never affect the sound path.\n\t\t}\n\t\treturn result;\n\t}\n}\n"]}
+{"version":3,"file":"completion-sound.d.ts","sourceRoot":"","sources":["../../src/core/completion-sound.ts"],"names":[],"mappings":"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","sourcesContent":["import { type CompletionSoundIo, defaultCompletionSoundIo } from \"./completion-sound-io.ts\";\nimport type { PromptSettledEvent } from \"./prompt-settlement.ts\";\n\nexport {\n\ttype CompletionSoundIo,\n\tcompletionSoundProcessOptions,\n\tdefaultCompletionSoundIo,\n} from \"./completion-sound-io.ts\";\n\n/**\n * Cross-platform completion sound service (OMK v0.97.x roadmap §17, M4/PR7).\n *\n * Consumes `prompt_settled` only (§16.1: never `agent_end`) and is a pure UX\n * signal — it must never influence run outcome, block the event loop, or\n * delay process exit (§17.4: spawn with `stdio: \"ignore\"`, `shell: false`,\n * `unref()`, bounded kill timer, never awaited by the prompt path).\n *\n * Security (§22.1): every backend uses a fixed executable and fixed argv;\n * no user text, paths, or model output is ever interpolated.\n *\n * Backend selection is a deterministic candidate chain per platform\n * (§17.3); a spawn failure falls through to the next candidate and finally\n * to the terminal BEL. All failures are diagnostics only (§4.6).\n */\n\nexport interface CompletionSoundSettings {\n\tenabled?: boolean; // default: true; interactive TTY only, with OMK_COMPLETION_SOUND=0 opt-out\n\tminDurationMs?: number; // default: 5000; applies to successful completion only\n\tonSuccess?: boolean; // default: true\n\tonFailure?: boolean; // default: true\n\tonAbort?: boolean; // default: true\n\tterminalBellFallback?: boolean; // default: true\n}\n\nexport interface NotificationSettings {\n\tcompletionSound?: CompletionSoundSettings;\n}\n\nexport type CompletionSoundBackend =\n\t| \"macos-afplay\"\n\t| \"windows-system-sound\"\n\t| \"linux-canberra\"\n\t| \"linux-paplay\"\n\t| \"linux-aplay\"\n\t| \"terminal-bell\"\n\t| \"none\";\n\nexport interface CompletionSoundRequest {\n\treadonly promptRunId: string;\n\treadonly outcome: \"completed\" | \"failed\" | \"aborted\";\n\treadonly durationMs: number;\n}\n\nexport interface CompletionSoundResult {\n\treadonly backend: CompletionSoundBackend;\n\treadonly attempted: boolean;\n\treadonly success: boolean;\n\treadonly diagnostic?: string;\n}\n\nexport const COMPLETION_SOUND_ENV = \"OMK_COMPLETION_SOUND\";\nexport interface ResolvedCompletionSoundSettings {\n\treadonly enabled: boolean;\n\treadonly minDurationMs: number;\n\treadonly onSuccess: boolean;\n\treadonly onFailure: boolean;\n\treadonly onAbort?: boolean;\n\treadonly terminalBellFallback: boolean;\n}\n\n/** Defaults per §17.1; `OMK_COMPLETION_SOUND=0|1` (§18.2) overrides `enabled`. */\nexport function resolveCompletionSoundSettings(\n\tsettings?: CompletionSoundSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedCompletionSoundSettings {\n\tlet enabled = settings?.enabled ?? true;\n\tconst envValue = env[COMPLETION_SOUND_ENV]?.trim();\n\tif (envValue === \"0\") {\n\t\tenabled = false;\n\t} else if (envValue === \"1\") {\n\t\tenabled = true;\n\t}\n\treturn {\n\t\tenabled,\n\t\tminDurationMs:\n\t\t\ttypeof settings?.minDurationMs === \"number\" && settings.minDurationMs >= 0 ? settings.minDurationMs : 5000,\n\t\tonSuccess: settings?.onSuccess ?? true,\n\t\tonFailure: settings?.onFailure ?? true,\n\t\tonAbort: settings?.onAbort ?? true,\n\t\tterminalBellFallback: settings?.terminalBellFallback ?? true,\n\t};\n}\n\nexport interface CompletionSoundSurface {\n\t/** Only the interactive TUI plays sounds by default (§17.4). */\n\treadonly isTui: boolean;\n\treadonly isTty: boolean;\n\treadonly isCi: boolean;\n}\n\n/** §17.1/§17.4 gate: settings, outcome mapping, duration floor, and surface. */\nexport function shouldPlayCompletionSound(input: {\n\treadonly settings: ResolvedCompletionSoundSettings;\n\treadonly event: PromptSettledEvent;\n\treadonly surface: CompletionSoundSurface;\n}): boolean {\n\tconst { settings, event, surface } = input;\n\tif (!settings.enabled || !surface.isTui || !surface.isTty || surface.isCi) {\n\t\treturn false;\n\t}\n\tswitch (event.outcome) {\n\t\tcase \"completed\":\n\t\t\treturn event.durationMs >= settings.minDurationMs && settings.onSuccess;\n\t\tcase \"failed\":\n\t\t\treturn settings.onFailure;\n\t\tcase \"aborted\":\n\t\t\treturn settings.onAbort ?? true;\n\t\tdefault: {\n\t\t\tconst exhaustive: never = event.outcome;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\nexport interface CompletionSoundCandidate {\n\treadonly backend: CompletionSoundBackend;\n\t/** Fixed argv (§22.1); empty for terminal-bell (written, not spawned). */\n\treadonly argv: readonly string[];\n}\n\n/**\n * Deterministic backend candidate chain per platform (§17.3, §23.2 property\n * 14). The runner tries candidates in order on spawn failure.\n */\nexport function selectCompletionSoundCandidates(input: {\n\treadonly platform: NodeJS.Platform;\n\treadonly isWsl: boolean;\n\treadonly terminalBellFallback: boolean;\n}): readonly CompletionSoundCandidate[] {\n\tconst bell: CompletionSoundCandidate[] = input.terminalBellFallback ? [{ backend: \"terminal-bell\", argv: [] }] : [];\n\tif (input.platform === \"darwin\") {\n\t\treturn [{ backend: \"macos-afplay\", argv: [\"/usr/bin/afplay\", \"/System/Library/Sounds/Glass.aiff\"] }, ...bell];\n\t}\n\tif (input.platform === \"win32\") {\n\t\treturn [\n\t\t\t{\n\t\t\t\tbackend: \"windows-system-sound\",\n\t\t\t\targv: windowsSystemSoundArgv(\"C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\"),\n\t\t\t},\n\t\t\t...bell,\n\t\t];\n\t}\n\tif (input.platform === \"linux\" && input.isWsl) {\n\t\t// WSL has no trustworthy fixed mount path for Windows PowerShell; use BEL.\n\t\treturn [...bell];\n\t}\n\tif (input.platform === \"linux\") {\n\t\treturn [\n\t\t\t{ backend: \"linux-canberra\", argv: [\"/usr/bin/canberra-gtk-play\", \"-i\", \"complete\"] },\n\t\t\t{ backend: \"linux-paplay\", argv: [\"/usr/bin/paplay\", \"/usr/share/sounds/freedesktop/stereo/complete.oga\"] },\n\t\t\t{ backend: \"linux-aplay\", argv: [\"/usr/bin/aplay\", \"-q\", \"/usr/share/sounds/alsa/Front_Center.wav\"] },\n\t\t\t...bell,\n\t\t];\n\t}\n\treturn [...bell];\n}\n\n/** Fixed expression only (§17.3 Windows): no user text ever enters the command. */\nfunction windowsSystemSoundArgv(executable: string): readonly string[] {\n\treturn [executable, \"-NoProfile\", \"-NonInteractive\", \"-Command\", \"[System.Media.SystemSounds]::Asterisk.Play()\"];\n}\n\n/**\n * Stateful service: once per promptRunId (§17.4), deterministic candidate\n * walk, all failures downgraded to diagnostics. `handleSettled` is fire and\n * forget — callers must not await it on the prompt path.\n */\nexport interface CompletionSoundServiceDeps {\n\treadonly getSettings: () => CompletionSoundSettings | undefined;\n\treadonly surface: () => CompletionSoundSurface;\n\treadonly candidates: () => readonly CompletionSoundCandidate[];\n\treadonly io?: CompletionSoundIo;\n\treadonly env?: NodeJS.ProcessEnv;\n\t/** §20.2 observability hook; fail-open, never affects the result. */\n\treadonly onResult?: (result: CompletionSoundResult) => void;\n}\n\nexport class CompletionSoundService {\n\tprivate readonly playedRunIds = new Set<string>();\n\tprivate lastResult: CompletionSoundResult | null = null;\n\tprivate readonly deps: CompletionSoundServiceDeps;\n\n\tconstructor(deps: CompletionSoundServiceDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/** Most recent attempt, for diagnostics/tests. */\n\tget lastPlaybackResult(): CompletionSoundResult | null {\n\t\treturn this.lastResult;\n\t}\n\n\tasync handleSettled(event: PromptSettledEvent): Promise<CompletionSoundResult> {\n\t\ttry {\n\t\t\tconst settings = resolveCompletionSoundSettings(this.deps.getSettings(), this.deps.env ?? process.env);\n\t\t\tif (this.playedRunIds.has(event.promptRunId)) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: false, diagnostic: \"already_played\" });\n\t\t\t}\n\t\t\tif (!shouldPlayCompletionSound({ settings, event, surface: this.deps.surface() })) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: true });\n\t\t\t}\n\t\t\tthis.playedRunIds.add(event.promptRunId);\n\t\t\tconst io = this.deps.io ?? defaultCompletionSoundIo();\n\t\t\tconst diagnostics: string[] = [];\n\t\t\tfor (const candidate of this.deps.candidates()) {\n\t\t\t\tif (candidate.backend === \"terminal-bell\") {\n\t\t\t\t\tconst ok = io.writeBell();\n\t\t\t\t\treturn this.finish({\n\t\t\t\t\t\tbackend: \"terminal-bell\",\n\t\t\t\t\t\tattempted: true,\n\t\t\t\t\t\tsuccess: ok,\n\t\t\t\t\t\tdiagnostic: diagnostics.length > 0 ? diagnostics.join(\", \") : undefined,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tconst spawned = await io.spawnBackend(candidate.argv);\n\t\t\t\tif (spawned.ok) {\n\t\t\t\t\treturn this.finish({ backend: candidate.backend, attempted: true, success: true });\n\t\t\t\t}\n\t\t\t\tdiagnostics.push(`${candidate.backend}: ${spawned.diagnostic ?? \"failed\"}`);\n\t\t\t}\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: diagnostics.join(\", \") });\n\t\t} catch (error) {\n\t\t\t// §23.2 property 13: sound failure never changes the prompt outcome.\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: String(error) });\n\t\t}\n\t}\n\n\tprivate finish(result: CompletionSoundResult): CompletionSoundResult {\n\t\tthis.lastResult = result;\n\t\ttry {\n\t\t\tthis.deps.onResult?.(result);\n\t\t} catch {\n\t\t\t// Observability must never affect the sound path.\n\t\t}\n\t\treturn result;\n\t}\n}\n"]}

package/dist/core/completion-sound.js

@@ -1,9 +1,9 @@
-import { spawn } from "node:child_process";
+import { defaultCompletionSoundIo } from "./completion-sound-io.js";
+export { completionSoundProcessOptions, defaultCompletionSoundIo, } from "./completion-sound-io.js";
 export const COMPLETION_SOUND_ENV = "OMK_COMPLETION_SOUND";
-const SPAWN_KILL_TIMEOUT_MS = 1000;
 /** Defaults per §17.1; `OMK_COMPLETION_SOUND=0|1` (§18.2) overrides `enabled`. */
 export function resolveCompletionSoundSettings(settings, env = process.env) {
-    let enabled = settings?.enabled ?? false;
+    let enabled = settings?.enabled ?? true;
     const envValue = env[COMPLETION_SOUND_ENV]?.trim();
     if (envValue === "0") {
         enabled = false;
@@ -16,6 +16,7 @@ export function resolveCompletionSoundSettings(settings, env = process.env) {
         minDurationMs: typeof settings?.minDurationMs === "number" && settings.minDurationMs >= 0 ? settings.minDurationMs : 5000,
         onSuccess: settings?.onSuccess ?? true,
         onFailure: settings?.onFailure ?? true,
+        onAbort: settings?.onAbort ?? true,
         terminalBellFallback: settings?.terminalBellFallback ?? true,
     };
 }
@@ -25,17 +26,18 @@ export function shouldPlayCompletionSound(input) {
     if (!settings.enabled || !surface.isTui || !surface.isTty || surface.isCi) {
         return false;
     }
-    if (event.durationMs < settings.minDurationMs) {
-        return false;
-    }
-    if (event.outcome === "completed") {
-        return settings.onSuccess;
-    }
-    if (event.outcome === "failed") {
-        return settings.onFailure;
+    switch (event.outcome) {
+        case "completed":
+            return event.durationMs >= settings.minDurationMs && settings.onSuccess;
+        case "failed":
+            return settings.onFailure;
+        case "aborted":
+            return settings.onAbort ?? true;
+        default: {
+            const exhaustive = event.outcome;
+            return exhaustive;
+        }
     }
-    // User-initiated aborts never chime: the user is already at the keyboard.
-    return false;
 }
 /**
  * Deterministic backend candidate chain per platform (§17.3, §23.2 property
@@ -44,20 +46,26 @@ export function shouldPlayCompletionSound(input) {
 export function selectCompletionSoundCandidates(input) {
     const bell = input.terminalBellFallback ? [{ backend: "terminal-bell", argv: [] }] : [];
     if (input.platform === "darwin") {
-        return [{ backend: "macos-afplay", argv: ["afplay", "/System/Library/Sounds/Glass.aiff"] }, ...bell];
+        return [{ backend: "macos-afplay", argv: ["/usr/bin/afplay", "/System/Library/Sounds/Glass.aiff"] }, ...bell];
     }
     if (input.platform === "win32") {
-        return [{ backend: "windows-system-sound", argv: windowsSystemSoundArgv("powershell.exe") }, ...bell];
+        return [
+            {
+                backend: "windows-system-sound",
+                argv: windowsSystemSoundArgv("C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"),
+            },
+            ...bell,
+        ];
     }
     if (input.platform === "linux" && input.isWsl) {
-        // §17.3 WSL: Windows PowerShell first, then the terminal BEL.
-        return [{ backend: "windows-system-sound", argv: windowsSystemSoundArgv("powershell.exe") }, ...bell];
+        // WSL has no trustworthy fixed mount path for Windows PowerShell; use BEL.
+        return [...bell];
     }
     if (input.platform === "linux") {
         return [
-            { backend: "linux-canberra", argv: ["canberra-gtk-play", "-i", "complete"] },
-            { backend: "linux-paplay", argv: ["paplay", "/usr/share/sounds/freedesktop/stereo/complete.oga"] },
-            { backend: "linux-aplay", argv: ["aplay", "-q", "/usr/share/sounds/alsa/Front_Center.wav"] },
+            { backend: "linux-canberra", argv: ["/usr/bin/canberra-gtk-play", "-i", "complete"] },
+            { backend: "linux-paplay", argv: ["/usr/bin/paplay", "/usr/share/sounds/freedesktop/stereo/complete.oga"] },
+            { backend: "linux-aplay", argv: ["/usr/bin/aplay", "-q", "/usr/share/sounds/alsa/Front_Center.wav"] },
             ...bell,
         ];
     }
@@ -67,44 +75,6 @@ export function selectCompletionSoundCandidates(input) {
 function windowsSystemSoundArgv(executable) {
     return [executable, "-NoProfile", "-NonInteractive", "-Command", "[System.Media.SystemSounds]::Asterisk.Play()"];
 }
-/** Default IO: detached-ish fire-and-forget spawn per §17.4. */
-export function defaultCompletionSoundIo() {
-    return {
-        spawnBackend: (argv) => new Promise((resolve) => {
-            try {
-                const [executable, ...args] = argv;
-                const child = spawn(executable, args, { stdio: "ignore", shell: false, windowsHide: true });
-                const killTimer = setTimeout(() => {
-                    try {
-                        child.kill();
-                    }
-                    catch {
-                        // Best effort only.
-                    }
-                }, SPAWN_KILL_TIMEOUT_MS);
-                killTimer.unref();
-                child.once("error", (error) => resolve({ ok: false, diagnostic: error.code ?? "spawn_error" }));
-                // Success means "spawned"; playback is not awaited (§17.4).
-                child.once("spawn", () => {
-                    child.unref();
-                    resolve({ ok: true });
-                });
-            }
-            catch {
-                resolve({ ok: false, diagnostic: "spawn_error" });
-            }
-        }),
-        writeBell: () => {
-            try {
-                process.stdout.write("\u0007");
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-    };
-}
 export class CompletionSoundService {
     playedRunIds = new Set();
     lastResult = null;

package/dist/core/completion-sound.js.map

@@ -1 +1 @@
-{"version":3,"file":"completion-sound.js","sourceRoot":"","sources":["../../src/core/completion-sound.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"node:child_process\";\nimport type { PromptSettledEvent } from \"./prompt-settlement.ts\";\n\n/**\n * Cross-platform completion sound service (OMK v0.97.x roadmap §17, M4/PR7).\n *\n * Consumes `prompt_settled` only (§16.1: never `agent_end`) and is a pure UX\n * signal — it must never influence run outcome, block the event loop, or\n * delay process exit (§17.4: spawn with `stdio: \"ignore\"`, `shell: false`,\n * `unref()`, bounded kill timer, never awaited by the prompt path).\n *\n * Security (§22.1): every backend uses a fixed executable and fixed argv;\n * no user text, paths, or model output is ever interpolated.\n *\n * Backend selection is a deterministic candidate chain per platform\n * (§17.3); a spawn failure falls through to the next candidate and finally\n * to the terminal BEL. All failures are diagnostics only (§4.6).\n */\n\nexport interface CompletionSoundSettings {\n\tenabled?: boolean; // default: false (§17.1: backward compat, CI/headless surprise, accessibility)\n\tminDurationMs?: number; // default: 5000\n\tonSuccess?: boolean; // default: true\n\tonFailure?: boolean; // default: true\n\tterminalBellFallback?: boolean; // default: true\n}\n\nexport interface NotificationSettings {\n\tcompletionSound?: CompletionSoundSettings;\n}\n\nexport type CompletionSoundBackend =\n\t| \"macos-afplay\"\n\t| \"windows-system-sound\"\n\t| \"linux-canberra\"\n\t| \"linux-paplay\"\n\t| \"linux-aplay\"\n\t| \"terminal-bell\"\n\t| \"none\";\n\nexport interface CompletionSoundRequest {\n\treadonly promptRunId: string;\n\treadonly outcome: \"completed\" | \"failed\" | \"aborted\";\n\treadonly durationMs: number;\n}\n\nexport interface CompletionSoundResult {\n\treadonly backend: CompletionSoundBackend;\n\treadonly attempted: boolean;\n\treadonly success: boolean;\n\treadonly diagnostic?: string;\n}\n\nexport const COMPLETION_SOUND_ENV = \"OMK_COMPLETION_SOUND\";\nconst SPAWN_KILL_TIMEOUT_MS = 1000;\n\nexport interface ResolvedCompletionSoundSettings {\n\treadonly enabled: boolean;\n\treadonly minDurationMs: number;\n\treadonly onSuccess: boolean;\n\treadonly onFailure: boolean;\n\treadonly terminalBellFallback: boolean;\n}\n\n/** Defaults per §17.1; `OMK_COMPLETION_SOUND=0|1` (§18.2) overrides `enabled`. */\nexport function resolveCompletionSoundSettings(\n\tsettings?: CompletionSoundSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedCompletionSoundSettings {\n\tlet enabled = settings?.enabled ?? false;\n\tconst envValue = env[COMPLETION_SOUND_ENV]?.trim();\n\tif (envValue === \"0\") {\n\t\tenabled = false;\n\t} else if (envValue === \"1\") {\n\t\tenabled = true;\n\t}\n\treturn {\n\t\tenabled,\n\t\tminDurationMs:\n\t\t\ttypeof settings?.minDurationMs === \"number\" && settings.minDurationMs >= 0 ? settings.minDurationMs : 5000,\n\t\tonSuccess: settings?.onSuccess ?? true,\n\t\tonFailure: settings?.onFailure ?? true,\n\t\tterminalBellFallback: settings?.terminalBellFallback ?? true,\n\t};\n}\n\nexport interface CompletionSoundSurface {\n\t/** Only the interactive TUI plays sounds by default (§17.4). */\n\treadonly isTui: boolean;\n\treadonly isTty: boolean;\n\treadonly isCi: boolean;\n}\n\n/** §17.1/§17.4 gate: settings, outcome mapping, duration floor, and surface. */\nexport function shouldPlayCompletionSound(input: {\n\treadonly settings: ResolvedCompletionSoundSettings;\n\treadonly event: PromptSettledEvent;\n\treadonly surface: CompletionSoundSurface;\n}): boolean {\n\tconst { settings, event, surface } = input;\n\tif (!settings.enabled || !surface.isTui || !surface.isTty || surface.isCi) {\n\t\treturn false;\n\t}\n\tif (event.durationMs < settings.minDurationMs) {\n\t\treturn false;\n\t}\n\tif (event.outcome === \"completed\") {\n\t\treturn settings.onSuccess;\n\t}\n\tif (event.outcome === \"failed\") {\n\t\treturn settings.onFailure;\n\t}\n\t// User-initiated aborts never chime: the user is already at the keyboard.\n\treturn false;\n}\n\nexport interface CompletionSoundCandidate {\n\treadonly backend: CompletionSoundBackend;\n\t/** Fixed argv (§22.1); empty for terminal-bell (written, not spawned). */\n\treadonly argv: readonly string[];\n}\n\n/**\n * Deterministic backend candidate chain per platform (§17.3, §23.2 property\n * 14). The runner tries candidates in order on spawn failure.\n */\nexport function selectCompletionSoundCandidates(input: {\n\treadonly platform: NodeJS.Platform;\n\treadonly isWsl: boolean;\n\treadonly terminalBellFallback: boolean;\n}): readonly CompletionSoundCandidate[] {\n\tconst bell: CompletionSoundCandidate[] = input.terminalBellFallback ? [{ backend: \"terminal-bell\", argv: [] }] : [];\n\tif (input.platform === \"darwin\") {\n\t\treturn [{ backend: \"macos-afplay\", argv: [\"afplay\", \"/System/Library/Sounds/Glass.aiff\"] }, ...bell];\n\t}\n\tif (input.platform === \"win32\") {\n\t\treturn [{ backend: \"windows-system-sound\", argv: windowsSystemSoundArgv(\"powershell.exe\") }, ...bell];\n\t}\n\tif (input.platform === \"linux\" && input.isWsl) {\n\t\t// §17.3 WSL: Windows PowerShell first, then the terminal BEL.\n\t\treturn [{ backend: \"windows-system-sound\", argv: windowsSystemSoundArgv(\"powershell.exe\") }, ...bell];\n\t}\n\tif (input.platform === \"linux\") {\n\t\treturn [\n\t\t\t{ backend: \"linux-canberra\", argv: [\"canberra-gtk-play\", \"-i\", \"complete\"] },\n\t\t\t{ backend: \"linux-paplay\", argv: [\"paplay\", \"/usr/share/sounds/freedesktop/stereo/complete.oga\"] },\n\t\t\t{ backend: \"linux-aplay\", argv: [\"aplay\", \"-q\", \"/usr/share/sounds/alsa/Front_Center.wav\"] },\n\t\t\t...bell,\n\t\t];\n\t}\n\treturn [...bell];\n}\n\n/** Fixed expression only (§17.3 Windows): no user text ever enters the command. */\nfunction windowsSystemSoundArgv(executable: string): readonly string[] {\n\treturn [executable, \"-NoProfile\", \"-NonInteractive\", \"-Command\", \"[System.Media.SystemSounds]::Asterisk.Play()\"];\n}\n\nexport interface CompletionSoundIo {\n\t/** Spawn a fixed argv; resolve success/failure. Must never throw synchronously into the caller. */\n\treadonly spawnBackend: (argv: readonly string[]) => Promise<{ readonly ok: boolean; readonly diagnostic?: string }>;\n\treadonly writeBell: () => boolean;\n}\n\n/** Default IO: detached-ish fire-and-forget spawn per §17.4. */\nexport function defaultCompletionSoundIo(): CompletionSoundIo {\n\treturn {\n\t\tspawnBackend: (argv) =>\n\t\t\tnew Promise((resolve) => {\n\t\t\t\ttry {\n\t\t\t\t\tconst [executable, ...args] = argv;\n\t\t\t\t\tconst child = spawn(executable, args, { stdio: \"ignore\", shell: false, windowsHide: true });\n\t\t\t\t\tconst killTimer = setTimeout(() => {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tchild.kill();\n\t\t\t\t\t\t} catch {\n\t\t\t\t\t\t\t// Best effort only.\n\t\t\t\t\t\t}\n\t\t\t\t\t}, SPAWN_KILL_TIMEOUT_MS);\n\t\t\t\t\tkillTimer.unref();\n\t\t\t\t\tchild.once(\"error\", (error: NodeJS.ErrnoException) =>\n\t\t\t\t\t\tresolve({ ok: false, diagnostic: error.code ?? \"spawn_error\" }),\n\t\t\t\t\t);\n\t\t\t\t\t// Success means \"spawned\"; playback is not awaited (§17.4).\n\t\t\t\t\tchild.once(\"spawn\", () => {\n\t\t\t\t\t\tchild.unref();\n\t\t\t\t\t\tresolve({ ok: true });\n\t\t\t\t\t});\n\t\t\t\t} catch {\n\t\t\t\t\tresolve({ ok: false, diagnostic: \"spawn_error\" });\n\t\t\t\t}\n\t\t\t}),\n\t\twriteBell: () => {\n\t\t\ttry {\n\t\t\t\tprocess.stdout.write(\"\\u0007\");\n\t\t\t\treturn true;\n\t\t\t} catch {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t},\n\t};\n}\n\n/**\n * Stateful service: once per promptRunId (§17.4), deterministic candidate\n * walk, all failures downgraded to diagnostics. `handleSettled` is fire and\n * forget — callers must not await it on the prompt path.\n */\nexport interface CompletionSoundServiceDeps {\n\treadonly getSettings: () => CompletionSoundSettings | undefined;\n\treadonly surface: () => CompletionSoundSurface;\n\treadonly candidates: () => readonly CompletionSoundCandidate[];\n\treadonly io?: CompletionSoundIo;\n\treadonly env?: NodeJS.ProcessEnv;\n\t/** §20.2 observability hook; fail-open, never affects the result. */\n\treadonly onResult?: (result: CompletionSoundResult) => void;\n}\n\nexport class CompletionSoundService {\n\tprivate readonly playedRunIds = new Set<string>();\n\tprivate lastResult: CompletionSoundResult | null = null;\n\tprivate readonly deps: CompletionSoundServiceDeps;\n\n\tconstructor(deps: CompletionSoundServiceDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/** Most recent attempt, for diagnostics/tests. */\n\tget lastPlaybackResult(): CompletionSoundResult | null {\n\t\treturn this.lastResult;\n\t}\n\n\tasync handleSettled(event: PromptSettledEvent): Promise<CompletionSoundResult> {\n\t\ttry {\n\t\t\tconst settings = resolveCompletionSoundSettings(this.deps.getSettings(), this.deps.env ?? process.env);\n\t\t\tif (this.playedRunIds.has(event.promptRunId)) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: false, diagnostic: \"already_played\" });\n\t\t\t}\n\t\t\tif (!shouldPlayCompletionSound({ settings, event, surface: this.deps.surface() })) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: true });\n\t\t\t}\n\t\t\tthis.playedRunIds.add(event.promptRunId);\n\t\t\tconst io = this.deps.io ?? defaultCompletionSoundIo();\n\t\t\tconst diagnostics: string[] = [];\n\t\t\tfor (const candidate of this.deps.candidates()) {\n\t\t\t\tif (candidate.backend === \"terminal-bell\") {\n\t\t\t\t\tconst ok = io.writeBell();\n\t\t\t\t\treturn this.finish({\n\t\t\t\t\t\tbackend: \"terminal-bell\",\n\t\t\t\t\t\tattempted: true,\n\t\t\t\t\t\tsuccess: ok,\n\t\t\t\t\t\tdiagnostic: diagnostics.length > 0 ? diagnostics.join(\", \") : undefined,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tconst spawned = await io.spawnBackend(candidate.argv);\n\t\t\t\tif (spawned.ok) {\n\t\t\t\t\treturn this.finish({ backend: candidate.backend, attempted: true, success: true });\n\t\t\t\t}\n\t\t\t\tdiagnostics.push(`${candidate.backend}: ${spawned.diagnostic ?? \"failed\"}`);\n\t\t\t}\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: diagnostics.join(\", \") });\n\t\t} catch (error) {\n\t\t\t// §23.2 property 13: sound failure never changes the prompt outcome.\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: String(error) });\n\t\t}\n\t}\n\n\tprivate finish(result: CompletionSoundResult): CompletionSoundResult {\n\t\tthis.lastResult = result;\n\t\ttry {\n\t\t\tthis.deps.onResult?.(result);\n\t\t} catch {\n\t\t\t// Observability must never affect the sound path.\n\t\t}\n\t\treturn result;\n\t}\n}\n"]}
+{"version":3,"file":"completion-sound.js","sourceRoot":"","sources":["../../src/core/completion-sound.ts"],"names":[],"mappings":"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","sourcesContent":["import { type CompletionSoundIo, defaultCompletionSoundIo } from \"./completion-sound-io.ts\";\nimport type { PromptSettledEvent } from \"./prompt-settlement.ts\";\n\nexport {\n\ttype CompletionSoundIo,\n\tcompletionSoundProcessOptions,\n\tdefaultCompletionSoundIo,\n} from \"./completion-sound-io.ts\";\n\n/**\n * Cross-platform completion sound service (OMK v0.97.x roadmap §17, M4/PR7).\n *\n * Consumes `prompt_settled` only (§16.1: never `agent_end`) and is a pure UX\n * signal — it must never influence run outcome, block the event loop, or\n * delay process exit (§17.4: spawn with `stdio: \"ignore\"`, `shell: false`,\n * `unref()`, bounded kill timer, never awaited by the prompt path).\n *\n * Security (§22.1): every backend uses a fixed executable and fixed argv;\n * no user text, paths, or model output is ever interpolated.\n *\n * Backend selection is a deterministic candidate chain per platform\n * (§17.3); a spawn failure falls through to the next candidate and finally\n * to the terminal BEL. All failures are diagnostics only (§4.6).\n */\n\nexport interface CompletionSoundSettings {\n\tenabled?: boolean; // default: true; interactive TTY only, with OMK_COMPLETION_SOUND=0 opt-out\n\tminDurationMs?: number; // default: 5000; applies to successful completion only\n\tonSuccess?: boolean; // default: true\n\tonFailure?: boolean; // default: true\n\tonAbort?: boolean; // default: true\n\tterminalBellFallback?: boolean; // default: true\n}\n\nexport interface NotificationSettings {\n\tcompletionSound?: CompletionSoundSettings;\n}\n\nexport type CompletionSoundBackend =\n\t| \"macos-afplay\"\n\t| \"windows-system-sound\"\n\t| \"linux-canberra\"\n\t| \"linux-paplay\"\n\t| \"linux-aplay\"\n\t| \"terminal-bell\"\n\t| \"none\";\n\nexport interface CompletionSoundRequest {\n\treadonly promptRunId: string;\n\treadonly outcome: \"completed\" | \"failed\" | \"aborted\";\n\treadonly durationMs: number;\n}\n\nexport interface CompletionSoundResult {\n\treadonly backend: CompletionSoundBackend;\n\treadonly attempted: boolean;\n\treadonly success: boolean;\n\treadonly diagnostic?: string;\n}\n\nexport const COMPLETION_SOUND_ENV = \"OMK_COMPLETION_SOUND\";\nexport interface ResolvedCompletionSoundSettings {\n\treadonly enabled: boolean;\n\treadonly minDurationMs: number;\n\treadonly onSuccess: boolean;\n\treadonly onFailure: boolean;\n\treadonly onAbort?: boolean;\n\treadonly terminalBellFallback: boolean;\n}\n\n/** Defaults per §17.1; `OMK_COMPLETION_SOUND=0|1` (§18.2) overrides `enabled`. */\nexport function resolveCompletionSoundSettings(\n\tsettings?: CompletionSoundSettings,\n\tenv: NodeJS.ProcessEnv = process.env,\n): ResolvedCompletionSoundSettings {\n\tlet enabled = settings?.enabled ?? true;\n\tconst envValue = env[COMPLETION_SOUND_ENV]?.trim();\n\tif (envValue === \"0\") {\n\t\tenabled = false;\n\t} else if (envValue === \"1\") {\n\t\tenabled = true;\n\t}\n\treturn {\n\t\tenabled,\n\t\tminDurationMs:\n\t\t\ttypeof settings?.minDurationMs === \"number\" && settings.minDurationMs >= 0 ? settings.minDurationMs : 5000,\n\t\tonSuccess: settings?.onSuccess ?? true,\n\t\tonFailure: settings?.onFailure ?? true,\n\t\tonAbort: settings?.onAbort ?? true,\n\t\tterminalBellFallback: settings?.terminalBellFallback ?? true,\n\t};\n}\n\nexport interface CompletionSoundSurface {\n\t/** Only the interactive TUI plays sounds by default (§17.4). */\n\treadonly isTui: boolean;\n\treadonly isTty: boolean;\n\treadonly isCi: boolean;\n}\n\n/** §17.1/§17.4 gate: settings, outcome mapping, duration floor, and surface. */\nexport function shouldPlayCompletionSound(input: {\n\treadonly settings: ResolvedCompletionSoundSettings;\n\treadonly event: PromptSettledEvent;\n\treadonly surface: CompletionSoundSurface;\n}): boolean {\n\tconst { settings, event, surface } = input;\n\tif (!settings.enabled || !surface.isTui || !surface.isTty || surface.isCi) {\n\t\treturn false;\n\t}\n\tswitch (event.outcome) {\n\t\tcase \"completed\":\n\t\t\treturn event.durationMs >= settings.minDurationMs && settings.onSuccess;\n\t\tcase \"failed\":\n\t\t\treturn settings.onFailure;\n\t\tcase \"aborted\":\n\t\t\treturn settings.onAbort ?? true;\n\t\tdefault: {\n\t\t\tconst exhaustive: never = event.outcome;\n\t\t\treturn exhaustive;\n\t\t}\n\t}\n}\n\nexport interface CompletionSoundCandidate {\n\treadonly backend: CompletionSoundBackend;\n\t/** Fixed argv (§22.1); empty for terminal-bell (written, not spawned). */\n\treadonly argv: readonly string[];\n}\n\n/**\n * Deterministic backend candidate chain per platform (§17.3, §23.2 property\n * 14). The runner tries candidates in order on spawn failure.\n */\nexport function selectCompletionSoundCandidates(input: {\n\treadonly platform: NodeJS.Platform;\n\treadonly isWsl: boolean;\n\treadonly terminalBellFallback: boolean;\n}): readonly CompletionSoundCandidate[] {\n\tconst bell: CompletionSoundCandidate[] = input.terminalBellFallback ? [{ backend: \"terminal-bell\", argv: [] }] : [];\n\tif (input.platform === \"darwin\") {\n\t\treturn [{ backend: \"macos-afplay\", argv: [\"/usr/bin/afplay\", \"/System/Library/Sounds/Glass.aiff\"] }, ...bell];\n\t}\n\tif (input.platform === \"win32\") {\n\t\treturn [\n\t\t\t{\n\t\t\t\tbackend: \"windows-system-sound\",\n\t\t\t\targv: windowsSystemSoundArgv(\"C:\\\\Windows\\\\System32\\\\WindowsPowerShell\\\\v1.0\\\\powershell.exe\"),\n\t\t\t},\n\t\t\t...bell,\n\t\t];\n\t}\n\tif (input.platform === \"linux\" && input.isWsl) {\n\t\t// WSL has no trustworthy fixed mount path for Windows PowerShell; use BEL.\n\t\treturn [...bell];\n\t}\n\tif (input.platform === \"linux\") {\n\t\treturn [\n\t\t\t{ backend: \"linux-canberra\", argv: [\"/usr/bin/canberra-gtk-play\", \"-i\", \"complete\"] },\n\t\t\t{ backend: \"linux-paplay\", argv: [\"/usr/bin/paplay\", \"/usr/share/sounds/freedesktop/stereo/complete.oga\"] },\n\t\t\t{ backend: \"linux-aplay\", argv: [\"/usr/bin/aplay\", \"-q\", \"/usr/share/sounds/alsa/Front_Center.wav\"] },\n\t\t\t...bell,\n\t\t];\n\t}\n\treturn [...bell];\n}\n\n/** Fixed expression only (§17.3 Windows): no user text ever enters the command. */\nfunction windowsSystemSoundArgv(executable: string): readonly string[] {\n\treturn [executable, \"-NoProfile\", \"-NonInteractive\", \"-Command\", \"[System.Media.SystemSounds]::Asterisk.Play()\"];\n}\n\n/**\n * Stateful service: once per promptRunId (§17.4), deterministic candidate\n * walk, all failures downgraded to diagnostics. `handleSettled` is fire and\n * forget — callers must not await it on the prompt path.\n */\nexport interface CompletionSoundServiceDeps {\n\treadonly getSettings: () => CompletionSoundSettings | undefined;\n\treadonly surface: () => CompletionSoundSurface;\n\treadonly candidates: () => readonly CompletionSoundCandidate[];\n\treadonly io?: CompletionSoundIo;\n\treadonly env?: NodeJS.ProcessEnv;\n\t/** §20.2 observability hook; fail-open, never affects the result. */\n\treadonly onResult?: (result: CompletionSoundResult) => void;\n}\n\nexport class CompletionSoundService {\n\tprivate readonly playedRunIds = new Set<string>();\n\tprivate lastResult: CompletionSoundResult | null = null;\n\tprivate readonly deps: CompletionSoundServiceDeps;\n\n\tconstructor(deps: CompletionSoundServiceDeps) {\n\t\tthis.deps = deps;\n\t}\n\n\t/** Most recent attempt, for diagnostics/tests. */\n\tget lastPlaybackResult(): CompletionSoundResult | null {\n\t\treturn this.lastResult;\n\t}\n\n\tasync handleSettled(event: PromptSettledEvent): Promise<CompletionSoundResult> {\n\t\ttry {\n\t\t\tconst settings = resolveCompletionSoundSettings(this.deps.getSettings(), this.deps.env ?? process.env);\n\t\t\tif (this.playedRunIds.has(event.promptRunId)) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: false, diagnostic: \"already_played\" });\n\t\t\t}\n\t\t\tif (!shouldPlayCompletionSound({ settings, event, surface: this.deps.surface() })) {\n\t\t\t\treturn this.finish({ backend: \"none\", attempted: false, success: true });\n\t\t\t}\n\t\t\tthis.playedRunIds.add(event.promptRunId);\n\t\t\tconst io = this.deps.io ?? defaultCompletionSoundIo();\n\t\t\tconst diagnostics: string[] = [];\n\t\t\tfor (const candidate of this.deps.candidates()) {\n\t\t\t\tif (candidate.backend === \"terminal-bell\") {\n\t\t\t\t\tconst ok = io.writeBell();\n\t\t\t\t\treturn this.finish({\n\t\t\t\t\t\tbackend: \"terminal-bell\",\n\t\t\t\t\t\tattempted: true,\n\t\t\t\t\t\tsuccess: ok,\n\t\t\t\t\t\tdiagnostic: diagnostics.length > 0 ? diagnostics.join(\", \") : undefined,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t\tconst spawned = await io.spawnBackend(candidate.argv);\n\t\t\t\tif (spawned.ok) {\n\t\t\t\t\treturn this.finish({ backend: candidate.backend, attempted: true, success: true });\n\t\t\t\t}\n\t\t\t\tdiagnostics.push(`${candidate.backend}: ${spawned.diagnostic ?? \"failed\"}`);\n\t\t\t}\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: diagnostics.join(\", \") });\n\t\t} catch (error) {\n\t\t\t// §23.2 property 13: sound failure never changes the prompt outcome.\n\t\t\treturn this.finish({ backend: \"none\", attempted: true, success: false, diagnostic: String(error) });\n\t\t}\n\t}\n\n\tprivate finish(result: CompletionSoundResult): CompletionSoundResult {\n\t\tthis.lastResult = result;\n\t\ttry {\n\t\t\tthis.deps.onResult?.(result);\n\t\t} catch {\n\t\t\t// Observability must never affect the sound path.\n\t\t}\n\t\treturn result;\n\t}\n}\n"]}

package/dist/core/context-budget-relevance.d.ts

@@ -33,10 +33,23 @@ export declare function scoreSkillRelevance(skill: {
 /**
  * Score context file relevance against a query context.
  *
- * - queryContext undefined -> isGlobal ? 0.9 : 0.6
+ * - Baseline (no query evidence) -> isGlobal ? 0.9 : 0.6
  * - Coverage of query tokens against path segments + content sample
  * - Path tokens weighted 2x
- * - isGlobal bonus: +0.1
+ * - Coverage allocates the headroom ABOVE the baseline; it never cuts into it
+ *
+ * A context file is not retrieved reference material — it is the standing
+ * instruction set the agent is required to follow, and it applies whether or
+ * not the user's current sentence reuses its vocabulary. Scoring it purely by
+ * lexical overlap made the rules rank LOWEST exactly when the agent was doing
+ * work: this repository's own AGENTS.md scored 0.9 idle but 0.1 under queries
+ * like "rename this variable". Coverage therefore raises the score from the
+ * baseline toward 1 instead of replacing it, which also reconciles the two
+ * readings the function used to have — an absent query and a present-but-
+ * non-overlapping query now agree that there is simply no evidence to add.
+ *
+ * Lexical scoring stays the right metric for skills, which really are
+ * topic-scoped; see scoreSkillRelevance.
  */
 export declare function scoreContextFileRelevance(contextFile: {
     readonly path: string;

package/dist/core/context-budget-relevance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-relevance.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-relevance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyJH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAmCpE;AAkED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC9D,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CA2BR;AAYD;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACxC,WAAW,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EAC5F,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CAkCR","sourcesContent":["/**\n * Query-aware relevance scoring for context budget items.\n *\n * Replaces heuristic proxies (description length, isGlobal hardcoding)\n * with token-based coverage scoring that measures semantic overlap\n * between the current query context and each resource item.\n *\n * Design: Coverage-based IR (not Jaccard) — avoids penalizing long\n * descriptions whose large union would dilute the score.\n */\n\n// ---------------------------------------------------------------------------\n// Stop words — English + common Korean particles\n// ---------------------------------------------------------------------------\n\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n\t// English common stop words\n\t\"the\",\n\t\"a\",\n\t\"an\",\n\t\"is\",\n\t\"are\",\n\t\"was\",\n\t\"were\",\n\t\"be\",\n\t\"been\",\n\t\"being\",\n\t\"have\",\n\t\"has\",\n\t\"had\",\n\t\"do\",\n\t\"does\",\n\t\"did\",\n\t\"will\",\n\t\"would\",\n\t\"could\",\n\t\"should\",\n\t\"may\",\n\t\"might\",\n\t\"shall\",\n\t\"can\",\n\t\"to\",\n\t\"of\",\n\t\"in\",\n\t\"on\",\n\t\"for\",\n\t\"and\",\n\t\"or\",\n\t\"with\",\n\t\"how\",\n\t\"i\",\n\t\"you\",\n\t\"he\",\n\t\"she\",\n\t\"it\",\n\t\"we\",\n\t\"they\",\n\t\"me\",\n\t\"him\",\n\t\"her\",\n\t\"us\",\n\t\"them\",\n\t\"my\",\n\t\"your\",\n\t\"his\",\n\t\"its\",\n\t\"our\",\n\t\"their\",\n\t\"this\",\n\t\"that\",\n\t\"these\",\n\t\"those\",\n\t\"what\",\n\t\"which\",\n\t\"who\",\n\t\"whom\",\n\t\"where\",\n\t\"when\",\n\t\"why\",\n\t\"not\",\n\t\"no\",\n\t\"nor\",\n\t\"so\",\n\t\"if\",\n\t\"then\",\n\t\"than\",\n\t\"too\",\n\t\"very\",\n\t\"just\",\n\t\"about\",\n\t\"above\",\n\t\"after\",\n\t\"again\",\n\t\"all\",\n\t\"also\",\n\t\"am\",\n\t\"any\",\n\t\"because\",\n\t\"before\",\n\t\"between\",\n\t\"both\",\n\t\"but\",\n\t\"by\",\n\t\"from\",\n\t\"into\",\n\t\"more\",\n\t\"most\",\n\t\"other\",\n\t\"out\",\n\t\"over\",\n\t\"own\",\n\t\"same\",\n\t\"some\",\n\t\"such\",\n\t\"there\",\n\t\"up\",\n\t\"down\",\n\t\"here\",\n\t\"at\",\n\t\"as\",\n\t\"while\",\n\t\"through\",\n\t\"during\",\n\t\"each\",\n\t\"few\",\n\t\"further\",\n\t\"once\",\n\t\"only\",\n\t\"until\",\n\t// Korean particles (조사)\n\t\"은\",\n\t\"는\",\n\t\"이\",\n\t\"가\",\n\t\"을\",\n\t\"를\",\n\t\"에\",\n\t\"의\",\n\t\"와\",\n\t\"과\",\n\t\"도\",\n\t\"로\",\n\t\"으로\",\n\t\"에서\",\n\t\"까지\",\n\t\"부터\",\n\t\"만\",\n\t\"라도\",\n\t\"나\",\n\t\"이며\",\n\t\"이고\",\n\t\"이나\",\n\t\"라\",\n\t\"이다\",\n\t\"하다\",\n\t\"된\",\n]);\n\n// ---------------------------------------------------------------------------\n// Tokenizer\n// ---------------------------------------------------------------------------\n\n/**\n * Tokenize text for relevance scoring.\n *\n * 1. Lowercase\n * 2. Split: Latin words via regex, Korean syllable groups via regex\n * 3. Remove stop words\n * 4. Remove short Latin tokens (<=2 chars)\n * 5. Deduplicate\n */\nexport function tokenizeForRelevance(text: string): readonly string[] {\n\tconst lower = text.toLowerCase();\n\tconst raw = lower.match(/[\\uac00-\\ud7a3]+|[a-z0-9]+/g);\n\tif (!raw) {\n\t\treturn [];\n\t}\n\n\tconst seen = new Set<string>();\n\tconst tokens: string[] = [];\n\n\tfor (const token of raw) {\n\t\t// Skip stop words\n\t\tif (STOP_WORDS.has(token)) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Latin tokens, skip very short ones (<=2 chars)\n\t\tif (/^[a-z0-9]+$/.test(token) && token.length <= 2) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Korean, keep 2+ syllable groups\n\t\tif (/^[\\uac00-\\ud7a3]+$/.test(token)) {\n\t\t\tif (token.length >= 2 && !seen.has(token)) {\n\t\t\t\tseen.add(token);\n\t\t\t\ttokens.push(token);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\t// Deduplicate\n\t\tif (!seen.has(token)) {\n\t\t\tseen.add(token);\n\t\t\ttokens.push(token);\n\t\t}\n\t}\n\n\treturn tokens;\n}\n\n// ---------------------------------------------------------------------------\n// Coverage scoring\n// ---------------------------------------------------------------------------\n\n/**\n * Compute coverage: fraction of query tokens found in the item token set.\n * Optional per-token weights boost high-value matches (name, path).\n */\nfunction computeCoverage(\n\tqueryTokens: readonly string[],\n\titemTokenSet: ReadonlySet<string>,\n\titemTokenWeights?: ReadonlyMap<string, number>,\n): number {\n\tif (queryTokens.length === 0) {\n\t\treturn 0;\n\t}\n\n\tlet matchWeight = 0;\n\tfor (const qt of queryTokens) {\n\t\tif (itemTokenSet.has(qt)) {\n\t\t\tmatchWeight += itemTokenWeights?.get(qt) ?? 1;\n\t\t}\n\t}\n\n\t// Normalize: each query token contributes at most 1 to the numerator\n\treturn Math.min(1, matchWeight / queryTokens.length);\n}\n\n/**\n * Build a token set with optional high-weight tokens.\n */\nfunction buildWeightedTokenSet(\n\tbaseText: string,\n\thighWeightText: string | undefined,\n\tweight: number,\n): { tokens: Set<string>; weights: Map<string, number> } {\n\tconst baseTokens = tokenizeForRelevance(baseText);\n\tconst highTokens = highWeightText ? tokenizeForRelevance(highWeightText) : [];\n\n\tconst tokenSet = new Set<string>();\n\tconst weights = new Map<string, number>();\n\n\tfor (const t of baseTokens) {\n\t\ttokenSet.add(t);\n\t\tif (!weights.has(t)) {\n\t\t\tweights.set(t, 1);\n\t\t}\n\t}\n\tfor (const t of highTokens) {\n\t\ttokenSet.add(t);\n\t\tweights.set(t, Math.max(weights.get(t) ?? 0, weight));\n\t}\n\n\treturn { tokens: tokenSet, weights };\n}\n\n// ---------------------------------------------------------------------------\n// Skill relevance\n// ---------------------------------------------------------------------------\n\nconst SKILL_NEUTRAL_SCORE = 0.3;\nconst NAME_MATCH_BONUS = 0.2;\nconst NAME_TOKEN_WEIGHT = 3;\n\n/**\n * Score skill relevance against a query context.\n *\n * - queryContext undefined or empty -> 0.3 (neutral)\n * - Coverage of query tokens against skill name+description\n * - Name tokens weighted 3x\n * - Name substring match bonus: +0.2 (capped at 1.0)\n */\nexport function scoreSkillRelevance(\n\tskill: { readonly name: string; readonly description: string },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\t// Build skill token set: description is base, name tokens get 3x weight\n\tconst { tokens: skillTokenSet, weights: skillWeights } = buildWeightedTokenSet(\n\t\tskill.description,\n\t\tskill.name,\n\t\tNAME_TOKEN_WEIGHT,\n\t);\n\n\tlet score = computeCoverage(queryTokens, skillTokenSet, skillWeights);\n\n\t// Name substring bonus: if skill.name appears in query text (or vice versa)\n\tconst queryLower = queryContext.toLowerCase();\n\tconst nameLower = skill.name.toLowerCase();\n\tif (queryLower.includes(nameLower) || nameLower.includes(queryLower.trim())) {\n\t\tscore = Math.min(1, score + NAME_MATCH_BONUS);\n\t}\n\n\treturn clamp01(score);\n}\n\n// ---------------------------------------------------------------------------\n// Context file relevance\n// ---------------------------------------------------------------------------\n\nconst CONTEXT_NEUTRAL_GLOBAL = 0.9;\nconst CONTEXT_NEUTRAL_LOCAL = 0.6;\nconst PATH_TOKEN_WEIGHT = 2;\nconst GLOBAL_BONUS = 0.1;\nconst CONTENT_SAMPLE_CHARS = 2000;\n\n/**\n * Score context file relevance against a query context.\n *\n * - queryContext undefined -> isGlobal ? 0.9 : 0.6\n * - Coverage of query tokens against path segments + content sample\n * - Path tokens weighted 2x\n * - isGlobal bonus: +0.1\n */\nexport function scoreContextFileRelevance(\n\tcontextFile: { readonly path: string; readonly content: string; readonly isGlobal: boolean },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\t// Path segments as high-weight text\n\tconst pathText = extractPathSegments(contextFile.path);\n\n\t// Content sample for performance\n\tconst contentSample =\n\t\tcontextFile.content.length > CONTENT_SAMPLE_CHARS\n\t\t\t? contextFile.content.slice(0, CONTENT_SAMPLE_CHARS)\n\t\t\t: contextFile.content;\n\n\t// Build token set: content is base, path tokens get 2x weight\n\tconst { tokens: fileTokenSet, weights: fileWeights } = buildWeightedTokenSet(\n\t\tcontentSample,\n\t\tpathText,\n\t\tPATH_TOKEN_WEIGHT,\n\t);\n\n\tlet score = computeCoverage(queryTokens, fileTokenSet, fileWeights);\n\n\t// Global file bonus\n\tif (contextFile.isGlobal) {\n\t\tscore = Math.min(1, score + GLOBAL_BONUS);\n\t}\n\n\treturn clamp01(score);\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract meaningful segments from a file path for token matching.\n */\nfunction extractPathSegments(path: string): string {\n\treturn path\n\t\t.toLowerCase()\n\t\t.split(/[/\\\\._-]+/)\n\t\t.filter((seg) => seg.length > 0)\n\t\t.join(\" \");\n}\n\nfunction clamp01(value: number): number {\n\treturn Math.max(0, Math.min(1, value));\n}\n"]}
+{"version":3,"file":"context-budget-relevance.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-relevance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAyJH;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAmCpE;AAkED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC9D,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CA2BR;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACxC,WAAW,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,EAC5F,YAAY,EAAE,MAAM,GAAG,SAAS,GAC9B,MAAM,CAiCR","sourcesContent":["/**\n * Query-aware relevance scoring for context budget items.\n *\n * Replaces heuristic proxies (description length, isGlobal hardcoding)\n * with token-based coverage scoring that measures semantic overlap\n * between the current query context and each resource item.\n *\n * Design: Coverage-based IR (not Jaccard) — avoids penalizing long\n * descriptions whose large union would dilute the score.\n */\n\n// ---------------------------------------------------------------------------\n// Stop words — English + common Korean particles\n// ---------------------------------------------------------------------------\n\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n\t// English common stop words\n\t\"the\",\n\t\"a\",\n\t\"an\",\n\t\"is\",\n\t\"are\",\n\t\"was\",\n\t\"were\",\n\t\"be\",\n\t\"been\",\n\t\"being\",\n\t\"have\",\n\t\"has\",\n\t\"had\",\n\t\"do\",\n\t\"does\",\n\t\"did\",\n\t\"will\",\n\t\"would\",\n\t\"could\",\n\t\"should\",\n\t\"may\",\n\t\"might\",\n\t\"shall\",\n\t\"can\",\n\t\"to\",\n\t\"of\",\n\t\"in\",\n\t\"on\",\n\t\"for\",\n\t\"and\",\n\t\"or\",\n\t\"with\",\n\t\"how\",\n\t\"i\",\n\t\"you\",\n\t\"he\",\n\t\"she\",\n\t\"it\",\n\t\"we\",\n\t\"they\",\n\t\"me\",\n\t\"him\",\n\t\"her\",\n\t\"us\",\n\t\"them\",\n\t\"my\",\n\t\"your\",\n\t\"his\",\n\t\"its\",\n\t\"our\",\n\t\"their\",\n\t\"this\",\n\t\"that\",\n\t\"these\",\n\t\"those\",\n\t\"what\",\n\t\"which\",\n\t\"who\",\n\t\"whom\",\n\t\"where\",\n\t\"when\",\n\t\"why\",\n\t\"not\",\n\t\"no\",\n\t\"nor\",\n\t\"so\",\n\t\"if\",\n\t\"then\",\n\t\"than\",\n\t\"too\",\n\t\"very\",\n\t\"just\",\n\t\"about\",\n\t\"above\",\n\t\"after\",\n\t\"again\",\n\t\"all\",\n\t\"also\",\n\t\"am\",\n\t\"any\",\n\t\"because\",\n\t\"before\",\n\t\"between\",\n\t\"both\",\n\t\"but\",\n\t\"by\",\n\t\"from\",\n\t\"into\",\n\t\"more\",\n\t\"most\",\n\t\"other\",\n\t\"out\",\n\t\"over\",\n\t\"own\",\n\t\"same\",\n\t\"some\",\n\t\"such\",\n\t\"there\",\n\t\"up\",\n\t\"down\",\n\t\"here\",\n\t\"at\",\n\t\"as\",\n\t\"while\",\n\t\"through\",\n\t\"during\",\n\t\"each\",\n\t\"few\",\n\t\"further\",\n\t\"once\",\n\t\"only\",\n\t\"until\",\n\t// Korean particles (조사)\n\t\"은\",\n\t\"는\",\n\t\"이\",\n\t\"가\",\n\t\"을\",\n\t\"를\",\n\t\"에\",\n\t\"의\",\n\t\"와\",\n\t\"과\",\n\t\"도\",\n\t\"로\",\n\t\"으로\",\n\t\"에서\",\n\t\"까지\",\n\t\"부터\",\n\t\"만\",\n\t\"라도\",\n\t\"나\",\n\t\"이며\",\n\t\"이고\",\n\t\"이나\",\n\t\"라\",\n\t\"이다\",\n\t\"하다\",\n\t\"된\",\n]);\n\n// ---------------------------------------------------------------------------\n// Tokenizer\n// ---------------------------------------------------------------------------\n\n/**\n * Tokenize text for relevance scoring.\n *\n * 1. Lowercase\n * 2. Split: Latin words via regex, Korean syllable groups via regex\n * 3. Remove stop words\n * 4. Remove short Latin tokens (<=2 chars)\n * 5. Deduplicate\n */\nexport function tokenizeForRelevance(text: string): readonly string[] {\n\tconst lower = text.toLowerCase();\n\tconst raw = lower.match(/[\\uac00-\\ud7a3]+|[a-z0-9]+/g);\n\tif (!raw) {\n\t\treturn [];\n\t}\n\n\tconst seen = new Set<string>();\n\tconst tokens: string[] = [];\n\n\tfor (const token of raw) {\n\t\t// Skip stop words\n\t\tif (STOP_WORDS.has(token)) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Latin tokens, skip very short ones (<=2 chars)\n\t\tif (/^[a-z0-9]+$/.test(token) && token.length <= 2) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Korean, keep 2+ syllable groups\n\t\tif (/^[\\uac00-\\ud7a3]+$/.test(token)) {\n\t\t\tif (token.length >= 2 && !seen.has(token)) {\n\t\t\t\tseen.add(token);\n\t\t\t\ttokens.push(token);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\t// Deduplicate\n\t\tif (!seen.has(token)) {\n\t\t\tseen.add(token);\n\t\t\ttokens.push(token);\n\t\t}\n\t}\n\n\treturn tokens;\n}\n\n// ---------------------------------------------------------------------------\n// Coverage scoring\n// ---------------------------------------------------------------------------\n\n/**\n * Compute coverage: fraction of query tokens found in the item token set.\n * Optional per-token weights boost high-value matches (name, path).\n */\nfunction computeCoverage(\n\tqueryTokens: readonly string[],\n\titemTokenSet: ReadonlySet<string>,\n\titemTokenWeights?: ReadonlyMap<string, number>,\n): number {\n\tif (queryTokens.length === 0) {\n\t\treturn 0;\n\t}\n\n\tlet matchWeight = 0;\n\tfor (const qt of queryTokens) {\n\t\tif (itemTokenSet.has(qt)) {\n\t\t\tmatchWeight += itemTokenWeights?.get(qt) ?? 1;\n\t\t}\n\t}\n\n\t// Normalize: each query token contributes at most 1 to the numerator\n\treturn Math.min(1, matchWeight / queryTokens.length);\n}\n\n/**\n * Build a token set with optional high-weight tokens.\n */\nfunction buildWeightedTokenSet(\n\tbaseText: string,\n\thighWeightText: string | undefined,\n\tweight: number,\n): { tokens: Set<string>; weights: Map<string, number> } {\n\tconst baseTokens = tokenizeForRelevance(baseText);\n\tconst highTokens = highWeightText ? tokenizeForRelevance(highWeightText) : [];\n\n\tconst tokenSet = new Set<string>();\n\tconst weights = new Map<string, number>();\n\n\tfor (const t of baseTokens) {\n\t\ttokenSet.add(t);\n\t\tif (!weights.has(t)) {\n\t\t\tweights.set(t, 1);\n\t\t}\n\t}\n\tfor (const t of highTokens) {\n\t\ttokenSet.add(t);\n\t\tweights.set(t, Math.max(weights.get(t) ?? 0, weight));\n\t}\n\n\treturn { tokens: tokenSet, weights };\n}\n\n// ---------------------------------------------------------------------------\n// Skill relevance\n// ---------------------------------------------------------------------------\n\nconst SKILL_NEUTRAL_SCORE = 0.3;\nconst NAME_MATCH_BONUS = 0.2;\nconst NAME_TOKEN_WEIGHT = 3;\n\n/**\n * Score skill relevance against a query context.\n *\n * - queryContext undefined or empty -> 0.3 (neutral)\n * - Coverage of query tokens against skill name+description\n * - Name tokens weighted 3x\n * - Name substring match bonus: +0.2 (capped at 1.0)\n */\nexport function scoreSkillRelevance(\n\tskill: { readonly name: string; readonly description: string },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\t// Build skill token set: description is base, name tokens get 3x weight\n\tconst { tokens: skillTokenSet, weights: skillWeights } = buildWeightedTokenSet(\n\t\tskill.description,\n\t\tskill.name,\n\t\tNAME_TOKEN_WEIGHT,\n\t);\n\n\tlet score = computeCoverage(queryTokens, skillTokenSet, skillWeights);\n\n\t// Name substring bonus: if skill.name appears in query text (or vice versa)\n\tconst queryLower = queryContext.toLowerCase();\n\tconst nameLower = skill.name.toLowerCase();\n\tif (queryLower.includes(nameLower) || nameLower.includes(queryLower.trim())) {\n\t\tscore = Math.min(1, score + NAME_MATCH_BONUS);\n\t}\n\n\treturn clamp01(score);\n}\n\n// ---------------------------------------------------------------------------\n// Context file relevance\n// ---------------------------------------------------------------------------\n\nconst CONTEXT_NEUTRAL_GLOBAL = 0.9;\nconst CONTEXT_NEUTRAL_LOCAL = 0.6;\nconst PATH_TOKEN_WEIGHT = 2;\nconst CONTENT_SAMPLE_CHARS = 2000;\n\n/**\n * Score context file relevance against a query context.\n *\n * - Baseline (no query evidence) -> isGlobal ? 0.9 : 0.6\n * - Coverage of query tokens against path segments + content sample\n * - Path tokens weighted 2x\n * - Coverage allocates the headroom ABOVE the baseline; it never cuts into it\n *\n * A context file is not retrieved reference material — it is the standing\n * instruction set the agent is required to follow, and it applies whether or\n * not the user's current sentence reuses its vocabulary. Scoring it purely by\n * lexical overlap made the rules rank LOWEST exactly when the agent was doing\n * work: this repository's own AGENTS.md scored 0.9 idle but 0.1 under queries\n * like \"rename this variable\". Coverage therefore raises the score from the\n * baseline toward 1 instead of replacing it, which also reconciles the two\n * readings the function used to have — an absent query and a present-but-\n * non-overlapping query now agree that there is simply no evidence to add.\n *\n * Lexical scoring stays the right metric for skills, which really are\n * topic-scoped; see scoreSkillRelevance.\n */\nexport function scoreContextFileRelevance(\n\tcontextFile: { readonly path: string; readonly content: string; readonly isGlobal: boolean },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\t// Path segments as high-weight text\n\tconst pathText = extractPathSegments(contextFile.path);\n\n\t// Content sample for performance\n\tconst contentSample =\n\t\tcontextFile.content.length > CONTENT_SAMPLE_CHARS\n\t\t\t? contextFile.content.slice(0, CONTENT_SAMPLE_CHARS)\n\t\t\t: contextFile.content;\n\n\t// Build token set: content is base, path tokens get 2x weight\n\tconst { tokens: fileTokenSet, weights: fileWeights } = buildWeightedTokenSet(\n\t\tcontentSample,\n\t\tpathText,\n\t\tPATH_TOKEN_WEIGHT,\n\t);\n\n\tconst coverage = computeCoverage(queryTokens, fileTokenSet, fileWeights);\n\n\t// The baseline is a floor, not a starting guess: query evidence distributes\n\t// the remaining headroom above it. Zero coverage returns the baseline exactly,\n\t// matching the no-query branch above.\n\tconst baseline = contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\treturn clamp01(baseline + (1 - baseline) * clamp01(coverage));\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract meaningful segments from a file path for token matching.\n */\nfunction extractPathSegments(path: string): string {\n\treturn path\n\t\t.toLowerCase()\n\t\t.split(/[/\\\\._-]+/)\n\t\t.filter((seg) => seg.length > 0)\n\t\t.join(\" \");\n}\n\nfunction clamp01(value: number): number {\n\treturn Math.max(0, Math.min(1, value));\n}\n"]}

package/dist/core/context-budget-relevance.js

@@ -277,15 +277,27 @@ export function scoreSkillRelevance(skill, queryContext) {
 const CONTEXT_NEUTRAL_GLOBAL = 0.9;
 const CONTEXT_NEUTRAL_LOCAL = 0.6;
 const PATH_TOKEN_WEIGHT = 2;
-const GLOBAL_BONUS = 0.1;
 const CONTENT_SAMPLE_CHARS = 2000;
 /**
  * Score context file relevance against a query context.
  *
- * - queryContext undefined -> isGlobal ? 0.9 : 0.6
+ * - Baseline (no query evidence) -> isGlobal ? 0.9 : 0.6
  * - Coverage of query tokens against path segments + content sample
  * - Path tokens weighted 2x
- * - isGlobal bonus: +0.1
+ * - Coverage allocates the headroom ABOVE the baseline; it never cuts into it
+ *
+ * A context file is not retrieved reference material — it is the standing
+ * instruction set the agent is required to follow, and it applies whether or
+ * not the user's current sentence reuses its vocabulary. Scoring it purely by
+ * lexical overlap made the rules rank LOWEST exactly when the agent was doing
+ * work: this repository's own AGENTS.md scored 0.9 idle but 0.1 under queries
+ * like "rename this variable". Coverage therefore raises the score from the
+ * baseline toward 1 instead of replacing it, which also reconciles the two
+ * readings the function used to have — an absent query and a present-but-
+ * non-overlapping query now agree that there is simply no evidence to add.
+ *
+ * Lexical scoring stays the right metric for skills, which really are
+ * topic-scoped; see scoreSkillRelevance.
  */
 export function scoreContextFileRelevance(contextFile, queryContext) {
     if (!queryContext || queryContext.trim() === "") {
@@ -303,12 +315,12 @@ export function scoreContextFileRelevance(contextFile, queryContext) {
         : contextFile.content;
     // Build token set: content is base, path tokens get 2x weight
     const { tokens: fileTokenSet, weights: fileWeights } = buildWeightedTokenSet(contentSample, pathText, PATH_TOKEN_WEIGHT);
-    let score = computeCoverage(queryTokens, fileTokenSet, fileWeights);
-    // Global file bonus
-    if (contextFile.isGlobal) {
-        score = Math.min(1, score + GLOBAL_BONUS);
-    }
-    return clamp01(score);
+    const coverage = computeCoverage(queryTokens, fileTokenSet, fileWeights);
+    // The baseline is a floor, not a starting guess: query evidence distributes
+    // the remaining headroom above it. Zero coverage returns the baseline exactly,
+    // matching the no-query branch above.
+    const baseline = contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;
+    return clamp01(baseline + (1 - baseline) * clamp01(coverage));
 }
 // ---------------------------------------------------------------------------
 // Helpers

package/dist/core/context-budget-relevance.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-relevance.js","sourceRoot":"","sources":["../../src/core/context-budget-relevance.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Query-aware relevance scoring for context budget items.\n *\n * Replaces heuristic proxies (description length, isGlobal hardcoding)\n * with token-based coverage scoring that measures semantic overlap\n * between the current query context and each resource item.\n *\n * Design: Coverage-based IR (not Jaccard) — avoids penalizing long\n * descriptions whose large union would dilute the score.\n */\n\n// ---------------------------------------------------------------------------\n// Stop words — English + common Korean particles\n// ---------------------------------------------------------------------------\n\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n\t// English common stop words\n\t\"the\",\n\t\"a\",\n\t\"an\",\n\t\"is\",\n\t\"are\",\n\t\"was\",\n\t\"were\",\n\t\"be\",\n\t\"been\",\n\t\"being\",\n\t\"have\",\n\t\"has\",\n\t\"had\",\n\t\"do\",\n\t\"does\",\n\t\"did\",\n\t\"will\",\n\t\"would\",\n\t\"could\",\n\t\"should\",\n\t\"may\",\n\t\"might\",\n\t\"shall\",\n\t\"can\",\n\t\"to\",\n\t\"of\",\n\t\"in\",\n\t\"on\",\n\t\"for\",\n\t\"and\",\n\t\"or\",\n\t\"with\",\n\t\"how\",\n\t\"i\",\n\t\"you\",\n\t\"he\",\n\t\"she\",\n\t\"it\",\n\t\"we\",\n\t\"they\",\n\t\"me\",\n\t\"him\",\n\t\"her\",\n\t\"us\",\n\t\"them\",\n\t\"my\",\n\t\"your\",\n\t\"his\",\n\t\"its\",\n\t\"our\",\n\t\"their\",\n\t\"this\",\n\t\"that\",\n\t\"these\",\n\t\"those\",\n\t\"what\",\n\t\"which\",\n\t\"who\",\n\t\"whom\",\n\t\"where\",\n\t\"when\",\n\t\"why\",\n\t\"not\",\n\t\"no\",\n\t\"nor\",\n\t\"so\",\n\t\"if\",\n\t\"then\",\n\t\"than\",\n\t\"too\",\n\t\"very\",\n\t\"just\",\n\t\"about\",\n\t\"above\",\n\t\"after\",\n\t\"again\",\n\t\"all\",\n\t\"also\",\n\t\"am\",\n\t\"any\",\n\t\"because\",\n\t\"before\",\n\t\"between\",\n\t\"both\",\n\t\"but\",\n\t\"by\",\n\t\"from\",\n\t\"into\",\n\t\"more\",\n\t\"most\",\n\t\"other\",\n\t\"out\",\n\t\"over\",\n\t\"own\",\n\t\"same\",\n\t\"some\",\n\t\"such\",\n\t\"there\",\n\t\"up\",\n\t\"down\",\n\t\"here\",\n\t\"at\",\n\t\"as\",\n\t\"while\",\n\t\"through\",\n\t\"during\",\n\t\"each\",\n\t\"few\",\n\t\"further\",\n\t\"once\",\n\t\"only\",\n\t\"until\",\n\t// Korean particles (조사)\n\t\"은\",\n\t\"는\",\n\t\"이\",\n\t\"가\",\n\t\"을\",\n\t\"를\",\n\t\"에\",\n\t\"의\",\n\t\"와\",\n\t\"과\",\n\t\"도\",\n\t\"로\",\n\t\"으로\",\n\t\"에서\",\n\t\"까지\",\n\t\"부터\",\n\t\"만\",\n\t\"라도\",\n\t\"나\",\n\t\"이며\",\n\t\"이고\",\n\t\"이나\",\n\t\"라\",\n\t\"이다\",\n\t\"하다\",\n\t\"된\",\n]);\n\n// ---------------------------------------------------------------------------\n// Tokenizer\n// ---------------------------------------------------------------------------\n\n/**\n * Tokenize text for relevance scoring.\n *\n * 1. Lowercase\n * 2. Split: Latin words via regex, Korean syllable groups via regex\n * 3. Remove stop words\n * 4. Remove short Latin tokens (<=2 chars)\n * 5. Deduplicate\n */\nexport function tokenizeForRelevance(text: string): readonly string[] {\n\tconst lower = text.toLowerCase();\n\tconst raw = lower.match(/[\\uac00-\\ud7a3]+|[a-z0-9]+/g);\n\tif (!raw) {\n\t\treturn [];\n\t}\n\n\tconst seen = new Set<string>();\n\tconst tokens: string[] = [];\n\n\tfor (const token of raw) {\n\t\t// Skip stop words\n\t\tif (STOP_WORDS.has(token)) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Latin tokens, skip very short ones (<=2 chars)\n\t\tif (/^[a-z0-9]+$/.test(token) && token.length <= 2) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Korean, keep 2+ syllable groups\n\t\tif (/^[\\uac00-\\ud7a3]+$/.test(token)) {\n\t\t\tif (token.length >= 2 && !seen.has(token)) {\n\t\t\t\tseen.add(token);\n\t\t\t\ttokens.push(token);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\t// Deduplicate\n\t\tif (!seen.has(token)) {\n\t\t\tseen.add(token);\n\t\t\ttokens.push(token);\n\t\t}\n\t}\n\n\treturn tokens;\n}\n\n// ---------------------------------------------------------------------------\n// Coverage scoring\n// ---------------------------------------------------------------------------\n\n/**\n * Compute coverage: fraction of query tokens found in the item token set.\n * Optional per-token weights boost high-value matches (name, path).\n */\nfunction computeCoverage(\n\tqueryTokens: readonly string[],\n\titemTokenSet: ReadonlySet<string>,\n\titemTokenWeights?: ReadonlyMap<string, number>,\n): number {\n\tif (queryTokens.length === 0) {\n\t\treturn 0;\n\t}\n\n\tlet matchWeight = 0;\n\tfor (const qt of queryTokens) {\n\t\tif (itemTokenSet.has(qt)) {\n\t\t\tmatchWeight += itemTokenWeights?.get(qt) ?? 1;\n\t\t}\n\t}\n\n\t// Normalize: each query token contributes at most 1 to the numerator\n\treturn Math.min(1, matchWeight / queryTokens.length);\n}\n\n/**\n * Build a token set with optional high-weight tokens.\n */\nfunction buildWeightedTokenSet(\n\tbaseText: string,\n\thighWeightText: string | undefined,\n\tweight: number,\n): { tokens: Set<string>; weights: Map<string, number> } {\n\tconst baseTokens = tokenizeForRelevance(baseText);\n\tconst highTokens = highWeightText ? tokenizeForRelevance(highWeightText) : [];\n\n\tconst tokenSet = new Set<string>();\n\tconst weights = new Map<string, number>();\n\n\tfor (const t of baseTokens) {\n\t\ttokenSet.add(t);\n\t\tif (!weights.has(t)) {\n\t\t\tweights.set(t, 1);\n\t\t}\n\t}\n\tfor (const t of highTokens) {\n\t\ttokenSet.add(t);\n\t\tweights.set(t, Math.max(weights.get(t) ?? 0, weight));\n\t}\n\n\treturn { tokens: tokenSet, weights };\n}\n\n// ---------------------------------------------------------------------------\n// Skill relevance\n// ---------------------------------------------------------------------------\n\nconst SKILL_NEUTRAL_SCORE = 0.3;\nconst NAME_MATCH_BONUS = 0.2;\nconst NAME_TOKEN_WEIGHT = 3;\n\n/**\n * Score skill relevance against a query context.\n *\n * - queryContext undefined or empty -> 0.3 (neutral)\n * - Coverage of query tokens against skill name+description\n * - Name tokens weighted 3x\n * - Name substring match bonus: +0.2 (capped at 1.0)\n */\nexport function scoreSkillRelevance(\n\tskill: { readonly name: string; readonly description: string },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\t// Build skill token set: description is base, name tokens get 3x weight\n\tconst { tokens: skillTokenSet, weights: skillWeights } = buildWeightedTokenSet(\n\t\tskill.description,\n\t\tskill.name,\n\t\tNAME_TOKEN_WEIGHT,\n\t);\n\n\tlet score = computeCoverage(queryTokens, skillTokenSet, skillWeights);\n\n\t// Name substring bonus: if skill.name appears in query text (or vice versa)\n\tconst queryLower = queryContext.toLowerCase();\n\tconst nameLower = skill.name.toLowerCase();\n\tif (queryLower.includes(nameLower) || nameLower.includes(queryLower.trim())) {\n\t\tscore = Math.min(1, score + NAME_MATCH_BONUS);\n\t}\n\n\treturn clamp01(score);\n}\n\n// ---------------------------------------------------------------------------\n// Context file relevance\n// ---------------------------------------------------------------------------\n\nconst CONTEXT_NEUTRAL_GLOBAL = 0.9;\nconst CONTEXT_NEUTRAL_LOCAL = 0.6;\nconst PATH_TOKEN_WEIGHT = 2;\nconst GLOBAL_BONUS = 0.1;\nconst CONTENT_SAMPLE_CHARS = 2000;\n\n/**\n * Score context file relevance against a query context.\n *\n * - queryContext undefined -> isGlobal ? 0.9 : 0.6\n * - Coverage of query tokens against path segments + content sample\n * - Path tokens weighted 2x\n * - isGlobal bonus: +0.1\n */\nexport function scoreContextFileRelevance(\n\tcontextFile: { readonly path: string; readonly content: string; readonly isGlobal: boolean },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\t// Path segments as high-weight text\n\tconst pathText = extractPathSegments(contextFile.path);\n\n\t// Content sample for performance\n\tconst contentSample =\n\t\tcontextFile.content.length > CONTENT_SAMPLE_CHARS\n\t\t\t? contextFile.content.slice(0, CONTENT_SAMPLE_CHARS)\n\t\t\t: contextFile.content;\n\n\t// Build token set: content is base, path tokens get 2x weight\n\tconst { tokens: fileTokenSet, weights: fileWeights } = buildWeightedTokenSet(\n\t\tcontentSample,\n\t\tpathText,\n\t\tPATH_TOKEN_WEIGHT,\n\t);\n\n\tlet score = computeCoverage(queryTokens, fileTokenSet, fileWeights);\n\n\t// Global file bonus\n\tif (contextFile.isGlobal) {\n\t\tscore = Math.min(1, score + GLOBAL_BONUS);\n\t}\n\n\treturn clamp01(score);\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract meaningful segments from a file path for token matching.\n */\nfunction extractPathSegments(path: string): string {\n\treturn path\n\t\t.toLowerCase()\n\t\t.split(/[/\\\\._-]+/)\n\t\t.filter((seg) => seg.length > 0)\n\t\t.join(\" \");\n}\n\nfunction clamp01(value: number): number {\n\treturn Math.max(0, Math.min(1, value));\n}\n"]}
+{"version":3,"file":"context-budget-relevance.js","sourceRoot":"","sources":["../../src/core/context-budget-relevance.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Query-aware relevance scoring for context budget items.\n *\n * Replaces heuristic proxies (description length, isGlobal hardcoding)\n * with token-based coverage scoring that measures semantic overlap\n * between the current query context and each resource item.\n *\n * Design: Coverage-based IR (not Jaccard) — avoids penalizing long\n * descriptions whose large union would dilute the score.\n */\n\n// ---------------------------------------------------------------------------\n// Stop words — English + common Korean particles\n// ---------------------------------------------------------------------------\n\nconst STOP_WORDS: ReadonlySet<string> = new Set([\n\t// English common stop words\n\t\"the\",\n\t\"a\",\n\t\"an\",\n\t\"is\",\n\t\"are\",\n\t\"was\",\n\t\"were\",\n\t\"be\",\n\t\"been\",\n\t\"being\",\n\t\"have\",\n\t\"has\",\n\t\"had\",\n\t\"do\",\n\t\"does\",\n\t\"did\",\n\t\"will\",\n\t\"would\",\n\t\"could\",\n\t\"should\",\n\t\"may\",\n\t\"might\",\n\t\"shall\",\n\t\"can\",\n\t\"to\",\n\t\"of\",\n\t\"in\",\n\t\"on\",\n\t\"for\",\n\t\"and\",\n\t\"or\",\n\t\"with\",\n\t\"how\",\n\t\"i\",\n\t\"you\",\n\t\"he\",\n\t\"she\",\n\t\"it\",\n\t\"we\",\n\t\"they\",\n\t\"me\",\n\t\"him\",\n\t\"her\",\n\t\"us\",\n\t\"them\",\n\t\"my\",\n\t\"your\",\n\t\"his\",\n\t\"its\",\n\t\"our\",\n\t\"their\",\n\t\"this\",\n\t\"that\",\n\t\"these\",\n\t\"those\",\n\t\"what\",\n\t\"which\",\n\t\"who\",\n\t\"whom\",\n\t\"where\",\n\t\"when\",\n\t\"why\",\n\t\"not\",\n\t\"no\",\n\t\"nor\",\n\t\"so\",\n\t\"if\",\n\t\"then\",\n\t\"than\",\n\t\"too\",\n\t\"very\",\n\t\"just\",\n\t\"about\",\n\t\"above\",\n\t\"after\",\n\t\"again\",\n\t\"all\",\n\t\"also\",\n\t\"am\",\n\t\"any\",\n\t\"because\",\n\t\"before\",\n\t\"between\",\n\t\"both\",\n\t\"but\",\n\t\"by\",\n\t\"from\",\n\t\"into\",\n\t\"more\",\n\t\"most\",\n\t\"other\",\n\t\"out\",\n\t\"over\",\n\t\"own\",\n\t\"same\",\n\t\"some\",\n\t\"such\",\n\t\"there\",\n\t\"up\",\n\t\"down\",\n\t\"here\",\n\t\"at\",\n\t\"as\",\n\t\"while\",\n\t\"through\",\n\t\"during\",\n\t\"each\",\n\t\"few\",\n\t\"further\",\n\t\"once\",\n\t\"only\",\n\t\"until\",\n\t// Korean particles (조사)\n\t\"은\",\n\t\"는\",\n\t\"이\",\n\t\"가\",\n\t\"을\",\n\t\"를\",\n\t\"에\",\n\t\"의\",\n\t\"와\",\n\t\"과\",\n\t\"도\",\n\t\"로\",\n\t\"으로\",\n\t\"에서\",\n\t\"까지\",\n\t\"부터\",\n\t\"만\",\n\t\"라도\",\n\t\"나\",\n\t\"이며\",\n\t\"이고\",\n\t\"이나\",\n\t\"라\",\n\t\"이다\",\n\t\"하다\",\n\t\"된\",\n]);\n\n// ---------------------------------------------------------------------------\n// Tokenizer\n// ---------------------------------------------------------------------------\n\n/**\n * Tokenize text for relevance scoring.\n *\n * 1. Lowercase\n * 2. Split: Latin words via regex, Korean syllable groups via regex\n * 3. Remove stop words\n * 4. Remove short Latin tokens (<=2 chars)\n * 5. Deduplicate\n */\nexport function tokenizeForRelevance(text: string): readonly string[] {\n\tconst lower = text.toLowerCase();\n\tconst raw = lower.match(/[\\uac00-\\ud7a3]+|[a-z0-9]+/g);\n\tif (!raw) {\n\t\treturn [];\n\t}\n\n\tconst seen = new Set<string>();\n\tconst tokens: string[] = [];\n\n\tfor (const token of raw) {\n\t\t// Skip stop words\n\t\tif (STOP_WORDS.has(token)) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Latin tokens, skip very short ones (<=2 chars)\n\t\tif (/^[a-z0-9]+$/.test(token) && token.length <= 2) {\n\t\t\tcontinue;\n\t\t}\n\t\t// For Korean, keep 2+ syllable groups\n\t\tif (/^[\\uac00-\\ud7a3]+$/.test(token)) {\n\t\t\tif (token.length >= 2 && !seen.has(token)) {\n\t\t\t\tseen.add(token);\n\t\t\t\ttokens.push(token);\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\t// Deduplicate\n\t\tif (!seen.has(token)) {\n\t\t\tseen.add(token);\n\t\t\ttokens.push(token);\n\t\t}\n\t}\n\n\treturn tokens;\n}\n\n// ---------------------------------------------------------------------------\n// Coverage scoring\n// ---------------------------------------------------------------------------\n\n/**\n * Compute coverage: fraction of query tokens found in the item token set.\n * Optional per-token weights boost high-value matches (name, path).\n */\nfunction computeCoverage(\n\tqueryTokens: readonly string[],\n\titemTokenSet: ReadonlySet<string>,\n\titemTokenWeights?: ReadonlyMap<string, number>,\n): number {\n\tif (queryTokens.length === 0) {\n\t\treturn 0;\n\t}\n\n\tlet matchWeight = 0;\n\tfor (const qt of queryTokens) {\n\t\tif (itemTokenSet.has(qt)) {\n\t\t\tmatchWeight += itemTokenWeights?.get(qt) ?? 1;\n\t\t}\n\t}\n\n\t// Normalize: each query token contributes at most 1 to the numerator\n\treturn Math.min(1, matchWeight / queryTokens.length);\n}\n\n/**\n * Build a token set with optional high-weight tokens.\n */\nfunction buildWeightedTokenSet(\n\tbaseText: string,\n\thighWeightText: string | undefined,\n\tweight: number,\n): { tokens: Set<string>; weights: Map<string, number> } {\n\tconst baseTokens = tokenizeForRelevance(baseText);\n\tconst highTokens = highWeightText ? tokenizeForRelevance(highWeightText) : [];\n\n\tconst tokenSet = new Set<string>();\n\tconst weights = new Map<string, number>();\n\n\tfor (const t of baseTokens) {\n\t\ttokenSet.add(t);\n\t\tif (!weights.has(t)) {\n\t\t\tweights.set(t, 1);\n\t\t}\n\t}\n\tfor (const t of highTokens) {\n\t\ttokenSet.add(t);\n\t\tweights.set(t, Math.max(weights.get(t) ?? 0, weight));\n\t}\n\n\treturn { tokens: tokenSet, weights };\n}\n\n// ---------------------------------------------------------------------------\n// Skill relevance\n// ---------------------------------------------------------------------------\n\nconst SKILL_NEUTRAL_SCORE = 0.3;\nconst NAME_MATCH_BONUS = 0.2;\nconst NAME_TOKEN_WEIGHT = 3;\n\n/**\n * Score skill relevance against a query context.\n *\n * - queryContext undefined or empty -> 0.3 (neutral)\n * - Coverage of query tokens against skill name+description\n * - Name tokens weighted 3x\n * - Name substring match bonus: +0.2 (capped at 1.0)\n */\nexport function scoreSkillRelevance(\n\tskill: { readonly name: string; readonly description: string },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn SKILL_NEUTRAL_SCORE;\n\t}\n\n\t// Build skill token set: description is base, name tokens get 3x weight\n\tconst { tokens: skillTokenSet, weights: skillWeights } = buildWeightedTokenSet(\n\t\tskill.description,\n\t\tskill.name,\n\t\tNAME_TOKEN_WEIGHT,\n\t);\n\n\tlet score = computeCoverage(queryTokens, skillTokenSet, skillWeights);\n\n\t// Name substring bonus: if skill.name appears in query text (or vice versa)\n\tconst queryLower = queryContext.toLowerCase();\n\tconst nameLower = skill.name.toLowerCase();\n\tif (queryLower.includes(nameLower) || nameLower.includes(queryLower.trim())) {\n\t\tscore = Math.min(1, score + NAME_MATCH_BONUS);\n\t}\n\n\treturn clamp01(score);\n}\n\n// ---------------------------------------------------------------------------\n// Context file relevance\n// ---------------------------------------------------------------------------\n\nconst CONTEXT_NEUTRAL_GLOBAL = 0.9;\nconst CONTEXT_NEUTRAL_LOCAL = 0.6;\nconst PATH_TOKEN_WEIGHT = 2;\nconst CONTENT_SAMPLE_CHARS = 2000;\n\n/**\n * Score context file relevance against a query context.\n *\n * - Baseline (no query evidence) -> isGlobal ? 0.9 : 0.6\n * - Coverage of query tokens against path segments + content sample\n * - Path tokens weighted 2x\n * - Coverage allocates the headroom ABOVE the baseline; it never cuts into it\n *\n * A context file is not retrieved reference material — it is the standing\n * instruction set the agent is required to follow, and it applies whether or\n * not the user's current sentence reuses its vocabulary. Scoring it purely by\n * lexical overlap made the rules rank LOWEST exactly when the agent was doing\n * work: this repository's own AGENTS.md scored 0.9 idle but 0.1 under queries\n * like \"rename this variable\". Coverage therefore raises the score from the\n * baseline toward 1 instead of replacing it, which also reconciles the two\n * readings the function used to have — an absent query and a present-but-\n * non-overlapping query now agree that there is simply no evidence to add.\n *\n * Lexical scoring stays the right metric for skills, which really are\n * topic-scoped; see scoreSkillRelevance.\n */\nexport function scoreContextFileRelevance(\n\tcontextFile: { readonly path: string; readonly content: string; readonly isGlobal: boolean },\n\tqueryContext: string | undefined,\n): number {\n\tif (!queryContext || queryContext.trim() === \"\") {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\tconst queryTokens = tokenizeForRelevance(queryContext);\n\tif (queryTokens.length === 0) {\n\t\treturn contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\t}\n\n\t// Path segments as high-weight text\n\tconst pathText = extractPathSegments(contextFile.path);\n\n\t// Content sample for performance\n\tconst contentSample =\n\t\tcontextFile.content.length > CONTENT_SAMPLE_CHARS\n\t\t\t? contextFile.content.slice(0, CONTENT_SAMPLE_CHARS)\n\t\t\t: contextFile.content;\n\n\t// Build token set: content is base, path tokens get 2x weight\n\tconst { tokens: fileTokenSet, weights: fileWeights } = buildWeightedTokenSet(\n\t\tcontentSample,\n\t\tpathText,\n\t\tPATH_TOKEN_WEIGHT,\n\t);\n\n\tconst coverage = computeCoverage(queryTokens, fileTokenSet, fileWeights);\n\n\t// The baseline is a floor, not a starting guess: query evidence distributes\n\t// the remaining headroom above it. Zero coverage returns the baseline exactly,\n\t// matching the no-query branch above.\n\tconst baseline = contextFile.isGlobal ? CONTEXT_NEUTRAL_GLOBAL : CONTEXT_NEUTRAL_LOCAL;\n\treturn clamp01(baseline + (1 - baseline) * clamp01(coverage));\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Extract meaningful segments from a file path for token matching.\n */\nfunction extractPathSegments(path: string): string {\n\treturn path\n\t\t.toLowerCase()\n\t\t.split(/[/\\\\._-]+/)\n\t\t.filter((seg) => seg.length > 0)\n\t\t.join(\" \");\n}\n\nfunction clamp01(value: number): number {\n\treturn Math.max(0, Math.min(1, value));\n}\n"]}